14.1 ANNOTATION
The annotation command adds, retrieves, modifies, deletes, and generates metadata annotations for database objects. It also provides commands for managing annotation groups, generating annotation reports, and viewing annotation statistics.
For information about annotations, prerequisites, and workflows for creating and managing annotations, see AI Enrichment Using the Annotation Command.
Syntax
annotation <command> [options]Supported Subcommands
| Subcommand | Description |
|---|---|
| install | Installs the AI Enrichment package in the connected database. |
| status | Checks whether the AI Enrichment package is installed. |
| annotation | Adds an annotation to a database object. |
| get-annotation | Retrieves an existing annotation. |
| edit-annotation | Modifies the value of an existing annotation. |
| delete-annotation | Deletes an annotation from a database object. |
| add-group | Creates an annotation group. |
| list-groups | Lists annotation groups. |
| add-to-group | Adds a database object to a group. |
| remove-from-group | Removes a database object from a group. |
| delete-group | Deletes a group. |
| report | Generates a Markdown report of tables and column annotations. |
| auto-annotate | Uses a configured LLM to generate missing DESCRIPTION annotations.
|
| list-tables | Lists tables in the current schema. |
| stats | Displays annotation statistics. |
| most-referenced-tables | Lists tables ranked by inbound foreign key references. |
14.1.1 Annotation Subcommands
For a description of the options, see the Add an Annotation section.
Add an Annotation
This command enables you to add a new annotation to an object. An object can have multiple annotations using different labels.
Syntax
annotation annotate
-type <object-type>
-name <object-name>
-label <annotation-label>
-value <annotation-value>
[-debug]
[-verbose]Options
| Option | Required | Description |
|---|---|---|
| -type <object-type> | Yes | The type of object being annotated. For example, TABLE or TABLE COLUMN.
|
| -name <object-name> | Yes | The object name. For a table, use the table name. For a table column, use TABLENAME.COLUMNNAME.
|
| -label <annotation-label> | Yes | The annotation label. For example, DESCRIPTION.
|
| -value <annotation-value> | Yes | The annotation text stored under the label. |
| -debug | No | Enables debugging information. |
| -verbose | No | Enables verbose output. |
For a list of object types supported, see Supported Object Types.
Get an Annotation
Use annotation get-annotation to read the value of an existing annotation.
Syntax
annotation get-annotation
-type <object-type>
-name <object-name>
-label <annotation-label>
[-debug]
[-verbose]Edit an Annotation
Use annotation edit-annotation to replace the value of an existing annotation.
Syntax
annotation edit-annotation
-type <object-type>
-name <object-name>
-label <annotation-label>
-value <new-annotation-value>
[-debug]
[-verbose]Delete an Annotation
Use annotation delete-annotation to remove an existing annotation from an object by using its label, object name, and object type.
Syntax
annotation delete-annotation
-type <object-type>
-name <object-name>
-label <annotation-label>
[-debug]
[-verbose]14.1.1.1 Supported Object Types
The AI Enrichment extension supports the following object types:
| Category | Supported Types |
|---|---|
| Tables | Table, Table Column, Table Partition, Table Subpartition |
| Views | View, View Column, Materialized View, Materialized View Column |
| PL/SQL | Package, Package Procedure, Package Function, Procedure, Function |
| Other | Database, Schema, Group |
14.1.2 Group Subcommands
For a description of the options, see the Add an Object to a Group section.
Create a Group
Use annotation add-group to create a new group.
Syntax
annotation add-group -group <group-name>
[-debug] [-verbose]
List Groups
Use annotation list-groups to list the groups that have been created.
Syntax
annotation list-groups
[-debug] [-verbose]Add an Object to a Group
Use annotation add-to-group to add a database object to a group.
Syntax
annotation add-to-group -group <group-name>
-type <object-type> -name <object-name>
[-debug] [-verbose]| Parameter | Required | Description |
|---|---|---|
| -group <group-name> | Yes | The group name. |
| -type <object-type> | Yes | The type of object being added to the group. For example, TABLE or TABLE COLUMN.
|
| -name <object-name> | Yes | The object name. For a table, use the table name. For a table column, use TABLENAME.COLUMNNAME.
|
Remove an Object from a Group
Use annotation remove-from-group to remove an object from a group.
Syntax
annotation remove-from-group -group <group-name>
-type <object-type> -name <object-name>
[-debug] [-verbose]Delete a Group
Use annotation delete-group to delete a group.
Syntax
annotation delete-group -group <group-name>
[-debug] [-verbose]14.1.3 Auto-Annotate
This command generates DESCRIPTION annotations for TABLE and TABLE COLUMN objects.
Syntax
annotation auto-annotate {OPTIONS}Options
| Option | Description |
|---|---|
| -prompt <prompt> | Additional user guidance to consider after the built-in annotation rules. |
| -prompt-file <prompt-file> | File containing additional user guidance to consider after the built-in annotation rules. |
| -reference <references> | Provide one or more comma-separated reference files containing business or domain context. |
| -list <list> | Annotate the specified comma separated list of tables. Table names may include % wildcards. |
| -ignore-list <ignore-list> | Exclude the specified comma separated list of tables from being annotated. % wildcards are supported. |
| -debug | Show diagnostic information. |
| -verbose | Show additional processing information. |
Note:
auto-annotate generates DESCRIPTION annotations only for TABLE and TABLE COLUMN targets. You can manually add annotations to other supported object types, but auto-annotate does not generate annotations for those objects.