Class Session

A session holds connections to a Cassandra cluster, allowing it to be queried.

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.

Inheritance
object
Session
Implements
Inherited Members
Namespace: Cassandra
Assembly: Cassandra.dll
Syntax
public class Session : ISession, IDisposable

Properties

BinaryProtocolVersion

Gets the Cassandra native binary protocol version

Declaration
public int BinaryProtocolVersion { get; }
Property Value
Type Description
int

Cluster

Gets the cluster information and state

Declaration
public ICluster Cluster { get; }
Property Value
Type Description
ICluster

Configuration

Gets the cluster configuration

Declaration
public Configuration Configuration { get; protected set; }
Property Value
Type Description
Configuration

IsDisposed

Determines if the session is already disposed

Declaration
public bool IsDisposed { get; }
Property Value
Type Description
bool

Keyspace

Gets or sets the keyspace

Declaration
public string Keyspace { get; }
Property Value
Type Description
string

Policies

Declaration
public Policies Policies { get; }
Property Value
Type Description
Policies

SessionName

Session name. This will be autogenerated if it is not set with WithSessionName(string). This is used as part of the metric bucket name, for example, which can be used to separate metric paths per session.

Declaration
public string SessionName { get; }
Property Value
Type Description
string

UserDefinedTypes

Gets the user defined type mappings

Declaration
public UdtMappingDefinitions UserDefinedTypes { get; }
Property Value
Type Description
UdtMappingDefinitions

Methods

BeginExecute(IStatement, AsyncCallback, object)

Begins asynchronous execute operation.

Declaration
public IAsyncResult BeginExecute(IStatement statement, AsyncCallback callback, object state)
Parameters
Type Name Description
IStatement statement
AsyncCallback callback
object state
Returns
Type Description
IAsyncResult

BeginExecute(string, ConsistencyLevel, AsyncCallback, object)

Begins asynchronous execute operation

Declaration
public IAsyncResult BeginExecute(string cqlQuery, ConsistencyLevel consistency, AsyncCallback callback, object state)
Parameters
Type Name Description
string cqlQuery
ConsistencyLevel consistency
AsyncCallback callback
object state
Returns
Type Description
IAsyncResult

BeginPrepare(string, AsyncCallback, object)

Begins asynchronous prepare operation

Declaration
public IAsyncResult BeginPrepare(string cqlQuery, AsyncCallback callback, object state)
Parameters
Type Name Description
string cqlQuery
AsyncCallback callback
object state
Returns
Type Description
IAsyncResult

ChangeKeyspace(string)

Switches to the specified keyspace.

Declaration
public void ChangeKeyspace(string keyspace)
Parameters
Type Name Description
string keyspace
Exceptions
Type Condition
InvalidQueryException

When keyspace does not exist

CreateKeyspace(string, Dictionary<string, string>, bool)

Creates new keyspace in current cluster.

Declaration
public void CreateKeyspace(string keyspace, Dictionary<string, string> replication = null, bool durableWrites = true)
Parameters
Type Name Description
string keyspace
Dictionary<string, string> replication

Replication property for this keyspace. To set it, refer to the ReplicationStrategies class methods. It is a dictionary of replication property sub-options where key is a sub-option name and value is a value for that sub-option.

Default value is SimpleStrategy with replication_factor = 1
bool durableWrites

Whether to use the commit log for updates on this keyspace. Default is set to true.

CreateKeyspaceIfNotExists(string, Dictionary<string, string>, bool)

Creates new keyspace in current cluster. If keyspace with specified name already exists, then this method does nothing.

Declaration
public void CreateKeyspaceIfNotExists(string keyspaceName, Dictionary<string, string> replication = null, bool durableWrites = true)
Parameters
Type Name Description
string keyspaceName

Case-sensitive name of keyspace to be created.
Dictionary<string, string> replication

Replication property for this keyspace. To set it, refer to the ReplicationStrategies class methods. It is a dictionary of replication property sub-options where key is a sub-option name and value is a value for that sub-option.

Default value is 'SimpleStrategy' with 'replication_factor' = 2
bool durableWrites

Whether to use the commit log for updates on this keyspace. Default is set to true.

DeleteKeyspace(string)

Deletes specified keyspace from current cluster. If keyspace with specified name does not exist, then exception will be thrown.

Declaration
public void DeleteKeyspace(string keyspaceName)
Parameters
Type Name Description
string keyspaceName

Name of keyspace to be deleted.

DeleteKeyspaceIfExists(string)

Deletes specified keyspace from current cluster. If keyspace with specified name does not exist, then this method does nothing.

Declaration
public void DeleteKeyspaceIfExists(string keyspaceName)
Parameters
Type Name Description
string keyspaceName

Name of keyspace to be deleted.

Dispose()

