You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cassandra.apache.org by bl...@apache.org on 2017/01/18 15:07:52 UTC
[3/3] cassandra git commit: Merge branch cassandra-3.0 into
cassandra-3.11
Merge branch cassandra-3.0 into cassandra-3.11
Project: http://git-wip-us.apache.org/repos/asf/cassandra/repo
Commit: http://git-wip-us.apache.org/repos/asf/cassandra/commit/d3882895
Tree: http://git-wip-us.apache.org/repos/asf/cassandra/tree/d3882895
Diff: http://git-wip-us.apache.org/repos/asf/cassandra/diff/d3882895
Branch: refs/heads/cassandra-3.11
Commit: d38828953397fdae686c59561c5b48799d3d504f
Parents: e63c7a0 5f66d48
Author: Benjamin Lerer <b....@gmail.com>
Authored: Wed Jan 18 16:00:11 2017 +0100
Committer: Benjamin Lerer <b....@gmail.com>
Committed: Wed Jan 18 16:07:14 2017 +0100
----------------------------------------------------------------------
CHANGES.txt | 1 +
NEWS.txt | 26 ++--
doc/cql3/CQL.textile | 14 +-
doc/source/cql/changes.rst | 6 +
doc/source/cql/ddl.rst | 52 +------
doc/source/cql/types.rst | 5 +-
pylib/cqlshlib/cql3handling.py | 6 +-
.../org/apache/cassandra/config/CFMetaData.java | 29 +---
.../apache/cassandra/cql3/QueryProcessor.java | 2 +-
.../cql3/statements/AlterTableStatement.java | 86 +----------
.../cql3/statements/AlterTypeStatement.java | 36 +----
.../apache/cassandra/cql3/ViewSchemaTest.java | 76 ----------
.../entities/FrozenCollectionsTest.java | 42 ------
.../cql3/validation/entities/TypeTest.java | 32 -----
.../cql3/validation/entities/UserTypesTest.java | 1 -
.../cql3/validation/operations/AlterTest.java | 144 +------------------
.../cql3/validation/operations/UpdateTest.java | 32 -----
17 files changed, 44 insertions(+), 546 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/cassandra/blob/d3882895/CHANGES.txt
----------------------------------------------------------------------
diff --cc CHANGES.txt
index 9c0b51b,5a63213..453445a
--- a/CHANGES.txt
+++ b/CHANGES.txt
@@@ -1,118 -1,9 +1,119 @@@
-3.0.11
+3.10
+ * Fix TestHintedHandoff.hintedhandoff_decom_test (CASSANDRA-13058)
+ * Fixed query monitoring for range queries (CASSANDRA-13050)
+ * Remove outboundBindAny configuration property (CASSANDRA-12673)
+ * Use correct bounds for all-data range when filtering (CASSANDRA-12666)
+ * Remove timing window in test case (CASSANDRA-12875)
+ * Resolve unit testing without JCE security libraries installed (CASSANDRA-12945)
+ * Fix inconsistencies in cassandra-stress load balancing policy (CASSANDRA-12919)
+ * Fix validation of non-frozen UDT cells (CASSANDRA-12916)
+ * Don't shut down socket input/output on StreamSession (CASSANDRA-12903)
+ * Fix Murmur3PartitionerTest (CASSANDRA-12858)
+ * Move cqlsh syntax rules into separate module and allow easier customization (CASSANDRA-12897)
+ * Fix CommitLogSegmentManagerTest (CASSANDRA-12283)
+ * Fix cassandra-stress truncate option (CASSANDRA-12695)
+ * Fix crossNode value when receiving messages (CASSANDRA-12791)
+ * Don't load MX4J beans twice (CASSANDRA-12869)
+ * Extend native protocol request flags, add versions to SUPPORTED, and introduce ProtocolVersion enum (CASSANDRA-12838)
+ * Set JOINING mode when running pre-join tasks (CASSANDRA-12836)
+ * remove net.mintern.primitive library due to license issue (CASSANDRA-12845)
+ * Properly format IPv6 addresses when logging JMX service URL (CASSANDRA-12454)
+ * Optimize the vnode allocation for single replica per DC (CASSANDRA-12777)
+ * Use non-token restrictions for bounds when token restrictions are overridden (CASSANDRA-12419)
+ * Fix CQLSH auto completion for PER PARTITION LIMIT (CASSANDRA-12803)
+ * Use different build directories for Eclipse and Ant (CASSANDRA-12466)
+ * Avoid potential AttributeError in cqlsh due to no table metadata (CASSANDRA-12815)
+ * Fix RandomReplicationAwareTokenAllocatorTest.testExistingCluster (CASSANDRA-12812)
+ * Upgrade commons-codec to 1.9 (CASSANDRA-12790)
+ * Make the fanout size for LeveledCompactionStrategy to be configurable (CASSANDRA-11550)
+ * Add duration data type (CASSANDRA-11873)
+ * Fix timeout in ReplicationAwareTokenAllocatorTest (CASSANDRA-12784)
+ * Improve sum aggregate functions (CASSANDRA-12417)
+ * Make cassandra.yaml docs for batch_size_*_threshold_in_kb reflect changes in CASSANDRA-10876 (CASSANDRA-12761)
+ * cqlsh fails to format collections when using aliases (CASSANDRA-11534)
+ * Check for hash conflicts in prepared statements (CASSANDRA-12733)
+ * Exit query parsing upon first error (CASSANDRA-12598)
+ * Fix cassandra-stress to use single seed in UUID generation (CASSANDRA-12729)
+ * CQLSSTableWriter does not allow Update statement (CASSANDRA-12450)
+ * Config class uses boxed types but DD exposes primitive types (CASSANDRA-12199)
+ * Add pre- and post-shutdown hooks to Storage Service (CASSANDRA-12461)
+ * Add hint delivery metrics (CASSANDRA-12693)
+ * Remove IndexInfo cache from FileIndexInfoRetriever (CASSANDRA-12731)
+ * ColumnIndex does not reuse buffer (CASSANDRA-12502)
+ * cdc column addition still breaks schema migration tasks (CASSANDRA-12697)
+ * Upgrade metrics-reporter dependencies (CASSANDRA-12089)
+ * Tune compaction thread count via nodetool (CASSANDRA-12248)
+ * Add +=/-= shortcut syntax for update queries (CASSANDRA-12232)
+ * Include repair session IDs in repair start message (CASSANDRA-12532)
+ * Add a blocking task to Index, run before joining the ring (CASSANDRA-12039)
+ * Fix NPE when using CQLSSTableWriter (CASSANDRA-12667)
+ * Support optional backpressure strategies at the coordinator (CASSANDRA-9318)
+ * Make randompartitioner work with new vnode allocation (CASSANDRA-12647)
+ * Fix cassandra-stress graphing (CASSANDRA-12237)
+ * Allow filtering on partition key columns for queries without secondary indexes (CASSANDRA-11031)
+ * Fix Cassandra Stress reporting thread model and precision (CASSANDRA-12585)
+ * Add JMH benchmarks.jar (CASSANDRA-12586)
+ * Cleanup uses of AlterTableStatementColumn (CASSANDRA-12567)
+ * Add keep-alive to streaming (CASSANDRA-11841)
+ * Tracing payload is passed through newSession(..) (CASSANDRA-11706)
+ * avoid deleting non existing sstable files and improve related log messages (CASSANDRA-12261)
+ * json/yaml output format for nodetool compactionhistory (CASSANDRA-12486)
+ * Retry all internode messages once after a connection is
+ closed and reopened (CASSANDRA-12192)
+ * Add support to rebuild from targeted replica (CASSANDRA-9875)
+ * Add sequence distribution type to cassandra stress (CASSANDRA-12490)
+ * "SELECT * FROM foo LIMIT ;" does not error out (CASSANDRA-12154)
+ * Define executeLocally() at the ReadQuery Level (CASSANDRA-12474)
+ * Extend read/write failure messages with a map of replica addresses
+ to error codes in the v5 native protocol (CASSANDRA-12311)
+ * Fix rebuild of SASI indexes with existing index files (CASSANDRA-12374)
+ * Let DatabaseDescriptor not implicitly startup services (CASSANDRA-9054, 12550)
+ * Fix clustering indexes in presence of static columns in SASI (CASSANDRA-12378)
+ * Fix queries on columns with reversed type on SASI indexes (CASSANDRA-12223)
+ * Added slow query log (CASSANDRA-12403)
+ * Count full coordinated request against timeout (CASSANDRA-12256)
+ * Allow TTL with null value on insert and update (CASSANDRA-12216)
+ * Make decommission operation resumable (CASSANDRA-12008)
+ * Add support to one-way targeted repair (CASSANDRA-9876)
+ * Remove clientutil jar (CASSANDRA-11635)
+ * Fix compaction throughput throttle (CASSANDRA-12366, CASSANDRA-12717)
+ * Delay releasing Memtable memory on flush until PostFlush has finished running (CASSANDRA-12358)
+ * Cassandra stress should dump all setting on startup (CASSANDRA-11914)
+ * Make it possible to compact a given token range (CASSANDRA-10643)
+ * Allow updating DynamicEndpointSnitch properties via JMX (CASSANDRA-12179)
+ * Collect metrics on queries by consistency level (CASSANDRA-7384)
+ * Add support for GROUP BY to SELECT statement (CASSANDRA-10707)
+ * Deprecate memtable_cleanup_threshold and update default for memtable_flush_writers (CASSANDRA-12228)
+ * Upgrade to OHC 0.4.4 (CASSANDRA-12133)
+ * Add version command to cassandra-stress (CASSANDRA-12258)
+ * Create compaction-stress tool (CASSANDRA-11844)
+ * Garbage-collecting compaction operation and schema option (CASSANDRA-7019)
+ * Add beta protocol flag for v5 native protocol (CASSANDRA-12142)
+ * Support filtering on non-PRIMARY KEY columns in the CREATE
+ MATERIALIZED VIEW statement's WHERE clause (CASSANDRA-10368)
+ * Unify STDOUT and SYSTEMLOG logback format (CASSANDRA-12004)
+ * COPY FROM should raise error for non-existing input files (CASSANDRA-12174)
+ * Faster write path (CASSANDRA-12269)
+ * Option to leave omitted columns in INSERT JSON unset (CASSANDRA-11424)
+ * Support json/yaml output in nodetool tpstats (CASSANDRA-12035)
+ * Expose metrics for successful/failed authentication attempts (CASSANDRA-10635)
+ * Prepend snapshot name with "truncated" or "dropped" when a snapshot
+ is taken before truncating or dropping a table (CASSANDRA-12178)
+ * Optimize RestrictionSet (CASSANDRA-12153)
+ * cqlsh does not automatically downgrade CQL version (CASSANDRA-12150)
+ * Omit (de)serialization of state variable in UDAs (CASSANDRA-9613)
+ * Create a system table to expose prepared statements (CASSANDRA-8831)
+ * Reuse DataOutputBuffer from ColumnIndex (CASSANDRA-11970)
+ * Remove DatabaseDescriptor dependency from SegmentedFile (CASSANDRA-11580)
+ * Add supplied username to authentication error messages (CASSANDRA-12076)
+ * Remove pre-startup check for open JMX port (CASSANDRA-12074)
+ * Remove compaction Severity from DynamicEndpointSnitch (CASSANDRA-11738)
+ * Restore resumable hints delivery (CASSANDRA-11960)
+ * Properly report LWT contention (CASSANDRA-12626)
+Merged from 3.0:
+ * Remove ALTER TYPE support (CASSANDRA-12443)
* Fix assertion for certain legacy range tombstone pattern (CASSANDRA-12203)
- * Set javac encoding to utf-8 (CASSANDRA-11077)
* Replace empty strings with null values if they cannot be converted (CASSANDRA-12794)
- * Fixed flacky SSTableRewriterTest: check file counts before calling validateCFS (CASSANDRA-12348)
* Fix deserialization of 2.x DeletedCells (CASSANDRA-12620)
* Add parent repair session id to anticompaction log message (CASSANDRA-12186)
* Improve contention handling on failure to acquire MV lock for streaming and hints (CASSANDRA-12905)
http://git-wip-us.apache.org/repos/asf/cassandra/blob/d3882895/NEWS.txt
----------------------------------------------------------------------
diff --cc NEWS.txt
index 7bccaae,4505574..985c6d4
--- a/NEWS.txt
+++ b/NEWS.txt
@@@ -13,139 -13,37 +13,137 @@@ restore snapshots created with the prev
'sstableloader' tool. You can upgrade the file format of your snapshots
using the provided 'sstableupgrade' tool.
- 3.11
- ====
-3.0.11
-=====
--
--Upgrading
-----------
- - Support for alter types of already defined tables and of UDTs fields has been disabled.
- If it is necessary to return a different type, please use casting instead. See
- CASSANDRA-12443 for more details.
- - Nothing specific to this release, but please see previous versions upgrading section,
- especially if you are upgrading from 2.2.
-- - Specifying the default_time_to_live option when creating or altering a
-- materialized view was erroneously accepted (and ignored). It is now
-- properly rejected.
-- - Only Java and JavaScript are now supported UDF languages.
-- The sandbox in 3.0 already prevented the use of script languages except Java
-- and JavaScript.
-- - Compaction now correctly drops sstables out of CompactionTask when there
-- isn't enough disk space to perform the full compaction. This should reduce
-- pending compaction tasks on systems with little remaining disk space.
-3.0.10
-=====
+3.10
+====
-Upgrading
----------
- - memtable_allocation_type: offheap_buffers is no longer allowed to be specified in the 3.0 series.
- This was an oversight that can cause segfaults. Offheap was re-introduced in 3.4 see CASSANDRA-11039
- and CASSANDRA-9472 for details.
+New features
+------------
+ - New `DurationType` (cql duration). See CASSANDRA-11873
+ - Runtime modification of concurrent_compactors is now available via nodetool
+ - Support for the assignment operators +=/-= has been added for update queries.
+ - An Index implementation may now provide a task which runs prior to joining
+ the ring. See CASSANDRA-12039
+ - Filtering on partition key columns is now also supported for queries without
+ secondary indexes.
+ - A slow query log has been added: slow queries will be logged at DEBUG level.
+ For more details refer to CASSANDRA-12403 and slow_query_log_timeout_in_ms
+ in cassandra.yaml.
+ - Support for GROUP BY queries has been added.
+ - A new compaction-stress tool has been added to test the throughput of compaction
+ for any cassandra-stress user schema. see compaction-stress help for how to use.
+ - Compaction can now take into account overlapping tables that don't take part
+ in the compaction to look for deleted or overwritten data in the compacted tables.
+ Then such data is found, it can be safely discarded, which in turn should enable
+ the removal of tombstones over that data.
+
+ The behavior can be engaged in two ways:
+ - as a "nodetool garbagecollect -g CELL/ROW" operation, which applies
+ single-table compaction on all sstables to discard deleted data in one step.
+ - as a "provide_overlapping_tombstones:CELL/ROW/NONE" compaction strategy flag,
+ which uses overlapping tables as a source of deletions/overwrites during all
+ compactions.
+ The argument specifies the granularity at which deleted data is to be found:
+ - If ROW is specified, only whole deleted rows (or sets of rows) will be
+ discarded.
+ - If CELL is specified, any columns whose value is overwritten or deleted
+ will also be discarded.
+ - NONE (default) specifies the old behavior, overlapping tables are not used to
+ decide when to discard data.
+ Which option to use depends on your workload, both ROW and CELL increase the
+ disk load on compaction (especially with the size-tiered compaction strategy),
+ with CELL being more resource-intensive. Both should lead to better read
+ performance if deleting rows (resp. overwriting or deleting cells) is common.
+ - Prepared statements are now persisted in the table prepared_statements in
+ the system keyspace. Upon startup, this table is used to preload all
+ previously prepared statements - i.e. in many cases clients do not need to
+ re-prepare statements against restarted nodes.
+ - cqlsh can now connect to older Cassandra versions by downgrading the native
+ protocol version. Please note that this is currently not part of our release
+ testing and, as a consequence, it is not guaranteed to work in all cases.
+ See CASSANDRA-12150 for more details.
+ - Snapshots that are automatically taken before a table is dropped or truncated
+ will have a "dropped" or "truncated" prefix on their snapshot tag name.
+ - Metrics are exposed for successful and failed authentication attempts.
+ These can be located using the object names org.apache.cassandra.metrics:type=Client,name=AuthSuccess
+ and org.apache.cassandra.metrics:type=Client,name=AuthFailure respectively.
+ - Add support to "unset" JSON fields in prepared statements by specifying DEFAULT UNSET.
+ See CASSANDRA-11424 for details
+ - Allow TTL with null value on insert and update. It will be treated as equivalent to inserting a 0.
+ - Removed outboundBindAny configuration property. See CASSANDRA-12673 for details.
+
+Upgrading
+---------
++ - Support for alter types of already defined tables and of UDTs fields has been disabled.
++ If it is necessary to return a different type, please use casting instead. See
++ CASSANDRA-12443 for more details.
++ - Specifying the default_time_to_live option when creating or altering a
++ materialized view was erroneously accepted (and ignored). It is now
++ properly rejected.
++ - Only Java and JavaScript are now supported UDF languages.
++ The sandbox in 3.0 already prevented the use of script languages except Java
++ and JavaScript.
++ - Compaction now correctly drops sstables out of CompactionTask when there
++ isn't enough disk space to perform the full compaction. This should reduce
++ pending compaction tasks on systems with little remaining disk space.
+ - Request timeouts in cassandra.yaml (read_request_timeout_in_ms, etc) now apply to the
+ "full" request time on the coordinator. Previously, they only covered the time from
+ when the coordinator sent a message to a replica until the time that the replica
+ responded. Additionally, the previous behavior was to reset the timeout when performing
+ a read repair, making a second read to fix a short read, and when subranges were read
+ as part of a range scan or secondary index query. In 3.10 and higher, the timeout
+ is no longer reset for these "subqueries". The entire request must complete within
+ the specified timeout. As a consequence, your timeouts may need to be adjusted
+ to account for this. See CASSANDRA-12256 for more details.
+ - Logs written to stdout are now consistent with logs written to files.
+ Time is now local (it was UTC on the console and local in files). Date, thread, file
+ and line info where added to stdout. (see CASSANDRA-12004)
+ - The 'clientutil' jar, which has been somewhat broken on the 3.x branch, is not longer provided.
+ The features provided by that jar are provided by any good java driver and we advise relying on drivers rather on
+ that jar, but if you need that jar for backward compatiblity until you do so, you should use the version provided
+ on previous Cassandra branch, like the 3.0 branch (by design, the functionality provided by that jar are stable
+ accross versions so using the 3.0 jar for a client connecting to 3.x should work without issues).
+ - (Tools development) DatabaseDescriptor no longer implicitly startups components/services like
+ commit log replay. This may break existing 3rd party tools and clients. In order to startup
+ a standalone tool or client application, use the DatabaseDescriptor.toolInitialization() or
+ DatabaseDescriptor.clientInitialization() methods. Tool initialization sets up partitioner,
+ snitch, encryption context. Client initialization just applies the configuration but does not
+ setup anything. Instead of using Config.setClientMode() or Config.isClientMode(), which are
+ deprecated now, use one of the appropiate new methods in DatabaseDescriptor.
+ - Application layer keep-alives were added to the streaming protocol to prevent idle incoming connections from
+ timing out and failing the stream session (CASSANDRA-11839). This effectively deprecates the streaming_socket_timeout_in_ms
+ property in favor of streaming_keep_alive_period_in_secs. See cassandra.yaml for more details about this property.
+ - Duration litterals support the ISO 8601 format. By consequence, identifiers matching that format
+ (e.g P2Y or P1MT6H) will not be supported anymore (CASSANDRA-11873).
+
+3.8
+===
-3.0.9
-=====
+New features
+------------
+ - Shared pool threads are now named according to the stage they are executing
+ tasks for. Thread names mentioned in traced queries change accordingly.
+ - A new option has been added to cassandra-stress "-rate fixed={number}/s"
+ that forces a scheduled rate of operations/sec over time. Using this, stress can
+ accurately account for coordinated ommission from the stress process.
+ - The cassandra-stress "-rate limit=" option has been renamed to "-rate throttle="
+ - hdr histograms have been added to stress runs, it's output can be saved to disk using:
+ "-log hdrfile=" option. This histogram includes response/service/wait times when used with the
+ fixed or throttle rate options. The histogram file can be plotted on
+ http://hdrhistogram.github.io/HdrHistogram/plotFiles.html
+ - TimeWindowCompactionStrategy has been added. This has proven to be a better approach
+ to time series compaction and new tables should use this instead of DTCS. See
+ CASSANDRA-9666 for details.
+ - Change-Data-Capture is now available. See cassandra.yaml and for cdc-specific flags and
+ a brief explanation of on-disk locations for archived data in CommitLog form. This can
+ be enabled via ALTER TABLE ... WITH cdc=true.
+ Upon flush, CommitLogSegments containing data for CDC-enabled tables are moved to
+ the data/cdc_raw directory until removed by the user and writes to CDC-enabled tables
+ will be rejected with a WriteTimeoutException once cdc_total_space_in_mb is reached
+ between unflushed CommitLogSegments and cdc_raw.
+ NOTE: CDC is disabled by default in the .yaml file. Do not enable CDC on a mixed-version
+ cluster as it will lead to exceptions which can interrupt traffic. Once all nodes
+ have been upgraded to 3.8 it is safe to enable this feature and restart the cluster.
Upgrading
---------
http://git-wip-us.apache.org/repos/asf/cassandra/blob/d3882895/doc/cql3/CQL.textile
----------------------------------------------------------------------
diff --cc doc/cql3/CQL.textile
index 78882a5,1efa6d4..f2f9bd8
--- a/doc/cql3/CQL.textile
+++ b/doc/cql3/CQL.textile
@@@ -396,11 -397,8 +396,10 @@@ __Syntax:_
bc(syntax)..
<alter-table-stmt> ::= ALTER (TABLE | COLUMNFAMILY) <tablename> <instruction>
- <instruction> ::= ALTER <identifier> TYPE <type>
- | ADD <identifier> <type>
+ <instruction> ::= ADD <identifier> <type>
+ | ADD ( <identifier> <type> ( , <identifier> <type> )* )
| DROP <identifier>
+ | DROP ( <identifier> ( , <identifier> )* )
| WITH <option> ( AND <option> )*
p.
__Sample:__
http://git-wip-us.apache.org/repos/asf/cassandra/blob/d3882895/doc/source/cql/changes.rst
----------------------------------------------------------------------
diff --cc doc/source/cql/changes.rst
index 913bdb4,0000000..1eee536
mode 100644,000000..100644
--- a/doc/source/cql/changes.rst
+++ b/doc/source/cql/changes.rst
@@@ -1,198 -1,0 +1,204 @@@
+.. Licensed to the Apache Software Foundation (ASF) under one
+.. or more contributor license agreements. See the NOTICE file
+.. distributed with this work for additional information
+.. regarding copyright ownership. The ASF licenses this file
+.. to you under the Apache License, Version 2.0 (the
+.. "License"); you may not use this file except in compliance
+.. with the License. You may obtain a copy of the License at
+..
+.. http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS,
+.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. See the License for the specific language governing permissions and
+.. limitations under the License.
+
+.. highlight:: cql
+
+Changes
+-------
+
+The following describes the changes in each version of CQL.
+
++3.4.4
++^^^^^
++
++- ``ALTER TABLE`` ``ALTER`` has been removed; a column's type may not be changed after creation (:jira:`12443`).
++- ``ALTER TYPE`` ``ALTER`` has been removed; a field's type may not be changed after creation (:jira:`12443`).
++
+3.4.3
+^^^^^
+
+- Adds a new ``duration `` :ref:`data types <data-types>` (:jira:`11873`).
+- Support for ``GROUP BY`` (:jira:`10707`).
+- Adds a ``DEFAULT UNSET`` option for ``INSERT JSON`` to ignore omitted columns (:jira:`11424`).
+- Allows ``null`` as a legal value for TTL on insert and update. It will be treated as equivalent to
+inserting a 0 (:jira:`12216`).
+
+3.4.2
+^^^^^
+
+- 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.
+
+3.4.0
+^^^^^
+
+- 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``.
+
+3.3.0
+^^^^^
+
+- :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
+^^^^^
+
+- :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.
+- ``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 has been added.
+- Support for ``DELETE ... IF EXISTS`` syntax.
+
+3.1.5
+^^^^^
+
+- 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.
+
+3.1.3
+^^^^^
+
+- Millisecond precision formats have been added to the :ref:`timestamp <timestamps>` parser.
+
+3.1.2
+^^^^^
+
+- ``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 ``?``).
+
+3.1.0
+^^^^^
+
+- ``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)>`__.
+
+3.0.4
+^^^^^
+
+- 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 :ref:`secondary indexes <secondary-indexes>` has been added.
+
+3.0.2
+^^^^^
+
+- 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 (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.
+========= =============================================================================================================
http://git-wip-us.apache.org/repos/asf/cassandra/blob/d3882895/doc/source/cql/ddl.rst
----------------------------------------------------------------------
diff --cc doc/source/cql/ddl.rst
index 029c1cb,0000000..9c1946e
mode 100644,000000..100644
--- a/doc/source/cql/ddl.rst
+++ b/doc/source/cql/ddl.rst
@@@ -1,677 -1,0 +1,627 @@@
+.. Licensed to the Apache Software Foundation (ASF) under one
+.. or more contributor license agreements. See the NOTICE file
+.. distributed with this work for additional information
+.. regarding copyright ownership. The ASF licenses this file
+.. to you under the Apache License, Version 2.0 (the
+.. "License"); you may not use this file except in compliance
+.. with the License. You may obtain a copy of the License at
+..
+.. http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS,
+.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. See the License for the specific language governing permissions and
+.. limitations under the License.
+
+.. highlight:: cql
+
+.. _data-definition:
+
+Data Definition
+---------------
+
+CQL stores data in *tables*, whose schema defines the layout of said data in the table, and those tables are grouped in
+*keyspaces*. A keyspace defines a number of options that applies to all the tables it contains, most prominently of
+which is the :ref:`replication strategy <replication-strategy>` used by the keyspace. It is generally encouraged to use
+one keyspace by *application*, and thus many cluster may define only one keyspace.
+
+This section describes the statements used to create, modify, and remove those keyspace and tables.
+
+Common definitions
+^^^^^^^^^^^^^^^^^^
+
+The names of the keyspaces and tables are defined by the following grammar:
+
+.. productionlist::
+ keyspace_name: `name`
+ table_name: [ `keyspace_name` '.' ] `name`
+ name: `unquoted_name` | `quoted_name`
+ unquoted_name: re('[a-zA-Z_0-9]{1, 48}')
+ quoted_name: '"' `unquoted_name` '"'
+
+Both keyspace and table name should be comprised of only alphanumeric characters, cannot be empty and are limited in
+size to 48 characters (that limit exists mostly to avoid filenames (which may include the keyspace and table name) to go
+over the limits of certain file systems). By default, keyspace and table names are case insensitive (``myTable`` is
+equivalent to ``mytable``) but case sensitivity can be forced by using double-quotes (``"myTable"`` is different from
+``mytable``).
+
+Further, a table is always part of a keyspace and a table name can be provided fully-qualified by the keyspace it is
+part of. If is is not fully-qualified, the table is assumed to be in the *current* keyspace (see :ref:`USE statement
+<use-statement>`).
+
+Further, the valid names for columns is simply defined as:
+
+.. productionlist::
+ column_name: `identifier`
+
+We also define the notion of statement options for use in the following section:
+
+.. productionlist::
+ options: `option` ( AND `option` )*
+ option: `identifier` '=' ( `identifier` | `constant` | `map_literal` )
+
+.. _create-keyspace-statement:
+
+CREATE KEYSPACE
+^^^^^^^^^^^^^^^
+
+A keyspace is created using a ``CREATE KEYSPACE`` statement:
+
+.. productionlist::
+ create_keyspace_statement: CREATE KEYSPACE [ IF NOT EXISTS ] `keyspace_name` WITH `options`
+
+For instance::
+
+ CREATE KEYSPACE Excelsior
+ WITH replication = {'class': 'SimpleStrategy', 'replication_factor' : 3};
+
+ CREATE KEYSPACE Excalibur
+ WITH replication = {'class': 'NetworkTopologyStrategy', 'DC1' : 1, 'DC2' : 3}
+ AND durable_writes = false;
+
+
+The supported ``options`` are:
+
+=================== ========== =========== ========= ===================================================================
+name kind mandatory default description
+=================== ========== =========== ========= ===================================================================
+``replication`` *map* yes The replication strategy and options to use for the keyspace (see
+ details below).
+``durable_writes`` *simple* no true Whether to use the commit log for updates on this keyspace
+ (disable this option at your own risk!).
+=================== ========== =========== ========= ===================================================================
+
+The ``replication`` property is mandatory and must at least contains the ``'class'`` sub-option which defines the
+:ref:`replication strategy <replication-strategy>` class to use. The rest of the sub-options depends on what replication
+strategy is used. By default, Cassandra support the following ``'class'``:
+
+- ``'SimpleStrategy'``: A simple strategy that defines a replication factor for the whole cluster. The only sub-options
+ supported is ``'replication_factor'`` to define that replication factor and is mandatory.
+- ``'NetworkTopologyStrategy'``: A replication strategy that allows to set the replication factor independently for
+ each data-center. The rest of the sub-options are key-value pairs where a key is a data-center name and its value is
+ the associated replication factor.
+
+Attempting to create a keyspace that already exists will return an error unless the ``IF NOT EXISTS`` option is used. If
+it is used, the statement will be a no-op if the keyspace already exists.
+
+.. _use-statement:
+
+USE
+^^^
+
+The ``USE`` statement allows to change the *current* keyspace (for the *connection* on which it is executed). A number
+of objects in CQL are bound to a keyspace (tables, user-defined types, functions, ...) and the current keyspace is the
+default keyspace used when those objects are referred without a fully-qualified name (that is, without being prefixed a
+keyspace name). A ``USE`` statement simply takes the keyspace to use as current as argument:
+
+.. productionlist::
+ use_statement: USE `keyspace_name`
+
+.. _alter-keyspace-statement:
+
+ALTER KEYSPACE
+^^^^^^^^^^^^^^
+
+An ``ALTER KEYSPACE`` statement allows to modify the options of a keyspace:
+
+.. productionlist::
+ alter_keyspace_statement: ALTER KEYSPACE `keyspace_name` WITH `options`
+
+For instance::
+
+ ALTER KEYSPACE Excelsior
+ WITH replication = {'class': 'SimpleStrategy', 'replication_factor' : 4};
+
+The supported options are the same than for :ref:`creating a keyspace <create-keyspace-statement>`.
+
+.. _drop-keyspace-statement:
+
+DROP KEYSPACE
+^^^^^^^^^^^^^
+
+Dropping a keyspace can be done using the ``DROP KEYSPACE`` statement:
+
+.. productionlist::
+ drop_keyspace_statement: DROP KEYSPACE [ IF EXISTS ] `keyspace_name`
+
+For instance::
+
+ DROP KEYSPACE Excelsior;
+
+Dropping a keyspace results in the immediate, irreversible removal of that keyspace, including all the tables, UTD and
+functions in it, and all the data contained in those tables.
+
+If the keyspace does not exists, the statement will return an error, unless ``IF EXISTS`` is used in which case the
+operation is a no-op.
+
+.. _create-table-statement:
+
+CREATE TABLE
+^^^^^^^^^^^^
+
+Creating a new table uses the ``CREATE TABLE`` statement:
+
+.. productionlist::
+ create_table_statement: CREATE TABLE [ IF NOT EXISTS ] `table_name`
+ : '('
+ : `column_definition`
+ : ( ',' `column_definition` )*
+ : [ ',' PRIMARY KEY '(' `primary_key` ')' ]
+ : ')' [ WITH `table_options` ]
+ column_definition: `column_name` `cql_type` [ STATIC ] [ PRIMARY KEY]
+ primary_key: `partition_key` [ ',' `clustering_columns` ]
+ partition_key: `column_name`
+ : | '(' `column_name` ( ',' `column_name` )* ')'
+ clustering_columns: `column_name` ( ',' `column_name` )*
+ table_options: COMPACT STORAGE [ AND `table_options` ]
+ : | CLUSTERING ORDER BY '(' `clustering_order` ')' [ AND `table_options` ]
+ : | `options`
+ clustering_order: `column_name` (ASC | DESC) ( ',' `column_name` (ASC | DESC) )*
+
+For instance::
+
+ CREATE TABLE monkeySpecies (
+ species text PRIMARY KEY,
+ common_name text,
+ population varint,
+ average_size int
+ ) WITH comment='Important biological records'
+ AND read_repair_chance = 1.0;
+
+ CREATE TABLE timeline (
+ userid uuid,
+ posted_month int,
+ posted_time uuid,
+ body text,
+ posted_by text,
+ PRIMARY KEY (userid, posted_month, posted_time)
+ ) WITH compaction = { 'class' : 'LeveledCompactionStrategy' };
+
+ CREATE TABLE loads (
+ machine inet,
+ cpu int,
+ mtime timeuuid,
+ load float,
+ PRIMARY KEY ((machine, cpu), mtime)
+ ) WITH CLUSTERING ORDER BY (mtime DESC);
+
+A CQL table has a name and is composed of a set of *rows*. Creating a table amounts to defining which :ref:`columns
+<column-definition>` the rows will be composed, which of those columns compose the :ref:`primary key <primary-key>`, as
+well as optional :ref:`options <create-table-options>` for the table.
+
+Attempting to create an already existing table will return an error unless the ``IF NOT EXISTS`` directive is used. If
+it is used, the statement will be a no-op if the table already exists.
+
+
+.. _column-definition:
+
+Column definitions
+~~~~~~~~~~~~~~~~~~
+
+Every rows in a CQL table has a set of predefined columns defined at the time of the table creation (or added later
+using an :ref:`alter statement<alter-table-statement>`).
+
+A :token:`column_definition` is primarily comprised of the name of the column defined and it's :ref:`type <data-types>`,
+which restrict which values are accepted for that column. Additionally, a column definition can have the following
+modifiers:
+
+``STATIC``
+ it declares the column as being a :ref:`static column <static-columns>`.
+
+``PRIMARY KEY``
+ it declares the column as being the sole component of the :ref:`primary key <primary-key>` of the table.
+
+.. _static-columns:
+
+Static columns
+``````````````
+Some columns can be declared as ``STATIC`` in a table definition. A column that is static will be \u201cshared\u201d by all the
+rows belonging to the same partition (having the same :ref:`partition key <partition-key>`). For instance::
+
+ CREATE TABLE t (
+ pk int,
+ t int,
+ v text,
+ s text static,
+ PRIMARY KEY (pk, t)
+ );
+
+ INSERT INTO t (pk, t, v, s) VALUES (0, 0, 'val0', 'static0');
+ INSERT INTO t (pk, t, v, s) VALUES (0, 1, 'val1', 'static1');
+
+ SELECT * FROM t;
+ pk | t | v | s
+ ----+---+--------+-----------
+ 0 | 0 | 'val0' | 'static1'
+ 0 | 1 | 'val1' | 'static1'
+
+As can be seen, the ``s`` value is the same (``static1``) for both of the row in the partition (the partition key in
+that example being ``pk``, both rows are in that same partition): the 2nd insertion has overridden the value for ``s``.
+
+The use of static columns as the following restrictions:
+
+- tables with the ``COMPACT STORAGE`` option (see below) cannot use them.
+- a table without clustering columns cannot have static columns (in a table without clustering columns, every partition
+ has only one row, and so every column is inherently static).
+- only non ``PRIMARY KEY`` columns can be static.
+
+.. _primary-key:
+
+The Primary key
+~~~~~~~~~~~~~~~
+
+Within a table, a row is uniquely identified by its ``PRIMARY KEY``, and hence all table **must** define a PRIMARY KEY
+(and only one). A ``PRIMARY KEY`` definition is composed of one or more of the columns defined in the table.
+Syntactically, the primary key is defined the keywords ``PRIMARY KEY`` followed by comma-separated list of the column
+names composing it within parenthesis, but if the primary key has only one column, one can alternatively follow that
+column definition by the ``PRIMARY KEY`` keywords. The order of the columns in the primary key definition matter.
+
+A CQL primary key is composed of 2 parts:
+
+- the :ref:`partition key <partition-key>` part. It is the first component of the primary key definition. It can be a
+ single column or, using additional parenthesis, can be multiple columns. A table always have at least a partition key,
+ the smallest possible table definition is::
+
+ CREATE TABLE t (k text PRIMARY KEY);
+
+- the :ref:`clustering columns <clustering-columns>`. Those are the columns after the first component of the primary key
+ definition, and the order of those columns define the *clustering order*.
+
+Some example of primary key definition are:
+
+- ``PRIMARY KEY (a)``: ``a`` is the partition key and there is no clustering columns.
+- ``PRIMARY KEY (a, b, c)`` : ``a`` is the partition key and ``b`` and ``c`` are the clustering columns.
+- ``PRIMARY KEY ((a, b), c)`` : ``a`` and ``b`` compose the partition key (this is often called a *composite* partition
+ key) and ``c`` is the clustering column.
+
+
+.. _partition-key:
+
+The partition key
+`````````````````
+
+Within a table, CQL defines the notion of a *partition*. A partition is simply the set of rows that share the same value
+for their partition key. Note that if the partition key is composed of multiple columns, then rows belong to the same
+partition only they have the same values for all those partition key column. So for instance, given the following table
+definition and content::
+
+ CREATE TABLE t (
+ a int,
+ b int,
+ c int,
+ d int,
+ PRIMARY KEY ((a, b), c, d)
+ );
+
+ SELECT * FROM t;
+ a | b | c | d
+ ---+---+---+---
+ 0 | 0 | 0 | 0 // row 1
+ 0 | 0 | 1 | 1 // row 2
+ 0 | 1 | 2 | 2 // row 3
+ 0 | 1 | 3 | 3 // row 4
+ 1 | 1 | 4 | 4 // row 5
+
+``row 1`` and ``row 2`` are in the same partition, ``row 3`` and ``row 4`` are also in the same partition (but a
+different one) and ``row 5`` is in yet another partition.
+
+Note that a table always has a partition key, and that if the table has no :ref:`clustering columns
+<clustering-columns>`, then every partition of that table is only comprised of a single row (since the primary key
+uniquely identifies rows and the primary key is equal to the partition key if there is no clustering columns).
+
+The most important property of partition is that all the rows belonging to the same partition are guarantee to be stored
+on the same set of replica nodes. In other words, the partition key of a table defines which of the rows will be
+localized together in the Cluster, and it is thus important to choose your partition key wisely so that rows that needs
+to be fetch together are in the same partition (so that querying those rows together require contacting a minimum of
+nodes).
+
+Please note however that there is a flip-side to this guarantee: as all rows sharing a partition key are guaranteed to
+be stored on the same set of replica node, a partition key that groups too much data can create a hotspot.
+
+Another useful property of a partition is that when writing data, all the updates belonging to a single partition are
+done *atomically* and in *isolation*, which is not the case across partitions.
+
+The proper choice of the partition key and clustering columns for a table is probably one of the most important aspect
+of data modeling in Cassandra, and it largely impact which queries can be performed, and how efficiently they are.
+
+
+.. _clustering-columns:
+
+The clustering columns
+``````````````````````
+
+The clustering columns of a table defines the clustering order for the partition of that table. For a given
+:ref:`partition <partition-key>`, all the rows are physically ordered inside Cassandra by that clustering order. For
+instance, given::
+
+ CREATE TABLE t (
+ a int,
+ b int,
+ c int,
+ PRIMARY KEY (a, c, d)
+ );
+
+ SELECT * FROM t;
+ a | b | c
+ ---+---+---
+ 0 | 0 | 4 // row 1
+ 0 | 1 | 9 // row 2
+ 0 | 2 | 2 // row 3
+ 0 | 3 | 3 // row 4
+
+then the rows (which all belong to the same partition) are all stored internally in the order of the values of their
+``b`` column (the order they are displayed above). So where the partition key of the table allows to group rows on the
+same replica set, the clustering columns controls how those rows are stored on the replica. That sorting allows the
+retrieval of a range of rows within a partition (for instance, in the example above, ``SELECT * FROM t WHERE a = 0 AND b
+> 1 and b <= 3``) very efficient.
+
+
+.. _create-table-options:
+
+Table options
+~~~~~~~~~~~~~
+
+A CQL table has a number of options that can be set at creation (and, for most of them, :ref:`altered
+<alter-table-statement>` later). These options are specified after the ``WITH`` keyword.
+
+Amongst those options, two important ones cannot be changed after creation and influence which queries can be done
+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-tables:
+
+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 |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
+compatibility for definitions created before CQL version 3 (see `www.datastax.com/dev/blog/thrift-to-cql3
+<http://www.datastax.com/dev/blog/thrift-to-cql3>`__ for more details) and shouldn't be used for new tables. Declaring a
+table with this option creates limitations for the table which are largely arbitrary but necessary for backward
+compatibility with the (deprecated) Thrift API. Amongst those limitation:
+
+- a compact table cannot use collections nor static columns.
+- if a compact table has at least one clustering column, then it must have *exactly* one column outside of the primary
+ key ones. This imply you cannot add or remove columns after creation in particular.
+- a compact table is limited in the indexes it can create, and no materialized view can be created on it.
+
+.. _clustering-order:
+
+Reversing the clustering order
+``````````````````````````````
+
+The clustering order of a table is defined by the :ref:`clustering columns <clustering-columns>` of that table. By
+default, that ordering is based on natural order of those clustering order, but the ``CLUSTERING ORDER`` allows to
+change that clustering order to use the *reverse* natural order for some (potentially all) of the columns.
+
+The ``CLUSTERING ORDER`` option takes the comma-separated list of the clustering column, each with a ``ASC`` (for
+*ascendant*, e.g. the natural order) or ``DESC`` (for *descendant*, e.g. the reverse natural order). Note in particular
+that the default (if the ``CLUSTERING ORDER`` option is not used) is strictly equivalent to using the option with all
+clustering columns using the ``ASC`` modifier.
+
+Note that this option is basically a hint for the storage engine to change the order in which it stores the row but it
+has 3 visible consequences:
+
+# it limits which ``ORDER BY`` clause are allowed for :ref:`selects <select-statement>` on that table. You can only
+ order results by the clustering order or the reverse clustering order. Meaning that if a table has 2 clustering column
+ ``a`` and ``b`` and you defined ``WITH CLUSTERING ORDER (a DESC, b ASC)``, then in queries you will be allowed to use
+ ``ORDER BY (a DESC, b ASC)`` and (reverse clustering order) ``ORDER BY (a ASC, b DESC)`` but **not** ``ORDER BY (a
+ ASC, b ASC)`` (nor ``ORDER BY (a DESC, b DESC)``).
+# it also change the default order of results when queried (if no ``ORDER BY`` is provided). Results are always returned
+ in clustering order (within a partition).
+# it has a small performance impact on some queries as queries in reverse clustering order are slower than the one in
+ forward clustering order. In practice, this means that if you plan on querying mostly in the reverse natural order of
+ your columns (which is common with time series for instance where you often want data from the newest to the oldest),
+ it is an optimization to declare a descending clustering order.
+
+.. _create-table-general-options:
+
+Other table options
+```````````````````
+
+.. todo:: review (misses cdc if nothing else) and link to proper categories when appropriate (compaction for instance)
+
+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 (\u201cTTL\u201d) 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`` 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
+###################
+
+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 \u201cstring constant\u201d:#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
+###############
+
+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 (\u201ckey cache\u201d) for this table. Valid values are: ``ALL`` and
+ ``NONE``.
+ ``rows_per_partition`` NONE The amount of rows to cache per partition (\u201crow cache\u201d). 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:
+#####################
+
+- 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
+^^^^^^^^^^^
+
+Altering an existing table uses the ``ALTER TABLE`` statement:
+
+.. productionlist::
+ alter_table_statement: ALTER TABLE `table_name` `alter_table_instruction`
- alter_table_instruction: ALTER `column_name` TYPE `cql_type`
- : | ADD `column_name` `cql_type` ( ',' `column_name` `cql_type` )*
++ alter_table_instruction: ADD `column_name` `cql_type` ( ',' `column_name` `cql_type` )*
+ : | DROP `column_name` ( `column_name` )*
+ : | WITH `options`
+
+For instance::
+
- ALTER TABLE addamsFamily ALTER lastKnownLocation TYPE uuid;
-
+ ALTER TABLE addamsFamily ADD gravesite varchar;
+
+ ALTER TABLE addamsFamily
+ WITH comment = 'A most excellent and useful table'
+ AND read_repair_chance = 0.2;
+
+The ``ALTER TABLE`` statement can:
+
- - Change the type of one of the column in the table (through the ``ALTER`` instruction). Note that the type of a column
- cannot be changed arbitrarily. The change of type should be such that any value of the previous type should be a valid
- value of the new type. Further, for :ref:`clustering columns <clustering-columns>` and columns on which a secondary
- index is defined, the new type must sort values in the same way the previous type does. See the :ref:`type
- 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. 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. 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
+ erasing all previous ``compaction`` options, so you need to re-specify all the sub-options if you want to keep them.
+ The same note applies to the set of ``compression`` sub-options.
+
+.. warning:: Dropping a column assumes that the timestamps used for the value of this column are "real" timestamp in
+ microseconds. Using "real" timestamps in microseconds is the default is and is **strongly** recommended but as
+ Cassandra allows the client to provide any timestamp on any table it is theoretically possible to use another
+ 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).
+
- .. _alter-table-type-compatibility:
-
- CQL type compatibility:
- ~~~~~~~~~~~~~~~~~~~~~~~
-
- CQL data types may be converted only as the following table.
-
- +-------------------------------------------------------+--------------------+
- | Existing type | Can be altered to: |
- +=======================================================+====================+
- | timestamp | bigint |
- +-------------------------------------------------------+--------------------+
- | ascii, bigint, boolean, date, decimal, double, float, | blob |
- | inet, int, smallint, text, time, timestamp, timeuuid, | |
- | tinyint, uuid, varchar, varint | |
- +-------------------------------------------------------+--------------------+
- | int | date |
- +-------------------------------------------------------+--------------------+
- | ascii, varchar | text |
- +-------------------------------------------------------+--------------------+
- | bigint | time |
- +-------------------------------------------------------+--------------------+
- | bigint | timestamp |
- +-------------------------------------------------------+--------------------+
- | timeuuid | uuid |
- +-------------------------------------------------------+--------------------+
- | ascii, text | varchar |
- +-------------------------------------------------------+--------------------+
- | bigint, int, timestamp | varint |
- +-------------------------------------------------------+--------------------+
-
- Clustering columns have stricter requirements, only the following conversions are allowed:
-
- +------------------------+----------------------+
- | Existing type | Can be altered to |
- +========================+======================+
- | ascii, text, varchar | blob |
- +------------------------+----------------------+
- | ascii, varchar | text |
- +------------------------+----------------------+
- | ascii, text | varchar |
- +------------------------+----------------------+
+
+.. _drop-table-statement:
+
+DROP TABLE
+^^^^^^^^^^
+
+Dropping a table uses the ``DROP TABLE`` statement:
+
+.. productionlist::
+ drop_table_statement: DROP TABLE [ IF EXISTS ] `table_name`
+
+Dropping a table results in the immediate, irreversible removal of the table, including all data it contains.
+
+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
+^^^^^^^^
+
+A table can be truncated using the ``TRUNCATE`` statement:
+
+.. productionlist::
+ truncate_statement: TRUNCATE [ TABLE ] `table_name`
+
+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.