Documentation

Strategy for the execution of PrepQuerys.

Retry settings control if and how retries are performed by the client upon encountering errors during query execution.

There are three aspects to the retry settings:

1. What to retry. Determined by the retry handlers (setRetryHandlers).
2. How to perform the retries. Determined by the retry policy (setRetryPolicy).
3. Configuration adjustments to be performed before retrying. Determined by adjustConsistency, adjustSendTimeout and adjustResponseTimeout. These adjustments are performed once before the first retry and are scoped to the retries only.

Retry settings can be scoped to a client action by retry, thus locally overriding the "global" retry settings configured by setRetrySettings.

Default settings:

• The initial contact point is "localhost" on port 9042.
• The load-balancing policy is random.
• The binary protocol version is 3.
• The connection idle timeout is 60s.
• The connection pool uses 4 stripes to mitigate thread contention.
• Connections use a connect timeout of 5s, a send timeout of 3s and a receive timeout of 10s.
• 128 streams per connection are used.
• 16k receive buffer size.
• No compression is applied to frame bodies.
• No default keyspace is used.
• A single, immediate retry is performed for errors that are always safe to retry and are known to have good chances of succeeding on a retry. See defRetrySettings.
• Query preparation is done lazily. See PrepareStrategy.

Set the binary protocol version to use.

Set the initial contact points (hosts) from which node discovery will start.

Add an additional host to the contact list.

Set the portnumber to use to connect on every node of the cluster.

Set the load-balancing policy.

Set strategy to use for preparing statements.

Set the Logger to use for processing log messages emitted by the client.

Set the connection idle timeout. Connections in a pool will be closed if not in use for longer than this timeout.

Maximum connections per pool stripe.

Set the number of pool stripes to use. A good setting is equal to the number of CPU cores this codes is running on.

When receiving a response times out, we can no longer use the stream of the connection that was used to make the request as it is uncertain if a response will arrive later. Thus the bandwith of a connection will be decreased. This settings defines a threshold after which we close the connection to get a new one with all streams available.

Set the compression to use for frame body compression.

Set the maximum number of streams per connection. In version 2 of the binary protocol at most 128 streams can be used. Version 3 supports up to 32768 streams.

Set the connect timeout of a connection.

Set the send timeout of a connection. Requests exceeding the send timeout will cause the connection to be closed and fail with a ConnectionClosed exception.

Set the response timeout of a connection. Requests exceeding the response timeout will fail with a ResponseTimeout exception.

Set the default keyspace to use. Every new connection will be initialised to use this keyspace.

Set the retry settings to use.

Set maximum receive buffer size.

The actual buffer size used will be the minimum of the CQL response size and the value set here.

Set a fully configured SSL context.

This will make client server queries use TLS.

Set the supported authentication mechanisms.

When a Cassandra server requests authentication on a connection, it specifies the requested AuthMechanism. The client Authenticator is chosen based that name. If no authenticator with a matching name is configured, an AuthenticationError is thrown.

Never retry.

Default retry settings, combining defRetryHandlers with defRetryPolicy. Consistency is never reduced on retries and timeout values remain unchanged.

Eager retry settings, combining eagerRetryHandlers with eagerRetryPolicy. Consistency is never reduced on retries and timeout values remain unchanged.

The default retry policy permits a single, immediate retry.

The eager retry policy permits 5 retries with exponential backoff (base-2) with an initial delay of 100ms, i.e. the retries will be performed with 100ms, 200ms, 400ms, 800ms and 1.6s delay, respectively, for a maximum delay of ~3s.

The default retry handlers permit a retry for the following errors:

• A HostError, since it always occurs before a query has been sent to the server.
• A ConnectionError that is a ConnectTimeout, since it always occurs before a query has been sent to the server.

• A ResponseError that is one of the following:

  • Unavailable, since that is an error response from a coordinator before the query is actually executed.
  • A ReadTimeout that indicates that the required consistency level could be achieved but the data was unfortunately chosen by the coordinator to be returned from a replica that turned out to be unavailable. A retry has a good chance of getting the data from one of the other replicas.
  • A WriteTimeout for a write to the batch log failed. The batch log is written prior to execution of the statements of the batch and hence these errors are safe to retry.

The eager retry handlers permit a superset of the errors of defRetryHandlers, namely:

• Any ResponseError that is a ReadTimeout, WriteTimeout, Overloaded, Unavailable or ServerError.
• Any ConnectionError.
• Any IOException.
• Any HostError.
• Any SomeSSLException (if an SSL context is configured).

Notably, these retry handlers are only safe to use for idempotent queries, or if a duplicate write has no severe consequences in the context of the application's data model.

Set the RetryPolicy to apply on retryable exceptions, which determines the number and distribution of retries over time, i.e. how retries are performed. Configuring a retry policy does not specify what errors should actually be retried. See setRetryHandlers.

Set the exception handlers that decide whether a request can be retried by the client, i.e. what errors are permissible to retry. For configuring how the retries are performed, see setRetryPolicy.

On retry, change the consistency to the given value.

On retry adjust the send timeout. See setSendTimeout.

On retry adjust the response timeout. See setResponseTimeout.