Declaration
public void Dispose()

EndExecute(IAsyncResult)

Ends asynchronous execute operation

Declaration
public RowSet EndExecute(IAsyncResult ar)
Parameters
Type Name Description
IAsyncResult ar
Returns
Type Description
RowSet

EndPrepare(IAsyncResult)

Ends asynchronous prepare operation

Declaration
public PreparedStatement EndPrepare(IAsyncResult ar)
Parameters
Type Name Description
IAsyncResult ar
Returns
Type Description
PreparedStatement

Execute(IStatement)

Executes the provided query.

Declaration
public RowSet Execute(IStatement statement)
Parameters
Type Name Description
IStatement statement
Returns
Type Description
RowSet

Execute(IStatement, string)

Executes the provided statement with the provided execution profile. The execution profile must have been added previously to the Cluster using WithExecutionProfiles(Action<IExecutionProfileOptions>).

Declaration
public RowSet Execute(IStatement statement, string executionProfileName)
Parameters
Type Name Description
IStatement statement

Statement to execute.
string executionProfileName

ExecutionProfile name to be used while executing the statement.
Returns
Type Description
RowSet

Execute(string)

Executes the provided query.

Declaration
public RowSet Execute(string cqlQuery)
Parameters
Type Name Description
string cqlQuery
Returns
Type Description
RowSet

Execute(string, ConsistencyLevel)

Executes the provided query.

Declaration
public RowSet Execute(string cqlQuery, ConsistencyLevel consistency)
Parameters
Type Name Description
string cqlQuery
ConsistencyLevel consistency
Returns
Type Description
RowSet

Execute(string, int)

Executes the provided query.

Declaration
public RowSet Execute(string cqlQuery, int pageSize)
Parameters
Type Name Description
string cqlQuery
int pageSize
Returns
Type Description
RowSet

Execute(string, string)

Executes the provided query with the provided execution profile. The execution profile must have been added previously to the Cluster using WithExecutionProfiles(Action<IExecutionProfileOptions>).

Declaration
public RowSet Execute(string cqlQuery, string executionProfileName)
Parameters
Type Name Description
string cqlQuery

Query to execute.
string executionProfileName

ExecutionProfile name to be used while executing the statement.
Returns
Type Description
RowSet

ExecuteAsync(IStatement)

Executes a query asynchronously

Declaration
public Task<RowSet> ExecuteAsync(IStatement statement)
Parameters
Type Name Description
IStatement statement

The statement to execute (simple, bound or batch statement)
Returns
Type Description
Task<RowSet>

A task representing the asynchronous operation.

ExecuteAsync(IStatement, string)

Executes a query asynchronously with the provided execution profile. The execution profile must have been added previously to the Cluster using WithExecutionProfiles(Action<IExecutionProfileOptions>).

Declaration
public Task<RowSet> ExecuteAsync(IStatement statement, string executionProfileName)
Parameters
Type Name Description
IStatement statement

The statement to execute (simple, bound or batch statement)
string executionProfileName

ExecutionProfile name to be used while executing the statement.
Returns
Type Description
Task<RowSet>

A task representing the asynchronous operation.

ExecuteGraph(IGraphStatement)

Executes a graph statement.

Declaration
public GraphResultSet ExecuteGraph(IGraphStatement statement)
Parameters
Type Name Description
IGraphStatement statement

The graph statement containing the query
Returns
Type Description
GraphResultSet
Examples
GraphResultSet rs = session.ExecuteGraph(new SimpleGraphStatement("g.V()"));

ExecuteGraph(IGraphStatement, string)

Executes a graph statement with the provided execution profile. The execution profile must have been added previously to the Cluster using WithExecutionProfiles(Action<IExecutionProfileOptions>).

Declaration
public GraphResultSet ExecuteGraph(IGraphStatement statement, string executionProfileName)
Parameters
Type Name Description
IGraphStatement statement

The graph statement containing the query
string executionProfileName

The graph execution profile name to use while executing this statement.
Returns
Type Description
GraphResultSet
Examples
GraphResultSet rs = session.ExecuteGraph(new SimpleGraphStatement("g.V()"), "graphProfile");

ExecuteGraphAsync(IGraphStatement)

Executes a graph statement.

Declaration
public Task<GraphResultSet> ExecuteGraphAsync(IGraphStatement graphStatement)
Parameters
Type Name Description
IGraphStatement graphStatement
Returns
Type Description
Task<GraphResultSet>
Examples
Task<GraphResultSet$gt; task = session.ExecuteGraphAsync(new SimpleGraphStatement("g.V()"));

ExecuteGraphAsync(IGraphStatement, string)

Executes a graph statement asynchronously with the provided graph execution profile. The graph execution profile must have been added previously to the Cluster using WithExecutionProfiles(Action<IExecutionProfileOptions>).

