Skip to main content
ExecutionProfile is a grouping of configurable options regarding CQL statement execution. Profiles can be created to represent different workloads, which can be run conveniently on a single session.

​
Overview

Execution profiles enable you to configure different execution settings for different queries:
  • Consistency levels - Read and write consistency requirements
  • Timeouts - Client-side request timeouts
  • Load balancing - Node selection strategy
  • Retry policy - How to handle retries
  • Speculative execution - When to send speculative requests
Profiles use a handle-based architecture: Handles can be remapped to different profiles, affecting all sessions and statements using that handle.

​
Creating a Profile

Use the builder pattern to create a profile: 
use scylla::client::execution_profile::ExecutionProfile;
use scylla::statement::Consistency;
use std::time::Duration;

let profile = ExecutionProfile::builder()
    .consistency(Consistency::LocalQuorum)
    .request_timeout(Some(Duration::from_secs(30)))
    .build();

​
Using with Session

Set a default execution profile for all session operations: 
use scylla::client::session::Session;
use scylla::client::session_builder::SessionBuilder;
use scylla::client::execution_profile::ExecutionProfile;
use scylla::statement::Consistency;

let profile = ExecutionProfile::builder()
    .consistency(Consistency::LocalOne)
    .request_timeout(None) // No timeout
    .build();

let handle = profile.into_handle();

let session: Session = SessionBuilder::new()
    .known_node("127.0.0.1:9042")
    .default_execution_profile_handle(handle)
    .build()
    .await?;

​
Using with Statements

Attach a profile to individual statements: 
use scylla::statement::unprepared::Statement;
use scylla::client::execution_profile::ExecutionProfile;
use scylla::statement::Consistency;
use std::time::Duration;

let profile = ExecutionProfile::builder()
    .consistency(Consistency::All)
    .request_timeout(Some(Duration::from_secs(30)))
    .build();

let handle = profile.into_handle();

let mut query = Statement::from("SELECT * FROM ks.table");
query.set_execution_profile_handle(Some(handle));

​
Builder Methods

​
builder

​
builder
fn
Creates a new ExecutionProfileBuilder with all options set to defaults.Returns: ExecutionProfileBuilderExample:
let profile = ExecutionProfile::builder()
    .consistency(Consistency::Quorum)
    .build();

​
to_builder

​
to_builder
fn
Creates a builder with all options set to the same values as this profile.Useful for creating variations of an existing profile.Returns: ExecutionProfileBuilderExample:
let base_profile = ExecutionProfile::builder()
    .request_timeout(Some(Duration::from_secs(30)))
    .build();

// Create a variant with different consistency
let profile = base_profile.to_builder()
    .consistency(Consistency::All)
    .build();

​
Configuration Methods

​
consistency

​
consistency
fn
Sets the default consistency level for statement executions.Can be overridden by explicitly setting consistency on individual statements.Default: Consistency::LocalQuorumParameters:
  • consistency: Consistency - Consistency level to use
Returns: ExecutionProfileBuilderExample:
let profile = ExecutionProfile::builder()
    .consistency(Consistency::One)
    .build();

​
serial_consistency

​
serial_consistency
fn
Sets the default serial consistency for lightweight transactions (CAS operations).Can be overridden by explicitly setting serial consistency on individual statements.Default: Some(SerialConsistency::LocalSerial)Parameters:
  • serial_consistency: Option<SerialConsistency> - Serial consistency to use
Returns: ExecutionProfileBuilderExample:
use scylla_cql::frame::types::SerialConsistency;

let profile = ExecutionProfile::builder()
    .serial_consistency(Some(SerialConsistency::Serial))
    .build();

​
request_timeout

​
request_timeout
fn
Sets the client-side timeout for executing statements.If set to None, the driver will wait indefinitely for a response.Default: Some(Duration::from_secs(30))Parameters:
  • timeout: Option<Duration> - Timeout duration or None for no timeout
Returns: ExecutionProfileBuilderExample:
use std::time::Duration;

