com.datastax.driver.core.querybuilder
Class QueryBuilder

java.lang.Object
  com.datastax.driver.core.querybuilder.QueryBuilder

public final class QueryBuilder
extends Object

Static methods to build a CQL3 query.

The queries built by this builder will provide a value for the Query.getRoutingKey() method only when a TableMetadata is provided to the builder. It is thus advised to do so if a TokenAwarePolicy is in use.

The provider builders perform very little validation of the built query. There is thus no guarantee that a built query is valid, and it is definitively possible to create invalid queries.

Note that it could be convenient to use an 'import static' to use the methods of this class.

Method Summary

static Assignment	add(String name, Object value) Adds a value to a set column.
static Assignment	addAll(String name, Set<?> set) Adds a set of values to a set column.
static Assignment	append(String name, Object value) Append a value to a list column.
static Assignment	appendAll(String name, List<?> list) Append a list of values to a list column.
static Ordering	asc(String columnName) Ascending ordering for the provided column.
static Batch	batch(Statement... statements) Built a new BATCH query on the provided statements.
static Object	bindMarker() An object representing a bind marker (a question mark).
static Object	column(String name) Declares that the name in argument should be treated as a column name.
static Assignment	decr(String name) Decrementation of a counter column.
static Assignment	decr(String name, long value) Decrementation of a counter column by a provided value.
static Delete.Selection	delete() Start building a new DELETE query.
static Delete.Builder	delete(String... columns) Start building a new DELETE query that deletes the provided names.
static Ordering	desc(String columnName) Descending ordering for the provided column.
static Assignment	discard(String name, Object value) Discard a value from a list column.
static Assignment	discardAll(String name, List<?> list) Discard a list of values to a list column.
static Clause	eq(String name, Object value) Creates an "equal" where clause stating the provided column must be equal to the provided value.
static Object	fcall(String name, Object... parameters) Creates a function call.
static Clause	gt(String name, Object value) Creates a "greater than" where clause stating the provided column must be greater to the provided value.
static Clause	gte(String name, Object value) Creates a "greater than or equal" where clause stating the provided column must be greater than or equal to the provided value.
static Clause	in(String name, Object... values) Create an "in" where clause stating the provided column must be equal to one of the provided values.
static Assignment	incr(String name) Incrementation of a counter column.
static Assignment	incr(String name, long value) Incrementation of a counter column by a provided value.
static Insert	insertInto(String table) Start building a new INSERT query.
static Insert	insertInto(String keyspace, String table) Start building a new INSERT query.
static Insert	insertInto(TableMetadata table) Start building a new INSERT query.
static Clause	lt(String name, Object value) Creates a "lesser than" where clause stating the provided column must be less than the provided value.
static Clause	lte(String name, Object value) Creates a "lesser than or equal" where clause stating the provided column must be lesser than or equal to the provided value.
static Assignment	prepend(String name, Object value) Prepend a value to a list column.
static Assignment	prependAll(String name, List<?> list) Prepend a list of values to a list column.
static Assignment	put(String name, Object key, Object value) Puts a new key/value pair to a map column.
static Assignment	putAll(String name, Map<?,?> map) Puts a map of new key/value pairs to a map column.
static String	quote(String columnName) Quotes a columnName to make it case sensitive.
static Object	raw(String str) Creates a raw string value.
static Assignment	remove(String name, Object value) Remove a value from a set column.
static Assignment	removeAll(String name, Set<?> set) Remove a set of values from a set column.
static Select.Selection	select() Start building a new SELECT query.
static Select.Builder	select(String... columns) Start building a new SELECT query that selects the provided names.
static Assignment	set(String name, Object value) Simple "set" assignment of a value to a column.
static Assignment	setIdx(String name, int idx, Object value) Sets a list column value by index.
static Using	timestamp(long timestamp) Option to set the timestamp for a modification query (insert, update or delete).
static String	token(String... columnNames) The token of column names.
static String	token(String columnName) The token of a column name.
static Using	ttl(int ttl) Option to set the ttl for a modification query (insert, update or delete).
static Batch	unloggedBatch(Statement... statements) Built a new UNLOGGED BATCH query on the provided statements.
static Update	update(String table) Start building a new UPDATE query.
static Update	update(String keyspace, String table) Start building a new UPDATE query.
static Update	update(TableMetadata table) Start building a new UPDATE query.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

