From 0894fd97a2df87dd833272c5db16fb3238e11012 Mon Sep 17 00:00:00 2001
From: Benjamin Lerer <b.lerer@gmail.com>
Date: Wed, 10 Aug 2022 18:11:08 +0200
Subject: [PATCH] Adds missing changes to CQL.textile

Patch by Benjamin Lerer; review by Brandon Williams for CASSANDRA-17709
---
 doc/cql3/CQL.textile | 62 +++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 55 insertions(+), 7 deletions(-)

diff --git a/doc/cql3/CQL.textile b/doc/cql3/CQL.textile
index 8c7c3ab1b5..26cf66a403 100644
--- a/doc/cql3/CQL.textile
+++ b/doc/cql3/CQL.textile
@@ -18,7 +18,7 @@
 #
 -->
 
-h1. Cassandra Query Language (CQL) v3.4.3
+h1. Cassandra Query Language (CQL) v3.4.4
 
 
 
@@ -579,7 +579,7 @@ __Syntax:__
 bc(syntax). <alter-materialized-view-stmt> ::= ALTER MATERIALIZED VIEW <viewname>
                                                  WITH <option> ( AND <option> )*
 
-p.
+p. 
 The @ALTER MATERIALIZED VIEW@ statement allows options to be update; these options are the same as <a href="#createTableOptions">@CREATE TABLE@'s options</a>.
 
 
@@ -863,7 +863,7 @@ __Syntax:__
 bc(syntax).. 
 <insertStatement> ::= INSERT INTO <tablename>
                       ( ( <name-list> VALUES <value-list> )
-                      | ( JSON <string> ))
+                      | ( JSON <string> [ DEFAULT ( NULL | UNSET ) ]))
                       ( IF NOT EXISTS )?
                       ( USING <option> ( AND <option> )* )?
 
