Oracle 23c - Información Detallada de Tablas y Columnas con Annotations

ANNOTATIONS es una funcionalidad de Oracle Database 23c que complementa la opción COMMENTS disponible para muchos objetos (como ser tablas y columnas), permitiendo hace runa descripción mas detallada de los mismos.

A diferencia de COMMENTS que permite ingresar un único texto libre, ANNOTATIONS permite asociar valores o pares de valores (clave + valor) definidos libremente, con el objetivo de poder describir y clasificar los objetos.

Otra diferencia clave con COMMENTS es que ANNOTATIONS funciona en forma aditiva (se pueden agregar nuevas claves o pares clave valor) mientras que no es posible tener mas de un comentario por cada objeto o columna.

Sintaxis

La sintaxis es muy sencilla:

ANNOTATIONS ( {ADD|DROP} Nombre_Anotacion {'Valor_Anotacion'} )

La misma esta compuesta de un nombre de anotación y opcionalmente un valor (el cual es un literal de tipo texto). La palabra clave ADD no es requerida cuando se usa la sintaxis para crear los objetos o la anotación.

Ejemplos

Al crear una tabla podemos incluir valores que nos ayudan a comprender el uso de cada una de las columnas, como mostramos a continuación:

CREATE TABLE tComprobantes (
    ID_Comprobante NUMBER(10) NOT NULL
        ANNOTATIONS ( ClavePrimaria, NombreVisible 'Identificador Comprobante', TipoColumna 'Interno'),
    ID_TipoComprobante NUMBER(5) NOT NULL
        ANNOTATIONS ( Referencia, NombreVisible 'Identificador Tipo Comprobante', TipoColumna 'Interno'),
    Nro_Comprobante NUMBER(8) NOT NULL
        ANNOTATIONS ( NombreVisible 'Número de Comprobante', TipoColumna 'Visible'),
    Fecha_Comprobante DATE NOT NULL
        ANNOTATIONS ( NombreVisible 'Fecha de Comprobante', TipoColumna 'Visible'),
    Importe_Comprobante NUMBER (12,2) NOT NULL
        ANNOTATIONS ( NombreVisible 'Importe Comprobante', TipoColumna 'Visible'),
    Fecha_Alta DATE NOT NULL
        ANNOTATIONS ( NombreVisible 'Fecha Alta', TipoColumna 'Auditoria'),
    Fecha_Modificacion DATE 
        ANNOTATIONS ( NombreVisible 'Fecha Modificación', TipoColumna 'Auditoria'),
    Usuario_Alta VARCHAR2(50) NOT NULL
        ANNOTATIONS ( NombreVisible 'Usuario Alta', TipoColumna 'Auditoria'),
    Usuario_Modificacion VARCHAR2(50) 
        ANNOTATIONS ( NombreVisible 'Usuario Modificación', TipoColumna 'Auditoria')
    ) ANNOTATIONS (NombreVisible 'Comprobantes', TipoTabla 'Transaccional');

En el ejemplo podemos ver lo siguiente:

• La columna "ID_Comprobante" tiene una anotación ClavePrimaria que indica que la misma es la clave primaria de la tabla. Esta anotación no posee asociado un valor.
• La columna "ID_TipoComprobante" tiene una anotación  Referencia que indica que es una referencia o clave foránea a otra tabla. Esta anotación no posee asociado un valor.
• Tanto la tabla como todas las columnas tienen una anotación NombreVisible el cual tiene asociado en cada caso un valor que representa como debería etiquetarse la columna o tabla al ser mostrada por las aplicaciones que la usen.
• Todas las columnas tienen una anotación TipoColumna el cual tiene asociado un valor que indica si la columna es de tipo Interno (ID que no son mostrados), de tipo Visible (datos que usualmente se incluyen en la UI) o de tipo Auditoria (información de auditoria para controlar los cambios realizados a cada registro).
• La tabla posee también una anotación TipoTabla que identifica a la tabla como una tabla que contiene transacciones (podríamos tener otros tipos como ser "Datos Maestros", datos de "Auditoria", etc.).

Si queremos eliminar una anotación, solo debemos usar la palabra DROP en la clausula de Annotations, como vemos a continuación:

Objetos que Soportan ANNOTATIONS

Actualmente, los siguientes objetos de una base de datos Oracle soportan ANNOTATIONS:

• Tablas y sus columnas.
• Vistas y sus columnas.
• Vistas Materializadas y sus columnas.
• Indices.
• Dominios y columnas de Dominios multi columna.

¿Cómo Usar la Información de ANNOTATIONS?

Una vez que creamos nuestros objetos con anotaciones, podemos consultar las mismas usando dos vistas del diccionario de datos llamadas USER_ANNOTATIONS y USER_ANNOTATIONS_USAGE .

Suponiendo que tenemos que informar al equipo de desarrollo los nombres a utilizar al momento de visualizar las columnas de la tabla creada anteriormente, podemos obtener los mismos con la siguiente consulta:

SELECT object_name, object_type, column_name, annotation_name, annotation_value
FROM user_annotations_usage
WHERE Annotation_name = 'NOMBREVISIBLE';

La cual nos devuelve la siguiente información:

Lo mismo si queremos ver un detalle de alguna columna en particular, podemos probar con:

SELECT object_name, object_type, column_name, annotation_name, annotation_value
FROM user_annotations_usage
WHERE OBJECT_NAME = 'TCOMPROBANTES' 
AND COLUMN_NAME = 'ID_COMPROBANTE';

Lo cual nos mostrará las anotaciones asociadas a esa columna en particular:

Conclusión

Ahora es posible realizar documentar mas fácilmente los objetos de nuestras bases de datos mediante el uso de ANNOTATIONS, soportando multiples valores y combinaciones de Clave + Valor para describir correctamente los mismos.

La sección "Application Usage Annotations" de la documentación oficial contiene una descripción detallada de todo lo mencionado anteriormente, por si desean ver mas detalles.

Si desean conocer más sobre Oracle 23c, es recomendable que vean estos artículos en este blog como punto de partida:

• Oracle Database 23c Free - Developer Edition.
• Instalando Oracle Database 23c (Free Developer Edition) en Oracle Cloud.

Adicionalmente, pueden consultar todos los artículos relacionados a Oracle Database 23c agrupados en en el tag Database 23c.