ScyllaDB Documentation Logo Documentation
  • Server
    • ScyllaDB Open Source
    • ScyllaDB Enterprise
    • ScyllaDB Alternator
  • Cloud
  • Tools
    • ScyllaDB Manager
    • ScyllaDB Monitoring Stack
    • ScyllaDB Operator
  • Drivers
    • CQL Drivers
    • DynamoDB Drivers
Download
Menu
ScyllaDB Docs Scylla Rust Driver Making queries Batch statement

Batch statement¶

A batch statement allows to run many queries at once.
These queries can be simple queries or prepared queries.
Only queries like INSERT or UPDATE can be in a batch.

use scylla::batch::Batch;
use scylla::query::Query;
use scylla::prepared_statement::PreparedStatement;

// Create a batch statement
let mut batch: Batch = Default::default();

// Add a simple query to the batch using its text
batch.append_statement("INSERT INTO ks.tab(a, b) VALUES(?, ?)");

// Add a simple query created manually to the batch
let simple: Query = Query::new("INSERT INTO ks.tab (a, b) VALUES(3, 4)");
batch.append_statement(simple);

// Add a prepared query to the batch
let prepared: PreparedStatement = session
    .prepare("INSERT INTO ks.tab (a, b) VALUES(?, 6)")
    .await?;
batch.append_statement(prepared);

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

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

Preparing a batch¶

Instead of preparing each query individually, it’s possible to prepare a whole batch at once:

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?;

Batch options¶

You can set various options by operating on the Batch object.
For example to change consistency:

use scylla::batch::Batch;
use scylla::statement::Consistency;

// Create a batch
let mut batch: Batch = Default::default();
batch.append_statement("INSERT INTO ks.tab(a) VALUES(16)");

// Set batch consistency to One
batch.set_consistency(Consistency::One);

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

See Batch API documentation for more options

Batch values¶

Batch takes a tuple of values specified just like in simple or prepared queries.

Length of batch values must be equal to the number of statements in a batch.
Each query must have its values specified, even if they are empty.

Values passed to Session::batch must implement the trait BatchValues.
By default this includes tuples () and slices &[] of tuples and slices which implement ValueList.\

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?;

For more information about sending values in a query see Query values

Performance¶

Batch statements do not use token/shard aware load balancing, batches are sent to a random node.

Use prepared queries for best performance

PREVIOUS
Prepared query
NEXT
Paged query
Scylla Rust Driver
  • main
    • main
  • Scylla Rust Driver
  • Quick Start
    • Creating a project
    • Connecting and running a simple query
    • Running Scylla using Docker
  • Connecting to the cluster
    • Compression
    • Authentication
    • TLS
  • Making queries
    • Simple query
    • Query values
    • Query result
    • Prepared query
    • Batch statement
    • Paged query
    • USE keyspace
    • Schema agreement
    • Lightweight transaction (LWT) query
    • Query timeouts
  • Execution profiles
    • Creating a profile and setting it
    • All options supported by a profile
    • Priorities of execution settings
    • Remapping execution profile handles
  • Data Types
    • Bool, Tinyint, Smallint, Int, Bigint, Float, Double
    • Ascii, Text, Varchar
    • Counter
    • Blob
    • Inet
    • Uuid, Timeuuid
    • Date
    • Time
    • Timestamp
    • Duration
    • Decimal
    • Varint
    • List, Set, Map
    • Tuple
    • User defined types
  • Load balancing
    • DefaultPolicy
  • Retry policy configuration
    • Fallthrough retry policy
    • Default retry policy
    • Downgrading consistency retry policy
  • Speculative execution
    • Simple speculative execution
    • Percentile speculative execution
  • Driver metrics
  • Logging
  • Query tracing
    • Tracing a simple/prepared/batch query
    • Tracing a paged query
    • Tracing Session::prepare
    • Query Execution History
  • Schema
  • Create an issue
  • Edit this page

On this page

  • Batch statement
    • Preparing a batch
    • Batch options
    • Batch values
    • Performance
Logo
Docs Contact Us About Us
Mail List Icon Slack Icon Forum Icon
© 2023, ScyllaDB. All rights reserved.
Last updated on 22 March 2023.
Powered by Sphinx 4.3.2 & ScyllaDB Theme 1.3.5