com.datastax.driver.core

Interface ResultSet

All Superinterfaces:

Iterable<Row>

public interface ResultSet
extends Iterable<Row>

The result of a query.

The retrieval of the rows of a ResultSet is generally paged (a first page of result is fetched and the next one is only fetched once all the results of the first one has been consumed). The size of the pages can be configured either globally through QueryOptions.setFetchSize(int) or per-statement with Statement.setFetchSize(int). Though new pages are automatically (and transparently) fetched when needed, it is possible to force the retrieval of the next page early through fetchMoreResults(). Please note however that this ResultSet paging is not available with the version 1 of the native protocol (i.e. with Cassandra 1.2 or if version 1 has been explicitly requested through Cluster.Builder.withProtocolVersion(com.datastax.driver.core.ProtocolVersion)). If the protocol version 1 is in use, a ResultSet is always fetched in it's entirely and it's up to the client to make sure that no query can yield ResultSet that won't hold in memory.

Note that this class is not thread-safe.

Method Summary

Methods

Modifier and Type	Method and Description
List<Row>	all() Returns all the remaining rows in this ResultSet as a list.
com.google.common.util.concurrent.ListenableFuture<Void>	fetchMoreResults() Force fetching the next page of results for this result set, if any.
List<ExecutionInfo>	getAllExecutionInfo() Return the execution information for all queries made to retrieve this ResultSet.
int	getAvailableWithoutFetching() The number of rows that can be retrieved from this result set without blocking to fetch.
ColumnDefinitions	getColumnDefinitions() Returns the columns returned in this ResultSet.
ExecutionInfo	getExecutionInfo() Returns information on the execution of the last query made for this ResultSet.
boolean	isExhausted() Returns whether this ResultSet has more results.
boolean	isFullyFetched() Whether all results from this result set have been fetched from the database.
Iterator<Row>	iterator() Returns an iterator over the rows contained in this ResultSet.
Row	one() Returns the next result from this ResultSet.
boolean	wasApplied() If the query that produced this ResultSet was a conditional update, return whether it was successfully applied.

Method Detail

getColumnDefinitions

ColumnDefinitions getColumnDefinitions()

Returns the columns returned in this ResultSet.

Returns:

the columns returned in this ResultSet.

isExhausted

boolean isExhausted()

Returns whether this ResultSet has more results.

Returns:

whether this ResultSet has more results.

one

Row one()

Returns the next result from this ResultSet.

Returns:

the next row in this resultSet or null if this ResultSet is exhausted.

all

List<Row> all()

Returns all the remaining rows in this ResultSet as a list.

Note that, contrary to iterator() or successive calls to one(), this method forces fetching the full content of the ResultSet at once, holding it all in memory in particular. It is thus recommended to prefer iterations through iterator() when possible, especially if the ResultSet can be big.

Returns:

a list containing the remaining results of this ResultSet. The returned list is empty if and only the ResultSet is exhausted. The ResultSet will be exhausted after a call to this method.

iterator

Iterator<Row> iterator()

Returns an iterator over the rows contained in this ResultSet. The Iterator.next() method is equivalent to calling one(). So this iterator will consume results from this ResultSet and after a full iteration, the ResultSet will be empty. The returned iterator does not support the Iterator.remove() method.

Specified by:

iterator in interface Iterable<Row>

Returns:

an iterator that will consume and return the remaining rows of this ResultSet.

getAvailableWithoutFetching

int getAvailableWithoutFetching()

The number of rows that can be retrieved from this result set without blocking to fetch.

Returns:

the number of rows readily available in this result set. If isFullyFetched(), this is the total number of rows remaining in this result set (after which the result set will be exhausted).

isFullyFetched

boolean isFullyFetched()

Whether all results from this result set have been fetched from the database.

Note that if isFullyFetched(), then getAvailableWithoutFetching() will return how many rows remain in the result set before exhaustion. But please note that !isFullyFetched() never guarantees that the result set is not exhausted (you should call isExhausted() to verify it).

Returns:

whether all results have been fetched.

fetchMoreResults

com.google.common.util.concurrent.ListenableFuture<Void> fetchMoreResults()

Force fetching the next page of results for this result set, if any.

This method is entirely optional. It will be called automatically while the result set is consumed (through one(), all() or iteration) when needed (i.e. when getAvailableWithoutFetching() == 0 and isFullyFetched() == false).

You can however call this method manually to force the fetching of the next page of results. This can allow to prefetch results before they are strictly needed. For instance, if you want to prefetch the next page of results as soon as there is less than 100 rows readily available in this result set, you can do:

   ResultSet rs = session.execute(...);
   Iterator<Row> iter = rs.iterator();
   while (iter.hasNext()) {
       if (rs.getAvailableWithoutFetching() == 100 && !rs.isFullyFetched())
           rs.fetchMoreResults();
       Row row = iter.next()
       ... process the row ...
   }
 

This method is not blocking, so in the example above, the call to fetchMoreResults will not block the processing of the 100 currently available rows (but iter.hasNext() will block once those rows have been processed until the fetch query returns, if it hasn't yet).

Only one page of results (for a given result set) can be fetched at any given time. If this method is called twice and the query triggered by the first call has not returned yet when the second one is performed, then the 2nd call will simply return a future on the currently in progress query.

Returns:

a future on the completion of fetching the next page of results. If the result set is already fully retrieved (isFullyFetched() == true), then the returned future will return immediately but not particular error will be thrown (you should thus call isFullyFetched() to know if calling this method can be of any use).

getExecutionInfo

ExecutionInfo getExecutionInfo()

Returns information on the execution of the last query made for this ResultSet.

Note that in most cases, a ResultSet is fetched with only one query, but large result sets can be paged and thus be retrieved by multiple queries. In that case this method return the ExecutionInfo for the last query performed. To retrieve the information for all queries, use getAllExecutionInfo().

The returned object includes basic information such as the queried hosts, but also the Cassandra query trace if tracing was enabled for the query.

Returns:

the execution info for the last query made for this ResultSet.

getAllExecutionInfo

List<ExecutionInfo> getAllExecutionInfo()

Return the execution information for all queries made to retrieve this ResultSet.

Unless the ResultSet is large enough to get paged underneath, the returned list will be singleton. If paging has been used however, the returned list contains the ExecutionInfo for all the queries done to obtain this ResultSet (at the time of the call) in the order those queries were made.

Returns:

a list of the execution info for all the queries made for this ResultSet.

wasApplied

boolean wasApplied()

If the query that produced this ResultSet was a conditional update, return whether it was successfully applied.

This is equivalent to calling:

 rs.one().getBool("[applied]");
 

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 [applied] column.

Note that, for versions of Cassandra strictly lower than 2.0.9 and 2.1.0-rc2, a server-side bug (CASSANDRA-7337) causes this method to always return true for batches containing conditional queries.

Returns:

if the query was a conditional update, whether it was applied. true for other types of queries.

See Also:

CASSANDRA-7337