Declaration
public Task<GraphResultSet> ExecuteGraphAsync(IGraphStatement graphStatement, string executionProfileName)
Parameters
Type Name Description
IGraphStatement graphStatement
string executionProfileName

The graph execution profile name to use while executing this statement.
Returns
Type Description
Task<GraphResultSet>
Examples
Task<GraphResultSet$gt; task = session.ExecuteGraphAsync(new SimpleGraphStatement("g.V()"), "graphProfile");

GetMetrics()

Retrieves the driver metrics for this session.

Declaration
public IDriverMetrics GetMetrics()
Returns
Type Description
IDriverMetrics

Prepare(string)

Prepares the provided query string.

Declaration
public PreparedStatement Prepare(string cqlQuery)
Parameters
Type Name Description
string cqlQuery

cql query to prepare
Returns
Type Description
PreparedStatement

Prepare(string, IDictionary<string, byte[]>)

Prepares the query string, sending the custom payload request.

Declaration
public PreparedStatement Prepare(string cqlQuery, IDictionary<string, byte[]> customPayload)
Parameters
Type Name Description
string cqlQuery

cql query to prepare
IDictionary<string, byte[]> customPayload

Custom outgoing payload to send with the prepare request
Returns
Type Description
PreparedStatement

Prepare(string, string)

Prepares the query on the provided keyspace.

Declaration
public PreparedStatement Prepare(string cqlQuery, string keyspace)
Parameters
Type Name Description
string cqlQuery

Cql query to prepare
string keyspace

The keyspace to prepare this query with
Returns
Type Description
PreparedStatement
Remarks

Setting the keyspace parameter is only available with protocol v5 (not supported by the driver yet) or DSE 6.0+.

Prepare(string, string, IDictionary<string, byte[]>)

Prepares the provided query string asynchronously on the provided keyspace, sending the custom payload as part of the request.

Declaration
public PreparedStatement Prepare(string cqlQuery, string keyspace, IDictionary<string, byte[]> customPayload)
Parameters
Type Name Description
string cqlQuery

Cql query to prepare
string keyspace

The keyspace to prepare this query with
IDictionary<string, byte[]> customPayload

Custom outgoing payload to send with the prepare request
Returns
Type Description
PreparedStatement
Remarks

Setting the keyspace parameter is only available with protocol v5 (not supported by the driver yet) or DSE 6.0+.

PrepareAsync(string)

Prepares the provided query string asynchronously.

Declaration
public Task<PreparedStatement> PrepareAsync(string query)
Parameters
Type Name Description
string query
Returns
Type Description
Task<PreparedStatement>

PrepareAsync(string, IDictionary<string, byte[]>)

Prepares the provided query string asynchronously, and sending the custom payload request.

Declaration
public Task<PreparedStatement> PrepareAsync(string query, IDictionary<string, byte[]> customPayload)
Parameters
Type Name Description
string query
IDictionary<string, byte[]> customPayload

Custom outgoing payload to send with the prepare request
Returns
Type Description
Task<PreparedStatement>

PrepareAsync(string, string)

Prepares the query asynchronously on the provided keyspace.

Declaration
public Task<PreparedStatement> PrepareAsync(string cqlQuery, string keyspace)
Parameters
Type Name Description
string cqlQuery

Cql query to prepare
string keyspace

The keyspace to prepare this query with
Returns
Type Description
Task<PreparedStatement>
Remarks

Setting the keyspace parameter is only available with protocol v5 (not supported by the driver yet) or DSE 6.0+.

PrepareAsync(string, string, IDictionary<string, byte[]>)

Prepares the provided query asynchronously on the provided keyspace, sending the custom payload as part of the request.

Declaration
public Task<PreparedStatement> PrepareAsync(string cqlQuery, string keyspace, IDictionary<string, byte[]> customPayload)
Parameters
Type Name Description
string cqlQuery

Cql query to prepare
string keyspace

The keyspace to prepare this query with
IDictionary<string, byte[]> customPayload

Custom outgoing payload to send with the prepare request
Returns
Type Description
Task<PreparedStatement>
Remarks

Setting the keyspace parameter is only available with protocol v5 (not supported by the driver yet) or DSE 6.0+.

ShutdownAsync()

Disposes the session asynchronously.

Declaration
public Task ShutdownAsync()
Returns
Type Description
Task

WaitForSchemaAgreement(RowSet)

Declaration
public void WaitForSchemaAgreement(RowSet rs)
Parameters
Type Name Description
RowSet rs

WaitForSchemaAgreement(IPEndPoint)

Declaration
public bool WaitForSchemaAgreement(IPEndPoint hostAddress)
Parameters
Type Name Description
IPEndPoint hostAddress
Returns
Type Description
bool

Implements

Extension Methods