Scylla Documentation Logo Documentation
  • Server
    • Scylla Open Source
    • Scylla Enterprise
    • Scylla Alternator
  • Cloud
    • Scylla Cloud
    • Scylla Cloud Docs
  • Tools
    • Scylla Manager
    • Scylla Monitoring Stack
    • Scylla Operator
  • Drivers
    • CQL Drivers
    • DynamoDB Drivers
Download
Menu

Caution

You're viewing documentation for a previous version of Scylla Java Driver. Switch to the latest stable version.

Scylla Java Driver Manual Core driver Query idempotence

Query idempotence¶

Quick overview¶

A request is idempotent if executing it multiple times leaves the database in the same state as executing it only once.

  • basic.request.default-idempotence in the configuration (defaults to false).

  • can be overridden per statement Statement.setIdempotent or StatementBuilder.setIdempotence.

  • retries and speculative executions only happen for idempotent statements.


For example:

  • update my_table set list_col = [1] where pk = 1 is idempotent: no matter how many times it gets executed, list_col will always end up with the value [1];

  • update my_table set list_col = [1] + list_col where pk = 1 is not idempotent: if list_col was initially empty, it will contain [1] after the first execution, [1, 1] after the second, etc.

Idempotence matters because the driver sometimes re-runs requests automatically:

  • retries: if we’re waiting for a response from a node and the connection gets dropped, the default retry policy automatically retries on another node. But we can’t know what went wrong with the first node: maybe it went down, or maybe it was just a network issue; in any case, it might have applied the changes already. Therefore non-idempotent requests are never retried.

  • speculative executions: if they are enabled and a node takes too long to respond, the driver queries another node to get the response faster. But maybe both nodes will eventually apply the changes. Therefore non-idempotent requests are never speculatively executed.

In most cases, you need to flag your statements manually:

SimpleStatement statement =
    SimpleStatement.newInstance("SELECT first_name FROM user WHERE id=1")
        .setIdempotent(true);

// Or with a builder:
SimpleStatement statement =
    SimpleStatement.builder("SELECT first_name FROM user WHERE id=1")
        .setIdempotence(true)
        .build();

If you don’t, they default to the value defined in the configuration by the basic.request.default-idempotence option; out of the box, it is set to false.

When you prepare a statement, its idempotence carries over to bound statements:

PreparedStatement pst = session.prepare(
    SimpleStatement.newInstance("SELECT first_name FROM user WHERE id=?")
        .setIdempotent(true));
BoundStatement bs = pst.bind(1);
assert bs.isIdempotent();

The query builder tries to infer idempotence automatically; refer to its manual for more details.

PREVIOUS
Detachable types
NEXT
Integration
  • 4.7.2.x
    • 4.13.0.x
    • 4.12.0.x
    • 4.11.1.x
    • 4.10.0.x
    • 4.7.2.x
    • 3.11.2.x
    • 3.11.0.x
    • 3.10.2.x
    • 3.7.2.x
  • Java Driver for Scylla and Apache Cassandra®
  • API Documentation
  • Manual
    • API conventions
    • Case sensitivity
    • Core driver
      • Address resolution
      • Asynchronous programming
      • Authentication
      • Bill of Materials (BOM)
      • Compression
      • Configuration
        • Reference configuration
      • Control connection
      • Custom codecs
      • Detachable types
      • Query idempotence
      • Integration
      • Load balancing
      • Logging
      • Metadata
        • Node metadata
        • Schema metadata
        • Token metadata
      • Metrics
      • Native protocol
      • Paging
      • Performance
      • Connection pooling
      • Query timestamps
      • Reactive Style Programming
      • Reconnection
      • Request tracker
      • Retries
      • Using the shaded JAR
      • Speculative query execution
      • SSL
      • Statements
        • Batch statements
        • Per-query keyspace
        • Prepared statements
        • Simple statements
      • Temporal types
      • Request throttling
      • Query tracing
      • Tuples
      • User-defined types
    • Developer docs
      • Administrative tasks
      • Common infrastructure
        • Concurrency
        • Driver context
        • Event bus
      • Native protocol layer
      • Netty pipeline
      • Request execution
    • Mapper
      • Integration
      • DAOs
        • Custom result types
        • Delete methods
        • GetEntity methods
        • Insert methods
        • Null saving strategy
        • Query methods
        • Query provider methods
        • Select methods
        • SetEntity methods
        • Statement attributes
        • Update methods
      • Entities
      • Mapper interface
    • OSGi
    • Query builder
      • Conditions
      • DELETE
      • Idempotence in the query builder
      • INSERT
      • Relations
      • Schema builder
        • Aggregate
        • Function
        • Index
        • Keyspace
        • Materialized View
        • Table
        • Type
      • SELECT
      • Terms
      • TRUNCATE
      • UPDATE
  • Upgrade guide
  • Frequently asked questions
  • Changelog
  • Create an issue
  • Edit this page

On this page

  • Query idempotence
    • Quick overview
Logo
Docs Contact Us About Us
Mail List Icon Slack Icon
© 2022, ScyllaDB. All rights reserved.
Last updated on 25 May 2022.
Powered by Sphinx 4.3.2 & ScyllaDB Theme 1.2.2