Skip to main content

Overview

The Statement struct represents an unprepared CQL statement that can be executed on a server. It contains the CQL query text along with various execution options. For reusable statements or statements with bound values, prefer using PreparedStatement which offers better performance and type safety.

Type Definition

pub struct Statement {
    pub contents: String,
    // ... internal fields
}
Source: scylla/src/statement/unprepared.rs:16

Constructor

new

Creates a new Statement from a CQL query string.
pub fn new(query_text: impl Into<String>) -> Self
query_text
impl Into<String>
required
The CQL statement text (e.g., "SELECT * FROM my_table")
Statement
Statement
A new statement instance with default configuration
Example:
use scylla::statement::Statement;

let stmt = Statement::new("SELECT * FROM users WHERE id = ?");

Configuration Methods

Paging

set_page_size

Sets the page size for paged query execution.
pub fn set_page_size(&mut self, page_size: i32)
page_size
i32
required
Number of rows to fetch per page. Must be positive. Default is 5000.
Panics: If page_size is non-positive.

with_page_size

Builder-style method to set page size.
pub fn with_page_size(self, page_size: i32) -> Self

get_page_size

Returns the configured page size.
pub fn get_page_size(&self) -> i32

Consistency

set_consistency

Sets the consistency level for this statement.
pub fn set_consistency(&mut self, c: Consistency)
c
Consistency
required
Consistency level (e.g., Consistency::Quorum)

unset_consistency

Removes the consistency override, falling back to the execution profile.
pub fn unset_consistency(&mut self)

get_consistency

Returns the overridden consistency level, if set.
pub fn get_consistency(&self) -> Option<Consistency>

Serial Consistency

set_serial_consistency

Sets the serial consistency for lightweight transactions (LWTs).
pub fn set_serial_consistency(&mut self, sc: Option<SerialConsistency>)
sc
Option<SerialConsistency>
required
Serial consistency level for LWT operations

unset_serial_consistency

Removes the serial consistency override.
pub fn unset_serial_consistency(&mut self)

get_serial_consistency

Returns the configured serial consistency.
pub fn get_serial_consistency(&self) -> Option<SerialConsistency>

Idempotence

set_is_idempotent

Marks whether the statement is idempotent.
pub fn set_is_idempotent(&mut self, is_idempotent: bool)
is_idempotent
bool
required
true if the statement can be safely retried
Idempotent statements can be applied multiple times without changing the result. This affects retry behavior.

get_is_idempotent

pub fn get_is_idempotent(&self) -> bool

Tracing

set_tracing

Enables or disables CQL tracing.
pub fn set_tracing(&mut self, should_trace: bool)
should_trace
bool
required
true to enable tracing
When enabled, the query result will contain a tracing ID.

get_tracing

pub fn get_tracing(&self) -> bool

Timestamp

set_timestamp

Sets a client-provided timestamp in microseconds.
pub fn set_timestamp(&mut self, timestamp: Option<i64>)
timestamp
Option<i64>
required
Timestamp in microseconds since Unix epoch, or None for server-side timestamp

get_timestamp

pub fn get_timestamp(&self) -> Option<i64>

Timeout

set_request_timeout

Sets the client-side request timeout.
pub fn set_request_timeout(&mut self, timeout: Option<Duration>)
timeout
Option<Duration>
required
Maximum time to wait for the request, or None to use execution profile timeout

get_request_timeout

pub fn get_request_timeout(&self) -> Option<Duration>

Policies

set_retry_policy

Overrides the retry policy for this statement.
pub fn set_retry_policy(&mut self, retry_policy: Option<Arc<dyn RetryPolicy>>)
retry_policy
Option<Arc<dyn RetryPolicy>>
required
Custom retry policy, or None to use the execution profile’s policy

get_retry_policy

pub fn get_retry_policy(&self) -> Option<&Arc<dyn RetryPolicy>>

set_load_balancing_policy

Overrides the load balancing policy for this statement.
pub fn set_load_balancing_policy(
    &mut self,
    load_balancing_policy: Option<Arc<dyn LoadBalancingPolicy>>
)

get_load_balancing_policy

pub fn get_load_balancing_policy(&self) -> Option<&Arc<dyn LoadBalancingPolicy>>

Execution Profile

set_execution_profile_handle

Associates the statement with an execution profile.
pub fn set_execution_profile_handle(
    &mut self,
    profile_handle: Option<ExecutionProfileHandle>
)

get_execution_profile_handle

pub fn get_execution_profile_handle(&self) -> Option<&ExecutionProfileHandle>

History Listener

set_history_listener

Sets a listener to track query execution events.
pub fn set_history_listener(&mut self, history_listener: Arc<dyn HistoryListener>)

remove_history_listener

Removes the history listener.
pub fn remove_history_listener(&mut self) -> Option<Arc<dyn HistoryListener>>

Trait Implementations

From<String>

impl From<String> for Statement
Converts a String into a Statement.

From<&str>

impl From<&str> for Statement
Converts a string slice into a Statement.

Example Usage

use scylla::{Session, SessionBuilder};
use scylla::statement::Statement;
use scylla::frame::types::Consistency;
use std::time::Duration;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let session = SessionBuilder::new()
        .known_node("127.0.0.1:9042")
        .build()
        .await?;

    // Create and configure a statement
    let mut stmt = Statement::new("SELECT * FROM my_keyspace.my_table");
    stmt.set_consistency(Consistency::Quorum);
    stmt.set_page_size(1000);
    stmt.set_is_idempotent(true);
    stmt.set_request_timeout(Some(Duration::from_secs(5)));

    // Execute the statement
    let result = session.query_unpaged(stmt, &[]).await?;
    println!("Query returned {} rows", result.rows_num()?);

    Ok(())
}

See Also

Build docs developers (and LLMs) love