From d6727d850b74b26fd5c19859363d63966b6c4a20 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 16 Dec 2025 10:01:02 +0000 Subject: [PATCH 1/5] Initial plan From 3da710e60032572177f8d2361cc9200dc62ae1fe Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 16 Dec 2025 10:11:30 +0000 Subject: [PATCH 2/5] Add COMMENT documentation for tables and columns in ALTER statement Co-authored-by: fengjiachun <3860496+fengjiachun@users.noreply.github.com> --- docs/reference/sql/alter.md | 26 ++++++++++++++++++++++++-- package-lock.json | 7 ++++--- 2 files changed, 28 insertions(+), 5 deletions(-) diff --git a/docs/reference/sql/alter.md b/docs/reference/sql/alter.md index c048aabc45..d4787eca70 100644 --- a/docs/reference/sql/alter.md +++ b/docs/reference/sql/alter.md @@ -1,5 +1,5 @@ --- -keywords: [ALTER statement, SQL, modify database, modify table, alter column, table options] +keywords: [ALTER statement, SQL, modify database, modify table, alter column, table options, column comment, table comment] description: Describes the `ALTER` statement used to modify database options, table options, or metadata, including syntax and examples for altering databases and tables. --- @@ -10,7 +10,7 @@ description: Describes the `ALTER` statement used to modify database options, ta * Modify database options * Add/Drop/Modify a column * Set/Drop column default values -* Drop column default values +* Set column comments * Rename a table * Modify table options @@ -89,6 +89,7 @@ ALTER TABLE [db.]table | MODIFY COLUMN name type | MODIFY COLUMN name SET DEFAULT value | MODIFY COLUMN name DROP DEFAULT + | MODIFY COLUMN name SET COMMENT comment | MODIFY COLUMN name SET FULLTEXT INDEX [WITH ] | MODIFY COLUMN name UNSET FULLTEXT INDEX | RENAME name @@ -175,12 +176,29 @@ ALTER TABLE monitor MODIFY COLUMN load_15 DROP DEFAULT; After dropping the default value, the column will use `NULL` as the default. The database only allow dropping defaults for nullable columns. +### Set column comment + +Set or update a comment for an existing column: + +```sql +ALTER TABLE monitor MODIFY COLUMN load_15 SET COMMENT 'Load average over 15 minutes'; +``` + +Set a comment for a string column: + +```sql +ALTER TABLE monitor MODIFY COLUMN host SET COMMENT 'Hostname of the server'; +``` + +The comment is stored in the column metadata and can be viewed through `SHOW CREATE TABLE` or by querying the `INFORMATION_SCHEMA.COLUMNS` table. + ### Alter table options `ALTER TABLE` statements can also be used to change the options of tables. Currently following options are supported: - `ttl`: the retention time of data in table. +- `comment`: the table comment. - `compaction.twcs.time_window`: the time window parameter of TWCS compaction strategy. The value should be a [time duration string](/reference/time-durations.md). - `compaction.twcs.max_output_file_size`: the maximum allowed output file size of TWCS compaction strategy. - `compaction.twcs.trigger_file_num`: the number of files in a specific time window to trigger a compaction. @@ -189,6 +207,8 @@ Currently following options are supported: ```sql ALTER TABLE monitor SET 'ttl'='1d'; +ALTER TABLE monitor SET 'comment'='Monitor metrics table'; + ALTER TABLE monitor SET 'compaction.twcs.time_window'='2h'; ALTER TABLE monitor SET 'compaction.twcs.max_output_file_size'='500MB'; @@ -202,6 +222,8 @@ ALTER TABLE monitor SET 'sst_format'='flat'; ```sql ALTER TABLE monitor UNSET 'ttl'; + +ALTER TABLE monitor UNSET 'comment'; ``` ### Create an index for a column diff --git a/package-lock.json b/package-lock.json index fd783868e3..f2983cc48e 100644 --- a/package-lock.json +++ b/package-lock.json @@ -16,6 +16,7 @@ "@octokit/rest": "^21.0.2", "axios": "^1.12.0", "clsx": "^2.0.0", + "copy-text-to-clipboard": "^3.2.2", "docusaurus-biel": "^1.0.5", "minimatch": "^10.0.1", "prism-react-renderer": "^2.3.0", @@ -6736,9 +6737,9 @@ "license": "MIT" }, "node_modules/copy-text-to-clipboard": { - "version": "3.2.0", - "resolved": "https://registry.npmjs.org/copy-text-to-clipboard/-/copy-text-to-clipboard-3.2.0.tgz", - "integrity": "sha512-RnJFp1XR/LOBDckxTib5Qjr/PMfkatD0MUCQgdpqS8MdKiNUzBjAQBEN6oUy+jW7LI93BBG3DtMB2KOOKpGs2Q==", + "version": "3.2.2", + "resolved": "https://registry.npmjs.org/copy-text-to-clipboard/-/copy-text-to-clipboard-3.2.2.tgz", + "integrity": "sha512-T6SqyLd1iLuqPA90J5N4cTalrtovCySh58iiZDGJ6FGznbclKh4UI+FGacQSgFzwKG77W7XT5gwbVEbd9cIH1A==", "license": "MIT", "engines": { "node": ">=12" From 282f50910e2f475d7d931dcf4c1e1087f0aba8b3 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 17 Dec 2025 11:33:37 +0000 Subject: [PATCH 3/5] Fix: Use correct COMMENT ON syntax based on test file grammar Co-authored-by: waynexia <15380403+waynexia@users.noreply.github.com> --- docs/reference/sql/alter.md | 26 +------ docs/reference/sql/comment.md | 131 ++++++++++++++++++++++++++++++++++ sidebars.ts | 1 + 3 files changed, 134 insertions(+), 24 deletions(-) create mode 100644 docs/reference/sql/comment.md diff --git a/docs/reference/sql/alter.md b/docs/reference/sql/alter.md index d4787eca70..c048aabc45 100644 --- a/docs/reference/sql/alter.md +++ b/docs/reference/sql/alter.md @@ -1,5 +1,5 @@ --- -keywords: [ALTER statement, SQL, modify database, modify table, alter column, table options, column comment, table comment] +keywords: [ALTER statement, SQL, modify database, modify table, alter column, table options] description: Describes the `ALTER` statement used to modify database options, table options, or metadata, including syntax and examples for altering databases and tables. --- @@ -10,7 +10,7 @@ description: Describes the `ALTER` statement used to modify database options, ta * Modify database options * Add/Drop/Modify a column * Set/Drop column default values -* Set column comments +* Drop column default values * Rename a table * Modify table options @@ -89,7 +89,6 @@ ALTER TABLE [db.]table | MODIFY COLUMN name type | MODIFY COLUMN name SET DEFAULT value | MODIFY COLUMN name DROP DEFAULT - | MODIFY COLUMN name SET COMMENT comment | MODIFY COLUMN name SET FULLTEXT INDEX [WITH ] | MODIFY COLUMN name UNSET FULLTEXT INDEX | RENAME name @@ -176,29 +175,12 @@ ALTER TABLE monitor MODIFY COLUMN load_15 DROP DEFAULT; After dropping the default value, the column will use `NULL` as the default. The database only allow dropping defaults for nullable columns. -### Set column comment - -Set or update a comment for an existing column: - -```sql -ALTER TABLE monitor MODIFY COLUMN load_15 SET COMMENT 'Load average over 15 minutes'; -``` - -Set a comment for a string column: - -```sql -ALTER TABLE monitor MODIFY COLUMN host SET COMMENT 'Hostname of the server'; -``` - -The comment is stored in the column metadata and can be viewed through `SHOW CREATE TABLE` or by querying the `INFORMATION_SCHEMA.COLUMNS` table. - ### Alter table options `ALTER TABLE` statements can also be used to change the options of tables. Currently following options are supported: - `ttl`: the retention time of data in table. -- `comment`: the table comment. - `compaction.twcs.time_window`: the time window parameter of TWCS compaction strategy. The value should be a [time duration string](/reference/time-durations.md). - `compaction.twcs.max_output_file_size`: the maximum allowed output file size of TWCS compaction strategy. - `compaction.twcs.trigger_file_num`: the number of files in a specific time window to trigger a compaction. @@ -207,8 +189,6 @@ Currently following options are supported: ```sql ALTER TABLE monitor SET 'ttl'='1d'; -ALTER TABLE monitor SET 'comment'='Monitor metrics table'; - ALTER TABLE monitor SET 'compaction.twcs.time_window'='2h'; ALTER TABLE monitor SET 'compaction.twcs.max_output_file_size'='500MB'; @@ -222,8 +202,6 @@ ALTER TABLE monitor SET 'sst_format'='flat'; ```sql ALTER TABLE monitor UNSET 'ttl'; - -ALTER TABLE monitor UNSET 'comment'; ``` ### Create an index for a column diff --git a/docs/reference/sql/comment.md b/docs/reference/sql/comment.md new file mode 100644 index 0000000000..21e5851d9c --- /dev/null +++ b/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. diff --git a/sidebars.ts b/sidebars.ts index 9d495c3057..8e54892db8 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -636,6 +636,7 @@ const sidebars: SidebarsConfig = { 'reference/sql/alter', 'reference/sql/case', 'reference/sql/cast', + 'reference/sql/comment', 'reference/sql/copy', 'reference/sql/create', 'reference/sql/delete', From 3761ce26445e448310178a77ce6cfeee91d4847f Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 17 Dec 2025 12:24:49 +0000 Subject: [PATCH 4/5] Add Chinese documentation for COMMENT ON statement Co-authored-by: waynexia <15380403+waynexia@users.noreply.github.com> --- .../current/reference/sql/comment.md | 131 ++++++++++++++++++ 1 file changed, 131 insertions(+) create mode 100644 i18n/zh/docusaurus-plugin-content-docs/current/reference/sql/comment.md diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/reference/sql/comment.md b/i18n/zh/docusaurus-plugin-content-docs/current/reference/sql/comment.md new file mode 100644 index 0000000000..6c7695f40b --- /dev/null +++ b/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` 会删除现有注释，如果注释不存在也不会产生错误。 +- 注释对于记录数据库对象的用途特别有用，特别是在协作环境中。 From 0c3570880c58a97681c70498d69f039719a36471 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 18 Dec 2025 02:15:29 +0000 Subject: [PATCH 5/5] Add COMMENT documentation for version 1.0 (latest stable release) Co-authored-by: fengjiachun <3860496+fengjiachun@users.noreply.github.com> --- .../version-1.0/reference/sql/comment.md | 131 ++++++++++++++++++ .../version-1.0/reference/sql/comment.md | 131 ++++++++++++++++++ versioned_sidebars/version-1.0-sidebars.json | 1 + 3 files changed, 263 insertions(+) create mode 100644 i18n/zh/docusaurus-plugin-content-docs/version-1.0/reference/sql/comment.md create mode 100644 versioned_docs/version-1.0/reference/sql/comment.md diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-1.0/reference/sql/comment.md b/i18n/zh/docusaurus-plugin-content-docs/version-1.0/reference/sql/comment.md new file mode 100644 index 0000000000..6c7695f40b --- /dev/null +++ b/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` 会删除现有注释，如果注释不存在也不会产生错误。 +- 注释对于记录数据库对象的用途特别有用，特别是在协作环境中。 diff --git a/versioned_docs/version-1.0/reference/sql/comment.md b/versioned_docs/version-1.0/reference/sql/comment.md new file mode 100644 index 0000000000..21e5851d9c --- /dev/null +++ b/versioned_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 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. diff --git a/versioned_sidebars/version-1.0-sidebars.json b/versioned_sidebars/version-1.0-sidebars.json index 9f43e1f12f..3cc6c404a4 100644 --- a/versioned_sidebars/version-1.0-sidebars.json +++ b/versioned_sidebars/version-1.0-sidebars.json @@ -638,6 +638,7 @@ "reference/sql/alter", "reference/sql/case", "reference/sql/cast", + "reference/sql/comment", "reference/sql/copy", "reference/sql/create", "reference/sql/delete",