@@ -961,7 +961,7 @@ h4(#updateOptions). @<options>@
 
 The @UPDATE@ and @INSERT@ statements support the following options:
 * @TIMESTAMP@: sets the timestamp for the operation. If not specified, the coordinator will use the current time (in microseconds) at the start of statement execution as the timestamp. This is usually a suitable default.
-* @TTL@: specifies an optional Time To Live (in seconds) for the inserted values. If set, the inserted values are automatically removed from the database after the specified time. Note that the TTL concerns the inserted values, not the columns themselves. This means that any subsequent update of the column will also reset the TTL (to whatever TTL is specified in that update). By default, values never expire. A TTL of 0 is equivalent to no TTL. If the table has a default_time_to_live, a TTL of 0 will remove the TTL for the inserted or updated values.
+* @TTL@: specifies an optional Time To Live (in seconds) for the inserted values. If set, the inserted values are automatically removed from the database after the specified time. Note that the TTL concerns the inserted values, not the columns themselves. This means that any subsequent update of the column will also reset the TTL (to whatever TTL is specified in that update). By default, values never expire. A TTL of 0 is equivalent to no TTL. If the table has a default_time_to_live, a TTL of 0 will remove the TTL for the inserted or updated values. A TTL of @null@ is equivalent to inserting with a TTL of 0.
 
 
 h3(#deleteStmt). DELETE
@@ -1653,7 +1653,7 @@ bc(syntax)..
              | FUNCTION <functionname>
              | ALL MBEANS
              | ( MBEAN | MBEANS ) <objectName>
-p.
+p. 
 
 __Sample:__ 
 
@@ -1683,7 +1683,7 @@ bc(syntax)..
              | FUNCTION <functionname>
              | ALL MBEANS
              | ( MBEAN | MBEANS ) <objectName>
-p.
+p. 
 
 __Sample:__
 
@@ -1722,6 +1722,7 @@ bc(syntax)..
                 | date
                 | decimal
                 | double
+                | duration
                 | float
                 | inet
                 | int
@@ -1752,6 +1753,7 @@ p. The following table gives additional informations on the native data types, a
 |@date@     |   integers, strings  |A date (with no corresponding time value).  See "Working with dates":#usingdates below for more information.|
 |@decimal@  |   integers, floats   |Variable-precision decimal|
 |@double@   |   integers           |64-bit IEEE-754 floating point|
+|@duration@ |   duration           |A duration with nanosecond precision. See "Working with durations":#usingdurations below for details.|
 |@float@    |   integers, floats   |32-bit IEEE-754 floating point|
 |@inet@     |   strings            |An IP address. It can be either 4 bytes long (IPv4) or 16 bytes long (IPv6). There is no @inet@ constant, IP address should be inputed as strings|
 |@int@      |   integers           |32-bit signed int|
@@ -1825,6 +1827,44 @@ They can also be input as string literals in any of the following formats:
 * @08:12:54.123456@
 * @08:12:54.123456789@
 
+h3(#usingdurations). Working with durations
+
+Values of the @duration@ type are encoded as 3 signed integers of variable lengths. The first integer represents the
+number of months, the second the number of days and the third the number of nanoseconds. This is due to the fact that
+the number of days in a month can change, and a day can have 23 or 25 hours depending on the daylight saving.
+
+A duration can be input as:
+
+* (quantity unit)+ like @12h30m@ where the unit can be:
+** @y@: years (12 months)
+** @mo@: months (1 month)
+** @w@: weeks (7 days)
+** @d@: days (1 day)
+** @h@: hours (3,600,000,000,000 nanoseconds)
+** @m@: minutes (60,000,000,000 nanoseconds)
+** @s@: seconds (1,000,000,000 nanoseconds)
+** @ms@: milliseconds (1,000,000 nanoseconds)
+** @us@ or @µs@ : microseconds (1000 nanoseconds)
+** @ns@: nanoseconds (1 nanosecond)
+* ISO 8601 format:  @P[n]Y[n]M[n]DT[n]H[n]M[n]S@ or @P[n]W@
+* ISO 8601 alternative format: @P[YYYY]-[MM]-[DD]T[hh]:[mm]:[ss]@
+
+For example:
+
+bc(sample). 
+    INSERT INTO RiderResults (rider, race, result) VALUES ('Christopher Froome', 'Tour de France', 89h4m48s);
+    INSERT INTO RiderResults (rider, race, result) VALUES ('BARDET Romain', 'Tour de France', PT89H8M53S);
+    INSERT INTO RiderResults (rider, race, result) VALUES ('QUINTANA Nairo', 'Tour de France', P0000-00-00T89:09:09);
+
+h4. duration-limitation:
+
+Duration columns cannot be used in a table's @PRIMARY KEY@. This limitation is due to the fact that
+durations cannot be ordered. It is effectively not possible to know if @1mo@ is greater than @29d@ without a date
+context.
+
+A @1d@ duration is not equals to a @24h@ one as the duration type has been created to be able to support daylight
+saving.
+
 
 h3(#counters). Counters
 
@@ -2253,7 +2293,7 @@ With @INSERT@ statements, the new @JSON@ keyword can be used to enable inserting
 bc(sample). 
 INSERT INTO mytable JSON '{"\"myKey\"": 0, "value": 0}'
 
-Any columns which are ommitted from the @JSON@ map will be defaulted to a @NULL@ value (which will result in a tombstone being created).
+By default (or if @DEFAULT NULL@ is explicitly used), a column omitted from the @JSON@ map will be set to @NULL@, meaning that any pre-existing value for that column will be removed (resulting in a tombstone being created). Alternatively, if the @DEFAULT UNSET@ directive is used after the value, omitted column values will be left unset, meaning that pre-existing values for those column will be preserved.
 
 h3(#jsonEncoding). JSON Encoding of Cassandra Data Types
 
@@ -2454,9 +2494,17 @@ h2(#changes). Changes
 
 The following describes the changes in each version of CQL.
 
+h3. 3.4.4
+
+* @ALTER TABLE ALTER@ has been removed; a column’s type may not be changed after creation (see "CASSANDRA-12443":https://issues.apache.org/jira/browse/CASSANDRA-12443).
+* @ALTER TYPE ALTER@ has been removed; a field’s type may not be changed after creation (see "CASSANDRA-12443":https://issues.apache.org/jira/browse/CASSANDRA-12443).
+
 h3. 3.4.3
 
+* Adds a new @duration@ data type See "Data Types":#types (see "CASSANDRA-11873":https://issues.apache.org/jira/browse/CASSANDRA-11873).
 * Support for @GROUP BY@. See "@<group-by>@":#selectGroupBy (see "CASSANDRA-10707":https://issues.apache.org/jira/browse/CASSANDRA-10707).
+* Adds a @DEFAULT UNSET@ option for @INSERT JSON@ to ignore omitted columns (see "CASSANDRA-11424":https://issues.apache.org/jira/browse/CASSANDRA-11424).
+* Allows @null@ as a legal value for TTL on insert and update. It will be treated as equivalent to inserting a 0 (see "CASSANDRA-12216":https://issues.apache.org/jira/browse/CASSANDRA-12216).
 
 h3. 3.4.2