Finish fixing the CQL doc
Project: http://git-wip-us.apache.org/repos/asf/cassandra/repo Commit: http://git-wip-us.apache.org/repos/asf/cassandra/commit/0e624238 Tree: http://git-wip-us.apache.org/repos/asf/cassandra/tree/0e624238 Diff: http://git-wip-us.apache.org/repos/asf/cassandra/diff/0e624238 Branch: refs/heads/trunk Commit: 0e624238c15558155a57bcfa7ada9b3b84067658 Parents: 7dfb25e Author: Sylvain Lebresne <sylv...@datastax.com> Authored: Fri Jun 24 17:01:37 2016 +0200 Committer: Sylvain Lebresne <sylv...@datastax.com> Committed: Fri Jun 24 17:01:37 2016 +0200 ---------------------------------------------------------------------- .gitignore | 2 +- doc/convert_yaml_to_rst.py | 2 +- doc/source/cql/appendices.rst | 2 - doc/source/cql/changes.rst | 242 ++--- doc/source/cql/ddl.rst | 232 +++-- doc/source/cql/definitions.rst | 27 +- doc/source/cql/dml.rst | 964 ++++++++----------- doc/source/cql/functions.rst | 890 ++++++++--------- doc/source/cql/index.rst | 2 - doc/source/cql/indexes.rst | 93 +- doc/source/cql/json.rst | 168 ++-- doc/source/cql/mvs.rst | 183 ++-- doc/source/cql/security.rst | 768 ++++++--------- doc/source/cql/triggers.rst | 48 +- doc/source/cql/types.rst | 6 +- doc/source/operating/compaction.rst | 8 +- doc/source/operating/security.rst | 10 +- .../cql3/statements/CreateViewStatement.java | 9 +- 18 files changed, 1626 insertions(+), 2030 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/cassandra/blob/0e624238/.gitignore ---------------------------------------------------------------------- diff --git a/.gitignore b/.gitignore index 4f33eda..f5b1ce1 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 http://git-wip-us.apache.org/repos/asf/cassandra/blob/0e624238/doc/convert_yaml_to_rst.py ---------------------------------------------------------------------- diff --git a/doc/convert_yaml_to_rst.py b/doc/convert_yaml_to_rst.py index 398295d..fee6d8c 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 http://git-wip-us.apache.org/repos/asf/cassandra/blob/0e624238/doc/source/cql/appendices.rst ---------------------------------------------------------------------- diff --git a/doc/source/cql/appendices.rst b/doc/source/cql/appendices.rst index 9788a56..c4bb839 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`` | http://git-wip-us.apache.org/repos/asf/cassandra/blob/0e624238/doc/source/cql/changes.rst ---------------------------------------------------------------------- diff --git a/doc/source/cql/changes.rst b/doc/source/cql/changes.rst index 9549f8f..263df13 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 <https://issues.apache.org/jira/browse/CASSANDRA-7017)>`__. -- `User-defined functions <#udfs>`__ can now instantiate ``UDTValue`` - and ``TupleValue`` instances via the new ``UDFContext`` interface - (see - `CASSANDRA-10818 <https://issues.apache.org/jira/browse/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 <https://issues.apache.org/jira/browse/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 + <https://issues.apache.org/jira/browse/CASSANDRA-7017)>`__. +- :ref:`User-defined functions <cql-functions>` can now instantiate ``UDTValue`` and ``TupleValue`` instances via the + new ``UDFContext`` interface (see `CASSANDRA-10818 <https://issues.apache.org/jira/browse/CASSANDRA-10818)>`__. +- :ref:`User-defined types <udts>` 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 + <https://issues.apache.org/jira/browse/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 <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`` <usingtime>`__ 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 <cql-functions>` 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 <data-types>` have been added. +- :ref:`JSON support <cql-json>` 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 <udts>` 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 <tuples>` 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 <where-clause>` clauses. +- Added support for :ref:`static columns <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 <timestamps>` 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 <https://issues.apache.org/jira/browse/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 + <https://issues.apache.org/jira/browse/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 <https://issues.apache.org/jira/browse/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 <https://issues.apache.org/jira/browse/CASSANDRA-5626)>`__. +- ``SELECT``, ``UPDATE``, and ``DELETE`` statements now allow empty ``IN`` relations (see `CASSANDRA-5626 + <https://issues.apache.org/jira/browse/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 <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 <where-clause>`). 3.0.3 ^^^^^ -- Support for custom `secondary indexes <#createIndexStmt>`__ has been - added. +- Support for custom :ref:`secondary indexes <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 <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 <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 <cql-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 <https://issues.apache.org/jira/browse/CASSANDRA-4936>`__. - 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 + <https://issues.apache.org/jira/browse/CASSANDRA-4936>`__. 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 <http://semver.org>`__ 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. | -+-----------+-------------------------------------------------------------------------------------------------------------------+ +Versioning of the CQL language adheres to the `Semantic Versioning <http://semver.org>`__ 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. +========= ============================================================================================================= http://git-wip-us.apache.org/repos/asf/cassandra/blob/0e624238/doc/source/cql/ddl.rst ---------------------------------------------------------------------- diff --git a/doc/source/cql/ddl.rst b/doc/source/cql/ddl.rst index 6c3b6d1..948298b 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 <create-keyspace-options>`. +The supported options are the same than for :ref:`creating a keyspace <create-keyspace-statement>`. .. _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 <cql-compaction-options>`. | ++--------------------------------+----------+-------------+-----------------------------------------------------------+ +| ``compression`` | *map* | *see below* | :ref:`Compression options <cql-compression-options>`. | ++--------------------------------+----------+-------------+-----------------------------------------------------------+ +| ``caching`` | *map* | *see below* | :ref:`Caching options <cql-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: - -+--------------------------------------+---------------------------------+----------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| 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. | -+--------------------------------------+---------------------------------+----------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +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 <STCS>`), +``'LeveledCompactionStrategy'`` (:ref:`LCS <LCS>`) and ``'TimeWindowCompactionStrategy'`` (:ref:`TWCS <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 +<constants>`. + +All default strategies support a number of :ref:`common options <compaction-options>`, as well as options specific to +the strategy chosen (see the section corresponding to your strategy for details: :ref:`STCS <stcs-options>`, :ref:`LCS +<lcs-options>` and :ref:`TWCS <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 <alter-table-type-compatibility>` 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 <compact-tables>` have restrictions regarding column addition. + tables <compact-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 <create-table-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:* - -bc(syntax). ::= DROP TABLE ( IF EXISTS )? +Dropping a table uses the ``DROP TABLE`` statement: -*Sample:* +.. productionlist:: + drop_table_statement: DROP TABLE [ IF EXISTS ] `table_name` -bc(sample). DROP TABLE worldSeriesAttendees; +Dropping a table results in the immediate, irreversible removal of the table, including all data it contains. -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. -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:* - -bc(syntax). ::= TRUNCATE ( TABLE \| COLUMNFAMILY )? +A table can be truncated using the ``TRUNCATE`` statement: -*Sample:* - -bc(sample). TRUNCATE superImportantData; +.. productionlist:: + truncate_statement: TRUNCATE [ TABLE ] `table_name` -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. http://git-wip-us.apache.org/repos/asf/cassandra/blob/0e624238/doc/source/cql/definitions.rst ---------------------------------------------------------------------- diff --git a/doc/source/cql/definitions.rst b/doc/source/cql/definitions.rst index 61ed47c..5f0cafb 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 <constants>`. - A literal for either :ref:`a collection <collections>`, :ref:`a user-defined type <udts>` or :ref:`a tuple <tuples>` (see the linked sections for details). -- A function call: see :ref:`the section on functions <functions>` for details on which :ref:`native function - <native-functions>` exists and how to define your own :ref:`user-defined ones <user-defined-functions>`. +- A function call: see :ref:`the section on functions <cql-functions>` for details on which :ref:`native function + <native-functions>` exists and how to define your own :ref:`user-defined ones <udfs>`. - A *type hint*: see the :ref:`related section <type-hints>` 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 <udfs>` 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`
