ExecutionProfile

Configurable options for CQL statement execution

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:

• ExecutionProfile - Immutable set of settings
• ExecutionProfileHandle - Handle that points to a profile

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

Example:

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

Example:

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

Parameters:

• consistency: Consistency - Consistency level to use

Returns: ExecutionProfileBuilder

Example:

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

Example:

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

Example:

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

Parameters:

• load_balancing_policy: Arc<dyn LoadBalancingPolicy> - Policy to use

Returns: ExecutionProfileBuilder

Example:

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

Parameters:

• retry_policy: Arc<dyn RetryPolicy> - Policy to use

Returns: ExecutionProfileBuilder

Example:

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

Example:

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

Example:

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

Example:

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

Example:

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

Example:

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

Example:

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

Setting	Default Value
Consistency	LocalQuorum
Serial Consistency	Some(LocalSerial)
Request Timeout	Some(30 seconds)
Load Balancing Policy	DefaultPolicy
Retry Policy	DefaultRetryPolicy
Speculative Execution	None (disabled)

Related Types

• Session - Can use execution profiles for all operations
• SessionBuilder - Set default execution profile with default_execution_profile_handle()
• Statement - Can have an execution profile attached
• PreparedStatement - Can have an execution profile attached
• LoadBalancingPolicy - Node selection strategy
• RetryPolicy - Retry behavior configuration
• SpeculativeExecutionPolicy - Speculative execution configuration