com.datastax.dse.driver.api.core.cql.continuous

Interface ContinuousSession

All Superinterfaces:

com.datastax.oss.driver.api.core.AsyncAutoCloseable, AutoCloseable, com.datastax.oss.driver.api.core.session.Session

All Known Subinterfaces:

DseSession

public interface ContinuousSession
extends com.datastax.oss.driver.api.core.session.Session

A session that has the ability to execute continuous paging queries.

Continuous paging is a new method of streaming bulk amounts of records from Datastax Enterprise (DSE) to the Datastax Java Driver, available since DSE 5.1. It is mainly intended to be leveraged by DSE Analytics and Apache Spark™, or by any similar analytics tool that needs to read large portions of a table in one single operation, as quick and reliably as possible.

Continuous paging requires the following three conditions to be met on the client side:

1. The statement must target a single partition or a token range owned by one single replica; in practice, this means that the statement must have either a routing key or a routing token set;
2. The coordinator must be a replica; in practice, this is usually achieved by using token-aware routing (if you are using the driver's default LoadBalancingPolicy, then this condition is met);
3. The consistency level must be ONE (or LOCAL_ONE).

It's the caller's responsibility to make sure that the above conditions are met. If this is not the case, continuous paging will silently degrade into a normal read operation, and the coordinator will retrieve pages one by one from replicas.

Note that when the continuous paging optimization kicks in (range read at ONE performed directly on a replica), the snitch is bypassed and the coordinator will always chose itself as a replica. Therefore, other functionality such as probabilistic read repair and speculative retry is also not available when contacting a replica at ONE.

Continuous paging is disabled by default and needs to be activated server-side. See Enabling continuous paging in the DSE docs to learn how to enable it.

See Also:

DSE Continuous Paging Tuning and Support Guide

Field Summary

Fields inherited from interface com.datastax.oss.driver.api.core.session.Session

OSS_DRIVER_COORDINATES

Method Summary

Modifier and Type	Method and Description
default ContinuousResultSet	executeContinuously(com.datastax.oss.driver.api.core.cql.Statement<?> statement) Executes the provided query with continuous paging synchronously.
default CompletionStage<ContinuousAsyncResultSet>	executeContinuouslyAsync(com.datastax.oss.driver.api.core.cql.Statement<?> statement) Executes the provided query with continuous paging asynchronously.

Methods inherited from interface com.datastax.oss.driver.api.core.session.Session

checkSchemaAgreement, checkSchemaAgreementAsync, execute, getContext, getKeyspace, getMetadata, getMetrics, getName, isSchemaMetadataEnabled, refreshSchema, refreshSchemaAsync, setSchemaMetadataEnabled

Methods inherited from interface com.datastax.oss.driver.api.core.AsyncAutoCloseable

close, closeAsync, closeFuture, forceCloseAsync, isClosed

Method Detail

executeContinuously

@NonNull
default ContinuousResultSet executeContinuously(@NonNull
                                                         com.datastax.oss.driver.api.core.cql.Statement<?> statement)

Executes the provided query with continuous paging synchronously.

This method takes care of chaining the successive results into a convenient iterable, provided that you always access the result from the same thread. For more flexibility, consider using the asynchronous variant of this method instead.

Parameters:

statement - the query to execute.

Returns:

a synchronous iterable on the results.

executeContinuouslyAsync

@NonNull
default CompletionStage<ContinuousAsyncResultSet> executeContinuouslyAsync(@NonNull
                                                                                    com.datastax.oss.driver.api.core.cql.Statement<?> statement)

Executes the provided query with continuous paging asynchronously.

The server will push all requested pages asynchronously, according to the options defined in the current execution profile. The client should consume all pages as quickly as possible, to avoid blocking the server for too long. The server will adjust the rate according to the client speed, but it will give up if the client does not consume any pages in a period of time equal to the read request timeout.

Parameters:

statement - the query to execute.

Returns:

a future to the first asynchronous result.