Package org.apache.cassandra.service.pager

Interface QueryPager

All Known Implementing Classes:

AggregationQueryPager, MultiPartitionPager, PartitionRangeQueryPager, SinglePartitionPager

public interface QueryPager

Perform a query, paging it by page of a given size. This is essentially an iterator of pages. Each call to fetchPage() will return the next page (i.e. the next list of rows) and isExhausted() indicates whether there is more page to fetch. The pageSize will either be in term of cells or in term of CQL3 row, depending on the parameters of the command we page. Please note that the pager might page within rows, so there is no guarantee that successive pages won't return the same row (though with different columns every time). Also, there is no guarantee that fetchPage() won't return an empty list, even if isExhausted() return false (but it is guaranteed to return an empty list *if* isExhausted() return true). Indeed, isExhausted() does *not* trigger a query so in some (fairly rare) case we might not know the paging is done even though it is.

Field Summary

Fields

Modifier and Type	Field	Description
static QueryPager	EMPTY

Method Summary

Modifier and Type	Method	Description
ReadExecutionController	executionController()	Starts a new read operation.
PartitionIterator	fetchPage(int pageSize, ConsistencyLevel consistency, ClientState clientState, Dispatcher.RequestTime requestTime)	Fetches the next page.
PartitionIterator	fetchPageInternal(int pageSize, ReadExecutionController executionController)	Fetches the next page internally (in other, this does a local query).
boolean	isExhausted()	Whether or not this pager is exhausted, i.e.
default boolean	isTopK()
int	maxRemaining()	The maximum number of cells/CQL3 row that we may still have to return.
PagingState	state()	Get the current state of the pager.
QueryPager	withUpdatedLimit(DataLimits newLimits)	Creates a new QueryPager that use the new limits.

Field Detail

EMPTY

static final QueryPager EMPTY

Method Detail

fetchPage

PartitionIterator fetchPage(int pageSize,
                            ConsistencyLevel consistency,
                            ClientState clientState,
                            Dispatcher.RequestTime requestTime)
                     throws RequestValidationException,
                            RequestExecutionException

Fetches the next page.

Parameters:

pageSize - the maximum number of elements to return in the next page.

consistency - the consistency level to achieve for the query.

clientState - the ClientState for the query. In practice, this can be null unless consistency is a serial consistency.

Returns:

the page of result.

Throws:

RequestValidationException

RequestExecutionException

executionController

ReadExecutionController executionController()

Starts a new read operation.

This must be called before fetchPageInternal(int,org.apache.cassandra.db.ReadExecutionController) and passed to it to protect the read. The returned object must be closed on all path and it is thus strongly advised to use it in a try-with-ressource construction.

Returns:

a newly started order group for this QueryPager.

fetchPageInternal

PartitionIterator fetchPageInternal(int pageSize,
                                    ReadExecutionController executionController)
                             throws RequestValidationException,
                                    RequestExecutionException

Fetches the next page internally (in other, this does a local query).

Parameters:

pageSize - the maximum number of elements to return in the next page.

executionController - the ReadExecutionController protecting the read.

Returns:

the page of result.

Throws:

RequestValidationException

RequestExecutionException

isExhausted

boolean isExhausted()

Whether or not this pager is exhausted, i.e. whether or not a call to fetchPage may return more result.

Returns:

whether the pager is exhausted.

maxRemaining

int maxRemaining()

The maximum number of cells/CQL3 row that we may still have to return. In other words, that's the initial user limit minus what we've already returned (note that it's not how many we *will* return, just the upper limit on it).

state

PagingState state()

Get the current state of the pager. The state can allow to restart the paging on another host from where we are at this point.

Returns:

the current paging state. Will return null if paging is at the beginning. If the pager is exhausted, the result is undefined.

withUpdatedLimit

QueryPager withUpdatedLimit(DataLimits newLimits)

Creates a new QueryPager that use the new limits.

Parameters:

newLimits - the new limits

Returns:

a new QueryPager that use the new limits

isTopK

default boolean isTopK()

Returns:

true given read query is a top-k request