diff --git a/.gitignore b/.gitignore index 4f33eda38b..f5b1ce1cee 100644 --- a/.gitignore +++ b/.gitignore @@ -74,4 +74,4 @@ lib/jsr223/scala/*.jar /.ant-targets-build.xml # Generated files from the documentation -doc/source/cassandra_config_file.rst +doc/source/configuration/cassandra_config_file.rst diff --git a/doc/convert_yaml_to_rst.py b/doc/convert_yaml_to_rst.py index 398295d509..fee6d8c10b 100644 --- a/doc/convert_yaml_to_rst.py +++ b/doc/convert_yaml_to_rst.py @@ -59,7 +59,7 @@ def convert(yaml_file, dest_file): with open(dest_file, 'w') as outfile: outfile.write("Cassandra Configuration File\n") - outfile.write("=====================\n") + outfile.write("============================\n") # since comments preceed an option, this holds all of the comment # lines we've seen since the last option diff --git a/doc/source/cql/appendices.rst b/doc/source/cql/appendices.rst index 9788a56993..c4bb839071 100644 --- a/doc/source/cql/appendices.rst +++ b/doc/source/cql/appendices.rst @@ -300,8 +300,6 @@ names as their name. +-----------------+ | ``complex`` | +-----------------+ -| ``date`` | -+-----------------+ | ``enum`` | +-----------------+ | ``interval`` | diff --git a/doc/source/cql/changes.rst b/doc/source/cql/changes.rst index 9549f8f5f4..263df135d5 100644 --- a/doc/source/cql/changes.rst +++ b/doc/source/cql/changes.rst @@ -24,234 +24,166 @@ The following describes the changes in each version of CQL. 3.4.2 ^^^^^ -- ```INSERT/UPDATE options`` <#updateOptions>`__ for tables having a - default\_time\_to\_live specifying a TTL of 0 will remove the TTL - from the inserted or updated values -- ```ALTER TABLE`` <#alterTableStmt>`__ ``ADD`` and ``DROP`` now allow - mutiple columns to be added/removed -- New ```PER PARTITION LIMIT`` <#selectLimit>`__ option (see - `CASSANDRA-7017 `__. -- `User-defined functions <#udfs>`__ can now instantiate ``UDTValue`` - and ``TupleValue`` instances via the new ``UDFContext`` interface - (see - `CASSANDRA-10818 `__. -- “User-defined types”#createTypeStmt may now be stored in a non-frozen - form, allowing individual fields to be updated and deleted in - ```UPDATE`` statements <#updateStmt>`__ and ```DELETE`` - statements <#deleteStmt>`__, respectively. - (`CASSANDRA-7423 `__ +- If a table has a non zero ``default_time_to_live``, then explicitly specifying a TTL of 0 in an ``INSERT`` or + ``UPDATE`` statement will result in the new writes not having any expiration (that is, an explicit TTL of 0 cancels + the ``default_time_to_live``). This wasn't the case before and the ``default_time_to_live`` was applied even though a + TTL had been explicitly set. +- ``ALTER TABLE`` ``ADD`` and ``DROP`` now allow multiple columns to be added/removed. +- New ``PER PARTITION LIMIT`` option for ``SELECT`` statements (see `CASSANDRA-7017 + `__. +- :ref:`User-defined functions ` can now instantiate ``UDTValue`` and ``TupleValue`` instances via the + new ``UDFContext`` interface (see `CASSANDRA-10818 `__. +- :ref:`User-defined types ` may now be stored in a non-frozen form, allowing individual fields to be updated and + deleted in ``UPDATE`` statements and ``DELETE`` statements, respectively. (`CASSANDRA-7423 + `__). 3.4.1 ^^^^^ -- Adds ``CAST`` functions. See ```Cast`` <#castFun>`__. +- Adds ``CAST`` functions. 3.4.0 ^^^^^ -- Support for `materialized views <#createMVStmt>`__ -- ```DELETE`` <#deleteStmt>`__ support for inequality expressions and - ``IN`` restrictions on any primary key columns -- ```UPDATE`` <#updateStmt>`__ support for ``IN`` restrictions on any - primary key columns +- Support for :ref:`materialized views `. +- ``DELETE`` support for inequality expressions and ``IN`` restrictions on any primary key columns. +- ``UPDATE`` support for ``IN`` restrictions on any primary key columns. 3.3.1 ^^^^^ -- The syntax ``TRUNCATE TABLE X`` is now accepted as an alias for - ``TRUNCATE X`` +- The syntax ``TRUNCATE TABLE X`` is now accepted as an alias for ``TRUNCATE X``. 3.3.0 ^^^^^ -- Adds new `aggregates <#aggregates>`__ -- User-defined functions are now supported through - ```CREATE FUNCTION`` <#createFunctionStmt>`__ and - ```DROP FUNCTION`` <#dropFunctionStmt>`__. -- User-defined aggregates are now supported through - ```CREATE AGGREGATE`` <#createAggregateStmt>`__ and - ```DROP AGGREGATE`` <#dropAggregateStmt>`__. -- Allows double-dollar enclosed strings literals as an alternative to - single-quote enclosed strings. -- Introduces Roles to supercede user based authentication and access - control -- ```Date`` <#usingdates>`__ and ```Time`` `__ data types - have been added -- ```JSON`` <#json>`__ support has been added -- ``Tinyint`` and ``Smallint`` data types have been added -- Adds new time conversion functions and deprecate ``dateOf`` and - ``unixTimestampOf``. See ```Time conversion functions`` <#timeFun>`__ +- :ref:`User-defined functions and aggregates ` are now supported. +- Allows double-dollar enclosed strings literals as an alternative to single-quote enclosed strings. +- Introduces Roles to supersede user based authentication and access control +- New ``date``, ``time``, ``tinyint`` and ``smallint`` :ref:`data types ` have been added. +- :ref:`JSON support ` has been added +- Adds new time conversion functions and deprecate ``dateOf`` and ``unixTimestampOf``. 3.2.0 ^^^^^ -- User-defined types are now supported through - ```CREATE TYPE`` <#createTypeStmt>`__, - ```ALTER TYPE`` <#alterTypeStmt>`__, and - ```DROP TYPE`` <#dropTypeStmt>`__ -- ```CREATE INDEX`` <#createIndexStmt>`__ now supports indexing - collection columns, including indexing the keys of map collections - through the ``keys()`` function -- Indexes on collections may be queried using the new ``CONTAINS`` and - ``CONTAINS KEY`` operators -- Tuple types were added to hold fixed-length sets of typed positional - fields (see the section on `types <#types>`__ ) -- ```DROP INDEX`` <#dropIndexStmt>`__ now supports optionally - specifying a keyspace +- :ref:`User-defined types ` supported. +- ``CREATE INDEX`` now supports indexing collection columns, including indexing the keys of map collections through the + ``keys()`` function +- Indexes on collections may be queried using the new ``CONTAINS`` and ``CONTAINS KEY`` operators +- :ref:`Tuple types ` were added to hold fixed-length sets of typed positional fields. +- ``DROP INDEX`` now supports optionally specifying a keyspace. 3.1.7 ^^^^^ -- ``SELECT`` statements now support selecting multiple rows in a single - partition using an ``IN`` clause on combinations of clustering - columns. See `SELECT WHERE <#selectWhere>`__ clauses. -- ``IF NOT EXISTS`` and ``IF EXISTS`` syntax is now supported by - ``CREATE USER`` and ``DROP USER`` statmenets, respectively. +- ``SELECT`` statements now support selecting multiple rows in a single partition using an ``IN`` clause on combinations + of clustering columns. +- ``IF NOT EXISTS`` and ``IF EXISTS`` syntax is now supported by ``CREATE USER`` and ``DROP USER`` statements, + respectively. 3.1.6 ^^^^^ -- A new ```uuid`` method <#uuidFun>`__ has been added. -- Support for ``DELETE ... IF EXISTS`` syntax. +- A new ``uuid()`` method has been added. +- Support for ``DELETE ... IF EXISTS`` syntax. 3.1.5 ^^^^^ -- It is now possible to group clustering columns in a relatiion, see - `SELECT WHERE <#selectWhere>`__ clauses. -- Added support for ``STATIC`` columns, see `static in CREATE - TABLE <#createTableStatic>`__. +- It is now possible to group clustering columns in a relation, see :ref:`WHERE ` clauses. +- Added support for :ref:`static columns `. 3.1.4 ^^^^^ -- ``CREATE INDEX`` now allows specifying options when creating CUSTOM - indexes (see `CREATE INDEX reference <#createIndexStmt>`__ ). +- ``CREATE INDEX`` now allows specifying options when creating CUSTOM indexes. 3.1.3 ^^^^^ -- Millisecond precision formats have been added to the timestamp parser - (see `working with dates <#usingtimestamps>`__ ). +- Millisecond precision formats have been added to the :ref:`timestamp ` parser. 3.1.2 ^^^^^ -- ``NaN`` and ``Infinity`` has been added as valid float contants. They - are now reserved keywords. In the unlikely case you we using them as - a column identifier (or keyspace/table one), you will noew need to - double quote them (see `quote identifiers <#identifiers>`__ ). +- ``NaN`` and ``Infinity`` has been added as valid float constants. They are now reserved keywords. In the unlikely case + you we using them as a column identifier (or keyspace/table one), you will now need to double quote them. 3.1.1 ^^^^^ -- ``SELECT`` statement now allows listing the partition keys (using the - ``DISTINCT`` modifier). See - `CASSANDRA-4536 `__. -- The syntax ``c IN ?`` is now supported in ``WHERE`` clauses. In that - case, the value expected for the bind variable will be a list of - whatever type ``c`` is. -- It is now possible to use named bind variables (using ``:name`` - instead of ``?``). +- ``SELECT`` statement now allows listing the partition keys (using the ``DISTINCT`` modifier). See `CASSANDRA-4536 + `__. +- The syntax ``c IN ?`` is now supported in ``WHERE`` clauses. In that case, the value expected for the bind variable + will be a list of whatever type ``c`` is. +- It is now possible to use named bind variables (using ``:name`` instead of ``?``). 3.1.0 ^^^^^ -- `ALTER TABLE <#alterTableStmt>`__ ``DROP`` option has been reenabled - for CQL3 tables and has new semantics now: the space formerly used by - dropped columns will now be eventually reclaimed (post-compaction). - You should not readd previously dropped columns unless you use - timestamps with microsecond precision (see - `CASSANDRA-3919 `__ - for more details). -- ``SELECT`` statement now supports aliases in select clause. Aliases - in WHERE and ORDER BY clauses are not supported. See the `section on - select <#selectStmt>`__ for details. -- ``CREATE`` statements for ``KEYSPACE``, ``TABLE`` and ``INDEX`` now - supports an ``IF NOT EXISTS`` condition. Similarly, ``DROP`` - statements support a ``IF EXISTS`` condition. -- ``INSERT`` statements optionally supports a ``IF NOT EXISTS`` - condition and ``UPDATE`` supports ``IF`` conditions. +- ``ALTER TABLE`` ``DROP`` option added. +- ``SELECT`` statement now supports aliases in select clause. Aliases in WHERE and ORDER BY clauses are not supported. +- ``CREATE`` statements for ``KEYSPACE``, ``TABLE`` and ``INDEX`` now supports an ``IF NOT EXISTS`` condition. + Similarly, ``DROP`` statements support a ``IF EXISTS`` condition. +- ``INSERT`` statements optionally supports a ``IF NOT EXISTS`` condition and ``UPDATE`` supports ``IF`` conditions. 3.0.5 ^^^^^ -- ``SELECT``, ``UPDATE``, and ``DELETE`` statements now allow empty - ``IN`` relations (see - `CASSANDRA-5626 `__. +- ``SELECT``, ``UPDATE``, and ``DELETE`` statements now allow empty ``IN`` relations (see `CASSANDRA-5626 + `__. 3.0.4 ^^^^^ -- Updated the syntax for custom `secondary - indexes <#createIndexStmt>`__. -- Non-equal condition on the partition key are now never supported, - even for ordering partitioner as this was not correct (the order was - **not** the one of the type of the partition key). Instead, the - ``token`` method should always be used for range queries on the - partition key (see `WHERE clauses <#selectWhere>`__ ). +- Updated the syntax for custom :ref:`secondary indexes `. +- Non-equal condition on the partition key are now never supported, even for ordering partitioner as this was not + correct (the order was **not** the one of the type of the partition key). Instead, the ``token`` method should always + be used for range queries on the partition key (see :ref:`WHERE clauses `). 3.0.3 ^^^^^ -- Support for custom `secondary indexes <#createIndexStmt>`__ has been - added. +- Support for custom :ref:`secondary indexes ` has been added. 3.0.2 ^^^^^ -- Type validation for the `constants <#constants>`__ has been fixed. - For instance, the implementation used to allow ``'2'`` as a valid - value for an ``int`` column (interpreting it has the equivalent of - ``2``), or ``42`` as a valid ``blob`` value (in which case ``42`` was - interpreted as an hexadecimal representation of the blob). This is no - longer the case, type validation of constants is now more strict. See - the `data types <#types>`__ section for details on which constant is - allowed for which type. -- The type validation fixed of the previous point has lead to the - introduction of `blobs constants <#constants>`__ to allow inputing - blobs. Do note that while inputing blobs as strings constant is still - supported by this version (to allow smoother transition to blob - constant), it is now deprecated (in particular the `data - types <#types>`__ section does not list strings constants as valid - blobs) and will be removed by a future version. If you were using - strings as blobs, you should thus update your client code ASAP to - switch blob constants. -- A number of functions to convert native types to blobs have also been - introduced. Furthermore the token function is now also allowed in - select clauses. See the `section on functions <#functions>`__ for - details. +- Type validation for the :ref:`constants ` has been fixed. For instance, the implementation used to allow + ``'2'`` as a valid value for an ``int`` column (interpreting it has the equivalent of ``2``), or ``42`` as a valid + ``blob`` value (in which case ``42`` was interpreted as an hexadecimal representation of the blob). This is no longer + the case, type validation of constants is now more strict. See the :ref:`data types ` section for details + on which constant is allowed for which type. +- The type validation fixed of the previous point has lead to the introduction of blobs constants to allow the input of + blobs. Do note that while the input of blobs as strings constant is still supported by this version (to allow smoother + transition to blob constant), it is now deprecated and will be removed by a future version. If you were using strings + as blobs, you should thus update your client code ASAP to switch blob constants. +- A number of functions to convert native types to blobs have also been introduced. Furthermore the token function is + now also allowed in select clauses. See the :ref:`section on functions ` for details. 3.0.1 ^^^^^ -- `Date strings <#usingtimestamps>`__ (and timestamps) are no longer - accepted as valid ``timeuuid`` values. Doing so was a bug in the - sense that date string are not valid ``timeuuid``, and it was thus - resulting in `confusing - behaviors `__. - However, the following new methods have been added to help working - with ``timeuuid``: ``now``, ``minTimeuuid``, ``maxTimeuuid`` , - ``dateOf`` and ``unixTimestampOf``. See the `section dedicated to - these methods <#timeuuidFun>`__ for more detail. -- “Float constants”#constants now support the exponent notation. In - other words, ``4.2E10`` is now a valid floating point value. +- Date strings (and timestamps) are no longer accepted as valid ``timeuuid`` values. Doing so was a bug in the sense + that date string are not valid ``timeuuid``, and it was thus resulting in `confusing behaviors + `__. However, the following new methods have been added to help + working with ``timeuuid``: ``now``, ``minTimeuuid``, ``maxTimeuuid`` , + ``dateOf`` and ``unixTimestampOf``. +- Float constants now support the exponent notation. In other words, ``4.2E10`` is now a valid floating point value. Versioning ^^^^^^^^^^ -Versioning of the CQL language adheres to the `Semantic -Versioning `__ guidelines. Versions take the form -X.Y.Z where X, Y, and Z are integer values representing major, minor, -and patch level respectively. There is no correlation between Cassandra -release versions and the CQL language version. +Versioning of the CQL language adheres to the `Semantic Versioning `__ guidelines. Versions take the +form X.Y.Z where X, Y, and Z are integer values representing major, minor, and patch level respectively. There is no +correlation between Cassandra release versions and the CQL language version. -+-----------+-------------------------------------------------------------------------------------------------------------------+ -| version | description | -+===========+===================================================================================================================+ -| Major | The major version *must* be bumped when backward incompatible changes are introduced. This should rarely occur. | -+-----------+-------------------------------------------------------------------------------------------------------------------+ -| Minor | Minor version increments occur when new, but backward compatible, functionality is introduced. | -+-----------+-------------------------------------------------------------------------------------------------------------------+ -| Patch | The patch version is incremented when bugs are fixed. | -+-----------+-------------------------------------------------------------------------------------------------------------------+ +========= ============================================================================================================= + version description +========= ============================================================================================================= + Major The major version *must* be bumped when backward incompatible changes are introduced. This should rarely + occur. + Minor Minor version increments occur when new, but backward compatible, functionality is introduced. + Patch The patch version is incremented when bugs are fixed. +========= ============================================================================================================= diff --git a/doc/source/cql/ddl.rst b/doc/source/cql/ddl.rst index 6c3b6d125b..948298bd38 100644 --- a/doc/source/cql/ddl.rst +++ b/doc/source/cql/ddl.rst @@ -76,7 +76,6 @@ For instance:: AND durable_writes = false; -.. _create-keyspace-options: The supported ``options`` are: =================== ========== =========== ========= =================================================================== @@ -127,9 +126,9 @@ An ``ALTER KEYSPACE`` statement allows to modify the options of a keyspace: For instance:: ALTER KEYSPACE Excelsior - WITH replication = {’class’: ‘SimpleStrategy’, ‘replication_factor’ : 4}; + WITH replication = {'class': 'SimpleStrategy', 'replication_factor' : 4}; -The supported options are the same than for :ref:`creating a keyspace `. +The supported options are the same than for :ref:`creating a keyspace `. .. _drop-keyspace-statement: @@ -182,7 +181,7 @@ For instance:: common_name text, population varint, average_size int - ) WITH comment=‘Important biological records’ + ) WITH comment='Important biological records' AND read_repair_chance = 1.0; CREATE TABLE timeline ( @@ -192,7 +191,7 @@ For instance:: body text, posted_by text, PRIMARY KEY (userid, posted_month, posted_time) - ) WITH compaction = { ‘class’ : ‘LeveledCompactionStrategy’ }; + ) WITH compaction = { 'class' : 'LeveledCompactionStrategy' }; CREATE TABLE loads ( machine inet, @@ -373,7 +372,7 @@ retrieval of a range of rows within a partition (for instance, in the example ab > 1 and b <= 3``) very efficient. -.. _create-table-options +.. _create-table-options: Table options ~~~~~~~~~~~~~ @@ -385,7 +384,7 @@ Amongst those options, two important ones cannot be changed after creation and i against the table: the ``COMPACT STORAGE`` option and the ``CLUSTERING ORDER`` option. Those, as well as the other options of a table are described in the following sections. -.. _compact-storage: +.. _compact-tables: Compact tables `````````````` @@ -393,7 +392,7 @@ Compact tables .. warning:: Since Cassandra 3.0, compact tables have the exact same layout internally than non compact ones (for the same schema obviously), and declaring a table compact **only** creates artificial limitations on the table definition and usage that are necessary to ensure backward compatibility with the deprecated Thrift API. And as ``COMPACT - STORAGE`` cannot, as of Cassandra |3.8|, be removed, it is strongly discouraged to create new table with the + STORAGE`` cannot, as of Cassandra |version|, be removed, it is strongly discouraged to create new table with the ``COMPACT STORAGE`` option. A *compact* table is one defined with the ``COMPACT STORAGE`` option. This option is mainly targeted towards backward @@ -445,116 +444,108 @@ Other table options A table supports the following options: -+----------------------------------+------------+---------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| option | kind | default | description | -+==================================+============+===============+=================================================================================================================================================================================================================================+ -| ``comment`` | *simple* | none | A free-form, human-readable comment. | -+----------------------------------+------------+---------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``read_repair_chance`` | *simple* | 0.1 | The probability with which to query extra nodes (e.g. more nodes than required by the consistency level) for the purpose of read repairs. | -+----------------------------------+------------+---------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``dclocal_read_repair_chance`` | *simple* | 0 | The probability with which to query extra nodes (e.g. more nodes than required by the consistency level) belonging to the same data center than the read coordinator for the purpose of read repairs. | -+----------------------------------+------------+---------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``gc_grace_seconds`` | *simple* | 864000 | Time to wait before garbage collecting tombstones (deletion markers). | -+----------------------------------+------------+---------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``bloom_filter_fp_chance`` | *simple* | 0.00075 | The target probability of false positive of the sstable bloom filters. Said bloom filters will be sized to provide the provided probability (thus lowering this value impact the size of bloom filters in-memory and on-disk) | -+----------------------------------+------------+---------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``default_time_to_live`` | *simple* | 0 | The default expiration time (“TTL”) in seconds for a table. | -+----------------------------------+------------+---------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``compaction`` | *map* | *see below* | Compaction options, see “below”:#compactionOptions. | -+----------------------------------+------------+---------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``compression`` | *map* | *see below* | Compression options, see “below”:#compressionOptions. | -+----------------------------------+------------+---------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``caching`` | *map* | *see below* | Caching options, see “below”:#cachingOptions. | -+----------------------------------+------------+---------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ ++--------------------------------+----------+-------------+-----------------------------------------------------------+ +| option | kind | default | description | ++================================+==========+=============+===========================================================+ +| ``comment`` | *simple* | none | A free-form, human-readable comment. | ++--------------------------------+----------+-------------+-----------------------------------------------------------+ +| ``read_repair_chance`` | *simple* | 0.1 | The probability with which to query extra nodes (e.g. | +| | | | more nodes than required by the consistency level) for | +| | | | the purpose of read repairs. | ++--------------------------------+----------+-------------+-----------------------------------------------------------+ +| ``dclocal_read_repair_chance`` | *simple* | 0 | The probability with which to query extra nodes (e.g. | +| | | | more nodes than required by the consistency level) | +| | | | belonging to the same data center than the read | +| | | | coordinator for the purpose of read repairs. | ++--------------------------------+----------+-------------+-----------------------------------------------------------+ +| ``gc_grace_seconds`` | *simple* | 864000 | Time to wait before garbage collecting tombstones | +| | | | (deletion markers). | ++--------------------------------+----------+-------------+-----------------------------------------------------------+ +| ``bloom_filter_fp_chance`` | *simple* | 0.00075 | The target probability of false positive of the sstable | +| | | | bloom filters. Said bloom filters will be sized to provide| +| | | | the provided probability (thus lowering this value impact | +| | | | the size of bloom filters in-memory and on-disk) | ++--------------------------------+----------+-------------+-----------------------------------------------------------+ +| ``default_time_to_live`` | *simple* | 0 | The default expiration time (“TTL”) in seconds for a | +| | | | table. | ++--------------------------------+----------+-------------+-----------------------------------------------------------+ +| ``compaction`` | *map* | *see below* | :ref:`Compaction options `. | ++--------------------------------+----------+-------------+-----------------------------------------------------------+ +| ``compression`` | *map* | *see below* | :ref:`Compression options `. | ++--------------------------------+----------+-------------+-----------------------------------------------------------+ +| ``caching`` | *map* | *see below* | :ref:`Caching options `. | ++--------------------------------+----------+-------------+-----------------------------------------------------------+ + +.. _cql-compaction-options: Compaction options ################## -The ``compaction`` property must at least define the ``'class'`` -sub-option, that defines the compaction strategy class to use. The -default supported class are ``'SizeTieredCompactionStrategy'``, -``'LeveledCompactionStrategy'``, ``'DateTieredCompactionStrategy'`` and -``'TimeWindowCompactionStrategy'``. Custom strategy can be provided by -specifying the full class name as a `string constant <#constants>`__. -The rest of the sub-options depends on the chosen class. The sub-options -supported by the default classes are: +The ``compaction`` options must at least define the ``'class'`` sub-option, that defines the compaction strategy class +to use. The default supported class are ``'SizeTieredCompactionStrategy'`` (:ref:`STCS `), +``'LeveledCompactionStrategy'`` (:ref:`LCS `) and ``'TimeWindowCompactionStrategy'`` (:ref:`TWCS `) (the +``'DateTieredCompactionStrategy'`` is also supported but is deprecated and ``'TimeWindowCompactionStrategy'`` should be +preferred instead). Custom strategy can be provided by specifying the full class name as a :ref:`string constant +`. -+--------------------------------------+---------------------------------+----------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| option | supported compaction strategy | default | description | -+======================================+=================================+================+========================================================================================================================================================================================================================================================================================================================================+ -| ``enabled`` | *all* | true | A boolean denoting whether compaction should be enabled or not. | -+--------------------------------------+---------------------------------+----------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``tombstone_threshold`` | *all* | 0.2 | A ratio such that if a sstable has more than this ratio of gcable tombstones over all contained columns, the sstable will be compacted (with no other sstables) for the purpose of purging those tombstones. | -+--------------------------------------+---------------------------------+----------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``tombstone_compaction_interval`` | *all* | 1 day | The minimum time to wait after an sstable creation time before considering it for “tombstone compaction”, where “tombstone compaction” is the compaction triggered if the sstable has more gcable tombstones than ``tombstone_threshold``. | -+--------------------------------------+---------------------------------+----------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``unchecked_tombstone_compaction`` | *all* | false | Setting this to true enables more aggressive tombstone compactions - single sstable tombstone compactions will run without checking how likely it is that they will be successful. | -+--------------------------------------+---------------------------------+----------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``min_sstable_size`` | SizeTieredCompactionStrategy | 50MB | The size tiered strategy groups SSTables to compact in buckets. A bucket groups SSTables that differs from less than 50% in size. However, for small sizes, this would result in a bucketing that is too fine grained. ``min_sstable_size`` defines a size threshold (in bytes) below which all SSTables belong to one unique bucket | -+--------------------------------------+---------------------------------+----------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``min_threshold`` | SizeTieredCompactionStrategy | 4 | Minimum number of SSTables needed to start a minor compaction. | -+--------------------------------------+---------------------------------+----------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``max_threshold`` | SizeTieredCompactionStrategy | 32 | Maximum number of SSTables processed by one minor compaction. | -+--------------------------------------+---------------------------------+----------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``bucket_low`` | SizeTieredCompactionStrategy | 0.5 | Size tiered consider sstables to be within the same bucket if their size is within [average\_size \* ``bucket_low``, average\_size \* ``bucket_high`` ] (i.e the default groups sstable whose sizes diverges by at most 50%) | -+--------------------------------------+---------------------------------+----------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``bucket_high`` | SizeTieredCompactionStrategy | 1.5 | Size tiered consider sstables to be within the same bucket if their size is within [average\_size \* ``bucket_low``, average\_size \* ``bucket_high`` ] (i.e the default groups sstable whose sizes diverges by at most 50%). | -+--------------------------------------+---------------------------------+----------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``sstable_size_in_mb`` | LeveledCompactionStrategy | 5MB | The target size (in MB) for sstables in the leveled strategy. Note that while sstable sizes should stay less or equal to ``sstable_size_in_mb``, it is possible to exceptionally have a larger sstable as during compaction, data for a given partition key are never split into 2 sstables | -+--------------------------------------+---------------------------------+----------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``timestamp_resolution`` | DateTieredCompactionStrategy | MICROSECONDS | The timestamp resolution used when inserting data, could be MILLISECONDS, MICROSECONDS etc (should be understandable by Java TimeUnit) - don’t change this unless you do mutations with USING TIMESTAMP (or equivalent directly in the client) | -+--------------------------------------+---------------------------------+----------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``base_time_seconds`` | DateTieredCompactionStrategy | 60 | The base size of the time windows. | -+--------------------------------------+---------------------------------+----------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``max_sstable_age_days`` | DateTieredCompactionStrategy | 365 | SSTables only containing data that is older than this will never be compacted. | -+--------------------------------------+---------------------------------+----------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``timestamp_resolution`` | TimeWindowCompactionStrategy | MICROSECONDS | The timestamp resolution used when inserting data, could be MILLISECONDS, MICROSECONDS etc (should be understandable by Java TimeUnit) - don’t change this unless you do mutations with USING TIMESTAMP (or equivalent directly in the client) | -+--------------------------------------+---------------------------------+----------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``compaction_window_unit`` | TimeWindowCompactionStrategy | DAYS | The Java TimeUnit used for the window size, set in conjunction with ``compaction_window_size``. Must be one of DAYS, HOURS, MINUTES | -+--------------------------------------+---------------------------------+----------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``compaction_window_size`` | TimeWindowCompactionStrategy | 1 | The number of ``compaction_window_unit`` units that make up a time window. | -+--------------------------------------+---------------------------------+----------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +All default strategies support a number of :ref:`common options `, as well as options specific to +the strategy chosen (see the section corresponding to your strategy for details: :ref:`STCS `, :ref:`LCS +` and :ref:`TWCS `). + +.. _cql-compression-options: Compression options ################### -For the ``compression`` property, the following sub-options are +The ``compression`` options define if and how the sstables of the table are compressed. The following sub-options are available: -+------------------------+-----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| option | default | description | -+========================+=================+=======================================================================================================================================================================================================================================================================================================================================================================================================================+ -| ``class`` | LZ4Compressor | The compression algorithm to use. Default compressor are: LZ4Compressor, SnappyCompressor and DeflateCompressor. Use ``'enabled' : false`` to disable compression. Custom compressor can be provided by specifying the full class name as a “string constant”:#constants. | -+------------------------+-----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``enabled`` | true | By default compression is enabled. To disable it, set ``enabled`` to ``false`` | -+------------------------+-----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -|`` chunk_length_in_kb`` | 64KB | On disk SSTables are compressed by block (to allow random reads). This defines the size (in KB) of said block. Bigger values may improve the compression rate, but increases the minimum size of data to be read from disk for a read | -+------------------------+-----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``crc_check_chance`` | 1.0 | When compression is enabled, each compressed block includes a checksum of that block for the purpose of detecting disk bitrot and avoiding the propagation of corruption to other replica. This option defines the probability with which those checksums are checked during read. By default they are always checked. Set to 0 to disable checksum checking and to 0.5 for instance to check them every other read | -+------------------------+-----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +========================= =============== ============================================================================= + Option Default Description +========================= =============== ============================================================================= + ``class`` LZ4Compressor The compression algorithm to use. Default compressor are: LZ4Compressor, + SnappyCompressor and DeflateCompressor. Use ``'enabled' : false`` to disable + compression. Custom compressor can be provided by specifying the full class + name as a “string constant”:#constants. + ``enabled`` true Enable/disable sstable compression. + ``chunk_length_in_kb`` 64KB On disk SSTables are compressed by block (to allow random reads). This + defines the size (in KB) of said block. Bigger values may improve the + compression rate, but increases the minimum size of data to be read from disk + for a read + ``crc_check_chance`` 1.0 When compression is enabled, each compressed block includes a checksum of + that block for the purpose of detecting disk bitrot and avoiding the + propagation of corruption to other replica. This option defines the + probability with which those checksums are checked during read. By default + they are always checked. Set to 0 to disable checksum checking and to 0.5 for + instance to check them every other read | +========================= =============== ============================================================================= + +.. _cql-caching-options: Caching options ############### -For the ``caching`` property, the following sub-options are available: +The ``caching`` options allows to configure both the *key cache* and the *row cache* for the table. The following +sub-options are available: -+--------------------------+-----------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| option | default | description | -+==========================+===========+============================================================================================================================================================================================================================================================================+ -| ``keys`` | ALL | Whether to cache keys (“key cache”) for this table. Valid values are: ``ALL`` and ``NONE``. | -+--------------------------+-----------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``rows_per_partition`` | NONE | The amount of rows to cache per partition (“row cache”). If an integer ``n`` is specified, the first ``n`` queried rows of a partition will be cached. Other possible options are ``ALL``, to cache all rows of a queried partition, or ``NONE`` to disable row caching. | -+--------------------------+-----------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +======================== ========= ==================================================================================== + Option Default Description +======================== ========= ==================================================================================== + ``keys`` ALL Whether to cache keys (“key cache”) for this table. Valid values are: ``ALL`` and + ``NONE``. + ``rows_per_partition`` NONE The amount of rows to cache per partition (“row cache”). If an integer ``n`` is + specified, the first ``n`` queried rows of a partition will be cached. Other + possible options are ``ALL``, to cache all rows of a queried partition, or ``NONE`` + to disable row caching. +======================== ========= ==================================================================================== Other considerations: ##################### -- When `inserting <#insertStmt>`__ / `updating <#updateStmt>`__ a given - row, not all columns needs to be defined (except for those part of - the key), and missing columns occupy no space on disk. Furthermore, - adding new columns (see \ ``ALTER TABLE``\ ) is a constant time - operation. There is thus no need to try to anticipate future usage - (or to cry when you haven’t) when creating a table. +- Adding new columns (see ``ALTER TABLE`` below) is a constant time operation. There is thus no need to try to + anticipate future usage when creating a table. + +.. _alter-table-statement: ALTER TABLE ^^^^^^^^^^^ @@ -575,7 +566,7 @@ For instance:: ALTER TABLE addamsFamily ADD gravesite varchar; ALTER TABLE addamsFamily - WITH comment = ‘A most excellent and useful table’ + WITH comment = 'A most excellent and useful table' AND read_repair_chance = 0.2; The ``ALTER TABLE`` statement can: @@ -587,10 +578,12 @@ The ``ALTER TABLE`` statement can: compatibility table ` below for detail on which type changes are accepted. - Add new column(s) to the table (through the ``ADD`` instruction). Note that the primary key of a table cannot be changed and thus newly added column will, by extension, never be part of the primary key. Also note that :ref:`compact - tables ` have restrictions regarding column addition. + tables ` have restrictions regarding column addition. Note that this is constant (in the amount of + data the cluster contains) time operation. - Remove column(s) from the table. This drops both the column and all its content, but note that while the column becomes immediately unavailable, its content is only removed lazily during compaction. Please also see the warnings - below. + below. Due to lazy removal, the altering itself is a constant (in the amount of data removed or contained in the + cluster) time operation. - Change some of the table options (through the ``WITH`` instruction). The :ref:`supported options ` are the same that when creating a table (outside of ``COMPACT STORAGE`` and ``CLUSTERING ORDER`` that cannot be changed after creation). Note that setting any ``compaction`` sub-options has the effect of @@ -603,7 +596,7 @@ The ``ALTER TABLE`` statement can: convention. Please be aware that if you do so, dropping a column will not work correctly. .. warning:: Once a column is dropped, it is allowed to re-add a column with the same name than the dropped one - **unless* the type of the dropped column was a (non-frozen) column (due to an internal technical limitation). + **unless** the type of the dropped column was a (non-frozen) column (due to an internal technical limitation). .. _alter-table-type-compatibility: @@ -648,35 +641,32 @@ Clustering columns have stricter requirements, only the following conversions ar | ascii, text | varchar | +------------------------+-------------------+ +.. _drop-table-statement: + DROP TABLE ^^^^^^^^^^ -*Syntax:* +Dropping a table uses the ``DROP TABLE`` statement: -bc(syntax). ::= DROP TABLE ( IF EXISTS )? +.. productionlist:: + drop_table_statement: DROP TABLE [ IF EXISTS ] `table_name` -*Sample:* +Dropping a table results in the immediate, irreversible removal of the table, including all data it contains. -bc(sample). DROP TABLE worldSeriesAttendees; +If the table does not exist, the statement will return an error, unless ``IF EXISTS`` is used in which case the +operation is a no-op. -The ``DROP TABLE`` statement results in the immediate, irreversible -removal of a table, including all data contained in it. As for table -creation, ``DROP COLUMNFAMILY`` is allowed as an alias for -``DROP TABLE``. - -If the table does not exist, the statement will return an error, unless -``IF EXISTS`` is used in which case the operation is a no-op. +.. _truncate-statement: TRUNCATE ^^^^^^^^ -*Syntax:* +A table can be truncated using the ``TRUNCATE`` statement: -bc(syntax). ::= TRUNCATE ( TABLE \| COLUMNFAMILY )? +.. productionlist:: + truncate_statement: TRUNCATE [ TABLE ] `table_name` -*Sample:* - -bc(sample). TRUNCATE superImportantData; - -The ``TRUNCATE`` statement permanently removes all data from a table. +Note that ``TRUNCATE TABLE foo`` is allowed for consistency with other DDL statements but tables are the only object +that can be truncated currently and so the ``TABLE`` keyword can be omitted. +Truncating a table permanently removes all existing data from the table, but without removing the table itself. diff --git a/doc/source/cql/definitions.rst b/doc/source/cql/definitions.rst index 61ed47c28e..5f0cafb306 100644 --- a/doc/source/cql/definitions.rst +++ b/doc/source/cql/definitions.rst @@ -14,6 +14,8 @@ .. See the License for the specific language governing permissions and .. limitations under the License. +.. _UUID: https://en.wikipedia.org/wiki/Universally_unique_identifier + Definitions ----------- @@ -126,8 +128,8 @@ A term is thus one of: - A :ref:`constant `. - A literal for either :ref:`a collection `, :ref:`a user-defined type ` or :ref:`a tuple ` (see the linked sections for details). -- A function call: see :ref:`the section on functions ` for details on which :ref:`native function - ` exists and how to define your own :ref:`user-defined ones `. +- A function call: see :ref:`the section on functions ` for details on which :ref:`native function + ` exists and how to define your own :ref:`user-defined ones `. - A *type hint*: see the :ref:`related section ` for details. - A bind marker, which denotes a variable to be bound at execution time. See the section on :ref:`prepared-statements` for details. A bind marker can be either anonymous (``?``) or named (``:some_name``). The latter form provides a more @@ -155,11 +157,13 @@ CQL consists of statements that can be divided in the following categories: - :ref:`data-definition` statements, to define and change how the data is stored (keyspaces and tables). - :ref:`data-manipulation` statements, for selecting, inserting and deleting data. -- :ref:`index-and-views` statements. -- :ref:`roles-and-permissions` statements. -- :ref:`udfs` statements. +- :ref:`secondary-indexes` statements. +- :ref:`materialized-views` statements. +- :ref:`cql-roles` statements. +- :ref:`cql-permissions` statements. +- :ref:`User-Defined Functions ` statements. - :ref:`udts` statements. -- :ref:`triggers` statements. +- :ref:`cql-triggers` statements. All the statements are listed below and are described in the rest of this documentation (see links above): @@ -167,7 +171,8 @@ All the statements are listed below and are described in the rest of this docume cql_statement: `statement` [ ';' ] statement: `ddl_statement` : | `dml_statement` - : | `index_or_view_statement` + : | `secondary_index_statement` + : | `materialized_view_statement` : | `role_or_permission_statement` : | `udf_statement` : | `udt_statement` @@ -185,10 +190,10 @@ All the statements are listed below and are described in the rest of this docume : | `update_statement` : | `delete_statement` : | `batch_statement` - index_or_view_statement: `create_index_statement` - : | `drop_index_statement` - : | `create_materialized_view_statement` - : | `drop_materialized_view_statement` + secondary_index_statement: `create_index_statement` + : | `drop_index_statement` + materialized_view_statement: `create_materialized_view_statement` + : | `drop_materialized_view_statement` role_or_permission_statement: `create_role_statement` : | `alter_role_statement` : | `drop_role_statement` diff --git a/doc/source/cql/dml.rst b/doc/source/cql/dml.rst index 4cf34ebac2..58fdb05419 100644 --- a/doc/source/cql/dml.rst +++ b/doc/source/cql/dml.rst @@ -21,586 +21,478 @@ Data Manipulation ----------------- +This section describes the statements supported by CQL to insert, update, delete and query data. + +.. _select-statement: + SELECT ^^^^^^ -*Syntax:* +Querying data from data is done using a ``SELECT`` statement: -| bc(syntax).. -| ::= SELECT ( JSON )? -| FROM -| ( WHERE )? -| ( ORDER BY )? -| ( PER PARTITION LIMIT )? -| ( LIMIT )? -| ( ALLOW FILTERING )? +.. productionlist:: + select_statement: SELECT [ JSON | DISTINCT ] ( `select_clause` | '*' ) + : FROM `table_name` + : [ WHERE `where_clause` ] + : [ ORDER BY `ordering_clause` ] + : [ PER PARTITION LIMIT (`integer` | `bind_marker`) ] + : [ LIMIT (`integer` | `bind_marker`) ] + : [ ALLOW FILTERING ] + select_clause: `selector` [ AS `identifier` ] ( ',' `selector` [ AS `identifier` ] ) + selector: `identifier` + : | `term` + : | CAST '(' `selector` AS `cql_type` ')' + : | `function_name` '(' [ `selector` ( ',' `selector` )* ] ')' + : | COUNT '(' '*' ')' + where_clause: `relation` ( AND `relation` )* + relation: `identifier` `operator` `term` + : '(' `identifier` ( ',' `identifier` )* ')' `operator` `tuple_literal` + : TOKEN '(' `identifier` ( ',' `identifier` )* ')' `operator` `term` + operator: '=' | '<' | '>' | '<=' | '>=' | '!=' | IN | CONTAINS | CONTAINS KEY + ordering_clause: `identifier` [ ASC | DESC ] ( ',' `identifier` [ ASC | DESC ] )* -| ::= DISTINCT? -| \| COUNT ‘(’ ( ‘\*’ \| ‘1’ ) ‘)’ (AS )? +For instance:: -| ::= (AS )? ( ‘,’ (AS )? )\* -| \| ‘\*’ + SELECT name, occupation FROM users WHERE userid IN (199, 200, 207); + SELECT JSON name, occupation FROM users WHERE userid = 199; + SELECT name AS user_name, occupation AS user_occupation FROM users; -| ::= -| \| WRITETIME ‘(’ ‘)’ -| \| TTL ‘(’ ‘)’ -| \| CAST ‘(’ AS ‘)’ -| \| ‘(’ ( (‘,’ )\*)? ‘)’ + SELECT time, value + FROM events + WHERE event_type = 'myEvent' + AND time > '2011-02-03' + AND time <= '2012-01-01' - ::= ( AND )\* + SELECT COUNT (*) AS user_count FROM users; -| ::= -| \| ‘(’ (‘,’ )\* ‘)’ -| \| IN ‘(’ ( ( ‘,’ )\* )? ‘)’ -| \| ‘(’ (‘,’ )\* ‘)’ IN ‘(’ ( ( ‘,’ )\* )? ‘)’ -| \| TOKEN ‘(’ ( ‘,’ )\* ‘)’ +The ``SELECT`` statements reads one or more columns for one or more rows in a table. It returns a result-set of the rows +matching the request, where each row contains the values for the selection corresponding to the query. Additionally, +:ref:`functions ` including :ref:`aggregation ` ones can be applied to the result. -| ::= ‘=’ \| ‘<’ \| ‘>’ \| ‘<=’ \| ‘>=’ \| CONTAINS \| CONTAINS KEY -| ::= ( ‘,’ )\* -| ::= ( ASC \| DESC )? -| ::= ‘(’ (‘,’ )\* ‘)’ -| p. -| *Sample:* +A ``SELECT`` statement contains at least a :ref:`selection clause ` and the name of the table on which +the selection is on (note that CQL does **not** joins or sub-queries and thus a select statement only apply to a single +table). In most case, a select will also have a :ref:`where clause ` and it can optionally have additional +clauses to :ref:`order ` or :ref:`limit ` the results. Lastly, :ref:`queries that require +filtering ` can be allowed if the ``ALLOW FILTERING`` flag is provided. -| bc(sample).. -| SELECT name, occupation FROM users WHERE userid IN (199, 200, 207); +.. _selection-clause: -SELECT JSON name, occupation FROM users WHERE userid = 199; +Selection clause +~~~~~~~~~~~~~~~~ -SELECT name AS user\_name, occupation AS user\_occupation FROM users; +The :token:`select_clause` determines which columns needs to be queried and returned in the result-set, as well as any +transformation to apply to this result before returning. It consists of a comma-separated list of *selectors* or, +alternatively, of the wildcard character (``*``) to select all the columns defined in the table. -| SELECT time, value -| FROM events -| WHERE event\_type = ‘myEvent’ -| AND time > ‘2011-02-03’ -| AND time <= ‘2012-01-01’ +Selectors +````````` -SELECT COUNT (\*) FROM users; +A :token:`selector` can be one of: -SELECT COUNT (\*) AS user\_count FROM users; +- A column name of the table selected, to retrieve the values for that column. +- A term, which is usually used nested inside other selectors like functions (if a term is selected directly, then the + corresponding column of the result-set will simply have the value of this term for every row returned). +- A casting, which allows to convert a nested selector to a (compatible) type. +- A function call, where the arguments are selector themselves. See the section on :ref:`functions ` for + more details. +- The special call ``COUNT(*)`` to the :ref:`COUNT function `, which counts all non-null results. -The ``SELECT`` statements reads one or more columns for one or more rows -in a table. It returns a result-set of rows, where each row contains the -collection of columns corresponding to the query. If the ``JSON`` -keyword is used, the results for each row will contain only a single -column named “json”. See the section on -```SELECT JSON`` <#selectJson>`__ for more details. +Aliases +``````` -```` -~~~~~~~~~~~~~~~~~~~ +Every *top-level* selector can also be aliased (using `AS`). If so, the name of the corresponding column in the result +set will be that of the alias. For instance:: -The ```` determines which columns needs to be queried and -returned in the result-set. It consists of either the comma-separated -list of or the wildcard character (``*``) to select all the columns -defined for the table. + // Without alias + SELECT intAsBlob(4) FROM t; -A ```` is either a column name to retrieve or a ```` -of one or more ````\ s. The function allowed are the same as for -```` and are described in the `function section <#functions>`__. -In addition to these generic functions, the ``WRITETIME`` (resp. -``TTL``) function allows to select the timestamp of when the column was -inserted (resp. the time to live (in seconds) for the column (or null if -the column has no expiration set)) and the ```CAST`` <#castFun>`__ -function can be used to convert one data type to another. + // intAsBlob(4) + // -------------- + // 0x00000004 -Any ```` can be aliased using ``AS`` keyword (see examples). -Please note that ```` and ```` clause should -refer to the columns by their original names and not by their aliases. + // With alias + SELECT intAsBlob(4) AS four FROM t; -The ``COUNT`` keyword can be used with parenthesis enclosing ``*``. If -so, the query will return a single result: the number of rows matching -the query. Note that ``COUNT(1)`` is supported as an alias. + // four + // ------------ + // 0x00000004 -```` +.. note:: Currently, aliases aren't recognized anywhere else in the statement where they are used (not in the ``WHERE`` + clause, not in the ``ORDER BY`` clause, ...). You must use the orignal column name instead. + + +``WRITETIME`` and ``TTL`` function +``````````````````````````````````` + +Selection supports two special functions (that aren't allowed anywhere else): ``WRITETIME`` and ``TTL``. Both function +take only one argument and that argument *must* be a column name (so for instance ``TTL(3)`` is invalid). + +Those functions allow to retrieve meta-information that are stored internally for each column, namely: + +- the timestamp of the value of the column for ``WRITETIME``. +- the remaining time to live (in seconds) for the value of the column if it set to expire (and ``null`` otherwise). + +.. _where-clause: + +The ``WHERE`` clause +~~~~~~~~~~~~~~~~~~~~ + +The ``WHERE`` clause specifies which rows must be queried. It is composed of relations on the columns that are part of +the ``PRIMARY KEY`` and/or have a `secondary index <#createIndexStmt>`__ defined on them. + +Not all relations are allowed in a query. For instance, non-equal relations (where ``IN`` is considered as an equal +relation) on a partition key are not supported (but see the use of the ``TOKEN`` method below to do non-equal queries on +the partition key). Moreover, for a given partition key, the clustering columns induce an ordering of rows and relations +on them is restricted to the relations that allow to select a **contiguous** (for the ordering) set of rows. For +instance, given:: + + CREATE TABLE posts ( + userid text, + blog_title text, + posted_at timestamp, + entry_title text, + content text, + category int, + PRIMARY KEY (userid, blog_title, posted_at) + ) + +The following query is allowed:: + + SELECT entry_title, content FROM posts + WHERE userid = 'john doe' + AND blog_title='John''s Blog' + AND posted_at >= '2012-01-01' AND posted_at < '2012-01-31' + +But the following one is not, as it does not select a contiguous set of rows (and we suppose no secondary indexes are +set):: + + // Needs a blog_title to be set to select ranges of posted_at + SELECT entry_title, content FROM posts + WHERE userid = 'john doe' + AND posted_at >= '2012-01-01' AND posted_at < '2012-01-31' + +When specifying relations, the ``TOKEN`` function can be used on the ``PARTITION KEY`` column to query. In that case, +rows will be selected based on the token of their ``PARTITION_KEY`` rather than on the value. Note that the token of a +key depends on the partitioner in use, and that in particular the RandomPartitioner won't yield a meaningful order. Also +note that ordering partitioners always order token values by bytes (so even if the partition key is of type int, +``token(-1) > token(0)`` in particular). Example:: + + SELECT * FROM posts + WHERE token(userid) > token('tom') AND token(userid) < token('bob') + +Moreover, the ``IN`` relation is only allowed on the last column of the partition key and on the last column of the full +primary key. + +It is also possible to “group” ``CLUSTERING COLUMNS`` together in a relation using the tuple notation. For instance:: + + SELECT * FROM posts + WHERE userid = 'john doe' + AND (blog_title, posted_at) > ('John''s Blog', '2012-01-01') + +will request all rows that sorts after the one having “John's Blog” as ``blog_tile`` and '2012-01-01' for ``posted_at`` +in the clustering order. In particular, rows having a ``post_at <= '2012-01-01'`` will be returned as long as their +``blog_title > 'John''s Blog'``, which would not be the case for:: + + SELECT * FROM posts + WHERE userid = 'john doe' + AND blog_title > 'John''s Blog' + AND posted_at > '2012-01-01' + +The tuple notation may also be used for ``IN`` clauses on clustering columns:: + + SELECT * FROM posts + WHERE userid = 'john doe' + AND (blog_title, posted_at) IN (('John''s Blog', '2012-01-01), ('Extreme Chess', '2014-06-01')) + +The ``CONTAINS`` operator may only be used on collection columns (lists, sets, and maps). In the case of maps, +``CONTAINS`` applies to the map values. The ``CONTAINS KEY`` operator may only be used on map columns and applies to the +map keys. + +.. _ordering-clause: + +Ordering results +~~~~~~~~~~~~~~~~ + +The ``ORDER BY`` clause allows to select the order of the returned results. It takes as argument a list of column names +along with the order for the column (``ASC`` for ascendant and ``DESC`` for descendant, omitting the order being +equivalent to ``ASC``). Currently the possible orderings are limited by the :ref:`clustering order ` +defined on the table: + +- if the table has been defined without any specific ``CLUSTERING ORDER``, then then allowed orderings are the order + induced by the clustering columns and the reverse of that one. +- otherwise, the orderings allowed are the order of the ``CLUSTERING ORDER`` option and the reversed one. + +.. _limit-clause: + +Limiting results +~~~~~~~~~~~~~~~~ + +The ``LIMIT`` option to a ``SELECT`` statement limits the number of rows returned by a query, while the ``PER PARTITION +LIMIT`` option limits the number of rows returned for a given partition by the query. Note that both type of limit can +used in the same statement. + +.. _allow-filtering: + +Allowing filtering ~~~~~~~~~~~~~~~~~~ -The ```` specifies which rows must be queried. It is -composed of relations on the columns that are part of the -``PRIMARY KEY`` and/or have a `secondary index <#createIndexStmt>`__ -defined on them. +By default, CQL only allows select queries that don't involve “filtering” server side, i.e. queries where we know that +all (live) record read will be returned (maybe partly) in the result set. The reasoning is that those “non filtering” +queries have predictable performance in the sense that they will execute in a time that is proportional to the amount of +data **returned** by the query (which can be controlled through ``LIMIT``). -Not all relations are allowed in a query. For instance, non-equal -relations (where ``IN`` is considered as an equal relation) on a -partition key are not supported (but see the use of the ``TOKEN`` method -below to do non-equal queries on the partition key). Moreover, for a -given partition key, the clustering columns induce an ordering of rows -and relations on them is restricted to the relations that allow to -select a **contiguous** (for the ordering) set of rows. For instance, -given +The ``ALLOW FILTERING`` option allows to explicitly allow (some) queries that require filtering. Please note that a +query using ``ALLOW FILTERING`` may thus have unpredictable performance (for the definition above), i.e. even a query +that selects a handful of records **may** exhibit performance that depends on the total amount of data stored in the +cluster. -| bc(sample). -| CREATE TABLE posts ( -| userid text, -| blog\_title text, -| posted\_at timestamp, -| entry\_title text, -| content text, -| category int, -| PRIMARY KEY (userid, blog\_title, posted\_at) -| ) +For instance, considering the following table holding user profiles with their year of birth (with a secondary index on +it) and country of residence:: -The following query is allowed: + CREATE TABLE users ( + username text PRIMARY KEY, + firstname text, + lastname text, + birth_year int, + country text + ) -| bc(sample). -| SELECT entry\_title, content FROM posts WHERE userid=‘john doe’ AND - blog\_title=‘John’‘s Blog’ AND posted\_at >= ‘2012-01-01’ AND - posted\_at < ‘2012-01-31’ + CREATE INDEX ON users(birth_year); -But the following one is not, as it does not select a contiguous set of -rows (and we suppose no secondary indexes are set): +Then the following queries are valid:: -| bc(sample). -| // Needs a blog\_title to be set to select ranges of posted\_at -| SELECT entry\_title, content FROM posts WHERE userid=‘john doe’ AND - posted\_at >= ‘2012-01-01’ AND posted\_at < ‘2012-01-31’ + SELECT * FROM users; + SELECT * FROM users WHERE birth_year = 1981; -When specifying relations, the ``TOKEN`` function can be used on the -``PARTITION KEY`` column to query. In that case, rows will be selected -based on the token of their ``PARTITION_KEY`` rather than on the value. -Note that the token of a key depends on the partitioner in use, and that -in particular the RandomPartitioner won’t yield a meaningful order. Also -note that ordering partitioners always order token values by bytes (so -even if the partition key is of type int, ``token(-1) > token(0)`` in -particular). Example: +because in both case, Cassandra guarantees that these queries performance will be proportional to the amount of data +returned. In particular, if no users are born in 1981, then the second query performance will not depend of the number +of user profile stored in the database (not directly at least: due to secondary index implementation consideration, this +query may still depend on the number of node in the cluster, which indirectly depends on the amount of data stored. +Nevertheless, the number of nodes will always be multiple number of magnitude lower than the number of user profile +stored). Of course, both query may return very large result set in practice, but the amount of data returned can always +be controlled by adding a ``LIMIT``. -| bc(sample). -| SELECT \* FROM posts WHERE token(userid) > token(‘tom’) AND - token(userid) < token(‘bob’) +However, the following query will be rejected:: -Moreover, the ``IN`` relation is only allowed on the last column of the -partition key and on the last column of the full primary key. + SELECT * FROM users WHERE birth_year = 1981 AND country = 'FR'; -It is also possible to “group” ``CLUSTERING COLUMNS`` together in a -relation using the tuple notation. For instance: +because Cassandra cannot guarantee that it won't have to scan large amount of data even if the result to those query is +small. Typically, it will scan all the index entries for users born in 1981 even if only a handful are actually from +France. However, if you “know what you are doing”, you can force the execution of this query by using ``ALLOW +FILTERING`` and so the following query is valid:: -| bc(sample). -| SELECT \* FROM posts WHERE userid=‘john doe’ AND (blog\_title, - posted\_at) > (‘John’‘s Blog’, ‘2012-01-01’) + SELECT * FROM users WHERE birth_year = 1981 AND country = 'FR' ALLOW FILTERING; -will request all rows that sorts after the one having “John’s Blog” as -``blog_tile`` and ‘2012-01-01’ for ``posted_at`` in the clustering -order. In particular, rows having a ``post_at <= '2012-01-01'`` will be -returned as long as their ``blog_title > 'John''s Blog'``, which -wouldn’t be the case for: - -| bc(sample). -| SELECT \* FROM posts WHERE userid=‘john doe’ AND blog\_title > - ‘John’‘s Blog’ AND posted\_at > ‘2012-01-01’ - -The tuple notation may also be used for ``IN`` clauses on -``CLUSTERING COLUMNS``: - -| bc(sample). -| SELECT \* FROM posts WHERE userid=‘john doe’ AND (blog\_title, - posted\_at) IN ((‘John’‘s Blog’, ‘2012-01-01), (’Extreme Chess’, - ‘2014-06-01’)) - -The ``CONTAINS`` operator may only be used on collection columns (lists, -sets, and maps). In the case of maps, ``CONTAINS`` applies to the map -values. The ``CONTAINS KEY`` operator may only be used on map columns -and applies to the map keys. - -```` -~~~~~~~~~~~~~~ - -The ``ORDER BY`` option allows to select the order of the returned -results. It takes as argument a list of column names along with the -order for the column (``ASC`` for ascendant and ``DESC`` for descendant, -omitting the order being equivalent to ``ASC``). Currently the possible -orderings are limited (which depends on the table -```CLUSTERING ORDER`` <#createTableOptions>`__ ): - -- if the table has been defined without any specific - ``CLUSTERING ORDER``, then then allowed orderings are the order - induced by the clustering columns and the reverse of that one. -- otherwise, the orderings allowed are the order of the - ``CLUSTERING ORDER`` option and the reversed one. - -``LIMIT`` and ``PER PARTITION LIMIT`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The ``LIMIT`` option to a ``SELECT`` statement limits the number of rows -returned by a query, while the ``PER PARTITION LIMIT`` option limits the -number of rows returned for a given partition by the query. Note that -both type of limit can used in the same statement. - -``ALLOW FILTERING`` -~~~~~~~~~~~~~~~~~~~ - -By default, CQL only allows select queries that don’t involve -“filtering” server side, i.e. queries where we know that all (live) -record read will be returned (maybe partly) in the result set. The -reasoning is that those “non filtering” queries have predictable -performance in the sense that they will execute in a time that is -proportional to the amount of data **returned** by the query (which can -be controlled through ``LIMIT``). - -The ``ALLOW FILTERING`` option allows to explicitly allow (some) queries -that require filtering. Please note that a query using -``ALLOW FILTERING`` may thus have unpredictable performance (for the -definition above), i.e. even a query that selects a handful of records -**may** exhibit performance that depends on the total amount of data -stored in the cluster. - -For instance, considering the following table holding user profiles with -their year of birth (with a secondary index on it) and country of -residence: - -| bc(sample).. -| CREATE TABLE users ( -| username text PRIMARY KEY, -| firstname text, -| lastname text, -| birth\_year int, -| country text -| ) - -| CREATE INDEX ON users(birth\_year); -| p. - -Then the following queries are valid: - -| bc(sample). -| SELECT \* FROM users; -| SELECT firstname, lastname FROM users WHERE birth\_year = 1981; - -because in both case, Cassandra guarantees that these queries -performance will be proportional to the amount of data returned. In -particular, if no users are born in 1981, then the second query -performance will not depend of the number of user profile stored in the -database (not directly at least: due to secondary index implementation -consideration, this query may still depend on the number of node in the -cluster, which indirectly depends on the amount of data stored. -Nevertheless, the number of nodes will always be multiple number of -magnitude lower than the number of user profile stored). Of course, both -query may return very large result set in practice, but the amount of -data returned can always be controlled by adding a ``LIMIT``. - -However, the following query will be rejected: - -| bc(sample). -| SELECT firstname, lastname FROM users WHERE birth\_year = 1981 AND - country = ‘FR’; - -because Cassandra cannot guarantee that it won’t have to scan large -amount of data even if the result to those query is small. Typically, it -will scan all the index entries for users born in 1981 even if only a -handful are actually from France. However, if you “know what you are -doing”, you can force the execution of this query by using -``ALLOW FILTERING`` and so the following query is valid: - -| bc(sample). -| SELECT firstname, lastname FROM users WHERE birth\_year = 1981 AND - country = ‘FR’ ALLOW FILTERING; +.. _insert-statement: INSERT ^^^^^^ -*Syntax:* +Inserting data for a row is done using an ``INSERT`` statement: -| bc(syntax).. -| ::= INSERT INTO -| ( ( VALUES ) -| \| ( JSON )) -| ( IF NOT EXISTS )? -| ( USING ( AND )\* )? +.. productionlist:: + insert_statement: INSERT INTO `table_name` ( `names_values` | `json_clause` ) + : [ IF NOT EXISTS ] + : [ USING `update_parameter` ( AND `update_parameter` )* ] + names_values: `names` VALUES `tuple_literal` + names: '(' `identifier` ( ',' `identifier` )* ')' - ::= ‘(’ ( ‘,’ )\* ‘)’ +For instance:: - ::= ‘(’ ( ‘,’ )\* ‘)’ + INSERT INTO NerdMovies (movie, director, main_actor, year) + VALUES ('Serenity', 'Joss Whedon', 'Nathan Fillion', 2005) + USING TTL 86400; -| ::= -| \| + INSERT INTO NerdMovies JSON '{"movie": "Serenity", + "director": "Joss Whedon", + "year": 2005}'; -| ::= TIMESTAMP -| \| TTL -| p. -| *Sample:* +The ``INSERT`` statement writes one or more columns for a given row in a table. Note that since a row is identified by +its ``PRIMARY KEY``, at least the columns composing it must be specified. The list of columns to insert to must be +supplied when using the ``VALUES`` syntax. When using the ``JSON`` syntax, they are optional. See the +section on :ref:`JSON support ` for more detail. -| bc(sample).. -| INSERT INTO NerdMovies (movie, director, main\_actor, year) -| VALUES (‘Serenity’, ‘Joss Whedon’, ‘Nathan Fillion’, 2005) -| USING TTL 86400; +Note that unlike in SQL, ``INSERT`` does not check the prior existence of the row by default: the row is created if none +existed before, and updated otherwise. Furthermore, there is no mean to know which of creation or update happened. -| INSERT INTO NerdMovies JSON ‘{`movie <>`__ “Serenity”, `director <>`__ - “Joss Whedon”, `year <>`__ 2005}’ -| p. -| The ``INSERT`` statement writes one or more columns for a given row in - a table. Note that since a row is identified by its ``PRIMARY KEY``, - at least the columns composing it must be specified. The list of - columns to insert to must be supplied when using the ``VALUES`` - syntax. When using the ``JSON`` syntax, they are optional. See the - section on ```INSERT JSON`` <#insertJson>`__ for more details. - -Note that unlike in SQL, ``INSERT`` does not check the prior existence -of the row by default: the row is created if none existed before, and -updated otherwise. Furthermore, there is no mean to know which of -creation or update happened. - -It is however possible to use the ``IF NOT EXISTS`` condition to only -insert if the row does not exist prior to the insertion. But please note -that using ``IF NOT EXISTS`` will incur a non negligible performance -cost (internally, Paxos will be used) so this should be used sparingly. +It is however possible to use the ``IF NOT EXISTS`` condition to only insert if the row does not exist prior to the +insertion. But please note that using ``IF NOT EXISTS`` will incur a non negligible performance cost (internally, Paxos +will be used) so this should be used sparingly. All updates for an ``INSERT`` are applied atomically and in isolation. -Please refer to the ```UPDATE`` <#updateOptions>`__ section for -information on the ``