Interface ISession

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.

Inherited Members
IDisposable.Dispose()
Namespace: Cassandra
Assembly: Cassandra.dll
Syntax
public interface ISession : IDisposable

Properties

BinaryProtocolVersion

Gets the Cassandra native binary protocol version

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

Cluster

Gets the cluster information and state

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

IsDisposed

Determines if the object has been disposed.

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

Keyspace

Gets name of currently used keyspace.

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

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
string SessionName { get; }
Property Value
Type Description
string

UserDefinedTypes

Gets the user defined type mappings

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

Methods

BeginExecute(IStatement, AsyncCallback, object)

Begins asynchronous execute operation.

Declaration
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
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
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
void ChangeKeyspace(string keyspaceName)
Parameters
Type Name Description
string keyspaceName

Case-sensitive name of keyspace to be used.
Exceptions
Type Condition
InvalidQueryException

When keyspace does not exist

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

Creates new keyspace in current cluster.

Declaration
void CreateKeyspace(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 = 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
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
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
void DeleteKeyspaceIfExists(string keyspaceName)
Parameters
Type Name Description
string keyspaceName

Name of keyspace to be deleted.

EndExecute(IAsyncResult)

Ends asynchronous execute operation

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

EndPrepare(IAsyncResult)

Ends asynchronous prepare operation

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

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
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(IStatement)

Executes the provided query.

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

Execute(string, ConsistencyLevel)

Executes the provided query.

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

Execute(string)

Executes the provided query.

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

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

ExecuteAsync(IStatement)

Executes a query asynchronously

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

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
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");

ExecuteGraph(IGraphStatement)

Executes a graph statement.

Declaration
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()"));

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
Task<GraphResultSet> ExecuteGraphAsync(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
Task<GraphResultSet>
Examples
Task<GraphResultSet$gt; task = session.ExecuteGraphAsync(new SimpleGraphStatement("g.V()"), "graphProfile");

ExecuteGraphAsync(IGraphStatement)

Executes a graph statement.

Declaration
Task<GraphResultSet> ExecuteGraphAsync(IGraphStatement statement)
Parameters
Type Name Description
IGraphStatement statement

The graph statement containing the query
Returns
Type Description
Task<GraphResultSet>
Examples
Task<GraphResultSet$gt; task = session.ExecuteGraphAsync(new SimpleGraphStatement("g.V()"));

GetMetrics()

Retrieves the driver metrics for this session.

Declaration
IDriverMetrics GetMetrics()
Returns
Type Description
IDriverMetrics

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

Prepares the query string, sending the custom payload request.

Declaration
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, IDictionary<string, byte[]>)

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

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

Prepare(string, string)

Prepares the query on the provided keyspace.

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

Prepares the provided query string.

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

cql query to prepare
Returns
Type Description
PreparedStatement

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

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

Declaration
Task<PreparedStatement> PrepareAsync(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
Task<PreparedStatement>

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

PrepareAsync(string, string)

Prepares the query asynchronously on the provided keyspace.

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

Prepares the provided query string asynchronously.

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

cql query to prepare
Returns
Type Description
Task<PreparedStatement>

ShutdownAsync()

Disposes the session asynchronously.

Declaration
Task ShutdownAsync()
Returns
Type Description
Task

WaitForSchemaAgreement(RowSet)

Declaration
[Obsolete("Method deprecated. The driver internally waits for schema agreement when there is an schema change. See ProtocolOptions.MaxSchemaAgreementWaitSeconds for more info.")]
void WaitForSchemaAgreement(RowSet rs)
Parameters
Type Name Description
RowSet rs

WaitForSchemaAgreement(IPEndPoint)

Declaration
[Obsolete("Method deprecated. The driver internally waits for schema agreement when there is an schema change. See ProtocolOptions.MaxSchemaAgreementWaitSeconds for more info.")]
bool WaitForSchemaAgreement(IPEndPoint forHost)
Parameters
Type Name Description
IPEndPoint forHost
Returns
Type Description
bool

Extension Methods