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
Inherited Members
Namespace: Cassandra
Assembly: Cassandra.dll
Syntax
public class Session : IInternalSession, ISession, IDisposable
Properties
BinaryProtocolVersion
Declaration
public int BinaryProtocolVersion { get; }
Property Value
Type | Description |
---|---|
System.Int32 |
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 |
---|---|
System.Boolean |
Keyspace
Gets or sets the keyspace
Declaration
public string Keyspace { get; }
Property Value
Type | Description |
---|---|
System.String |
Policies
Declaration
public Policies Policies { get; }
Property Value
Type | Description |
---|---|
Policies |
SessionName
Declaration
public string SessionName { get; }
Property Value
Type | Description |
---|---|
System.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 | |
System.AsyncCallback | callback | |
System.Object | state |
Returns
Type | Description |
---|---|
System.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 |
---|---|---|
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
public 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
public void ChangeKeyspace(string keyspace)
Parameters
Type | Name | Description |
---|---|---|
System.String | keyspace |
Exceptions
Type | Condition |
---|---|
InvalidQueryException | When keyspace does not exist |
CreateKeyspace(String, Dictionary<String, String>, Boolean)
Creates new keyspace in current cluster.
Declaration
public void CreateKeyspace(string keyspace, Dictionary<string, string> replication = null, bool durableWrites = true)
Parameters
Type | Name | Description |
---|---|---|
System.String | keyspace | |
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 |
System.Boolean | durableWrites | Whether to use the commit log for updates on this keyspace. Default is set to |
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
public 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 |
System.Boolean | durableWrites | Whether to use the commit log for updates on this keyspace. Default is set to |
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 |
---|---|---|
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
public void DeleteKeyspaceIfExists(string keyspaceName)
Parameters
Type | Name | Description |
---|---|---|
System.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 |
---|---|---|
System.IAsyncResult | ar |
Returns
Type | Description |
---|---|
RowSet |
EndPrepare(IAsyncResult)
Ends asynchronous prepare operation
Declaration
public PreparedStatement EndPrepare(IAsyncResult ar)
Parameters
Type | Name | Description |
---|---|---|
System.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. |
System.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 |
---|---|---|
System.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 |
---|---|---|
System.String | cqlQuery | |
ConsistencyLevel | consistency |
Returns
Type | Description |
---|---|
RowSet |
Execute(String, Int32)
Executes the provided query.
Declaration
public 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
public 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
public 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
public 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. |
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 |
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 |
System.String | executionProfileName | The graph execution profile name to use while executing this statement. |
Returns
Type | Description |
---|---|
GraphResultSet |
ExecuteGraphAsync(IGraphStatement)
Executes a graph statement.
Declaration
public Task<GraphResultSet> ExecuteGraphAsync(IGraphStatement graphStatement)
Parameters
Type | Name | Description |
---|---|---|
IGraphStatement | graphStatement |
Returns
Type | Description |
---|---|
System.Threading.Tasks.Task<GraphResultSet> |
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 | |
System.String | executionProfileName | The graph execution profile name to use while executing this statement. |
Returns
Type | Description |
---|---|
System.Threading.Tasks.Task<GraphResultSet> |
GetMetrics()
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 |
---|---|---|
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
public 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
public 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 |
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 |
---|---|---|
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 |
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 |
---|---|---|
System.String | query |
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
public Task<PreparedStatement> PrepareAsync(string query, IDictionary<string, byte[]> customPayload)
Parameters
Type | Name | Description |
---|---|---|
System.String | query | |
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
public 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> |
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 |
---|---|---|
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> |
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 |
---|---|
System.Threading.Tasks.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 |
---|---|---|
System.Net.IPEndPoint | hostAddress |
Returns
Type | Description |
---|---|
System.Boolean |