Package com.datastax.driver.core.querybuilder

Class Insert

  • public class Insert
extends BuiltStatement
    A built INSERT statement.

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

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