select

public static Select.Builder select(String... columns)

Start building a new SELECT query that selects the provided names. Note that select(c1, c2) is just a shortcut for select().column(c1).column(c2) .

Parameters:

columns - the columns names that should be selected by the query.

Returns:

an in-construction SELECT query (you will need to provide at least a FROM clause to complete the query).

select

public static Select.Selection select()

Start building a new SELECT query.

Returns:

an in-construction SELECT query (you will need to provide a column selection and at least a FROM clause to complete the query).

insertInto

public static Insert insertInto(String table)

Start building a new INSERT query.

Parameters:

table - the name of the table in which to insert.

Returns:

an in-construction INSERT query.

insertInto

public static Insert insertInto(String keyspace,
                                String table)

Start building a new INSERT query.

Parameters:

keyspace - the name of the keyspace to use.

table - the name of the table to insert into.

Returns:

an in-construction INSERT query.

insertInto

public static Insert insertInto(TableMetadata table)

Start building a new INSERT query.

Parameters:

table - the name of the table to insert into.

Returns:

an in-construction INSERT query.

update

public static Update update(String table)

Start building a new UPDATE query.

Parameters:

table - the name of the table to update.

Returns:

an in-construction UPDATE query (at least a SET and a WHERE clause needs to be provided to complete the query).

update

public static Update update(String keyspace,
                            String table)

Start building a new UPDATE query.

Parameters:

keyspace - the name of the keyspace to use.

table - the name of the table to update.

Returns:

an in-construction UPDATE query (at least a SET and a WHERE clause needs to be provided to complete the query).

update

public static Update update(TableMetadata table)

Start building a new UPDATE query.

Parameters:

table - the name of the table to update.

Returns:

an in-construction UPDATE query (at least a SET and a WHERE clause needs to be provided to complete the query).

delete

public static Delete.Builder delete(String... columns)

Start building a new DELETE query that deletes the provided names.

Parameters:

columns - the columns names that should be deleted by the query.

Returns:

an in-construction DELETE query (At least a FROM and a WHERE clause needs to be provided to complete the query).

delete

public static Delete.Selection delete()

Start building a new DELETE query.

Returns:

an in-construction SELECT query (you will need to provide a column selection and at least a FROM and a WHERE clause to complete the query).

batch

public static Batch batch(Statement... statements)

Built a new BATCH query on the provided statements.

This method will build a logged batch (this is the default in CQL3). To create unlogged batches, use unloggedBatch(com.datastax.driver.core.Statement...). Also note that for convenience, if the provided statements are counter statements, this method will create a COUNTER batch even though COUNTER batches are never logged (so for counters, using this method is effectively equivalent to using unloggedBatch(com.datastax.driver.core.Statement...)).

Parameters:

statements - the statements to batch.

Returns:

a new Statement that batch statements.

unloggedBatch

public static Batch unloggedBatch(Statement... statements)

Built a new UNLOGGED BATCH query on the provided statements.

Compared to logged batches (the default), unlogged batch don't use the distributed batch log server side and as such are not guaranteed to be atomic. In other words, if an unlogged batch timeout, some of the batched statements may have been persisted while some have not. Unlogged batch will however be slightly faster than logged batch.

If the statements added to the batch are counter statements, the resulting batch will be a COUNTER one.

Parameters:

statements - the statements to batch.

Returns:

a new Statement that batch statements without using the batch log.

quote

public static String quote(String columnName)

Quotes a columnName to make it case sensitive.

Parameters:

columnName - the column name to quote.

Returns:

the quoted column name.

token

public static String token(String columnName)

The token of a column name.

Parameters:

columnName - the column name to take the token of.

Returns:

"token(" + columnName + ")".

token

public static String token(String... columnNames)

The token of column names.

This variant is most useful when the partition key is composite.

Parameters:

columnNames - the column names to take the token of.

Returns:

a string representing the token of the provided column names.

eq

public static Clause eq(String name,
                        Object value)

