COMMENT ON

Description

The COMMENT ON statement sets or updates the comment on a database, a table, or one or more table columns. Setting a column comment to NULL removes it.

Syntax

COMMENT ON { DATABASE | SCHEMA | NAMESPACE } database_name IS comment

COMMENT ON TABLE table_name IS comment

COMMENT ON COLUMN table_name.column_name IS comment

COMMENT ON TABLE table_name COLUMN ( column_name IS comment [ , ... ] )

Parameters

• database_name

  Specifies the name of the database on which the comment is set.

• table_name

  Specifies the name of the table on which the comment is set. The name may be qualified with a catalog and/or database name.

• column_name

  Specifies the column on which the comment is set. In the single-column form (COMMENT ON COLUMN), the identifier must have at least two parts: the last part is the column name and the preceding parts qualify the table (for example table_name.column_name or database_name.table_name.column_name). This form can only reference a top-level column. To comment on a nested field, or on multiple columns at once, use the COMMENT ON TABLE table_name COLUMN ( ... ) form, where each column_name may be a nested field path such as col.field.

  A parent field and one of its nested fields cannot be commented in the same COMMENT ON TABLE ... COLUMN statement.

  The target of a column comment must be a table; views are not supported.

• comment

  A STRING literal or NULL. For a column, setting the comment to NULL removes an existing comment, while an empty string '' sets an empty comment. For a database or table, both NULL and '' set an empty comment.

Examples

-- Set a comment on a database
COMMENT ON DATABASE some_db IS 'This is a database';

-- Set a comment on a table
COMMENT ON TABLE some_db.some_table IS 'This is a table';

-- Set a comment on a single column
COMMENT ON COLUMN some_db.some_table.some_column IS 'This is a column';

-- Remove a column comment
COMMENT ON COLUMN some_db.some_table.some_column IS NULL;

-- Set comments on multiple columns, including a nested field
COMMENT ON TABLE some_db.some_table COLUMN (
  id IS 'The identifier',
  address.city IS 'The city part of the address'
);

Related Statements

• ALTER TABLE
• DESCRIBE TABLE