public interface PagingIterable<ElementT> extends Iterable<ElementT>
It uses asynchronous calls internally, but blocks on the results in order to provide a synchronous API to its clients. If the query is paged, only the first page will be fetched initially, and iteration will trigger background fetches of the next pages when necessary.
Note that this object can only be iterated once: elements are "consumed" as they are read,
subsequent calls to
iterator() will return the same iterator instance.
Implementations of this type are not thread-safe. They can only be iterated by the
thread that invoked
This is a generalization of
ResultSet, replacing rows by an arbitrary element type.
|Modifier and Type||Method and Description|
Returns all the remaining elements as a list; not recommended for queries that return a large number of elements.
The number of elements that can be returned from this result set before a blocking background query needs to be performed to retrieve more results.
Metadata about the columns returned by the CQL request that was used to build this result.
The execution information for the last query performed for this iterable.
The execution information for all the queries that have been performed so far to assemble this iterable.
Whether all pages have been fetched from the database.
Creates a new instance by transforming each element of this iterable with the provided function.
Returns the next element, or
If the query that produced this result was a CQL conditional update, indicate whether it was successfully applied.
@NonNull ColumnDefinitions getColumnDefinitions()
@NonNull default ExecutionInfo getExecutionInfo()
This is a shortcut for:
getExecutionInfos().get(getExecutionInfos().size() - 1)
@NonNull List<ExecutionInfo> getExecutionInfos()
This will have multiple elements if the query is paged, since the driver performs blocking background queries to fetch additional pages transparently as the result set is being iterated.
@Nullable default ElementT one()
nullif the iterable is exhausted.
This is convenient for queries that are known to return exactly one row, for example count queries.
@NonNull default List<ElementT> all()
Iterable.iterator() or successive calls to
one(), this method forces
fetching the full contents at once; in particular, this means that a large number of
background queries might have to be run, and that all the data will be held in memory locally.
Therefore it is crucial to only call this method for queries that are known to return a
reasonable number of results.
If this is
false, it means that more blocking background queries will be triggered
as iteration continues.
This is useful if you use the paging state to pause the iteration and resume it later: after
you've retrieved the state (
getExecutionInfo().getPagingState()), call this method and iterate the remaining elements;
that way you're not leaving a gap between the last element and the position you'll restart from
when you reinject the state in a new query.
For consistency, this method always returns
true for non-conditional queries
(although there is no reason to call the method in that case). This is also the case for
conditional DDL statements (
CREATE KEYSPACE... IF NOT EXISTS,
CREATE TABLE... IF
NOT EXISTS), for which Cassandra doesn't return an
Note that, for versions of Cassandra strictly lower than 2.1.0-rc2, a server-side bug (CASSANDRA-7337) causes this
method to always return
true for batches containing conditional queries.
@NonNull default <TargetElementT> PagingIterable<TargetElementT> map(Function<? super ElementT,? extends TargetElementT> elementMapper)
Note that both instances share the same underlying data: consuming elements from the transformed iterable will also consume them from this object, and vice-versa.
@NonNull default Spliterator<ElementT> spliterator()
Default spliterators created by the driver will report the following characteristics:
result sets will also report
the result set size is known.
This method should be called at most once. Spliterators share the same underlying data but
do not support concurrent consumption; once a spliterator for this iterable is obtained, the
iterable should not be consumed through calls to other methods such as
all(); doing so will result in unpredictable results.
Copyright © 2017–2023. All rights reserved.