Cassandra Namespace

Represents a prepared statement with the parameter values set, ready for execution.

• Cassandra binary protocol level configuration (compression).
• Connection pooling configurations.
• low-level tcp configuration options (tcpNoDelay, keepAlive, ...).

This policy provides round-robin queries over the node of the local datacenter. Currently, it also includes in the query plans returned a configurable number of hosts in the remote datacenters (which are always tried after the local nodes) but this functionality will be removed in the next major version of the driver. See the comments on DCAwareRoundRobinPolicy(String, Int32) for more information.

This policy retries queries in only two cases:

• On a read timeout, if enough replica replied but data was not retrieved.
• On a write timeout, if we timeout while writting the distributed log used by batch statements.

This retry policy is conservative in that it will never retry with a different consistency level than the one of the initial operation.

In some cases, it may be convenient to use a more aggressive retry policy like DowngradingConsistencyRetryPolicy.

BEWARE: This policy may retry queries using a lower consistency level than the one initially requested. By doing so, it may break consistency guarantees. In other words, if you use this retry policy, there are cases (documented below) where a read at Quorum may not see a preceding write at Quorum. Do not use this policy unless you have understood the cases where this can happen and are OK with that. It is also highly recommended to always wrap this policy into LoggingRetryPolicy to log the occurrences of such consistency break. This policy behaves in the same way as the DefaultRetryPolicy policy, except for the following cases:

• On a read timeout: if the number of replica that responded is greater than one but lower than is required by the requested consistency level, the operation is retried at a lower consistency level.
• On a write timeout: if the operation is an UNLOGGED_BATCH and at least one replica acknowledged the write, the operation is retried at a lower consistency level. Furthermore, for other operation, if at least one replica acknowledged the write, the timeout is ignored.
• On an unavailable exception: if at least one replica is alive, the operation is retried at a lower consistency level.

The reasoning behind this retry policy is the following one. If, based on the information the Cassandra coordinator node returns, retrying the operation with the initially requested consistency has a change to succeed, do it. Otherwise, if based on these informations we know the initially requested consistency level cannot be achieve currently, then:

• For writes, ignore the exception (thus silently failing the consistency requirement) if we know the write has been persisted on at least one replica.
• For reads, try reading at a lower consistency level (thus silently failing the consistency requirement).

In other words, this policy : the idea that if the requested consistency level cannot be achieved, the next best thing for writes is to make sure the data is persisted, and that reading something is better than reading nothing, even if there is a risk of reading stale data.

 Cluster cluster = Cluster.builder()
             .addContactPoint(hostname) .withCredentials("username", "password") .build();
             

Its distinctive feature is that it translates addresses according to the location of the server host:

• Addresses in different EC2 regions (than the client) are unchanged
• Addresses in the same EC2 region are translated to private IPs

This provides the following information on the execution of a (successful) query:

• The list of Cassandra hosts tried in order (usually just one, unless a node has been tried but was dead/in error or a timeout provoked a retry (which depends on the RetryPolicy)).
• The consistency level achieved by the query (usually the one asked, though some specific RetryPolicy may allow this to be different).
• The query trace recorded by Cassandra if tracing had been set for the query.

All of the methods of this retry policy unconditionally return Rethrow. If this policy is used, retry will have to be implemented in business code.

In case of write timeouts this policy will always return Rethrow if the statement is considered non-idempotent (see IsIdempotent). For all other cases, this policy delegates the decision to the child policy.

This is generally throw by query that manipulate the schema (CREATE and ALTER) when the required configuration options are invalid.

Note that this policy only log the Ignore and Retry decisions (since Rethrow decisions just amount to propagate the cassandra exception). The logging is done at the Info level.

• either there is no host live in the cluster at the moment of the query
• all host that have been tried have failed due to a connection problem

This is only useful as a placeholder when no authentication is to be used.

This provider allows to programmatically define authentication information that will then apply to all hosts. The PlainTextAuthenticator instances it returns support SASL authentication using the PLAIN mechanism for version 2 or above of the CQL native protocol.

Represents the options related to connection pooling.

For each host selected by the load balancing policy, the driver keeps a core amount of connections open at all times (GetCoreConnectionsPerHost(HostDistance)). If the use of those connections reaches a configurable threshold (GetMaxSimultaneousRequestsPerConnectionTreshold(HostDistance)), more connections are created up to the configurable maximum number of connections (GetMaxConnectionPerHost(HostDistance)).

The driver uses connections in an asynchronous manner and multiple requests can be submitted on the same connection at the same time without waiting for a response. This means that the driver only needs to maintain a relatively small number of connections to each Cassandra host. The PoolingOptions allows you to to control how many connections are kept per host.

Each of these parameters can be separately set for Local and Remote hosts. For Ignored hosts, the default for all those settings is 0 and cannot be changed.

