Comment Definition

Comments on SQL objects are effective means to convey design information, such as metric scales and one-liner documentation. Comments are only allowed on persistent objects.

comment-statement:
   COMMENT ON SCHEMA schema_name IS comment-text
 | COMMENT ON TABLE  [ schema_name '.' ] table_name IS comment-text
 | COMMENT ON VIEW   [ schema_name '.' ] view_name IS comment-text
 | COMMENT ON COLUMN [ schema_name '.' ] table_or_view_name '.' column_name IS comment-text
 | COMMENT ON INDEX  [ schema_name '.' ] index_name IS comment-text
 | COMMENT ON SEQUENCE  [ schema_name '.' ] sequence_name IS comment-text
 | COMMENT ON FUNCTION  [ schema_name '.' ] function_name [ argument_type_list ] IS comment-text
 | COMMENT ON PROCEDURE [ schema_name '.' ] procedure_name [ argument_type_list ] IS comment-text
 | COMMENT ON AGGREGATE [ FUNCTION ] [ schema_name '.' ] aggregate_name [ argument_type_list ] IS comment-text
 | COMMENT ON FILTER    [ FUNCTION ] [ schema_name '.' ] filter_func_name [ argument_type_list ] IS comment-text
 | COMMENT ON LOADER    [ FUNCTION ] [ schema_name '.' ] loader_name [ argument_type_list ] IS comment-text
 | COMMENT ON WINDOW    [ FUNCTION ] [ schema_name '.' ] window_name [ argument_type_list ] IS comment-text

comment-text:
   string_literal | NULL

argument_type_list
   '(' [ data_type [',' ...] ] ')'

By specifying IS NULL or IS '' you remove the comment for the SQL object.

For functions, procedures, aggregates, filter functions, loader functions and window functions it may be necessary to add the argument(s) type list to uniquely identify an overloaded function. See examples below.

Associated system table: sys.comments

Examples

COMMENT ON SCHEMA prj4 IS 'schema of new project 4';

COMMENT ON TABLE sys.comments IS 'contains comments on all db objects';

COMMENT ON COLUMN sys.tables."name" IS 'name of the table or view. It must be unique within the schema.';

create sequence sys.article_id_seq;
COMMENT ON SEQUENCE sys.article_id_seq IS 'sequence for article id column';

create table article (id int primary key default next value for sys.article_id_seq, title varchar(500) NOT NULL);
COMMENT ON INDEX sys.article_id_pkey IS 'index on primary key column: id of table: article';

COMMENT ON FUNCTION sys.upper IS 'converts text into UPPERcase text';

COMMENT ON AGGREGATE sys.stddev_pop(int) IS 'computes the standard deviation of a group of integer numbers';

COMMENT ON FILTER FUNCTION sys."endswith"(clob, clob) IS 'filter to match strings ending with some string value';
COMMENT ON FILTER FUNCTION sys."endswith"(clob, clob, boolean)
  IS 'filter to match strings ending with some string value with match case sensitivity control';

COMMENT ON WINDOW FUNCTION sys.row_number IS 'returns the row number of the row within the window group, starting from 1';

SELECT id, remark FROM sys.comments
 WHERE id IN (SELECT id FROM sys.ids WHERE table_name = 'mytable');

-- removing comment for prj0 and prjX
COMMENT ON SCHEMA prj0 IS '';
COMMENT ON SCHEMA prjX IS NULL;