com.datastax.oss.driver.api.core.paging

Class OffsetPager

java.lang.Object

com.datastax.oss.driver.api.core.paging.OffsetPager

@ThreadSafe
public class OffsetPager
extends Object

A utility to emulate offset queries on the client side (this comes with important performance trade-offs, make sure you read and understand the whole javadocs before using this class).

Web UIs and services often provide paginated results with random access, for example: given a page size of 20 elements, fetch page 5. Cassandra does not support this natively (see CASSANDRA-6511), because such queries are inherently linear: the database would have to restart from the beginning every time, and skip unwanted rows until it reaches the desired offset.

However, random pagination is a real need for many applications, and linear performance can be a reasonable trade-off if the cardinality stays low. This class provides a way to emulate this behavior on the client side.

Performance considerations

For each page that you want to retrieve:

• you need to re-execute the query, in order to start with a fresh result set;
• this class starts iterating from the beginning, and skips rows until it reaches the desired offset.

 String query = "SELECT ...";
 OffsetPager pager = new OffsetPager(20);

 // Get page 2: start from a fresh result set, throw away rows 1-20, then return rows 21-40
 ResultSet rs = session.execute(query);
 OffsetPager.Page<Row> page2 = pager.getPage(rs, 2);

 // Get page 5: start from a fresh result set, throw away rows 1-80, then return rows 81-100
 rs = session.execute(query);
 OffsetPager.Page<Row> page5 = pager.getPage(rs, 5);
 

Establishing application-level guardrails

Linear performance should be fine for the values typically encountered in real-world applications: for example, if the page size is 25 and users never go past page 10, the worst case is only 250 rows, which is a very small result set. However, we strongly recommend that you implement hard limits in your application code: if the page number is exposed to the user (for example if it is passed as a URL parameter), make sure it is properly validated and enforce a maximum, so that an attacker can't inject a large value that could potentially fetch millions of rows.

Relation with protocol-level paging

Protocol-level paging refers to the ability to split large response into multiple network chunks: see Statement.setPageSize(int) and basic.request.page-size in the configuration. It happens under the hood, and is completely transparent for offset paging: this class will work the same no matter how many network roundtrips were needed to fetch the result. You don't need to set the protocol page size and the logical page size to the same value.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	OffsetPager.Page<ElementT> A page returned as the result of an offset query.

Constructor Summary

Constructors

Constructor and Description
OffsetPager(int pageSize) Creates a new instance.

Method Summary

Modifier and Type	Method and Description
<ElementT,IterableT extends AsyncPagingIterable<ElementT,IterableT>> CompletionStage<OffsetPager.Page<ElementT>>	getPage(IterableT iterable, int targetPageNumber) Extracts a page from an asynchronous result set, by skipping rows until we get to the requested offset.
<ElementT> OffsetPager.Page<ElementT>	getPage(PagingIterable<ElementT> iterable, int targetPageNumber) Extracts a page from a synchronous result set, by skipping rows until we get to the requested offset.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

OffsetPager

public OffsetPager(int pageSize)

Creates a new instance.

Parameters:

pageSize - the number of elements per page. Must be greater than or equal to 1.

Method Detail

getPage

@NonNull
public <ElementT> OffsetPager.Page<ElementT> getPage(@NonNull
                                                              PagingIterable<ElementT> iterable,
                                                              int targetPageNumber)

Extracts a page from a synchronous result set, by skipping rows until we get to the requested offset.

Parameters:

iterable - the iterable to extract the results from: typically a ResultSet, or a PagingIterable returned by the mapper.

targetPageNumber - the page to return (1 for the first page, 2 for the second page, etc). Must be greater than or equal to 1.

Returns:

the requested page, or the last page if the requested page was past the end of the iterable.

Throws:

IllegalArgumentException - if the conditions on the arguments are not respected.

getPage

@NonNull
public <ElementT,IterableT extends AsyncPagingIterable<ElementT,IterableT>> CompletionStage<OffsetPager.Page<ElementT>> getPage(@NonNull
                                                                                                                                         IterableT iterable,
                                                                                                                                         int targetPageNumber)

Extracts a page from an asynchronous result set, by skipping rows until we get to the requested offset.

Parameters:

iterable - the iterable to extract the results from. Typically an AsyncPagingIterable, or a MappedAsyncPagingIterable returned by the mapper.

targetPageNumber - the page to return (1 for the first page, 2 for the second page, etc). Must be greater than or equal to 1.

Returns:

a stage that will complete with the requested page, or the last page if the requested page was past the end of the iterable.

Throws:

IllegalArgumentException - if the conditions on the arguments are not respected.