Creates an "equal" where clause stating the provided column must be equal to the provided value.

Parameters:

name - the column name

value - the value

Returns:

the corresponding where clause.

in

public static Clause in(String name,
                        Object... values)

Create an "in" where clause stating the provided column must be equal to one of the provided values.

Parameters:

name - the column name

values - the values

Returns:

the corresponding where clause.

lt

public static Clause lt(String name,
                        Object value)

Creates a "lesser than" where clause stating the provided column must be less than the provided value.

Parameters:

name - the column name

value - the value

Returns:

the corresponding where clause.

lte

public static Clause lte(String name,
                         Object value)

Creates a "lesser than or equal" where clause stating the provided column must be lesser than or equal to the provided value.

Parameters:

name - the column name

value - the value

Returns:

the corresponding where clause.

gt

public static Clause gt(String name,
                        Object value)

Creates a "greater than" where clause stating the provided column must be greater to the provided value.

Parameters:

name - the column name

value - the value

Returns:

the corresponding where clause.

gte

public static Clause gte(String name,
                         Object value)

Creates a "greater than or equal" where clause stating the provided column must be greater than or equal to the provided value.

Parameters:

name - the column name

value - the value

Returns:

the corresponding where clause.

asc

public static Ordering asc(String columnName)

Ascending ordering for the provided column.

Parameters:

columnName - the column name

Returns:

the corresponding ordering

desc

public static Ordering desc(String columnName)

Descending ordering for the provided column.

Parameters:

columnName - the column name

Returns:

the corresponding ordering

timestamp

public static Using timestamp(long timestamp)

Option to set the timestamp for a modification query (insert, update or delete).

Parameters:

timestamp - the timestamp (in microseconds) to use.

Returns:

the corresponding option

Throws:

IllegalArgumentException - if timestamp > 0.

ttl

public static Using ttl(int ttl)

Option to set the ttl for a modification query (insert, update or delete).

Parameters:

ttl - the ttl (in seconds) to use.

Returns:

the corresponding option

Throws:

IllegalArgumentException - if ttl > 0.

set

public static Assignment set(String name,
                             Object value)

Simple "set" assignment of a value to a column.

This will generate: name = value.

Parameters:

name - the column name

value - the value to assign

Returns:

the correspond assignment (to use in an update query)

incr

public static Assignment incr(String name)

Incrementation of a counter column.

This will generate: name = name + 1.

Parameters:

name - the column name to increment

Returns:

the correspond assignment (to use in an update query)

incr

public static Assignment incr(String name,
                              long value)

Incrementation of a counter column by a provided value.

This will generate: name = name + value.

Parameters:

name - the column name to increment

value - the value by which to increment

Returns:

the correspond assignment (to use in an update query)

decr

public static Assignment decr(String name)

Decrementation of a counter column.

This will generate: name = name - 1.

Parameters:

name - the column name to decrement

Returns:

the correspond assignment (to use in an update query)

decr

public static Assignment decr(String name,
                              long value)

Decrementation of a counter column by a provided value.

This will generate: name = name - value.

Parameters:

name - the column name to decrement

value - the value by which to decrement

Returns:

the correspond assignment (to use in an update query)

prepend

public static Assignment prepend(String name,
                                 Object value)

Prepend a value to a list column.

This will generate: name = [ value ] + name.

Parameters:

name - the column name (must be of type list).

value - the value to prepend

Returns:

the correspond assignment (to use in an update query)

prependAll

public static Assignment prependAll(String name,
                                    List<?> list)

Prepend a list of values to a list column.

This will generate: name = list + name.

Parameters:

name - the column name (must be of type list).

list - the list of values to prepend

Returns:

the correspond assignment (to use in an update query)

append

public static Assignment append(String name,
                                Object value)

Append a value to a list column.

This will generate: name = name + [value].

Parameters:

name - the column name (must be of type list).

value - the value to append

Returns:

the correspond assignment (to use in an update query)

appendAll

public static Assignment appendAll(String name,
                                   List<?> list)

Append a list of values to a list column.

This will generate: name = name + list.

Parameters:

name - the column name (must be of type list).

list - the list of values to append

Returns:

the correspond assignment (to use in an update query)

