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/24 10:00:56 UTC
[GitHub] [cassandra] blerer commented on a change in pull request #745: [CASSANDRA-16117] Improve docs about frozen types and invert UDT/Tuple order
blerer commented on a change in pull request #745:
URL: https://github.com/apache/cassandra/pull/745#discussion_r494169292
##########
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
Review comment:
I would replace: `CQL also support tuples and tuple types (where the elements can be of different types).` by something like: `A Tuple is a fix-length set of values (fields) where each value can be of a different data type.`
##########
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'));
Review comment:
`duration` is now an official Apache Cassandra data type so that example might be a bit confusing.
##########
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). It is not possible to update only some elements of a tuple (without updating the whole tuple).
+A tuple literal must have the same number of items as its declaring type (some of
+those values can be null but they must be explicitly declared).
+
.. _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
+:token:`create_type_statement`, :token:`alter_type_statement` and :token:`drop_type_statement` described below. But
Review comment:
It is probably important to mention that a UDT is defined at the keyspace level and is not shared between keyspaces.
##########
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:
The fact that a UDT inherit from a Tuple is an implementation detail that can be changed in the future. I would not mention a link between UDT and Tuple.
UDTs were introduce to help users to demormalized their data. To help them to avoid using an extra table (which is a dangerous thing in a distributed database).
##########
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.
Review comment:
It might be good to start with some explanation about the non-frozen types to help the user understand.
Something like:
```
The ``frozen`` keyword is used to change the way a collection or user-defined type column is serialized.
`For non-frozen collections or UDTs, each value is serialized independently from the other values. This allow update or delete operations on a sub-set of the collections or UDTs values. For frozen collections or UDTs all the value are serialized as one, disabling the ability to perform partial updates on the values.`
```
##########
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). It is not possible to update only some elements of a tuple (without updating the whole tuple).
Review comment:
I would remove `(without the need of the frozen keyword)` as I believed it changed over time and might not be true on all versions.
##########
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
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+It's not possible to update an individual item of a collection::
+
+ UPDATE posts SET tags = tags - {'availability'} WHERE id = 1;
+
+The above command would result in the following error::
+
+ InvalidRequest: Error from server: code=2200 [Invalid query] message="Invalid operation (tags = tags -
+ {'availability'}) for frozen collection column tags"
+
+When there's a need to update, the full value must be provided::
+
+ UPDATE posts SET tags = {'cassandra'} WHERE id = 1;
+
+Note we're replacing the whole value, not just removing the unwanted item. The same is true for appending elements in
+a collection.
Review comment:
The `we` sound weird in a technical doc but it might be only me.
----------------------------------------------------------------
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