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

requireConstraint:spacing?
an optional constraint that specifies rules for leaving spaces on certain pages of the query result (see spacing constraint chapter for more details)
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.

Spacing

requireConstraint:gap+

one or more constraints that specify rules for leaving spaces on certain pages of the query result

The spacing requirement is a container for one or more gap constraints that specify rules for leaving spaces on particular pages of the query result. It modifies the default behavior of the page constraint, reducing the number of records returned on certain pages. It also affects the number of pages (the lastPageNumber property of the
). The gap rules are additive, and the gap sizes are the sum of all gap rules that apply to the given page.
To avoid having to recalculate the rule for every page in the result set, you can limit the scope by adding a constant expression to the rule. For example, the rule $pageNumber % 2 == 0 && $pageNumber <= 10 will only be recalculated for the first 10 pages of the query result, because the interpreter knows that the rule will never be satisfied for the remaining pages.

Spacing constraints are useful when you need to make room for additional content on certain pages of the query result, such as advertisements, banners, blog posts, or other external content that you want to display between records. For example, let's say you want to display an ad on every even page up to the 10th page, and you also want to display a blog post on the 1st and 4th page. To accomplish this, you would use the following query:

The first page contains 9 records (one slot left for the blog post), the second page contains 9 records (one slot left for the advertisement, because the page number is even), and the fourth page contains only 8 records (one slot left for the blog post and one slot left for the advertisement, because the page number is even), the last page number is recalculated because a total of 7 records were left on the front pages.

First page:
Second page:
Fourth page:

Gap

argument:int

a mandatory number specifying the size of the gap to leave empty on the page (i.e., the number of records to skip on the page)

argument:expression
a mandatory expression that must be evaluated to a boolean value, indicating whether the gap should be applied to the given page or not.
The gap requirement specifies a single rule for leaving a gap of a given size on a given page, identified by the expression for each page. Detailed usage is documented in the spacing constraint chapter.
The expression can use the following variables:
variableName: pageNumber of type: int

the number of the page to be evaluated

Author: Ing. Jan Novotný

Date updated: 23.7.2023

Documentation Source