// Set 5 second timeout
let profile = ExecutionProfile::builder()
    .request_timeout(Some(Duration::from_secs(5)))
    .build();

// No timeout
let no_timeout_profile = ExecutionProfile::builder()
    .request_timeout(None)
    .build();

​
load_balancing_policy

​
load_balancing_policy
fn
Sets the load balancing policy for selecting which nodes to query.Default: DefaultPolicyParameters:
  • load_balancing_policy: Arc<dyn LoadBalancingPolicy> - Policy to use
Returns: ExecutionProfileBuilderExample:
use scylla::policies::load_balancing::DefaultPolicy;
use std::sync::Arc;

let profile = ExecutionProfile::builder()
    .load_balancing_policy(Arc::new(DefaultPolicy::default()))
    .build();
See LoadBalancingPolicy for more information.

​
retry_policy

​
retry_policy
fn
Sets the retry policy for handling failed queries.Default: DefaultRetryPolicyParameters:
  • retry_policy: Arc<dyn RetryPolicy> - Policy to use
Returns: ExecutionProfileBuilderExample:
use scylla::policies::retry::DefaultRetryPolicy;
use std::sync::Arc;

let profile = ExecutionProfile::builder()
    .retry_policy(Arc::new(DefaultRetryPolicy::new()))
    .build();
See RetryPolicy for more information.

​
speculative_execution_policy

​
speculative_execution_policy
fn
Sets the speculative execution policy for sending backup queries.Speculative execution sends the same query to multiple nodes if the first doesn’t respond quickly enough.Default: None (disabled)Parameters:
  • speculative_execution_policy: Option<Arc<dyn SpeculativeExecutionPolicy>> - Policy to use
Returns: ExecutionProfileBuilderExample:
use scylla::policies::speculative_execution::SimpleSpeculativeExecutionPolicy;
use std::sync::Arc;
use std::time::Duration;

let policy = SimpleSpeculativeExecutionPolicy {
    max_retry_count: 3,
    retry_interval: Duration::from_millis(100),
};

let profile = ExecutionProfile::builder()
    .speculative_execution_policy(Some(Arc::new(policy)))
    .build();
See SpeculativeExecutionPolicy for more information.

​
build

​
build
fn
Builds the ExecutionProfile after setting all options.Returns: ExecutionProfileExample:
let profile = ExecutionProfile::builder()
    .consistency(Consistency::Two)
    .build();

​
Profile Methods

​
into_handle

​
into_handle
fn
Converts the profile into an ExecutionProfileHandle.Handles can be cloned and shared across multiple sessions and statements.Returns: ExecutionProfileHandleExample:
let profile = ExecutionProfile::builder()
    .consistency(Consistency::One)
    .build();

let handle = profile.into_handle();

// Can be cloned and used in multiple places
let handle2 = handle.clone();

​
into_handle_with_label

​
into_handle_with_label
fn
Converts the profile into an ExecutionProfileHandle with a debugging label.The label is useful for debugging when tracking which statements use which profiles.Parameters:
  • label: String - Debug label for the handle
Returns: ExecutionProfileHandleExample:
let profile = ExecutionProfile::builder()
    .consistency(Consistency::All)
    .build();

let handle = profile.into_handle_with_label("critical-writes".to_string());

​
Getters

The following methods retrieve the current settings from a profile:
​
get_request_timeout
fn
Gets the client timeout associated with this profile.Returns: Option<Duration>
​
get_consistency
fn
Gets the consistency level associated with this profile.Returns: Consistency
​
get_serial_consistency
fn
Gets the serial consistency (if set) associated with this profile.Returns: Option<SerialConsistency>
​
get_load_balancing_policy
fn
Gets the load balancing policy associated with this profile.Returns: &Arc<dyn LoadBalancingPolicy>
​
get_retry_policy
fn
Gets the retry policy associated with this profile.Returns: &Arc<dyn RetryPolicy>
​
get_speculative_execution_policy
fn
Gets the speculative execution policy associated with this profile.Returns: Option<&Arc<dyn SpeculativeExecutionPolicy>>