The default amount of connections depend on the Cassandra version of the Cluster, as newer versions of Cassandra (2.1 and above) support a higher number of in-flight requests.

For Cassandra 2.1 and above, the default amount of connections per host are:

• Local datacenter: 1 core connection per host, with 2 connections as maximum when the simultaneous requests threshold is reached.
• Remote datacenter: 1 core connection per host (being 1 also max).

For older Cassandra versions (1.2 and 2.0), the default amount of connections per host are:

• Local datacenter: 2 core connection per host, with 8 connections as maximum when the simultaneous requests threshold is reached.
• Remote datacenter: 1 core connection per host (being 2 the maximum).

A prepared statement can be executed once concrete values has been provided for the bound variables. The pair of a prepared statement and values for its bound variables is a BoundStatement and can be executed (by Session#Execute).

The trace is generated by Cassandra when query tracing is enabled for the query. The trace itself is stored in Cassandra in the sessions and events table in the system_traces keyspace and can be retrieve manually using the trace identifier (the one returned by TraceId).

A query trace is composed of a list of trace events.

There is three possible decision:

• Rethrow: no retry should be attempted and an exception should be thrown
• Retry: the operation will be retried. The consistency level of the retry should be specified.
• Ignore: no retry should be attempted and the exception should be ignored. In that case, the operation that triggered the Cassandra exception will return an empty result set.

This policy queries nodes in a round-robin fashion. For a given query, if an host fail, the next one (following the round-robin order) is tried, until all hosts have been tried.

This policy is not datacenter aware and will include every known Cassandra host in its round robin algorithm. If you use multiple datacenter this will be inefficient and you will want to use the DCAwareRoundRobinPolicy load balancing policy instead.

The retrieval of the rows of a RowSet is generally paged (a first page of result is fetched and the next one is only fetched once all the results of the first page have been consumed). The size of the pages can be configured either globally through SetPageSize(Int32) or per-statement with SetPageSize(Int32). Though new pages are automatically and transparently fetched when needed, it is possible to force the retrieval of the next page early through FetchMoreResults and FetchMoreResultsAsync.

The RowSet dequeues Row items while iterated. After a full enumeration of this instance, following enumerations will be empty, as all rows have been dequeued.

Each session maintains multiple connections to the cluster nodes, provides policies to choose which node to use for each query (round-robin on all nodes of the cluster by default), and handles retries for failed query (when it makes sense), etc...

Session instances are thread-safe and usually a single instance is enough per application. However, a given session can only be set to one keyspace at a time, so one instance per keyspace is necessary.

This policy encapsulates another policy. The resulting policy works in the following way:

1. The Distance(Host) method is inherited from the child policy.
2. The host yielded by the NewQueryPlan(String, IStatement) method will first return the Local replicas for the statement, based on the RoutingKey.

Backwards compatibility only.

In Cassandra 2.2 and above, when executing a UPDATE or INSERT query, a parameter can be unset. Designed to avoid tombstones, setting a parameter value to Unset will make Cassandra to ignore it.

Remarks

This is the main entry point of the driver. A simple example of access to a Cassandra cluster would be:

 Cluster cluster = Cluster.Builder.AddContactPoint("192.168.0.1").Build(); 
             Session session = Cluster.Connect("db1"); 
             foreach (var row in session.execute("SELECT * FROM table1")) 
               //do something ... 

A cluster object maintains a permanent connection to one of the cluster node that it uses solely to maintain informations on the state and current topology of the cluster. Using the connection, the driver will discover all the nodes composing the cluster as well as new nodes joining the cluster.

An execution profile. See the documentation of WithExecutionProfiles(ActionIExecutionProfileOptions) for an explanation on how to create these profiles and add them to the cluster.

You can use these profiles via their name (that is set when adding them to the cluster through WithExecutionProfiles(ActionIExecutionProfileOptions)) with the multiple driver APIs that execute requests (LINQ, Mapper and Session). Example with ExecuteAsync(IStatement, String):

var rowSet = await session.ExecuteAsync(new SimpleStatement("SELECT * FROM keyspace.table"), "profile1").ConfigureAwait(false);

If you want to create a new Cluster instance programmatically, then it is advised to use Cluster.Builder (obtained through the Cluster#builder method).

But it is also possible to implement a custom Initializer that retrieve initialization from a web-service or from a configuration file for instance.

Each session maintains multiple connections to the cluster nodes, provides policies to choose which node to use for each query (round-robin on all nodes of the cluster by default), and handles retries for failed query (when it makes sense), etc...

Session instances are thread-safe and usually a single instance is enough per application. However, a given session can only be set to one keyspace at a time, so one instance per keyspace is necessary.

Exposes information on the connections maintained by a Client at a specific time.

Given that Apache Cassandra uses those timestamps to resolve conflicts, implementations should generate monotonically increasing timestamps for successive invocations of Next.

The distance assigned to a host influences how many connections the driver maintains towards this host.