本文将会介绍如何使用 Oracle database 23c 新增的注解功能为数据库对象增加描述信息（元数据）。

基本概念

注解（Annotation）可以简单理解为数据库注释（Comment）的扩展功能。注释可以为数据库对象（例如表和列）增加描述信息。注解则进一步扩展了这个功能，可以为数据库对象创建名称-值对的描述。注解中的名称和值都是字符串，我们可以自定义有用的信息。

目前注解支持以下数据库对象：

• 表和字段

• 视图和字段

• 物化视图和字段

• 索引

• 域和多列域字段

使用注解

对于支持注解的对象，通常可以使用以下格式定义注解：

ANNOTATIONS ( {ADD|DROP} annotation_name {'annotation_value'} {,} )

以下是一个为表增加注解的示例，增加注解时的 ADD 关键字可以省略：

CREATE TABLE Employee (
  Id  NUMBER(5) ANNOTATIONS(Identity, Display 'Employee ID', Group 'Emp_Info'),
  Ename VARCHAR2(50) ANNOTATIONS(Display 'Employee Name',  Group 'Emp_Info'),
  Sal NUMBER ANNOTATIONS(Display 'Employee Salary', UI_Hidden)
) ANNOTATIONS (Display 'Employee Table');

其中，

• 注解 Identity 表明该字段是一个标识字段。该注解只有名字没有值；

• 注解 Display 为 UI 界面提供了推荐的显示名；

• 注解 Group 可以将显示信息进行分类。

注意，这些注解都是我们自定义的内容，对于数据库或者其他工具而言并没有任何意义。

我们可以通过添加或者删除操作修改对象注解。例如：

alter table Employee annotations (Visibility 'Everyone');

alter table Employee annotations (drop Visibility);

alter table Employee annotations (add Visibility 'Everyone');

对于字段级别的注解，也可以执行类似的操作：

alter table Employee modify (Id annotations (Visibility 'Hidden'));

alter table Employee modify (Id annotations (drop Visibility));

alter table Employee modify (Id annotations (add Visibility 'Hidden'));

相关视图

目前，与注解相关的视图包括：USER_ANNOTATIONS、USER_ANNOTATIONS_USAGE、USER_ANNOTATION_VALUES 以及对应的 ALL 视图和 DBA 视图。

select object_name,
       object_type,
       column_name,
       domain_name,
       domain_owner,
       annotation_name,
       annotation_value
from   user_annotations_usage
order by annotation_name, annotation_value;

OBJECT_NAME  OBJECT_TYPE  COLUMN_NAME  DOMAIN_NAME  DOMAIN_OWNER ANNOTATION_NAM ANNOTATION_VALUE
------------ ------------ ------------ ------------ ------------ -------------- --------------------
EMPLOYEE     TABLE        ID                                     DISPLAY        Employee ID
EMPLOYEE     TABLE        ENAME                                  DISPLAY        Employee Name
EMPLOYEE     TABLE        SAL                                    DISPLAY        Employee Salary
EMPLOYEE     TABLE                                               DISPLAY        Employee Table
EMPLOYEE     TABLE        ID                                     IDENTITY
EMPLOYEE     TABLE        ID                                     GROUP          Emp_Info
EMPLOYEE     TABLE        ENAME                                  GROUP          Emp_Info
EMPLOYEE     TABLE        SAL                                    UI_Hidden
EMPLOYEE     TABLE                                               VISIBILITY     Everyone
EMPLOYEE     TABLE        ID                                     VISIBILITY     Hidden