Struct scylla::transport::session::Session

source ·

pub struct Session { /* private fields */ }

Expand description

Session manages connections to the cluster and allows to perform queries

Implementations§

source §

impl Session

Represents a CQL session, which can be used to communicate with the database

source

pub async fn connect(config: SessionConfig) -> Result<Session, NewSessionError>

Establishes a CQL session with the database

Usually it’s easier to use SessionBuilder instead of calling Session::connect directly, because it’s more convenient.

§Arguments

config - Connection configuration - known nodes, Compression, etc. Must contain at least one known node.

§Example

use scylla::{Session, SessionConfig};
use scylla::transport::KnownNode;

let mut config = SessionConfig::new();
config.known_nodes.push(KnownNode::Hostname("127.0.0.1:9042".to_string()));

let session: Session = Session::connect(config).await?;

source

pub async fn query( &self, query: impl Into<Query>, values: impl SerializeRow ) -> Result<QueryResult, QueryError>

Sends a query to the database and receives a response.
Returns only a single page of results, to receive multiple pages use query_iter

This is the easiest way to make a query, but performance is worse than that of prepared queries.

It is discouraged to use this method with non-empty values argument (is_empty() method from SerializeRow trait returns false). In such case, query first needs to be prepared (on a single connection), so driver will perform 2 round trips instead of 1. Please use Session::execute() instead.

See the book for more information

§Arguments

query - query to perform, can be just a &str or the Query struct.
values - values bound to the query, easiest way is to use a tuple of bound values

§Examples

// Insert an int and text into a table
session
    .query(
        "INSERT INTO ks.tab (a, b) VALUES(?, ?)",
        (2_i32, "some text")
    )
    .await?;

use scylla::IntoTypedRows;

// Read rows containing an int and text
let rows_opt = session
.query("SELECT a, b FROM ks.tab", &[])
    .await?
    .rows;

if let Some(rows) = rows_opt {
    for row in rows.into_typed::<(i32, String)>() {
        // Parse row as int and text \
        let (int_val, text_val): (i32, String) = row?;
    }
}

source

pub async fn query_paged( &self, query: impl Into<Query>, values: impl SerializeRow, paging_state: Option<Bytes> ) -> Result<QueryResult, QueryError>

Queries the database with a custom paging state.

It is discouraged to use this method with non-empty values argument (is_empty() method from SerializeRow trait returns false). In such case, query first needs to be prepared (on a single connection), so driver will perform 2 round trips instead of 1. Please use Session::execute_paged() instead.

§Arguments

query - query to be performed
values - values bound to the query
paging_state - previously received paging state or None

source

pub async fn query_iter( &self, query: impl Into<Query>, values: impl SerializeRow ) -> Result<RowIterator, QueryError>

Run a simple query with paging
This method will query all pages of the result

Returns an async iterator (stream) over all received rows
Page size can be specified in the Query passed to the function

It is discouraged to use this method with non-empty values argument (is_empty() method from SerializeRow trait returns false). In such case, query first needs to be prepared (on a single connection), so driver will initially perform 2 round trips instead of 1. Please use Session::execute_iter() instead.

See the book for more information

§Arguments

query - query to perform, can be just a &str or the Query struct.
values - values bound to the query, easiest way is to use a tuple of bound values

§Example

use scylla::IntoTypedRows;
use futures::stream::StreamExt;

let mut rows_stream = session
   .query_iter("SELECT a, b FROM ks.t", &[])
   .await?
   .into_typed::<(i32, i32)>();

while let Some(next_row_res) = rows_stream.next().await {
    let (a, b): (i32, i32) = next_row_res?;
    println!("a, b: {}, {}", a, b);
}

source

pub async fn prepare( &self, query: impl Into<Query> ) -> Result<PreparedStatement, QueryError>

Prepares a statement on the server side and returns a prepared statement, which can later be used to perform more efficient queries

Prepared queries are much faster than simple queries:

Database doesn’t need to parse the query
They are properly load balanced using token aware routing

Warning
For token/shard aware load balancing to work properly, all partition key values must be sent as bound values (see performance section)

See the book for more information

§Arguments

query - query to prepare, can be just a &str or the Query struct.

§Example

use scylla::prepared_statement::PreparedStatement;

// Prepare the query for later execution
let prepared: PreparedStatement = session
    .prepare("INSERT INTO ks.tab (a) VALUES(?)")
    .await?;

// Run the prepared query with some values, just like a simple query
let to_insert: i32 = 12345;
session.execute(&prepared, (to_insert,)).await?;

source

pub async fn execute( &self, prepared: &PreparedStatement, values: impl SerializeRow ) -> Result<QueryResult, QueryError>

Execute a prepared query. Requires a PreparedStatement generated using Session::prepare
Returns only a single page of results, to receive multiple pages use execute_iter

Prepared queries are much faster than simple queries:

Database doesn’t need to parse the query
They are properly load balanced using token aware routing

Warning
For token/shard aware load balancing to work properly, all partition key values must be sent as bound values (see performance section)

See the book for more information

§Arguments

prepared - the prepared statement to execute, generated using Session::prepare
values - values bound to the query, easiest way is to use a tuple of bound values

§Example

use scylla::prepared_statement::PreparedStatement;

// Prepare the query for later execution
let prepared: PreparedStatement = session
    .prepare("INSERT INTO ks.tab (a) VALUES(?)")
    .await?;

// Run the prepared query with some values, just like a simple query
let to_insert: i32 = 12345;
session.execute(&prepared, (to_insert,)).await?;

source

pub async fn execute_paged( &self, prepared: &PreparedStatement, values: impl SerializeRow, paging_state: Option<Bytes> ) -> Result<QueryResult, QueryError>

