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)

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

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

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.

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.

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

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

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

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

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

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

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

Task<PreparedStatement> PrepareAsync(string cqlQuery)

Parameters

Type	Name	Description
string	cqlQuery	cql query to prepare

Returns

Type	Description
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
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)

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

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

SessionExtensions.CreateBatch(ISession)

SessionExtensions.CreateBatch(ISession, BatchType)

SessionExtensions.GetTable<TEntity>(ISession, string, string)

Extensions.GetState(ISession)