evitaDB - Fast e-commerce database
logo
page-background

Paging

Paging request constraints help to traverse large lists of records by splitting them into several parts that are requested separately. This technique is used to reduce the amount of data transferred over the network and to reduce the load on the server. evitaDB supports several ways to paginate query results, which are described in this section.

Page

argument:int

a mandatory number of page to be returned, positive integer starting from 1

argument:int

a mandatory size of the page to be returned, positive integer

The page
()
controls the number and slice of entities returned in the query response. If no
page requirement is
used
in the query
, the default page 1 with the default page size 20 is used. If the requested page exceeds the number of available pages, a result with the first page is returned. An empty result is only returned if the query returns no result at all or the page size is set to zero. By automatically returning the first page result when the requested page is exceeded, we try to avoid the need to issue a secondary request to fetch the data.
The information about the actual returned page and data statistics can be found in the query response, which is wrapped in a so-called data chunk object.
In case of the page constraint, the
is used as data chunk object.
The data chunk object contains the following information:
pageNumber

the number of the page returned in the query response

pageSize

the size of the page returned in the query response

lastPageNumber
the last page number available for the query, the request for lastPageNumber + 1 returns the first page
firstPageItemNumber

the offset of the first record of current page with current page size

lastPageItemNumber

the offset of the last record of current page with current page size

first
TRUE if the current page is the first page available
last
TRUE if the current page is the last page available
hasNext
TRUE if there is a data for the next page available (i.e. pageNumber + 1 <= lastPageNumber)
hasPrevious
TRUE if the current page is the last page available (i.e. pageNumber - 1 > 0)
empty
TRUE if the query returned no data at all (i.e. totalRecordCount == 0)
singlePage
TRUE if the query returned exactly one page of data (i.e. pageNumber == 1 && lastPageNumber == 1 && totalRecordCount > 0)
totalRecordCount

the total number of entities available for the query

data

the list of entities returned in the query response

The
page requirement
is the most natural and commonly used requirement for the pagination of the query results. To get the second page of the query result, use the following query:

The result contains the result from the 6th through the 10th record of the query result. It returns only a primary key of the records because no content request was specified, and it is sorted by the primary key in ascending order because no order was specified in the query.

Strip

argument:int

a mandatory offset of the first record of the page to be returned, positive integer starting from 0

argument:int

a mandatory limit of the records to be returned, positive integer

The strip
()
controls the number and slice of entities returned in the query response. If the requested strip exceeds the number of available records, a result from the zero offset with retained limit is returned. An empty result is only returned if the query returns no result at all or the limit is set to zero. By automatically returning the first strip result when the requested page is exceeded, we try to avoid the need to issue a secondary request to fetch the data.
The information about the actual returned page and data statistics can be found in the query response, which is wrapped in a so-called data chunk object.
In case of the strip constraint, the
is used as data chunk object.
The data chunk object contains the following information:
offset

the offset of the first record returned in the query response

limit

the limit of the records returned in the query response

first
TRUE if the current strip starts with the first records of the query result
last
TRUE if the current strip ends with the last records of the query result
hasNext
TRUE if there is a data for the next next available (i.e. last == false)
hasPrevious
TRUE if the current page is the last page available (i.e. first == false)
empty
TRUE if the query returned no data at all (i.e. totalRecordCount == 0)
totalRecordCount

the total number of entities available for the query

data

the list of entities returned in the query response

The strip requirement can be used to list query records in a non-uniform way - for example, when the entity listing is interleaved with an advertisement that requires an entity rendering to be skipped at certain positions. In other words, if you know that there is an "advertisement" block every 20 records, which means that the entity must be skipped for that position, and you want to correctly fetch records for the 5th page, you need to request a strip with offset 76 (4 pages * 20 positions per page - 4 records omitted on the previous 4 pages) and limit 19. To get such a strip, use the following query:

The result contains the result from the 76th through the 95th record of the query result. It returns only a primary key of the records because no content request was specified, and it is sorted by the primary key in ascending order because no order was specified in the query.

Author: Ing. Jan Novotný

Date updated: 23.7.2023

Documentation Source