com.datastax.driver.core.querybuilder

Class Insert

java.lang.Object

com.datastax.driver.core.Statement

com.datastax.driver.core.RegularStatement

com.datastax.driver.core.querybuilder.BuiltStatement

com.datastax.driver.core.querybuilder.Insert

public class Insert
extends BuiltStatement

A built INSERT statement.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Insert.Options The options of an INSERT statement.

Field Summary

Fields inherited from class com.datastax.driver.core.Statement

idempotent, NULL_PAYLOAD_VALUE

Method Summary

Modifier and Type	Method and Description
Insert	defaultNull() Appends a DEFAULT NULL clause to this {@code INSERT INTO ...
Insert	defaultUnset() Appends a DEFAULT UNSET clause to this {@code INSERT INTO ...
Insert	ifNotExists() Sets the 'IF NOT EXISTS' option for this INSERT statement.
Insert	json(Object json) Inserts the provided object, using the {@code INSERT INTO ...
Insert.Options	using() Returns the options for this INSERT statement.
Insert.Options	using(Using using) Adds a new options for this INSERT statement.
Insert	value(String name, Object value) Adds a column/value pair to the values inserted by this INSERT statement.
Insert	values(List<String> names, List<Object> values) Adds multiple column/value pairs to the values inserted by this INSERT statement.
Insert	values(String[] names, Object[] values) Adds multiple column/value pairs to the values inserted by this INSERT statement.

Methods inherited from class com.datastax.driver.core.querybuilder.BuiltStatement

escapeId, getKeyspace, getNamedValues, getObject, getObject, getQueryString, getRoutingKey, getValues, hasValues, isIdempotent, setForceNoValues, toString, usesNamedValues

Methods inherited from class com.datastax.driver.core.RegularStatement

getQueryString, getRoutingToken, hasValues, setRoutingToken

Methods inherited from class com.datastax.driver.core.Statement

disableTracing, enableTracing, executingAs, getConsistencyLevel, getDefaultTimestamp, getFetchSize, getOutgoingPayload, getReadTimeoutMillis, getRetryPolicy, getSerialConsistencyLevel, isBatchIdempotent, isTracing, setConsistencyLevel, setDefaultTimestamp, setFetchSize, setIdempotent, setOutgoingPayload, setPagingState, setPagingState, setPagingStateUnsafe, setReadTimeoutMillis, setRetryPolicy, setSerialConsistencyLevel

Methods inherited from class java.lang.Object

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

Method Detail

value

public Insert value(String name,
                    Object value)

Adds a column/value pair to the values inserted by this INSERT statement.

Parameters:

name - the name of the column to insert/update.

value - the value to insert/update for name.

Returns:

this INSERT statement.

Throws:

IllegalStateException - if this method is called and the json(Object) method has been called before, because it's not possible to mix INSERT JSON syntax with regular INSERT syntax.

values

public Insert values(String[] names,
                     Object[] values)

Adds multiple column/value pairs to the values inserted by this INSERT statement.

Parameters:

names - a list of column names to insert/update.

values - a list of values to insert/update. The ith value in values will be inserted for the ith column in names.

Returns:

this INSERT statement.

Throws:

IllegalArgumentException - if names.length != values.length.

IllegalStateException - if this method is called and the json(Object) method has been called before, because it's not possible to mix INSERT JSON syntax with regular INSERT syntax.

values

public Insert values(List<String> names,
                     List<Object> values)

Adds multiple column/value pairs to the values inserted by this INSERT statement.

Parameters:

names - a list of column names to insert/update.

values - a list of values to insert/update. The ith value in values will be inserted for the ith column in names.

Returns:

this INSERT statement.

Throws:

IllegalArgumentException - if names.size() != values.size().

IllegalStateException - if this method is called and the json(Object) method has been called before, because it's not possible to mix INSERT JSON syntax with regular INSERT syntax.

json

public Insert json(Object json)

Inserts the provided object, using the INSERT INTO ... JSON syntax introduced in Cassandra 2.2.

With INSERT statements, the new JSON keyword can be used to enable inserting a JSON structure as a single row.

The provided object can be of the following types:

1. A raw string. In this case, it will be appended to the query string as is. It should NOT be surrounded by single quotes. Its format should generally match that returned by a SELECT JSON statement on the same table. Note that it is not possible to insert function calls nor bind markers in a JSON string.
2. A bind marker. In this case, the statement is meant to be prepared and no JSON string will be appended to the query string, only a bind marker for the whole JSON parameter.
3. Any object that can be serialized to JSON. Such objects can be used provided that a matching codec is registered with the CodecRegistry in use. This allows the usage of JSON libraries, such as the Java API for JSON processing, the popular Jackson library, or Google's Gson library, for instance.

Case-sensitive column names

When passing raw strings to this method, users are required to handle case-sensitive column names by surrounding them with double quotes.

For example, to insert into a table with two columns named “myKey” and “value”, you would do the following:

 insertInto("mytable").json("{\"\\\"myKey\\\"\": 0, \"value\": 0}");
 

This will produce the following CQL:

 INSERT INTO mytable JSON '{"\"myKey\"": 0, "value": 0}';
 

Escaping quotes in column values

When passing raw strings to this method, double quotes should be escaped with a backslash, but single quotes should be escaped in the CQL manner, i.e. by another single quote. For example, the column value foo"'bar should be inserted in the JSON string as "foo\"''bar".

Null values and tombstones

Any columns which are omitted from the JSON string will be defaulted to a NULL value (which will result in a tombstone being created).

Parameters:

json - the JSON string, or a bind marker, or a JSON object handled by a specific codec.

Returns:

this INSERT statement.

Throws:

IllegalStateException - if this method is called and any of the value or values methods have been called before, because it's not possible to mix INSERT JSON syntax with regular INSERT syntax.

See Also:

JSON Support for CQL, JSON Support in Cassandra 2.2, Inserting JSON data

defaultUnset

public Insert defaultUnset()

Appends a DEFAULT UNSET clause to this INSERT INTO ... JSON statement.

Support for DEFAULT UNSET has been introduced in Cassandra 3.10.

Returns:

this INSERT statement.

Throws:

IllegalStateException - if this method is called and any of the value or values methods have been called before, because it's not possible to mix INSERT JSON syntax with regular INSERT syntax.

defaultNull

public Insert defaultNull()

Appends a DEFAULT NULL clause to this INSERT INTO ... JSON statement.

Support for DEFAULT NULL has been introduced in Cassandra 3.10.

Returns:

this INSERT statement.

Throws:

IllegalStateException - if this method is called and any of the value or values methods have been called before, because it's not possible to mix INSERT JSON syntax with regular INSERT syntax.

using

public Insert.Options using(Using using)

Adds a new options for this INSERT statement.

Parameters:

using - the option to add.

Returns:

the options of this INSERT statement.

using

public Insert.Options using()

Returns the options for this INSERT statement.

Chain this with Insert.Options.and(Using) to add options.

Returns:

the options of this INSERT statement.

ifNotExists

public Insert ifNotExists()

Sets the 'IF NOT EXISTS' option for this INSERT statement.

An insert with that option will not succeed unless the row does not exist at the time the insertion is executed. The existence check and insertions are done transactionally in the sense that if multiple clients attempt to create a given row with this option, then at most one may succeed.

Please keep in mind that using this option has a non negligible performance impact and should be avoided when possible.

This will configure the statement as non-idempotent, see Statement.isIdempotent() for more information.

Returns:

this INSERT statement.