smiklosovic commented on code in PR #4411: URL: https://github.com/apache/cassandra/pull/4411#discussion_r2440325543
########## doc/modules/cassandra/pages/developing/cql/ddl.adoc: ########## @@ -801,3 +801,161 @@ statements. However, tables are the only object that can be truncated currently, and the `TABLE` keyword can be omitted. Truncating a table permanently removes all existing data from the table, but without removing the table itself. + +[[comment-statement]] +== COMMENT ON + +The `COMMENT ON` statement allows you to add descriptive comments to schema elements for documentation purposes. +Comments are stored in the schema metadata and displayed when using `DESCRIBE` statements. + +=== COMMENT ON KEYSPACE + +Add or modify a comment on a keyspace: + +[source,cql] +---- +COMMENT ON KEYSPACE keyspace_name IS 'comment text'; +COMMENT ON KEYSPACE keyspace_name IS NULL; -- Remove comment +---- + +Example: + +[source,cql] +---- +COMMENT ON KEYSPACE cycling IS 'Keyspace for cycling application data'; +---- + +=== COMMENT ON TABLE + +Add or modify a comment on a table: + +[source,cql] +---- +COMMENT ON TABLE [keyspace_name.]table_name IS 'comment text'; +COMMENT ON TABLE [keyspace_name.]table_name IS NULL; -- Remove comment +---- + +Example: + +[source,cql] +---- +COMMENT ON TABLE cycling.cyclist_name IS 'Table storing cyclist names and basic information'; +---- + +=== COMMENT ON COLUMN + +Add or modify a comment on a column: + +[source,cql] +---- +COMMENT ON COLUMN [keyspace_name.]table_name.column_name IS 'comment text'; +COMMENT ON COLUMN [keyspace_name.]table_name.column_name IS NULL; -- Remove comment +---- + +Example: + +[source,cql] +---- +COMMENT ON COLUMN cycling.cyclist_name.id IS 'Unique identifier for each cyclist'; +---- + +=== COMMENT ON TYPE + +Add or modify a comment on a user-defined type: + +[source,cql] +---- +COMMENT ON TYPE [keyspace_name.]type_name IS 'comment text'; Review Comment: there is missing example category with "field" comment in this document. I would also get rid of "field" as reserved keyword and used "column" instead. Less keywords we have better it is. In this case it is completely fine to use "column" for UDT I think. `COMMENT ON COLUMN keyspace.my_type.my_column IS 'abc';` You would need to treat this internally and realize what we are dealing with here - `my_type` being name of a table or type but that is just internal detail. -- 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. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
