You are viewing a plain text version of this content. The canonical link for it is here.
Posted to pr@cassandra.apache.org by GitBox <gi...@apache.org> on 2020/09/21 13:58:12 UTC
[GitHub] [cassandra] belliottsmith commented on a change in pull request #745: [CASSANDRA-16117] Improve docs about frozen types and invert UDT/Tuple order
belliottsmith commented on a change in pull request #745:
URL: https://github.com/apache/cassandra/pull/745#discussion_r492062038
##########
File path: doc/source/cql/types.rst
##########
@@ -400,20 +398,46 @@ Further, lists support:
Lastly, as for :ref:`maps <maps>`, TTLs when used only apply to the newly inserted values.
+.. _tuples:
+
+Tuples
+^^^^^^
+
+CQL also support tuples and tuple types (where the elements can be of different types). Tuple types and tuple literals
+are defined by:
+
+.. productionlist::
+ tuple_type: TUPLE '<' `cql_type` ( ',' `cql_type` )* '>'
+ tuple_literal: '(' `term` ( ',' `term` )* ')'
+
+and can be used thusly::
+
+ CREATE TABLE durations (
+ event text,
+ duration tuple<int, text>,
+ )
+
+ INSERT INTO durations (event, duration) VALUES ('ev1', (3, 'hours'));
+
+Unlike other "composed" types (collections and UDT), a tuple is always :ref:`frozen <frozen>` (without the need of the
+`frozen` keyword) and it is not possible to update only some elements of a tuple (without updating the whole tuple).
Review comment:
```suggestion
`frozen` keyword). It is not possible to update only some elements of a tuple (without updating the whole tuple).
```
##########
File path: doc/source/cql/types.rst
##########
@@ -400,20 +398,46 @@ Further, lists support:
Lastly, as for :ref:`maps <maps>`, TTLs when used only apply to the newly inserted values.
+.. _tuples:
+
+Tuples
+^^^^^^
+
+CQL also support tuples and tuple types (where the elements can be of different types). Tuple types and tuple literals
+are defined by:
+
+.. productionlist::
+ tuple_type: TUPLE '<' `cql_type` ( ',' `cql_type` )* '>'
+ tuple_literal: '(' `term` ( ',' `term` )* ')'
+
+and can be used thusly::
+
+ CREATE TABLE durations (
+ event text,
+ duration tuple<int, text>,
+ )
+
+ INSERT INTO durations (event, duration) VALUES ('ev1', (3, 'hours'));
+
+Unlike other "composed" types (collections and UDT), a tuple is always :ref:`frozen <frozen>` (without the need of the
+`frozen` keyword) and it is not possible to update only some elements of a tuple (without updating the whole tuple).
+Also, a tuple literal should always have the same number of value than declared in the type it is a tuple of (some of
+those values can be null but they need to be explicitly declared as so).
+
.. _udts:
User-Defined Types
^^^^^^^^^^^^^^^^^^
-CQL support the definition of user-defined types (UDT for short). Such a type can be created, modified and removed using
-the :token:`create_type_statement`, :token:`alter_type_statement` and :token:`drop_type_statement` described below. But
+CQL support the definition of user-defined types (UDT for short), which is basically a tuple on steroids - it's
+literally an extension of the class that represents a tuple. Such a type can be created, modified and removed using the
Review comment:
It's better to keep implementation details out of these docs, I think - I'm not sure it's necessary to specify that a UDT is a form of tuple. Much as I like it, I think docs should also perhaps use less interesting language? (so "on steroids" might better be avoided, but just my 2c)
##########
File path: doc/source/cql/types.rst
##########
@@ -515,31 +539,48 @@ still in use by another type, table or function will result in an error.
If the type dropped does not exist, an error will be returned unless ``IF EXISTS`` is used, in which case the operation
is a no-op.
-.. _tuples:
+.. _frozen:
-Tuples
-^^^^^^
+Frozen Types
+^^^^^^^^^^^^
-CQL also support tuples and tuple types (where the elements can be of different types). Functionally, tuples can be
-though as anonymous UDT with anonymous fields. Tuple types and tuple literals are defined by:
+The ``frozen`` keyword is used to change the way a collection or user-defined type column is serialized. When it is
+present multiple values will be serialized as one, disabling updates on parts of UDTs or individual items of
+collections.
-.. productionlist::
- tuple_type: TUPLE '<' `cql_type` ( ',' `cql_type` )* '>'
- tuple_literal: '(' `term` ( ',' `term` )* ')'
+To freeze a column, use the keyword, followed by the type in angle brackets, for instance::
-and can be used thusly::
+ CREATE TABLE posts (
+ id int PRIMARY KEY,
+ title text,
+ content text,
+ tags frozen<set<text>>
+ );
- CREATE TABLE durations (
- event text,
- duration tuple<int, text>,
- )
+To insert a frozen value, it's just like a non-frozen column::
- INSERT INTO durations (event, duration) VALUES ('ev1', (3, 'hours'));
+ INSERT INTO posts (id, title, content, tags)
+ VALUES (1, 'Even Higher Availability with 5x Faster Streaming in Cassandra 4.0',
+ 'Streaming is a process...', {'cassandra', 'availability'});
-Unlike other "composed" types (collections and UDT), a tuple is always :ref:`frozen <frozen>` (without the need of the
-`frozen` keyword) and it is not possible to update only some elements of a tuple (without updating the whole tuple).
-Also, a tuple literal should always have the same number of value than declared in the type it is a tuple of (some of
-those values can be null but they need to be explicitly declared as so).
+Updating a frozen column
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+As mentioned before, it's not possible to update an individual item of a collection::
Review comment:
A user may scroll docs rapidly, so "As mentioned before" and similar kinds of comments probably aren't helpful.
##########
File path: doc/source/cql/types.rst
##########
@@ -400,20 +398,46 @@ Further, lists support:
Lastly, as for :ref:`maps <maps>`, TTLs when used only apply to the newly inserted values.
+.. _tuples:
+
+Tuples
+^^^^^^
+
+CQL also support tuples and tuple types (where the elements can be of different types). Tuple types and tuple literals
+are defined by:
+
+.. productionlist::
+ tuple_type: TUPLE '<' `cql_type` ( ',' `cql_type` )* '>'
+ tuple_literal: '(' `term` ( ',' `term` )* ')'
+
+and can be used thusly::
+
+ CREATE TABLE durations (
+ event text,
+ duration tuple<int, text>,
+ )
+
+ INSERT INTO durations (event, duration) VALUES ('ev1', (3, 'hours'));
+
+Unlike other "composed" types (collections and UDT), a tuple is always :ref:`frozen <frozen>` (without the need of the
+`frozen` keyword) and it is not possible to update only some elements of a tuple (without updating the whole tuple).
+Also, a tuple literal should always have the same number of value than declared in the type it is a tuple of (some of
Review comment:
```suggestion
A tuple literal must have the same number of items as its declaring type (some of
```
##########
File path: doc/source/cql/types.rst
##########
@@ -400,20 +398,46 @@ Further, lists support:
Lastly, as for :ref:`maps <maps>`, TTLs when used only apply to the newly inserted values.
+.. _tuples:
+
+Tuples
+^^^^^^
+
+CQL also support tuples and tuple types (where the elements can be of different types). Tuple types and tuple literals
+are defined by:
+
+.. productionlist::
+ tuple_type: TUPLE '<' `cql_type` ( ',' `cql_type` )* '>'
+ tuple_literal: '(' `term` ( ',' `term` )* ')'
+
+and can be used thusly::
+
+ CREATE TABLE durations (
+ event text,
+ duration tuple<int, text>,
+ )
+
+ INSERT INTO durations (event, duration) VALUES ('ev1', (3, 'hours'));
+
+Unlike other "composed" types (collections and UDT), a tuple is always :ref:`frozen <frozen>` (without the need of the
+`frozen` keyword) and it is not possible to update only some elements of a tuple (without updating the whole tuple).
+Also, a tuple literal should always have the same number of value than declared in the type it is a tuple of (some of
+those values can be null but they need to be explicitly declared as so).
Review comment:
```suggestion
those values can be null but they must be explicitly declared).
```
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: pr-unsubscribe@cassandra.apache.org
For additional commands, e-mail: pr-help@cassandra.apache.org