23ai: Annoations

Dokumentationen lesen ist zwar oftmals sehr hilfreich, aber dafür muss diese erst einmal vorhanden sein und dann muss man die relevanten Informationen auch noch finden. Hilfreich kann da sein, wenn die Informationen mit der Beschreibung gemeinsam mit der eigentlichen Implementierung gespeichert werden. Für Quellcode kennt das jeder, aber auch in der Oracle Datenbank gibt es die Möglichkeit zur Dokumentation. Es ist möglich, Kommentare an Tabellen, Spalten und noch ein paar andere Objekte zu hängen. Die Version 23ai bringt eine deutliche Erweiterung dieser Möglichkeit mit, die Annotations, die wir hier vorstellen wollen.

Die Oracle Datenbank bietet seit jeher die Möglichkeit, das Datenmodell mittels Kommentaren zu dokumentieren. Da die Kommentare direkt in der Datenbank abgelegt werden, ergibt das ein in sich geschlossenes System und man muss nicht separate Dokumentationen pflegen oder konsultieren. Hier ein kurzes Beispiel:

HR @ ORCL19:PDB1:>create table person (
  2    id      number,
  3    vorname varchar2(100),
  4    nachname varchar2(100)
  5* );

Table PERSON created.

HR @ ORCL19:PDB1:>comment on table person is 'Persönliche Daten von Personen';

Comment created.

HR @ ORCL19:PDB1:>comment on column person.id is 'Primary Key';

Comment created.

HR @ ORCL19:PDB1:>comment on column person.vorname is 'Vorname der Person';

Comment created.

Das SQLcl zeigt diese Kommentare beim “info” Befehl direkt mit an:

HR @ ORCL19:PDB1:>info person
TABLE: PERSON
        LAST ANALYZED:
        ROWS         :
        SAMPLE SIZE  :
        INMEMORY     :DISABLED
        COMMENTS     :Persönliche Daten von Personen
Columns
NAME         DATA TYPE            NULL  DEFAULT    COMMENTS
ID          NUMBER               Yes              Primary Key
VORNAME     VARCHAR2(100 BYTE)   Yes              Vorname der Person
NACHNAME    VARCHAR2(100 BYTE)   Yes              Nachname der Person

Die Version 23ai hebt die Möglichkeiten, Metainformationen in der Datenbank abzulegen, auf ein neues Level. Es ist nun möglich, beliebige Schlüssel/Wert-Paare an Objekte zu hängen. Man ist dabei auch nicht auf nur ein Wertepaar beschränkt, sondern kann beliebig viele davon an ein Objekt hängen. Diese Annotations lassen sich sehr vielfältig einsetzen.

Am besten erklärt sich das Feature natürlich an einem Beispiel:

MARCO @ DB23AI:PDB1:>create table car_vendors (
 2    id         number(15)   annotations (PrimaryKey, Description 'Primary Key', Class 'Number')
 3   ,vname      varchar2(30) annotations (Description 'Car Vendor Company Name', Class 'Text')
 4   ,country_id number(15)   annotations (ForeignKey, Description 'ID for Country Reference', Class 'Number')
 5  )
 6* annotations (Description 'List of Car Vendors', Visibility 'everyone');

Table CAR_VENDORS created.

Hier werden also gleich mehrere Schlüssel verwendet. Wie man sieht, muss auch nicht zwingend ein Wert an einen Schlüssel gebunden werden. Im Beispiel werden vier Arten von Metainformationen benutzt. Einmal die “Description” als klassische verbale Beschreibung, einmal “Class” als Definition des abstrakten Datentyps einer Spalte, dann “Visibility” zur Erklärung und ggf. Steuerung, wer die Daten sehen darf und zu guter Letzt mit “PrimaryKey” und “ForeignKey” Informationen zu den Schlüsselbeziehungen. 

Natürlich können diese Informationen auch jederzeit entfernt, geändert oder erweitert werden.

MARCO @ DB23AI:PDB1:>alter table car_vendors annotations (drop Visibility);

Table CAR_VENDORS altered.

MARCO @ DB23AI:PDB1:>alter table car_vendors annotations (add Visibility 'Mobility');

Table CAR_VENDORS altered.

MARCO @ DB23AI:PDB1:>alter table car_vendors modify (id annotations (add Visibility 'hidden'));

Table CAR_VENDORS altered.

MARCO @ DB23AI:PDB1:>alter table car_vendors modify (vname annotations (replace Description 'Car Manufacturer'));

Table CAR_VENDORS altered.

All diese Informationen können dann über die View USER_ANNOTATIONS_USAGE und deren Pendants abgefragt werden. 

MARCO @ DB23AI:PDB1:>select object_name,
 2         object_type,
 3         column_name,
 4         annotation_name,
 5         annotation_value
 6  from   user_annotations_usage
 7  where  object_name = 'CAR_VENDORS'
 8* order by annotation_name, annotation_value;
 
OBJECT_NAME        OBJECT_TYPE    COLUMN_NAME    ANNOTATION_NAME    ANNOTATION_VALUE
__________________ ______________ ______________ __________________ ________________________________
CAR_VENDORS        TABLE          ID             CLASS              Number
CAR_VENDORS        TABLE          COUNTRY_ID     CLASS              Number
CAR_VENDORS        TABLE          VNAME          CLASS              Text
CAR_VENDORS        TABLE          VNAME          DESCRIPTION        Car Maufacturer
CAR_VENDORS        TABLE          COUNTRY_ID     DESCRIPTION        ID for Country Reference
CAR_VENDORS        TABLE                         DESCRIPTION        List of Car Vendors
CAR_VENDORS        TABLE          ID             DESCRIPTION        Primary Key
CAR_VENDORS        TABLE          COUNTRY_ID     FOREIGNKEY
CAR_VENDORS        TABLE          ID             PRIMARYKEY
CAR_VENDORS        TABLE                         VISIBILITY         Mobility
CAR_VENDORS        TABLE          ID             VISIBILITY         hidden

Will man die Annotations z.B. für die Sichtbarkeit tatsächlich aktiv benutzen, dann muss man die Informationen dazu genau auf diese Weise selbst ermitteln, denn das übernimmt die Datenbank natürlich nicht. Zumindest nicht anhand der Annotations, dafür gibt es andere Funktionalitäten. Mit den Annotations aus dem Beispiel könnte man aber auch Recherchen über das Datenmodell durchführen, um alle Primary Key Spalten zu ermitteln.

Der Kreativität sind hier kaum Grenzen gesetzt. Die Möglichkeit, beliebig viele Schlüssel mit oder ohne Werten an Objekte zu binden, erweitert das klassische Konzept der Kommentare enorm. Dieses einfache Beispiel kann also nur als Anregung dienen, was für ein mächtiges Werkzeug uns Oracle da an die Hand gibt.