cassandra-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ble...@apache.org
Subject [3/3] cassandra git commit: Merge branch cassandra-3.0 into cassandra-3.11
Date Wed, 18 Jan 2017 15:07:52 GMT
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.lerer@gmail.com>
Authored: Wed Jan 18 16:00:11 2017 +0100
Committer: Benjamin Lerer <b.lerer@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 “shared” 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 (“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`` 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 “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
 +###############
 +
 +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.
 +======================== ========= ====================================================================================
 +
 +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.


Mime
View raw message