Merge pull request #24548 from kirillikoff/DOCSUP-9474-document-table-comments

Docsup 9474: document table comments

docs/en/operations/system-tables/tables.md

@@ -54,6 +54,9 @@ Columns:
 
 -   `lifetime_bytes` ([Nullable](../../sql-reference/data-types/nullable.md)([UInt64](../../sql-reference/data-types/int-uint.md))) - Total number of bytes INSERTed since server start (only for `Buffer` tables). 
 
+-   `comment` ([String](../../sql-reference/data-types/string.md)) - The comment for the table. 
+
+
 The `system.tables` table is used in `SHOW TABLES` query implementation.
 
 **Example**
@@ -65,47 +68,53 @@ SELECT * FROM system.tables LIMIT 2 FORMAT Vertical;
 ```text
 Row 1:
 ──────
-database:                   system
+database:                   base
-name:                       aggregate_function_combinators
+name:                       t1
-uuid:                       00000000-0000-0000-0000-000000000000
+uuid:                       81b1c20a-b7c6-4116-a2ce-7583fb6b6736
-engine:                     SystemAggregateFunctionCombinators
+engine:                     MergeTree
 is_temporary:               0
-data_paths:                 []
+data_paths:                 ['/var/lib/clickhouse/store/81b/81b1c20a-b7c6-4116-a2ce-7583fb6b6736/']
-metadata_path:              /var/lib/clickhouse/metadata/system/aggregate_function_combinators.sql
+metadata_path:              /var/lib/clickhouse/store/461/461cf698-fd0b-406d-8c01-5d8fd5748a91/t1.sql
-metadata_modification_time: 1970-01-01 03:00:00
+metadata_modification_time: 2021-01-25 19:14:32
 dependencies_database:      []
 dependencies_table:         []
-create_table_query:         
+create_table_query:         CREATE TABLE base.t1 (`n` UInt64) ENGINE = MergeTree ORDER BY n SETTINGS index_granularity = 8192
-engine_full:                
+engine_full:                MergeTree ORDER BY n SETTINGS index_granularity = 8192
 partition_key:
-sorting_key:                
+sorting_key:                n
-primary_key:                
+primary_key:                n
 sampling_key:
-storage_policy:             
+storage_policy:             default
-total_rows:                 ᴺᵁᴸᴸ
+total_rows:                 1
-total_bytes:                ᴺᵁᴸᴸ
+total_bytes:                99
+lifetime_rows:              ᴺᵁᴸᴸ
+lifetime_bytes:             ᴺᵁᴸᴸ
+comment:
 
 Row 2:
 ──────
-database:                   system
+database:                   default
-name:                       asynchronous_metrics
+name:                       53r93yleapyears
 uuid:                       00000000-0000-0000-0000-000000000000
-engine:                     SystemAsynchronousMetrics
+engine:                     MergeTree
 is_temporary:               0
-data_paths:                 []
+data_paths:                 ['/var/lib/clickhouse/data/default/53r93yleapyears/']
-metadata_path:              /var/lib/clickhouse/metadata/system/asynchronous_metrics.sql
+metadata_path:              /var/lib/clickhouse/metadata/default/53r93yleapyears.sql
-metadata_modification_time: 1970-01-01 03:00:00
+metadata_modification_time: 2020-09-23 09:05:36
 dependencies_database:      []
 dependencies_table:         []
-create_table_query:         
+create_table_query:         CREATE TABLE default.`53r93yleapyears` (`id` Int8, `febdays` Int8) ENGINE = MergeTree ORDER BY id SETTINGS index_granularity = 8192
-engine_full:                
+engine_full:                MergeTree ORDER BY id SETTINGS index_granularity = 8192
 partition_key:
-sorting_key:                
+sorting_key:                id
-primary_key:                
+primary_key:                id
 sampling_key:
-storage_policy:             
+storage_policy:             default
-total_rows:                 ᴺᵁᴸᴸ
+total_rows:                 2
-total_bytes:                ᴺᵁᴸᴸ
+total_bytes:                155
+lifetime_rows:              ᴺᵁᴸᴸ
+lifetime_bytes:             ᴺᵁᴸᴸ
+comment:
 ```
 
 [Original article](https://clickhouse.tech/docs/en/operations/system_tables/tables) <!--hide-->

docs/en/sql-reference/statements/create/table.md

@@ -354,3 +354,39 @@ SELECT * FROM base.t1;
 │ 3 │
 └───┘
 ```
+
+## COMMENT Clause {#comment-table}
+
+You can add a comment to the table when you creating it.
+
+!!!note "Note"
+    The comment is supported for all table engines except [Kafka](../../../engines/table-engines/integrations/kafka.md), [RabbitMQ](../../../engines/table-engines/integrations/rabbitmq.md) and [EmbeddedRocksDB](../../../engines/table-engines/integrations/embedded-rocksdb.md).
+	
+
+**Syntax**
+
+``` sql
+CREATE TABLE db.table_name
+(
+    name1 type1, name2 type2, ...
+)
+ENGINE = engine
+COMMENT 'Comment'
+```
+	
+**Example**
+
+Query:
+
+``` sql
+CREATE TABLE t1 (x String) ENGINE = Memory COMMENT 'The temporary table';
+SELECT name, comment FROM system.tables WHERE name = 't1';
+```
+
+Result:
+
+```text
+┌─name─┬─comment─────────────┐
+│ t1   │ The temporary table │
+└──────┴─────────────────────┘
+```

docs/ru/operations/system-tables/tables.md

@@ -39,6 +39,8 @@
 
 -   `lifetime_bytes` ([Nullable](../../sql-reference/data-types/nullable.md)([UInt64](../../sql-reference/data-types/int-uint.md))) - общее количество байт, добавленных оператором `INSERT` с момента запуска сервера (только для таблиц `Buffer`).
 
+-   `comment` ([String](../../sql-reference/data-types/string.md)) — комментарий к таблице.
+
 Таблица `system.tables` используется при выполнении запроса `SHOW TABLES`.
 
 **Пример**
@@ -50,45 +52,51 @@ SELECT * FROM system.tables LIMIT 2 FORMAT Vertical;
 ```text
 Row 1:
 ──────
-database:                   system
+database:                   base
-name:                       aggregate_function_combinators
+name:                       t1
-uuid:                       00000000-0000-0000-0000-000000000000
+uuid:                       81b1c20a-b7c6-4116-a2ce-7583fb6b6736
-engine:                     SystemAggregateFunctionCombinators
+engine:                     MergeTree
 is_temporary:               0
-data_paths:                 []
+data_paths:                 ['/var/lib/clickhouse/store/81b/81b1c20a-b7c6-4116-a2ce-7583fb6b6736/']
-metadata_path:              /var/lib/clickhouse/metadata/system/aggregate_function_combinators.sql
+metadata_path:              /var/lib/clickhouse/store/461/461cf698-fd0b-406d-8c01-5d8fd5748a91/t1.sql
-metadata_modification_time: 1970-01-01 03:00:00
+metadata_modification_time: 2021-01-25 19:14:32
 dependencies_database:      []
 dependencies_table:         []
-create_table_query:         
+create_table_query:         CREATE TABLE base.t1 (`n` UInt64) ENGINE = MergeTree ORDER BY n SETTINGS index_granularity = 8192
-engine_full:                
+engine_full:                MergeTree ORDER BY n SETTINGS index_granularity = 8192
 partition_key:
-sorting_key:                
+sorting_key:                n
-primary_key:                
+primary_key:                n
 sampling_key:
-storage_policy:             
+storage_policy:             default
-total_rows:                 ᴺᵁᴸᴸ
+total_rows:                 1
-total_bytes:                ᴺᵁᴸᴸ
+total_bytes:                99
+lifetime_rows:              ᴺᵁᴸᴸ
+lifetime_bytes:             ᴺᵁᴸᴸ
+comment:
 
 Row 2:
 ──────
-database:                   system
+database:                   default
-name:                       asynchronous_metrics
+name:                       53r93yleapyears
 uuid:                       00000000-0000-0000-0000-000000000000
-engine:                     SystemAsynchronousMetrics
+engine:                     MergeTree
 is_temporary:               0
-data_paths:                 []
+data_paths:                 ['/var/lib/clickhouse/data/default/53r93yleapyears/']
-metadata_path:              /var/lib/clickhouse/metadata/system/asynchronous_metrics.sql
+metadata_path:              /var/lib/clickhouse/metadata/default/53r93yleapyears.sql
-metadata_modification_time: 1970-01-01 03:00:00
+metadata_modification_time: 2020-09-23 09:05:36
 dependencies_database:      []
 dependencies_table:         []
-create_table_query:         
+create_table_query:         CREATE TABLE default.`53r93yleapyears` (`id` Int8, `febdays` Int8) ENGINE = MergeTree ORDER BY id SETTINGS index_granularity = 8192
-engine_full:                
+engine_full:                MergeTree ORDER BY id SETTINGS index_granularity = 8192
 partition_key:
-sorting_key:                
+sorting_key:                id
-primary_key:                
+primary_key:                id
 sampling_key:
-storage_policy:             
+storage_policy:             default
-total_rows:                 ᴺᵁᴸᴸ
+total_rows:                 2
-total_bytes:                ᴺᵁᴸᴸ
+total_bytes:                155
+lifetime_rows:              ᴺᵁᴸᴸ
+lifetime_bytes:             ᴺᵁᴸᴸ
+comment:
 ```

docs/ru/sql-reference/statements/create/table.md

@@ -346,4 +346,39 @@ SELECT * FROM base.t1;
 └───┘
 ```
 
+## Секция COMMENT {#comment-table}
+
+Вы можете добавить комментарий к таблице при ее создании.
+
+!!!note "Замечание"
+    Комментарий поддерживается для всех движков таблиц, кроме [Kafka](../../../engines/table-engines/integrations/kafka.md), [RabbitMQ](../../../engines/table-engines/integrations/rabbitmq.md) и [EmbeddedRocksDB](../../../engines/table-engines/integrations/embedded-rocksdb.md).
+	
+**Синтаксис**
+
+``` sql
+CREATE TABLE db.table_name
+(
+    name1 type1, name2 type2, ...
+)
+ENGINE = engine
+COMMENT 'Comment'
+```
+	
+**Пример**
+
+Запрос:
+
+``` sql
+CREATE TABLE t1 (x String) ENGINE = Memory COMMENT 'The temporary table';
+SELECT name, comment FROM system.tables WHERE name = 't1';
+```
+
+Результат:
+
+```text
+┌─name─┬─comment─────────────┐
+│ t1   │ The temporary table │
+└──────┴─────────────────────┘
+```
+
 <!--hide-->