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 Tuples

Tuples¶

Quick overview¶

Ordered set of anonymous, typed fields, e.g. tuple<int, text, float>, (1, 'a', 1.0).

  • row.getTupleValue() / boundStatement.setTupleValue().

  • positional getters and setters: tupleValue.getInt(0), tupleValue.setString(1, "a")…

  • getting hold of the TupleType: statement or session metadata, tupleValue.getType(), or DataTypes.tupleOf().

  • creating a value from a type: tupleType.newValue().


CQL tuples are ordered sets of anonymous, typed fields. They can be used as a column type in tables, or a field type in user-defined types:

CREATE TABLE ks.collect_things (
  pk int,
  ck1 text,
  ck2 text,
  v tuple<int, text, float>,
  PRIMARY KEY (pk, ck1, ck2)
);

Fetching tuples from results¶

The driver maps tuple columns to the TupleValue class, which exposes getters and setters to access individual fields by index:

Row row = session.execute("SELECT v FROM ks.collect_things WHERE pk = 1").one();

TupleValue tupleValue = row.getTupleValue("v");
int field0 = tupleValue.getInt(0);
String field1 = tupleValue.getString(1);
Float field2 = tupleValue.getFloat(2);

Using tuples as parameters¶

Statements may contain tuples as bound values:

PreparedStatement ps =
  session.prepare(
      "INSERT INTO ks.collect_things (pk, ck1, ck2, v) VALUES (:pk, :ck1, :ck2, :v)");

To create a new tuple value, you must first have a reference to its TupleType. There are various ways to get it:

  • from the statement’s metadata

    TupleType tupleType = (TupleType) ps.getVariableDefinitions().get("v").getType();
    
  • from the driver’s schema metadata:

    TupleType tupleType =
        (TupleType)
            session
                .getMetadata()
                .getKeyspace("ks")
                .getTable("collect_things")
                .getColumn("v")
                .getType();
    
  • from another tuple value:

    TupleType tupleType = tupleValue.getType();
    
  • or creating it from scratch:

    TupleType tupleType = DataTypes.tupleOf(DataTypes.INT, DataTypes.TEXT, DataTypes.FLOAT);
    

    Note that the resulting type is detached.

Once you have the type, call newValue() and set the fields:

TupleValue tupleValue =
    tupleType.newValue().setInt(0, 1).setString(1, "hello").setFloat(2, 2.3f);

// Or as a one-liner for convenience:
TupleValue tupleValue = tupleType.newValue(1, "hello", 2.3f);

And bind your tuple value like any other type:

BoundStatement bs =
    ps.boundStatementBuilder()
        .setInt("pk", 1)
        .setString("ck1", "1")
        .setString("ck2", "1")
        .setTupleValue("v", tupleValue)
        .build();
session.execute(bs);

Tuples are also used for multi-column IN restrictions (usually for tables with composite clustering keys):

PreparedStatement ps =
    session.prepare("SELECT * FROM ks.collect_things WHERE pk = 1 and (ck1, ck2) IN (:choice1, :choice2)");

TupleType tupleType = DataTypes.tupleOf(DataTypes.TEXT, DataTypes.TEXT);
BoundStatement bs = ps.boundStatementBuilder()
    .setTupleValue("choice1", tupleType.newValue("a", "b"))
    .setTupleValue("choice2", tupleType.newValue("c", "d"))
    .build();

If you bind the whole list of choices as a single variable, a list of tuple values is expected:

PreparedStatement ps =
    // Note the absence of parentheses around ':choices'
    session.prepare("SELECT * FROM ks.collect_things WHERE pk = 1 and (ck1, ck2) IN :choices");

TupleType tupleType = DataTypes.tupleOf(DataTypes.TEXT, DataTypes.TEXT);
List<TupleValue> choices = new ArrayList<>();
choices.add(tupleType.newValue("a", "b"));
choices.add(tupleType.newValue("c", "d"));
BoundStatement bs =
    ps.boundStatementBuilder().setList("choices", choices, TupleValue.class).build();
PREVIOUS
Query tracing
NEXT
User-defined types
  • 4.10.0.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
      • Non-blocking programming
      • 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
        • Kotlin
        • Lombok
        • Java 14 Records
        • Scala
      • DAOs
        • Custom result types
        • Delete methods
        • GetEntity methods
        • Increment 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

  • Tuples
    • Quick overview
    • Fetching tuples from results
    • Using tuples as parameters
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