Executes a previously prepared statement with previously received paging state

§Arguments

prepared - a statement prepared with prepare
values - values bound to the query
paging_state - paging state from the previous query or None

source

pub async fn execute_iter( &self, prepared: impl Into<PreparedStatement>, values: impl SerializeRow ) -> Result<RowIterator, QueryError>

Run a prepared query with paging
This method will query all pages of the result

Returns an async iterator (stream) over all received rows
Page size can be specified in the PreparedStatement passed to the function

See the book for more information

§Arguments

prepared - the prepared statement to execute, generated using Session::prepare
values - values bound to the query, easiest way is to use a tuple of bound values

§Example

use scylla::prepared_statement::PreparedStatement;
use scylla::IntoTypedRows;
use futures::stream::StreamExt;

// Prepare the query for later execution
let prepared: PreparedStatement = session
    .prepare("SELECT a, b FROM ks.t")
    .await?;

// Execute the query and receive all pages
let mut rows_stream = session
   .execute_iter(prepared, &[])
   .await?
   .into_typed::<(i32, i32)>();

while let Some(next_row_res) = rows_stream.next().await {
    let (a, b): (i32, i32) = next_row_res?;
    println!("a, b: {}, {}", a, b);
}

source

pub async fn batch( &self, batch: &Batch, values: impl BatchValues ) -> Result<QueryResult, QueryError>

Perform a batch query
Batch contains many simple or prepared queries which are executed at once
Batch doesn’t return any rows

Batch values must contain values for each of the queries

Avoid using non-empty values (SerializeRow::is_empty() return false) for simple queries inside the batch. Such queries will first need to be prepared, so the driver will need to send (numer_of_unprepared_queries_with_values + 1) requests instead of 1 request, severly affecting performance.

See the book for more information

§Arguments

batch - Batch to be performed
values - List of values for each query, it’s the easiest to use a tuple of tuples

§Example

use scylla::batch::Batch;

let mut batch: Batch = Default::default();

// A query with two bound values
batch.append_statement("INSERT INTO ks.tab(a, b) VALUES(?, ?)");

// A query with one bound value
batch.append_statement("INSERT INTO ks.tab(a, b) VALUES(3, ?)");

// A query with no bound values
batch.append_statement("INSERT INTO ks.tab(a, b) VALUES(5, 6)");

// Batch values is a tuple of 3 tuples containing values for each query
let batch_values = ((1_i32, 2_i32), // Tuple with two values for the first query
                    (4_i32,),       // Tuple with one value for the second query
                    ());            // Empty tuple/unit for the third query

// Run the batch
session.batch(&batch, batch_values).await?;

source

pub async fn prepare_batch(&self, batch: &Batch) -> Result<Batch, QueryError>

Prepares all statements within the batch and returns a new batch where every statement is prepared. /// # Example

use scylla::batch::Batch;

// Create a batch statement with unprepared statements
let mut batch: Batch = Default::default();
batch.append_statement("INSERT INTO ks.simple_unprepared1 VALUES(?, ?)");
batch.append_statement("INSERT INTO ks.simple_unprepared2 VALUES(?, ?)");

// Prepare all statements in the batch at once
let prepared_batch: Batch = session.prepare_batch(&batch).await?;

// Specify bound values to use with each query
let batch_values = ((1_i32, 2_i32),
                    (3_i32, 4_i32));

// Run the prepared batch
session.batch(&prepared_batch, batch_values).await?;

source

pub async fn use_keyspace( &self, keyspace_name: impl Into<String>, case_sensitive: bool ) -> Result<(), QueryError>

Sends USE <keyspace_name> request on all connections
This allows to write SELECT * FROM table instead of SELECT * FROM keyspace.table

Note that even failed use_keyspace can change currently used keyspace - the request is sent on all connections and can overwrite previously used keyspace.

Call only one use_keyspace at a time.
Trying to do two use_keyspace requests simultaneously with different names can end with some connections using one keyspace and the rest using the other.

See the book for more information

§Arguments

keyspace_name - keyspace name to use, keyspace names can have up to 48 alphanumeric characters and contain underscores
case_sensitive - if set to true the generated query will put keyspace name in quotes

§Example

session
    .query("INSERT INTO my_keyspace.tab (a) VALUES ('test1')", &[])
    .await?;

session.use_keyspace("my_keyspace", false).await?;

// Now we can omit keyspace name in the query
session
    .query("INSERT INTO tab (a) VALUES ('test2')", &[])
    .await?;

source

pub async fn refresh_metadata(&self) -> Result<(), QueryError>

Manually trigger a metadata refresh
The driver will fetch current nodes in the cluster and update its metadata

Normally this is not needed, the driver should automatically detect all metadata changes in the cluster

source

pub fn get_metrics(&self) -> Arc<Metrics>

Access metrics collected by the driver
Driver collects various metrics like number of queries or query latencies. They can be read using this method

source

pub fn get_cluster_data(&self) -> Arc<ClusterData>

Access cluster data collected by the driver
Driver collects various information about network topology or schema. They can be read using this method

source

pub async fn get_tracing_info( &self, tracing_id: &Uuid ) -> Result<TracingInfo, QueryError>

Get TracingInfo of a traced query performed earlier

See the book for more information about query tracing

source

pub fn get_keyspace(&self) -> Option<Arc<String>>

Gets the name of the keyspace that is currently set, or None if no keyspace was set.

It will initially return the name of the keyspace that was set in the session configuration, but calling use_keyspace will update it.

Note: the return value might be wrong if use_keyspace was called concurrently or it previously failed. It is also unspecified if get_keyspace is called concurrently with use_keyspace.

source