discard

public static Assignment discard(String name,
                                 Object value)

Discard a value from a list column.

This will generate: name = name - [value].

Parameters:

name - the column name (must be of type list).

value - the value to discard

Returns:

the correspond assignment (to use in an update query)

discardAll

public static Assignment discardAll(String name,
                                    List<?> list)

Discard a list of values to a list column.

This will generate: name = name - list.

Parameters:

name - the column name (must be of type list).

list - the list of values to discard

Returns:

the correspond assignment (to use in an update query)

setIdx

public static Assignment setIdx(String name,
                                int idx,
                                Object value)

Sets a list column value by index.

This will generate: name[idx] = value.

Parameters:

name - the column name (must be of type list).

idx - the index to set

value - the value to set

Returns:

the correspond assignment (to use in an update query)

add

public static Assignment add(String name,
                             Object value)

Adds a value to a set column.

This will generate: name = name + {value}.

Parameters:

name - the column name (must be of type set).

value - the value to add

Returns:

the correspond assignment (to use in an update query)

addAll

public static Assignment addAll(String name,
                                Set<?> set)

Adds a set of values to a set column.

This will generate: name = name + set.

Parameters:

name - the column name (must be of type set).

set - the set of values to append

Returns:

the correspond assignment (to use in an update query)

remove

public static Assignment remove(String name,
                                Object value)

Remove a value from a set column.

This will generate: name = name - {value}.

Parameters:

name - the column name (must be of type set).

value - the value to remove

Returns:

the correspond assignment (to use in an update query)

removeAll

public static Assignment removeAll(String name,
                                   Set<?> set)

Remove a set of values from a set column.

This will generate: name = name - set.

Parameters:

name - the column name (must be of type set).

set - the set of values to remove

Returns:

the correspond assignment (to use in an update query)

put

public static Assignment put(String name,
                             Object key,
                             Object value)

Puts a new key/value pair to a map column.

This will generate: name[key] = value.

Parameters:

name - the column name (must be of type map).

key - the key to put

value - the value to put

Returns:

the correspond assignment (to use in an update query)

putAll

public static Assignment putAll(String name,
                                Map<?,?> map)

Puts a map of new key/value pairs to a map column.

This will generate: name = name + map.

Parameters:

name - the column name (must be of type map).

map - the map of key/value pairs to put

Returns:

the correspond assignment (to use in an update query)

bindMarker

public static Object bindMarker()

An object representing a bind marker (a question mark).

This can be used wherever a value is expected. For instance, one can do:

 Insert i = QueryBuilder.insertInto("test").value("k", 0)
                                               .value("c", QueryBuilder.bindMarker());
     PreparedState p = session.prepare(i.toString());
 
 

Returns:

an object representing a bind marker.

raw

public static Object raw(String str)

Creates a raw string value. This allows inputing a string value that is not interpreted/escapted by the query builder in any way. By default, the query builder escape single quotes and recognize function calls in string values. This function avoid both of those behavior.

The following table exemplify the behavior of this function:

Code	Resulting query string
select().from("t").where(eq("c", "C'est la vie!"));	"SELECT * FROM t WHERE c='C''est la vie!';"
select().from("t").where(eq("c", raw("C'est la vie!")));	"SELECT * FROM t WHERE c='C'est la vie!';"
select().from("t").where(eq("c", "now()"));	"SELECT * FROM t WHERE c=now();"
select().from("t").where(eq("c", raw("now()")));	"SELECT * FROM t WHERE c='now()';"

Note: the 2nd example in this table is not a valid CQL3 query as the quote is not correctly escaped.

Parameters:

str - the string value to use

Returns:

the value but protected from being interpreted/escaped by the query builder.

fcall

public static Object fcall(String name,
                           Object... parameters)

Creates a function call.

Parameters:

name - the name of the function to call.

parameters - the paramters for the function.

Returns:

the function call.

column

public static Object column(String name)

Declares that the name in argument should be treated as a column name.

This mainly meant for use with Select.Selection.fcall(java.lang.String, java.lang.Object...) when a function should apply to a column name, not a string value.

Parameters:

name - the name of the column.

Returns:

the name as a column name.