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.

Add an additional host to the contact list.

Set the compression to use for frame body compression.

Set the connect timeout of a connection.

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

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

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

Maximum connections per pool stripe.

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.

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 load-balancing policy.

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

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

Strategy for the execution of PrepQuerys.

Set strategy to use for preparing statements.

Set the binary protocol version to use.

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

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 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.

A Logger provides functions for logging textual messages as well as binary CQL protocol requests and responses emitted by the client.

Log levels used by the client.

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

A logger that discards all log messages.

A logger that writes all log messages to stdout, discarding log messages whose level is less than the given level. Requests and responses are logged on debug level, formatted in hexadecimal blocks.

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.

A client authentication handler.

The fields of an Authenticator must implement the client-side of an (SASL) authentication mechanism as follows:

• When a Cassandra server requests authentication on a new connection, authOnRequest is called with the AuthContext of the connection.
• If additional challenges are posed by the server, authOnChallenge is called, if available, otherwise an AuthenticationError is thrown, i.e. every challenge must be answered.
• Upon successful authentication authOnSuccess is called.

The existential type s is chosen by an implementation and can be used to thread arbitrary state through the sequence of callback invocations during an authentication exchange.

See also: RFC4422 Authentication

Context information given to Authenticators when the server requests authentication on a connection. See authOnRequest.

The (unique) name of a SASL authentication mechanism.

In the case of Cassandra, this is currently always the fully-qualified Java class name of the configured server-side IAuthenticator implementation.

A password authentication handler for use with Cassandra's PasswordAuthenticator.

See: Configuring Authentication

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.

Never retry.

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

The default retry policy permits a single, immediate retry.

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.

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

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 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.

A policy defines a load-balancing strategy and generally handles host visibility.

Return hosts in random order.

Iterate over hosts one by one.

A Cassandra host known to the client.

This event will be passed to a Policy to inform it about cluster changes.

The IP address and port number of a host.

The data centre name (may be an empty string).

The rack name (may be an empty string).

The Client monad.

A simple reader monad on IO around some internal state. Prior to executing this monad via runClient, its state must be initialised through init and after finishing operation it should be terminated with shutdown.

To lift Client actions into another monad, see MonadClient.

Monads in which Client actions may be embedded.

Opaque client state/environment.

Initialise client state with the given Settings using the provided Logger for all it's logging output.

Execute the client monad.

Terminate client state, i.e. end all running background checks and shutdown all connection pools. Once this is entered, the client will eventually be shut down, though an asynchronous exception can interrupt the wait for that to occur.

Type tag for read queries, i.e. 'QueryString R a b'.

Type tag for write queries, i.e. 'QueryString W a b'.

Type tag for schema queries, i.e. 'QueryString S a b'.

Query parameters.

Construct default QueryParams for the given consistency and bound values. In particular, no page size, paging state or serial consistency will be set.

Consistency level.

See: Consistency

Consistency level for the serial phase of conditional updates (aka "lightweight transactions").

See: SerialConsistency

Identity functor and monad. (a non-strict monad)

Since: base-4.8.0.0

Run a CQL read-only query returning a list of results.

Run a CQL read-only query returning a single result.

Run a CQL write-only query (e.g. insert/update/delete), returning no result.

/Note: If the write operation is conditional, i.e. is in fact a "lightweight transaction" returning a result, trans must be used instead./

Run a CQL schema query, returning SchemaChange information, if any.

Representation of a prepared QueryString. A prepared query is executed in two stages:

1. The query string is sent to a server without parameters for preparation. The server responds with a QueryId.
2. The prepared query is executed by sending the QueryId and parameters to the server.

Thereby step 1 is only performed when the query has not yet been prepared with the host (coordinator) used for query execution. Thus, prepared queries enhance performance by avoiding the repeated sending and parsing of query strings.

Query preparation is handled transparently by the client. See setPrepareStrategy.

Note

Prepared statements are fully supported but rely on some assumptions beyond the scope of the CQL binary protocol specification (spec):

1. The spec scopes the QueryId to the node the query has been prepared with. The spec does not state anything about the format of the QueryId. However the official Java driver assumes that any given QueryString yields the same QueryId on every node. This client make the same assumption.
2. In case a node does not know a given QueryId an Unprepared error is returned. We assume that it is always safe to transparently re-prepare the corresponding QueryString and to re-execute the original request against the same node.

Besides these assumptions there is also a potential tradeoff in regards to eager vs. lazy query preparation. We understand eager to mean preparation against all current nodes of a cluster and lazy to mean preparation against a single node on demand, i.e. upon receiving an Unprepared error response. Which strategy to choose depends on the scope of query reuse and the size of the cluster. The global default can be changed through the Settings module as well as locally using withPrepareStrategy.

Return value of paginate. Contains the actual result values as well as an indication of whether there is more data available and the actual action to fetch the next page.

A page with an empty result list.

Run a CQL read-only query against a Cassandra node.

This function is like query, but limits the result size to 10000 (default) unless there is an explicit size restriction given in QueryParams. The returned Page can be used to continue the query.

Please note that -- as of Cassandra 2.1.0 -- if your requested page size is equal to the result size, hasMore might be true and a subsequent nextPage will return an empty list in result.

A row is a vector of Values.

Convert a row element.

Run a CQL conditional write query (e.g. insert/update/delete) as a "lightweight transaction", returning the result Rows describing the outcome.

Batch construction monad.

Add a query to this batch.

Add a prepared query to this batch.

Set the type of this batch.

Set Batch consistency level.

Set Batch serial consistency.

Run a batch query against a Cassandra node.

Use given RetrySettings during execution of some client action.

Execute a client action once, without retries, i.e.

once action = retry noRetry action.

Primarily for use in applications where global RetrySettings are configured and need to be selectively disabled for individual queries.

A type which can be run as a query.

A response that is known to originate from a specific Host.

Send a Request to the server and return a Response.

This function will first ask the clients load-balancing Policy for some host and use its connection pool to acquire a connection for request transmission.

If all available hosts are busy (i.e. their connection pools are fully utilised), the function will block until a connection becomes available or the maximum wait-queue length has been reached.

The request is retried according to the configured RetrySettings.

Get the Result out of a HostResponse. If the response is an RsError, a ResponseError is thrown. If the response is neither RsResult nor RsError, an UnexpectedResponse is thrown.

A protocol error indicates a problem related to the client-server communication protocol. The cause may either be misconfiguration on the client or server, or an implementation bug. In the latter case it should be reported. In either case these errors are not recoverable and should never be retried.

An error during host selection prior to query execution.

These errors are always safe to retry but may indicate an overload situation and thus suggest a review of the client and cluster configuration (number of hosts, pool sizes, connections per host, streams per connection, ...).

An error while establishing or using a connection to send a request or receive a response.

The server responded with an Error.

Most of these errors are either not retryable or only safe to retry for idempotent queries. For more details of which errors may be safely retried under which circumstances, see also the documentation of the Java driver.

An error occurred during the authentication phase while initialising a new connection. This indicates a configuration error or a faulty Authenticator.

An unexpected hash collision occurred for a prepared query string. This indicates a problem with the implementation of prepared queries and should be reported.