[cassandra] branch trunk updated: Update compact storage related docs Authored by Ekaterina Dimitrova; reviewed by Michael Semb Wever and Berenguer Blasi for CASSANDRA-16476

[ed...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

edimitrova pushed a commit to branch trunk
in repository https://gitbox.apache.org/repos/asf/cassandra.git


The following commit(s) were added to refs/heads/trunk by this push:
     new 0a49d25  Update compact storage related docs Authored by Ekaterina Dimitrova; reviewed by Michael Semb Wever and Berenguer Blasi for CASSANDRA-16476
0a49d25 is described below

commit 0a49d25078665da0ec30d9e69a036de163deb9c3
Author: Ekaterina Dimitrova <ek...@datastax.com>
AuthorDate: Fri Mar 5 23:33:00 2021 -0500

    Update compact storage related docs
    Authored by Ekaterina Dimitrova; reviewed by Michael Semb Wever and Berenguer Blasi for CASSANDRA-16476
---
 doc/cql3/CQL.textile   |  2 ++
 doc/source/cql/ddl.rst | 26 ++++++++++++++++++++++++++
 2 files changed, 28 insertions(+)

diff --git a/doc/cql3/CQL.textile b/doc/cql3/CQL.textile
index fafca14..f50b2ac 100644
--- a/doc/cql3/CQL.textile
+++ b/doc/cql3/CQL.textile
@@ -396,6 +396,7 @@ bc(syntax)..
                 | ADD   ( <identifier> <type> ( , <identifier> <type> )* )
                 | DROP  <identifier>
                 | DROP  ( <identifier> ( , <identifier> )* )
+                | DROP COMPACT STORAGE
                 | WITH  <option> ( AND <option> )*
 p. 
 __Sample:__
@@ -414,6 +415,7 @@ The @ALTER@ statement is used to manipulate table definitions. It allows for add
 The @<tablename>@ is the table name optionally preceded by the keyspace name.  The @<instruction>@ defines the alteration to perform:
 * @ADD@: Adds a new column to the table. The @<identifier>@ for the new column must not conflict with an existing column. Moreover, columns cannot be added to tables defined with the @COMPACT STORAGE@ option.
 * @DROP@: Removes a column from the table. Dropped columns will immediately become unavailable in the queries and will not be included in compacted sstables in the future. If a column is readded, queries won't return values written before the column was last dropped. It is assumed that timestamps represent actual time, so if this is not your case, you should NOT readd previously dropped columns. Columns can't be dropped from tables defined with the @COMPACT STORAGE@ option.
+* @DROP COMPACT STORAGE@: Removes Thrift compatibility mode from the table.
 * @WITH@: Allows to update the options of the table. The "supported @<option>@":#createTableOptions (and syntax) are the same as for the @CREATE TABLE@ statement except that @COMPACT STORAGE@ is not supported. 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.
 
 h4. CQL type compatibility:
diff --git a/doc/source/cql/ddl.rst b/doc/source/cql/ddl.rst
index d0e92ec..2f442e9 100644
--- a/doc/source/cql/ddl.rst
+++ b/doc/source/cql/ddl.rst
@@ -453,6 +453,32 @@ A CQL table has a number of options that can be set at creation (and, for most o
 <alter-table-statement>` later). These options are specified after the ``WITH`` keyword and are described
 in the following sections.
 
+.. _compact-tables:
+
+ COMPACT STORAGE tables
+ ``````````````
+
+.. warning:: It is strongly discouraged to create new tables with the ``COMPACT STORAGE`` option. Since Cassandra 3.0,
+    compact storage 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. As of Cassandra
+    |version| ``COMPACT STORAGE`` cannot be removed.
+
+.. warning:: ``DROP COMPACT STORAGE`` is not recommended for production environments. There are still cases where a change of
+    behavior is observed. To name a few: (1) Hidden columns show up, which breaks ``SELECT *`` queries.
+    (2) ``DELETE v`` and ``UPDATE v WITH TTL`` would result into row removals in non-dense compact storage tables (CASSANDRA-16069)
+    (3) ``INSERT`` allows skipping clusterings, which are filled with nulls by default.
+
+ A *compact storage* table is one defined with the ``COMPACT STORAGE`` option. This option is only maintained for backward
+ compatibility for definitions created before CQL version 3 and shouldn't be used for new tables. 4.0 supports partially
+ ``COMPACT STORAGE``. There is no support for super column family. Since Cassandra 3.0, compact storage tables have the exact
+ same layout internally than non compact ones (for the same schema obviously), and declaring a table with this option creates
+ limitations for the table which are largely arbitrary (and exists for historical reasons). Amongst those limitation:
+
+ - a compact storage table cannot use collections nor static columns.
+ - if a compact storage table has at least one clustering column, then it must have *exactly* one column outside of the primary
+   key ones. This implies you cannot add or remove columns after creation in particular.
+ - a compact storage table is limited in the indexes it can create, and no materialized view can be created on it.
+
 But please bear in mind that the ``CLUSTERING ORDER`` option cannot be changed after table creation and
 has influences on the performance of some queries.
 

---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@cassandra.apache.org
For additional commands, e-mail: commits-help@cassandra.apache.org