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
System.IDisposable.Dispose()
Namespace: Dse
Assembly: Dse.dll
Syntax
public interface ISession : IDisposable

Properties

BinaryProtocolVersion

Gets the Cassandra native binary protocol version

Declaration
int BinaryProtocolVersion { get; }
Property Value
Type Description
System.Int32

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

Keyspace

Gets name of currently used keyspace.

Declaration
string Keyspace { get; }
Property Value
Type Description
System.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
System.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
System.AsyncCallback callback
System.Object state
Returns
Type Description
System.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
System.String cqlQuery
ConsistencyLevel consistency
System.AsyncCallback callback
System.Object state
Returns
Type Description
System.IAsyncResult

BeginPrepare(String, AsyncCallback, Object)

Begins asynchronous prepare operation

Declaration
IAsyncResult BeginPrepare(string cqlQuery, AsyncCallback callback, object state)
Parameters
Type Name Description
System.String cqlQuery
System.AsyncCallback callback
System.Object state
Returns
Type Description
System.IAsyncResult

ChangeKeyspace(String)

Switches to the specified keyspace.

Declaration
void ChangeKeyspace(string keyspaceName)
Parameters
Type Name Description
System.String keyspaceName

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

When keyspace does not exist

CreateKeyspace(String, Dictionary<String, String>, Boolean)

Creates new keyspace in current cluster.

Declaration
void CreateKeyspace(string keyspaceName, Dictionary<string, string> replication = null, bool durableWrites = true)
Parameters
Type Name Description
System.String keyspaceName

Case-sensitive name of keyspace to be created.
System.Collections.Generic.Dictionary<System.String, System.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
System.Boolean durableWrites

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

CreateKeyspaceIfNotExists(String, Dictionary<String, String>, Boolean)

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
System.String keyspaceName

Case-sensitive name of keyspace to be created.
System.Collections.Generic.Dictionary<System.String, System.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
System.Boolean 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
System.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
System.String keyspaceName

Name of keyspace to be deleted.

EndExecute(IAsyncResult)

Ends asynchronous execute operation

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

EndPrepare(IAsyncResult)

Ends asynchronous prepare operation

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

Execute(IStatement)

Executes the provided query.

Declaration
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
RowSet Execute(IStatement statement, string executionProfileName)
Parameters
Type Name Description
IStatement statement

Statement to execute.
System.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
System.String cqlQuery
Returns
Type Description
RowSet

Execute(String, ConsistencyLevel)

Executes the provided query.

Declaration
RowSet Execute(string cqlQuery, ConsistencyLevel consistency)
Parameters
Type Name Description
System.String cqlQuery
ConsistencyLevel consistency
Returns
Type Description
RowSet

Execute(String, Int32)

Executes the provided query.

Declaration
RowSet Execute(string cqlQuery, int pageSize)
Parameters
Type Name Description
System.String cqlQuery
System.Int32 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
System.String cqlQuery

Query to execute.
System.String executionProfileName

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

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
System.Threading.Tasks.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
Task<RowSet> ExecuteAsync(IStatement statement, string executionProfileName)
Parameters
Type Name Description
IStatement statement

The statement to execute (simple, bound or batch statement)
System.String executionProfileName

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

A task representing the asynchronous operation.

GetMetrics()

Retrieves the driver metrics for this session.

Declaration
IDriverMetrics GetMetrics()
Returns
Type Description
IDriverMetrics

Prepare(String)

Prepares the provided query string.

Declaration
PreparedStatement Prepare(string cqlQuery)
Parameters
Type Name Description
System.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
PreparedStatement Prepare(string cqlQuery, IDictionary<string, byte[]> customPayload)
Parameters
Type Name Description
System.String cqlQuery

cql query to prepare
System.Collections.Generic.IDictionary<System.String, System.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
PreparedStatement Prepare(string cqlQuery, string keyspace)
Parameters
Type Name Description
System.String cqlQuery

Cql query to prepare
System.String keyspace

The keyspace to prepare this query with
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
System.String cqlQuery

Cql query to prepare
System.String keyspace

The keyspace to prepare this query with
System.Collections.Generic.IDictionary<System.String, System.Byte[]> customPayload

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

PrepareAsync(String)

Prepares the provided query string asynchronously.

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

cql query to prepare
Returns
Type Description
System.Threading.Tasks.Task<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
System.String cqlQuery

cql query to prepare
System.Collections.Generic.IDictionary<System.String, System.Byte[]> customPayload

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

PrepareAsync(String, String)

Prepares the query asynchronously on the provided keyspace.

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

Cql query to prepare
System.String keyspace

The keyspace to prepare this query with
Returns
Type Description
System.Threading.Tasks.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
System.String cqlQuery

Cql query to prepare
System.String keyspace

The keyspace to prepare this query with
System.Collections.Generic.IDictionary<System.String, System.Byte[]> customPayload

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

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
System.Net.IPEndPoint forHost
Returns
Type Description
System.Boolean

Extension Methods