docs: add documentation for COMMENT ON statement (#2260)

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: fengjiachun <3860496+fengjiachun@users.noreply.github.com>
Co-authored-by: waynexia <15380403+waynexia@users.noreply.github.com>

Author: 3 people

docs/reference/sql/comment.md

@@ -0,0 +1,131 @@
+---
+keywords: [SQL COMMENT, COMMENT ON TABLE, COMMENT ON COLUMN, COMMENT ON FLOW, SQL syntax, SQL examples]
+description: Covers the SQL COMMENT statement for adding or removing comments on tables, columns, and flows in GreptimeDB, including syntax and examples.
+---
+
+# COMMENT
+
+The `COMMENT` statement is used to add or remove comments on tables, columns, and flows. Comments provide descriptions that can help document the purpose and usage of database objects.
+
+## COMMENT ON TABLE
+
+`COMMENT ON TABLE` adds or removes a comment on a table.
+
+### Syntax
+
+```sql
+COMMENT ON TABLE table_name IS { 'comment' | NULL }
+```
+
+- `table_name`: The name of the table to comment on.
+- `'comment'`: A string literal containing the comment text.
+- `NULL`: Removes the existing comment from the table.
+
+### Examples
+
+Add a comment to a table:
+
+```sql
+COMMENT ON TABLE system_metrics IS 'System monitoring metrics collected every minute';
+```
+
+Remove a comment from a table:
+
+```sql
+COMMENT ON TABLE system_metrics IS NULL;
+```
+
+View the table comment using `SHOW CREATE TABLE`:
+
+```sql
+SHOW CREATE TABLE system_metrics;
+```
+
+The comment can also be viewed through the `INFORMATION_SCHEMA.TABLES` table by querying the `table_comment` column.
+
+## COMMENT ON COLUMN
+
+`COMMENT ON COLUMN` adds or removes a comment on a specific column of a table.
+
+### Syntax
+
+```sql
+COMMENT ON COLUMN table_name.column_name IS { 'comment' | NULL }
+```
+
+- `table_name`: The name of the table containing the column.
+- `column_name`: The name of the column to comment on.
+- `'comment'`: A string literal containing the comment text.
+- `NULL`: Removes the existing comment from the column.
+
+### Examples
+
+Add a comment to a column:
+
+```sql
+COMMENT ON COLUMN system_metrics.cpu_usage IS 'CPU usage percentage (0-100)';
+```
+
+Add comments to multiple columns:
+
+```sql
+COMMENT ON COLUMN system_metrics.memory_usage IS 'Memory usage in bytes';
+COMMENT ON COLUMN system_metrics.disk_usage IS 'Disk usage percentage';
+```
+
+Remove a comment from a column:
+
+```sql
+COMMENT ON COLUMN system_metrics.cpu_usage IS NULL;
+```
+
+View column comments using `SHOW CREATE TABLE`:
+
+```sql
+SHOW CREATE TABLE system_metrics;
+```
+
+Column comments can also be queried from the `INFORMATION_SCHEMA.COLUMNS` table by accessing the `column_comment` column.
+
+## COMMENT ON FLOW
+
+`COMMENT ON FLOW` adds or removes a comment on a flow.
+
+### Syntax
+
+```sql
+COMMENT ON FLOW flow_name IS { 'comment' | NULL }
+```
+
+- `flow_name`: The name of the flow to comment on.
+- `'comment'`: A string literal containing the comment text.
+- `NULL`: Removes the existing comment from the flow.
+
+### Examples
+
+Add a comment to a flow:
+
+```sql
+COMMENT ON FLOW temperature_monitoring IS 'Monitors temperature sensors and alerts on high values';
+```
+
+Remove a comment from a flow:
+
+```sql
+COMMENT ON FLOW temperature_monitoring IS NULL;
+```
+
+View the flow comment using `SHOW CREATE FLOW`:
+
+```sql
+SHOW CREATE FLOW temperature_monitoring;
+```
+
+Flow comments can also be queried from the `INFORMATION_SCHEMA.FLOWS` table by accessing the `comment` column.
+
+## Notes
+
+- Comments are stored as metadata and do not affect the behavior or performance of tables, columns, or flows.
+- Comments can be updated by issuing a new `COMMENT ON` statement with a different comment text.
+- Setting a comment to `NULL` removes the existing comment but does not generate an error if no comment exists.
+- Comments are particularly useful for documenting the purpose of database objects, especially in collaborative environments.

i18n/zh/docusaurus-plugin-content-docs/current/reference/sql/comment.md

@@ -0,0 +1,131 @@
+---
+keywords: [SQL COMMENT 语句, COMMENT ON TABLE, COMMENT ON COLUMN, COMMENT ON FLOW, SQL 语法, SQL 示例]
+description: COMMENT 语句用于在 GreptimeDB 中为表、列和流添加或删除注释，包括语法和示例。
+---
+
+# COMMENT
+
+`COMMENT` 语句用于为表、列和流添加或删除注释。注释提供的描述可以帮助记录数据库对象的用途和使用方法。
+
+## COMMENT ON TABLE
+
+`COMMENT ON TABLE` 用于为表添加或删除注释。
+
+### 语法
+
+```sql
+COMMENT ON TABLE table_name IS { 'comment' | NULL }
+```
+
+- `table_name`: 要添加注释的表名。
+- `'comment'`: 包含注释文本的字符串。
+- `NULL`: 删除表的现有注释。
+
+### 示例
+
+为表添加注释：
+
+```sql
+COMMENT ON TABLE system_metrics IS 'System monitoring metrics collected every minute';
+```
+
+删除表的注释：
+
+```sql
+COMMENT ON TABLE system_metrics IS NULL;
+```
+
+使用 `SHOW CREATE TABLE` 查看表注释：
+
+```sql
+SHOW CREATE TABLE system_metrics;
+```
+
+也可以通过查询 `INFORMATION_SCHEMA.TABLES` 表的 `table_comment` 列来查看注释。
+
+## COMMENT ON COLUMN
+
+`COMMENT ON COLUMN` 用于为表的特定列添加或删除注释。
+
+### 语法
+
+```sql
+COMMENT ON COLUMN table_name.column_name IS { 'comment' | NULL }
+```
+
+- `table_name`: 包含该列的表名。
+- `column_name`: 要添加注释的列名。
+- `'comment'`: 包含注释文本的字符串。
+- `NULL`: 删除列的现有注释。
+
+### 示例
+
+为列添加注释：
+
+```sql
+COMMENT ON COLUMN system_metrics.cpu_usage IS 'CPU usage percentage (0-100)';
+```
+
+为多个列添加注释：
+
+```sql
+COMMENT ON COLUMN system_metrics.memory_usage IS 'Memory usage in bytes';
+COMMENT ON COLUMN system_metrics.disk_usage IS 'Disk usage percentage';
+```
+
+删除列的注释：
+
+```sql
+COMMENT ON COLUMN system_metrics.cpu_usage IS NULL;
+```
+
+使用 `SHOW CREATE TABLE` 查看列注释：
+
+```sql
+SHOW CREATE TABLE system_metrics;
+```
+
+也可以通过查询 `INFORMATION_SCHEMA.COLUMNS` 表的 `column_comment` 列来查看列注释。
+
+## COMMENT ON FLOW
+
+`COMMENT ON FLOW` 用于为流添加或删除注释。
+
+### 语法
+
+```sql
+COMMENT ON FLOW flow_name IS { 'comment' | NULL }
+```
+
+- `flow_name`: 要添加注释的流名称。
+- `'comment'`: 包含注释文本的字符串。
+- `NULL`: 删除流的现有注释。
+
+### 示例
+
+为流添加注释：
+
+```sql
+COMMENT ON FLOW temperature_monitoring IS 'Monitors temperature sensors and alerts on high values';
+```
+
+删除流的注释：
+
+```sql
+COMMENT ON FLOW temperature_monitoring IS NULL;
+```
+
+使用 `SHOW CREATE FLOW` 查看流注释：
+
+```sql
+SHOW CREATE FLOW temperature_monitoring;
+```
+
+也可以通过查询 `INFORMATION_SCHEMA.FLOWS` 表的 `comment` 列来查看流注释。
+
+## 注意事项
+
+- 注释作为元数据存储，不会影响表、列或流的行为或性能。
+- 可以通过发出新的 `COMMENT ON` 语句来更新注释。
+- 将注释设置为 `NULL` 会删除现有注释，如果注释不存在也不会产生错误。
+- 注释对于记录数据库对象的用途特别有用，特别是在协作环境中。

i18n/zh/docusaurus-plugin-content-docs/version-1.0/reference/sql/comment.md

@@ -0,0 +1,131 @@
+---
+keywords: [SQL COMMENT 语句, COMMENT ON TABLE, COMMENT ON COLUMN, COMMENT ON FLOW, SQL 语法, SQL 示例]
+description: COMMENT 语句用于在 GreptimeDB 中为表、列和流添加或删除注释，包括语法和示例。
+---
+
+# COMMENT
+
+`COMMENT` 语句用于为表、列和流添加或删除注释。注释提供的描述可以帮助记录数据库对象的用途和使用方法。
+
+## COMMENT ON TABLE
+
+`COMMENT ON TABLE` 用于为表添加或删除注释。
+
+### 语法
+
+```sql
+COMMENT ON TABLE table_name IS { 'comment' | NULL }
+```
+
+- `table_name`: 要添加注释的表名。
+- `'comment'`: 包含注释文本的字符串。
+- `NULL`: 删除表的现有注释。
+
+### 示例
+
+为表添加注释：
+
+```sql
+COMMENT ON TABLE system_metrics IS 'System monitoring metrics collected every minute';
+```
+
+删除表的注释：
+
+```sql
+COMMENT ON TABLE system_metrics IS NULL;
+```
+
+使用 `SHOW CREATE TABLE` 查看表注释：
+
+```sql
+SHOW CREATE TABLE system_metrics;
+```
+
+也可以通过查询 `INFORMATION_SCHEMA.TABLES` 表的 `table_comment` 列来查看注释。
+
+## COMMENT ON COLUMN
+
+`COMMENT ON COLUMN` 用于为表的特定列添加或删除注释。
+
+### 语法
+
+```sql
+COMMENT ON COLUMN table_name.column_name IS { 'comment' | NULL }
+```
+
+- `table_name`: 包含该列的表名。
+- `column_name`: 要添加注释的列名。
+- `'comment'`: 包含注释文本的字符串。
+- `NULL`: 删除列的现有注释。
+
+### 示例
+
+为列添加注释：
+
+```sql
+COMMENT ON COLUMN system_metrics.cpu_usage IS 'CPU usage percentage (0-100)';
+```
+
+为多个列添加注释：
+
+```sql
+COMMENT ON COLUMN system_metrics.memory_usage IS 'Memory usage in bytes';
+COMMENT ON COLUMN system_metrics.disk_usage IS 'Disk usage percentage';
+```
+
+删除列的注释：
+
+```sql
+COMMENT ON COLUMN system_metrics.cpu_usage IS NULL;
+```
+
+使用 `SHOW CREATE TABLE` 查看列注释：
+
+```sql
+SHOW CREATE TABLE system_metrics;
+```
+
+也可以通过查询 `INFORMATION_SCHEMA.COLUMNS` 表的 `column_comment` 列来查看列注释。
+
+## COMMENT ON FLOW
+
+`COMMENT ON FLOW` 用于为流添加或删除注释。
+
+### 语法
+
+```sql
+COMMENT ON FLOW flow_name IS { 'comment' | NULL }
+```
+
+- `flow_name`: 要添加注释的流名称。
+- `'comment'`: 包含注释文本的字符串。
+- `NULL`: 删除流的现有注释。
+
+### 示例
+
+为流添加注释：
+
+```sql
+COMMENT ON FLOW temperature_monitoring IS 'Monitors temperature sensors and alerts on high values';
+```
+
+删除流的注释：
+
+```sql
+COMMENT ON FLOW temperature_monitoring IS NULL;
+```
+
+使用 `SHOW CREATE FLOW` 查看流注释：
+
+```sql
+SHOW CREATE FLOW temperature_monitoring;
+```
+
+也可以通过查询 `INFORMATION_SCHEMA.FLOWS` 表的 `comment` 列来查看流注释。
+
+## 注意事项
+
+- 注释作为元数据存储，不会影响表、列或流的行为或性能。
+- 可以通过发出新的 `COMMENT ON` 语句来更新注释。
+- 将注释设置为 `NULL` 会删除现有注释，如果注释不存在也不会产生错误。
+- 注释对于记录数据库对象的用途特别有用，特别是在协作环境中。