ScyllaDB Docs Scylla Java Driver Manual Query builder Terms

Terms¶

A term is an expression that does not involve the value of a column. It is used:

as an argument to some selectors, for example the indices of sub-element selectors;
as the right operand of relations.

To create a term, call one of the factory methods in QueryBuilder:

Literals¶

literal() takes a Java object and inlines it as a CQL literal:

selectFrom("user").all().whereColumn("id").isEqualTo(literal(1));
// SELECT * FROM user WHERE id=1

The argument is converted according to the driver’s default type mappings. If there is no default mapping, you will get a CodecNotFoundException.

If you use custom codecs, you might need to inline a custom Java type. You can pass a CodecRegistry as the second argument (most likely, this will be the registry of your session):

MyCustomId myCustomId = ...;
CodecRegistry registry = session.getContext().getCodecRegistry();
selectFrom("user").all().whereColumn("id").isEqualTo(literal(myCustomId, registry));

Alternatively, you can pass a codec directly:

TypeCodec<MyCustomId> codec = ...;
selectFrom("user").all().whereColumn("id").isEqualTo(literal(myCustomId, codec));

Function calls¶

function() invokes a built-in or user-defined function. It takes a function name (optionally qualified with a keyspace), and a list of terms that will be passed as arguments:

selectFrom("sensor_data")
    .all()
    .whereColumn("id").isEqualTo(bindMarker())
    .whereColumn("date").isEqualTo(function("system", "currentDate"));
// SELECT * FROM sensor_data WHERE id=? AND date=system.currentdate()

Arithmetic operations¶

Terms can be combined with arithmetic operations.

CQL Operator	Selector name
`a+b`	`add`
`a-b`	`subtract`
`-a`	`negate`
`a*b`	`multiply`
`a/b`	`divide`
`a%b`	`remainder`

selectFrom("sensor_data")
    .all()
    .whereColumn("id").isEqualTo(bindMarker())
    .whereColumn("unix_timestamp").isGreaterThan(
        subtract(function("toUnixTimestamp", function("now")),
        literal(3600)));
// SELECT * FROM sensor_data WHERE id=? AND unix_timestamp>tounixtimestamp(now())-3600

Operations can be nested, and will get parenthesized according to the usual precedence rules.

Type hints¶

typeHint forces a term to a particular CQL type. For instance, it could be used to ensure that an expression uses floating-point division:

selectFrom("test")
    .all()
    .whereColumn("k").isEqualTo(literal(1))
    .whereColumn("c").isGreaterThan(divide(
            typeHint(literal(1), DataTypes.DOUBLE), 
            literal(3)));
// SELECT * FROM test WHERE k=1 AND c>(double)1/3

Raw CQL snippets¶

Finally, it is possible to provide a raw CQL snippet with raw(); it will get appended to the query as-is, without any syntax checking or escaping:

selectFrom("sensor_data").all().whereColumn("id").isEqualTo(raw("  1 /*some random comment*/"));
// SELECT * FROM sensor_data WHERE id=  1 /*some random comment*/

This should be used with caution, as it’s possible to generate invalid CQL that will fail at execution time; on the other hand, it can be used as a workaround to handle new CQL features that are not yet covered by the query builder.

Was this page helpful?

ScyllaDB Java Driver is available under the Apache v2 License. ScyllaDB Java Driver is a fork of DataStax Java Driver. See Copyright here.