​
ExecutionProfileHandle

A handle that points to an ExecutionProfile. Handles enable remapping all associated entities (statements/sessions) to another profile at once.
Cloned handles initially point to the same execution profile. Remapping one handle affects all clones, as they share the same underlying reference through Arc<ArcSwap>.

​
pointee_to_builder

​
pointee_to_builder
fn
Creates a builder with settings from the profile this handle points to.Returns: ExecutionProfileBuilderExample:
let handle = profile.into_handle();

let new_profile = handle.pointee_to_builder()
    .consistency(Consistency::Two)
    .build();

​
to_profile

​
to_profile
fn
Returns the execution profile currently pointed to by this handle.Returns: ExecutionProfileExample:
let current_profile = handle.to_profile();
let consistency = current_profile.get_consistency();

​
map_to_another_profile

​
map_to_another_profile
fn
Makes the handle point to a new execution profile.All entities (statements/sessions) holding this handle will immediately reflect the change.Parameters:
  • profile: ExecutionProfile - New profile to point to
Example:
let profile1 = ExecutionProfile::builder()
    .consistency(Consistency::One)
    .build();

let profile2 = ExecutionProfile::builder()
    .consistency(Consistency::All)
    .build();

let mut handle = profile1.into_handle();

// Associate handle with a statement
let mut stmt = Statement::from("SELECT * FROM ks.tab");
stmt.set_execution_profile_handle(Some(handle.clone()));

// Later, remap to different profile - statement automatically uses new settings
handle.map_to_another_profile(profile2);

​
Workload Examples

​
Multiple Workloads

use scylla::client::execution_profile::ExecutionProfile;
use scylla::statement::Consistency;
use std::time::Duration;

// Profile for critical writes
let critical_writes = ExecutionProfile::builder()
    .consistency(Consistency::Quorum)
    .request_timeout(Some(Duration::from_secs(10)))
    .build();

// Profile for fast reads
let fast_reads = ExecutionProfile::builder()
    .consistency(Consistency::One)
    .request_timeout(Some(Duration::from_millis(500)))
    .build();

// Profile for batch jobs with no timeout
let batch_jobs = ExecutionProfile::builder()
    .consistency(Consistency::LocalQuorum)
    .request_timeout(None)
    .build();

let critical_handle = critical_writes.into_handle();
let reads_handle = fast_reads.into_handle();
let batch_handle = batch_jobs.into_handle();

// Use different profiles for different statements
let mut write_stmt = Statement::from("INSERT INTO ks.tab (a) VALUES (?)");
write_stmt.set_execution_profile_handle(Some(critical_handle));

let mut read_stmt = Statement::from("SELECT * FROM ks.tab WHERE a = ?");
read_stmt.set_execution_profile_handle(Some(reads_handle));

​
Dynamic Remapping

let normal_profile = ExecutionProfile::builder()
    .consistency(Consistency::LocalQuorum)
    .build();

let high_consistency_profile = ExecutionProfile::builder()
    .consistency(Consistency::Quorum)
    .build();

let mut handle = normal_profile.into_handle();

// Multiple statements share the handle
let mut stmt1 = Statement::from("INSERT INTO ks.tab1 (a) VALUES (?)");
stmt1.set_execution_profile_handle(Some(handle.clone()));

let mut stmt2 = Statement::from("INSERT INTO ks.tab2 (a) VALUES (?)");
stmt2.set_execution_profile_handle(Some(handle.clone()));

// During critical period, switch all statements to higher consistency
handle.map_to_another_profile(high_consistency_profile);

// Both stmt1 and stmt2 now use Quorum consistency

​
Default Values

SettingDefault Value
ConsistencyLocalQuorum
Serial ConsistencySome(LocalSerial)
Request TimeoutSome(30 seconds)
Load Balancing PolicyDefaultPolicy
Retry PolicyDefaultRetryPolicy
Speculative ExecutionNone (disabled)

Build docs developers (and LLMs) love

Get started for freeTalk to us