Merge pull request #31110 from sevirov/sevirov-DOCSUP-15458-document_the_alter_table_modify_comment

DOCSUP-15458: Document the SQL-statement ALTER TABLE ... MODIFY COMMENT

docs/en/sql-reference/statements/alter/comment.md

@@ -0,0 +1,58 @@
+---
+toc_priority: 51
+toc_title: COMMENT
+---
+
+# ALTER TABLE … MODIFY COMMENT {#alter-modify-comment}
+
+Adds, modifies, or removes comment to the table, regardless if it was set before or not. Comment change is reflected in both [system.tables](../../../operations/system-tables/tables.md) and `SHOW CREATE TABLE` query.
+
+**Syntax**
+
+``` sql
+ALTER TABLE [db].name [ON CLUSTER cluster] MODIFY COMMENT 'Comment'
+```
+
+**Examples**
+
+Creating a table with comment (for more information, see the [COMMENT] clause(../../../sql-reference/statements/create/table.md#comment-table)):
+
+``` sql
+CREATE TABLE table_with_comment
+(
+    `k` UInt64,
+    `s` String
+)
+ENGINE = Memory()
+COMMENT 'The temporary table';
+```
+
+Modifying the table comment:
+
+``` sql
+ALTER TABLE table_with_comment MODIFY COMMENT 'new comment on a table';
+SELECT comment FROM system.tables WHERE database = currentDatabase() AND name = 'table_with_comment';
+```
+
+Output of a new comment:
+
+```text
+┌─comment────────────────┐
+│ new comment on a table │
+└────────────────────────┘
+```
+
+Removing the table comment:
+
+``` sql
+ALTER TABLE table_with_comment MODIFY COMMENT '';
+SELECT comment FROM system.tables WHERE database = currentDatabase() AND name = 'table_with_comment';
+```
+
+Output of a removed comment:
+
+```text
+┌─comment─┐
+│         │
+└─────────┘
+```

docs/en/sql-reference/statements/alter/index.md

@@ -32,6 +32,8 @@ These `ALTER` statements modify entities related to role-based access control:
 -   [ROW POLICY](../../../sql-reference/statements/alter/row-policy.md)
 -   [SETTINGS PROFILE](../../../sql-reference/statements/alter/settings-profile.md)
 
+[ALTER TABLE ... MODIFY COMMENT](../../../sql-reference/statements/alter/comment.md) statement adds, modifies, or removes comments to the table, regardless if it was set before or not.
+
 ## Mutations {#mutations}
 
 `ALTER` queries that are intended to manipulate table data are implemented with a mechanism called “mutations”, most notably [ALTER TABLE … DELETE](../../../sql-reference/statements/alter/delete.md) and [ALTER TABLE … UPDATE](../../../sql-reference/statements/alter/update.md). They are asynchronous background processes similar to merges in [MergeTree](../../../engines/table-engines/mergetree-family/index.md) tables that to produce new “mutated” versions of parts.

docs/ru/sql-reference/statements/alter/comment.md

@@ -0,0 +1,58 @@
+---
+toc_priority: 51
+toc_title: COMMENT
+---
+
+# ALTER TABLE … MODIFY COMMENT {#alter-modify-comment}
+
+Добавляет, изменяет или удаляет комментарий к таблице, независимо от того, был ли он установлен раньше или нет. Изменение комментария отражается как в системной таблице [system.tables](../../../operations/system-tables/tables.md), так и в результате выполнения запроса `SHOW CREATE TABLE`.
+
+**Синтаксис**
+
+``` sql
+ALTER TABLE [db].name [ON CLUSTER cluster] MODIFY COMMENT 'Comment'
+```
+
+**Примеры**
+
+Создание таблицы с комментарием (для более подробной информации смотрите секцию [COMMENT](../../../sql-reference/statements/create/table.md#comment-table)):
+
+``` sql
+CREATE TABLE table_with_comment
+(
+    `k` UInt64,
+    `s` String
+)
+ENGINE = Memory()
+COMMENT 'The temporary table';
+```
+
+Изменение комментария:
+
+``` sql
+ALTER TABLE table_with_comment MODIFY COMMENT 'new comment on a table';
+SELECT comment FROM system.tables WHERE database = currentDatabase() AND name = 'table_with_comment';
+```
+
+Вывод нового комментария:
+
+```text
+┌─comment────────────────┐
+│ new comment on a table │
+└────────────────────────┘
+```
+
+Удаление комментария:
+
+``` sql
+ALTER TABLE table_with_comment MODIFY COMMENT '';
+SELECT comment FROM system.tables WHERE database = currentDatabase() AND name = 'table_with_comment';
+```
+
+Вывод удаленного комментария:
+
+```text
+┌─comment─┐
+│         │
+└─────────┘
+```

docs/ru/sql-reference/statements/alter/index.md

@@ -41,6 +41,8 @@ ALTER TABLE [db].name [ON CLUSTER cluster] ADD|DROP|CLEAR|COMMENT|MODIFY COLUMN
 -   [ROW POLICY](../../../sql-reference/statements/alter/row-policy.md)
 -   [SETTINGS PROFILE](../../../sql-reference/statements/alter/settings-profile.md)
 
+Выражение [ALTER TABLE ... MODIFY COMMENT](../../../sql-reference/statements/alter/comment.md) добавляет, изменяет или удаляет комментарий к таблице, независимо от того, был ли он установлен раньше или нет.
+
 ### Мутации {#mutations}
 
 Мутации - разновидность запроса ALTER, позволяющая изменять или удалять данные в таблице. В отличие от стандартных запросов [ALTER TABLE … DELETE](../../../sql-reference/statements/alter/delete.md) и [ALTER TABLE … UPDATE](../../../sql-reference/statements/alter/update.md), рассчитанных на точечное изменение данных, область применения мутаций - достаточно тяжёлые изменения, затрагивающие много строк в таблице. Поддержана для движков таблиц семейства [MergeTree](../../../engines/table-engines/mergetree-family/mergetree.md), в том числе для движков с репликацией.