Cassandra NamespaceA C# client driver for Apache Cassandra
The core module of the Datastax C# Driver for Apache Cassandra (C*). This module offers a simple (as in, not abstracted) but complete API to work with CQL3. The main goal of this module is to handle all the functionality related to managing connections to a Cassandra cluster (but leaving higher level abstraction like object mapping to separate modules).
Classes

  ClassDescription
Public classAlreadyExistsException
Exception thrown when a query attemps to create a keyspace or table that already exists.
Public classAsyncCallException
Public classAuthenticationException
Indicates an error during the authentication phase while connecting to a node.
Public classBigIntegerTypeAdapter
Public classBoundStatement
A prepared statement with values bound to the bind variables.

Once a BoundStatement has values for all the variables of the PreparedStatement it has been created from, it can executed (through Session#execute).

The values of a BoundStatement can be set by either index or name. When setting them by name, names follow the case insensitivity rules explained in ColumnDefinitions. Noteworthily, if multiple bind variables correspond to the same column (as would be the case if you prepare

SELECT * FROM t WHERE x > ? AND x < ?
), you will have to set values by indexes (or the #bind method) as the methods to set by name only allows to set the first prepared occurrence of the column.

Public classBuilder
Helper class to build Cluster instances.
Public classCassandraConnectionStringBuilder
Public classCassandraEventArgs
Public classClientOptions
Additional options of the .net Cassandra driver.
Public classCluster
Informations and known state of a Cassandra cluster.

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.

Public classColumnDesc
Public classConfiguration
The configuration of the cluster. This handle setting:
  • Cassandra binary protocol level configuration (compression).
  • Connection pooling configurations.
  • low-level tcp configuration options (tcpNoDelay, keepAlive, ...).
Public classConstantReconnectionPolicy
A reconnection policy that waits a constant time between each reconnection attempt.
Public classCqlColumn
Public classCustomColumnInfo
Public classDCAwareRoundRobinPolicy
A data-center aware Round-robin load balancing policy.

This policy provides round-robin queries over the node of the local datacenter. It also includes in the query plans returned a configurable number of hosts in the remote datacenters, but those are always tried after the local nodes. In other words, this policy guarantees that no host in a remote datacenter will be queried unless no host in the local datacenter can be reached.

If used with a single datacenter, this policy is equivalent to the

LoadBalancingPolicy.RoundRobin
LoadBalancingPolicy.RoundRobin
policy, but its DC awareness incurs a slight overhead so the policy could be prefered to this policy in that case.

Public classDecimalTypeAdapter
Public classDefaultRetryPolicy
The default retry policy.

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.

Public classDiagnostics
Public classDowngradingConsistencyRetryPolicy
A retry policy that sometimes retry with a lower consistency level than the one initially requested.

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 is cases (documented below) where a read at

may not see a preceding write at . 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 occurences of such consistency break.

This policy : the same retries than the DefaultRetryPolicy policy. But on top of that, it also retries in 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 concistency level.
  • On a write timeout: if the operation is an
    * WriteType.UNLOGGED_BATCH
    and at least one replica acknowleged the write, the operation is retried at a lower consistency level. Furthermore, for other operation, if at least one replica acknowleged 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 behing this retry policy is the following one. If, based on the information the Cassandra coordinator node returns, retrying the operation with the initally 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.

Public classDriverException
Top level class for exceptions thrown by the driver.
Public classDriverInternalError
An unexpected error happened internally. This should never be raise and indicates a bug (either in the driver or in Cassandra).
Public classExecutionException
Public classExecutionInfo
Public classExponentialReconnectionPolicy
A reconnection policy that waits exponentially longer between each reconnection attempt (but keeps a constant delay once a maximum delay is reached).
Public classFallthroughRetryPolicy
A retry policy that never retry (nor ignore).

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

Public classHost
A Cassandra node. This class keeps the informations the driver maintain on a given Cassandra node.
Public classHostsEventArgs
Public classInvalidConfigurationInQueryException
A specific invalid query exception that indicates that the query is invalid because of some configuration problem.

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

Public classInvalidQueryException
Indicates a syntactically correct but invalid query.
Public classInvalidTypeException
Public classIsBootstrappingException
Public classKeyspaceMetadata
Public classListColumnInfo
Public classLogger
Public classLoggingRetryPolicy
A retry policy that wraps another policy, logging the decision made by its sub-policy.

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

Public classMapColumnInfo
Public classMetadata
Keeps metadata on the connected cluster, including known nodes and schema definitions.
Public classNoHostAvailableException
Exception thrown when a query cannot be performed because no host are available. This exception is thrown if
  • 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
For debugging purpose, the list of hosts that have been tried along with the failure cause can be retrieved using the #errors method.
Public classNullTypeAdapter
Public classOverloadedException
Public classPolicies
Policies configured for a Cluster instance.
Public classPoolingOptions
Options related to connection pooling.

The driver uses connections in an asynchronous way. Meaning that multiple requests can be submitted on the same connection at the same time. This means that the driver only needs to maintain a relatively small number of connections to each Cassandra host. These options allow to control how many connections are kept exactly.

For each host, the driver keeps a core amount of connections open at all time (PoolingOptions#getCoreConnectionsPerHost). If the utilisation of those connections reaches a configurable threshold (PoolingOptions#getMaxSimultaneousRequestsPerConnectionTreshold), more connections are created up to a configurable maximum number of connections (PoolingOptions#getMaxConnectionPerHost). Once more than core connections have been created, connections in excess are reclaimed if the utilisation of opened connections drops below the configured threshold (PoolingOptions#getMinSimultaneousRequestsPerConnectionTreshold).

Each of these parameters can be separately set for

and hosts (HostDistance). For hosts, the default for all those settings is 0 and cannot be changed.

Public classPreparedQueryNotFoundException
Public classPreparedStatement
Represents a prepared statement, a query with bound variables that has been prepared (pre-parsed) by the database.

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

Public classProtocolErrorException
Public classProtocolOptions
Options of the Cassandra __native__ binary protocol.
Public classQuery
An executable query.

This represents either a Statement or a BoundStatement along with the query options (consistency level, whether to trace the query, ...).

Public classQueryExecutionException
Exception related to the execution of a query. This correspond to the exception that Cassandra throw when a (valid) query cannot be executed (TimeoutException, UnavailableException, ...).
Public classQueryTimeoutException
A Cassandra timeout during a query. Such an exception is returned when the query has been tried by Cassandra but cannot be achieved with the requested consistency level within the rpc timeout set for Cassandra.
Public classQueryTrace
Public classQueryTrace Event
A trace event.

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

Public classQueryValidationException
An exception indicating that a query cannot be executed because it is incorrect syntactically, invalid, unauthorized or any other reason.
Public classReadOnlyDictionary TKey, TValue 
Public classReadTimeoutException
A Cassandra timeout during a read query.
Public classReplicationStrategies
Public classRetryDecision
Public classRoundRobinPolicy
A Round-robin load balancing policy.

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.

Public classRoundRobinPolicyWithReconnectionRetries
Public classRoundRobinPolicyWithReconnectionRetriesEventArgs
Public classRoutingKey
Public classRow
Public classRow ColumnEnumerator
Public classRowSet
Public classRowSetMetadata
Public classSchemaChangeEventArgs
Public classServerErrorException
Public classSession
Public classSetColumnInfo
Public classSimpleAuthInfoProvider
A simple
AuthInfoProvider
implementation.

This provider allows to programmatically define authentication information that will then apply to all hosts.

Note that it is not safe to add new info to this provider once a Cluster instance has been created using this provider.

Public classSimpleStatement
A simple implementation built directly from a query string.
Public classSocketOptions
Options to configure low-level socket options for the connections kept to the Cassandra hosts.
Public classStatement
A non-prepared CQL statement.

This class represents a query string along with query options. This class can be extended but SimpleStatement is provided to build a

directly from its query string.

Public classStatusChangeEventArgs
Public classSyntaxError
Indicates a syntax error in a query.
Public classTableColumn
Public classTableMetadata
Public classTableOptions
Public classTokenAwarePolicy
A wrapper load balancing policy that add token awareness to a child policy.

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

  • the method is inherited from the child policy.
  • the iterator return by the
    newQueryPlan
    method will first return the replicas for the query (based on Query#getRoutingKey) if possible (i.e. if the query
    getRoutingKey
    method doesn't return {@code null} and if {@link Metadata#getReplicas}' returns a non empty set of replicas for that partition key). If no local replica can be either found or successfully contacted, the rest of the query plan will fallback to one of the child policy.

Do note that only replica for which the child policy

HostDistance.Local
method returns will be considered having priority. For example, if you wrap DCAwareRoundRobinPolicy with this token aware policy, replicas from remote data centers may only be returned after all the host of the local data center.

Public classTopologyChangeEventArgs
Public classTraceRetrievalException
Exception thrown if a query trace cannot be retrieved.
Public classTruncateException
Error during a truncation operation.
Public classTypeAdapters
Public classUnauthorizedException
Indicates that a query cannot be performed due to the authorisation restrictions of the logged user.
Public classUnavailableException
Exception thrown when the coordinator knows there is not enough replica alive to perform a query with the requested consistency level.
Public classWriteTimeoutException
A Cassandra timeout during a write query.
Interfaces

  InterfaceDescription
Public interfaceIColumnInfo
Public interfaceIInitializer
Initializer for Cluster instances.

If you want to create a new

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

that retrieve initialization from a web-service or from a configuration file for instance.

Public interfaceILoadBalancingPolicy
The policy that decides which Cassandra hosts to contact for each new query. For efficiency purposes, the policy is expected to exclude down hosts from query plans.
Public interfaceIReconnectionPolicy
Policy that decides how often the reconnection to a dead node is attempted. Each time a node is detected dead (because a connection error occurs), a new
IReconnectionSchedule
IReconnectionSchedule
instance is created (through the NewSchedule()). Then each call to the IReconnectionSchedule#NextDelayMs method of this instance will decide when the next reconnection attempt to this node will be tried. Note that if the driver receives a push notification from the Cassandra cluster that a node is UP, any existing on that node will be cancelled and a new one will be created (in effect, the driver reset the scheduler). The default ExponentialReconnectionPolicy policy is usually adequate.
Public interfaceIReconnectionSchedule
Schedules reconnection attempts to a node.
Public interfaceIRetryPolicy
A policy that defines a default behavior to adopt when a request returns a TimeoutException or an UnavailableException. Such policy allows to centralize the handling of query retries, allowing to minimize the need for exception catching/handling in business code.
Public interfaceITypeAdapter
Delegates

  DelegateDescription
Public delegateCassandraEventHandler
Public delegateHostsEventHandler
Public delegateRowSet CellEncoder
Enumerations

  EnumerationDescription
Public enumerationCassandraEventType
Public enumerationColumnTypeCode
Public enumerationCompressionType
Compression supported by the Cassandra binary protocol.
Public enumerationConsistencyLevel
Public enumerationHostDistance
Public enumerationHostsEventArgs Kind
Public enumerationKeyType
Public enumerationRetryDecision RetryDecisionType
The type of retry decisions.
Public enumerationSchemaChangeEventArgs Reason
Public enumerationStatusChangeEventArgs Reason
Public enumerationTopologyChangeEventArgs Reason