QueryBuilder (DataStax Java Driver for Apache Cassandra

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 Statement.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

Methods
Modifier and Type	Method and Description
`static Assignment`	`add(String name, Object value)` Adds a value to a set column.
`static Assignment`	`addAll(String name, BindMarker set)` Adds a set of values 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, BindMarker list)` Append a list of values 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(RegularStatement... statements)` Built a new BATCH query on the provided statements.
`static BindMarker`	`bindMarker()` An object representing an anonymous bind marker (a question mark).
`static BindMarker`	`bindMarker(String name)` An object representing a named bind marker.
`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, BindMarker value)` Decrementation of a counter column by a provided value.
`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, BindMarker list)` Discard a list of values to 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, BindMarker value)` Incrementation of a counter column by a provided value.
`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, BindMarker list)` Prepend a list of values 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, BindMarker map)` Puts a map of new key/value pairs 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)` Protects a value from any interpretation by the query builder.
`static Assignment`	`remove(String name, Object value)` Remove a value from a set column.
`static Assignment`	`removeAll(String name, BindMarker set)` Remove a set of values 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(BindMarker marker)` Option to prepare the timestamp (in microseconds) for a modification query (insert, update or delete).
`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 Truncate`	`truncate(String table)` Creates a new TRUNCATE query.
`static Truncate`	`truncate(String keyspace, String table)` Creates a new TRUNCATE query.
`static Truncate`	`truncate(TableMetadata table)` Creates a new TRUNCATE query.
`static Using`	`ttl(BindMarker marker)` Option to prepare the ttl (in seconds) for a modification query (insert, update or delete).
`static Using`	`ttl(int ttl)` Option to set the ttl for a modification query (insert, update or delete).
`static Batch`	`unloggedBatch(RegularStatement... 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(RegularStatement... 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.RegularStatement...). 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.RegularStatement...)).

Parameters:
statements - the statements to batch.

Returns:
a new RegularStatement that batch statements.

unloggedBatch
```
public static Batch unloggedBatch(RegularStatement... 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 RegularStatement that batch statements without using the batch log.

truncate
```
public static Truncate truncate(String table)
```
Creates a new TRUNCATE query.

Parameters:
table - the name of the table to truncate.

Returns:
the truncation query.

truncate
```
public static Truncate truncate(String keyspace,
                String table)
```
Creates a new TRUNCATE query.

Parameters:
keyspace - the name of the keyspace to use.
table - the name of the table to truncate.

Returns:
the truncation query.

truncate
```
public static Truncate truncate(TableMetadata table)
```
Creates a new TRUNCATE query.

Parameters:
table - the table to truncate.

Returns:
the truncation query.

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.

timestamp
```
public static Using timestamp(BindMarker marker)
```
Option to prepare the timestamp (in microseconds) for a modification query (insert, update or delete).

Parameters:
marker - bind marker to use for the timestamp.

Returns:
the corresponding option.

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.

ttl
```
public static Using ttl(BindMarker marker)
```
Option to prepare the ttl (in seconds) for a modification query (insert, update or delete).

Parameters:
marker - bind marker to use for the ttl.

Returns:
the corresponding option

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)

incr
```
public static Assignment incr(String name,
              BindMarker value)
```
Incrementation of a counter column by a provided value.
This will generate: name = name + value.

Parameters:
name - the column name to increment
value - a bind marker representing 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)

decr
```
public static Assignment decr(String name,
              BindMarker value)
```
Decrementation of a counter column by a provided value.
This will generate: name = name - value.

Parameters:
name - the column name to decrement
value - a bind marker representing 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)

prependAll
```
public static Assignment prependAll(String name,
                    BindMarker 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 - a bind marker representing 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)

appendAll
```
public static Assignment appendAll(String name,
                   BindMarker 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 - a bind marker representing 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)

discardAll
```
public static Assignment discardAll(String name,
                    BindMarker 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 - a bind marker representing 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)

addAll
```
public static Assignment addAll(String name,
                BindMarker 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 - a bind marker representing 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)

removeAll
```
public static Assignment removeAll(String name,
                   BindMarker 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 - a bind marker representing 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)

putAll
```
public static Assignment putAll(String name,
                BindMarker 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 - a bind marker representing the map of key/value pairs to put

Returns:
the correspond assignment (to use in an update query)

bindMarker

public static BindMarker bindMarker()

An object representing an anonymous 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:: a new bind marker.

bindMarker
```
public static BindMarker bindMarker(String name)
```
An object representing a named bind marker.
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("c_val"));
     PreparedState p = session.prepare(i.toString());
 
 
```
Please note that named bind makers are only supported starting with Cassandra 2.0.1.
Parameters:
name - the name for the bind marker.

Returns:
an object representing a bind marker named name.

raw

public static Object raw(String str)

Protects a value from any interpretation by the query builder.

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", 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 and 3rd examples in this table are not a valid CQL3 queries.

The use of that method is generally discouraged since it lead to security risks. However, if you know what you are doing, it allows to escape the interprations done by the QueryBuilder.

Parameters:: str - the raw value to use as a string
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.

Class QueryBuilder

Method Summary

Methods inherited from class java.lang.Object

Method Detail

select

select

insertInto

insertInto

insertInto

update

update

update

delete

delete

batch

unloggedBatch

truncate

truncate

truncate

quote

token

token

eq

in

lt

lte

gt

gte

asc

desc

timestamp

timestamp

ttl

ttl

set

incr

incr

incr

decr

decr

decr

prepend

prependAll

prependAll

append

appendAll

appendAll

discard

discardAll

discardAll

setIdx

add

addAll

addAll

remove

removeAll

removeAll

put

putAll

putAll

bindMarker

bindMarker

raw

fcall

column