10 データベースへのアプリケーション・データ使用状況の登録

この章では、スキーマ注釈と呼ばれる集中管理型のデータベース中心エンティティを使用してアプリケーション・データの用途に関する情報を登録する方法について説明します。

Oracle Database 19cでは、データの用途情報を処理するためにスキーマ注釈を使用する、集中管理型のデータベース中心アプローチが導入されています。スキーマ注釈をデータベースに一元的に追加してデータの用途を登録すると、様々なアプリケーションとツールからそれにアクセスできるようになります。

関連項目:

  • スキーマ注釈の詳細は、『Oracle Database概要』を参照してください。

  • スキーマ注釈に関する構文とセマンティクスについては、『Oracle Database SQL言語リファレンス』を参照してください。

10.1 スキーマ注釈

この項では、データベース・オブジェクトにスキーマ注釈(以降は、「注釈」と表記)を使用する方法について説明します。

多くのアプリケーションでは、表、ビュー、表の列、索引などのデータベース・オブジェクトについてさらにプロパティ・メタデータを保持することが重要です。注釈を使用すると、アプリケーションで、データベース・オブジェクトおよび表の列に関するユーザー固有のメタデータをさらに格納および取得できます。アプリケーションでは、このようなメタデータを使用して、効果的なユーザー・インタフェースをレンダリングしたり、アプリケーション・ロジックをカスタマイズできます。

トピック:

10.1.1 注釈の概要

注釈とは何ですか。また、どこで使用できますか。

注釈は、開発者がデータベース・スキーマ・オブジェクトの使用状況プロパティを一元的に登録するための軽量な宣言機能です。注釈はディクショナリ表に格納され、関連アプリケーションの共通データ全体にわたって動作の標準化を求めるアプリケーションで使用できます。注釈はデータベースによって解釈されません。これらはデータベース・メタデータのカスタム・データ・プロパティであり、表の列、表および索引に含まれており、アプリケーションは追加のプロパティ・メタデータとして使用してユーザー・インタフェースをレンダリングしたり、アプリケーション・ロジックをカスタマイズできます。

アプリケーション・メタデータをデータベースに一元的に定義および格納するメカニズムである注釈を使用すると、アプリケーション、モジュールおよびマイクロサービス間でメタデータ情報を共有できます。新しいオブジェクトを(CREATE文を使用して)作成したり、既存のオブジェクトを(ALTER文を使用して)変更するときに、注釈をスキーマ・オブジェクトに追加できます。

メタデータを使用してデータ・モデルに注釈を付けると、データの整合性と一貫性が向上し、データ・モデルのドキュメンテーションのメリットが高まります。アプリケーションでは、他のアプリケーションまたはユーザーが取得および使用できるデータベース・オブジェクトと表の列に関するユーザー定義のメタデータを格納できます。データとともにメタデータを格納すると、データを使用するユーザーまたはアプリケーションに対する一貫性と汎用的なアクセシビリティが保証されます。

個々の注釈には名前とオプションの値があります。名前とオプションの値は自由形式のテキスト・フィールドです。たとえば、名前と値のペアを持つ注釈(Display_Label 'Employee Salary'など)を保持したり、名前のみを持つ(名前が説明なしでわかるため値が不要の)スタンドアロンの注釈(UI_Hiddenなど)を保持できます。

次に、注釈の詳細を示します。

  • CREATE DDL文を使用してスキーマ・オブジェクトに注釈名を指定すると、注釈が自動的に作成されます。

  • 注釈は付加的です。つまり、同じスキーマ・オブジェクトに複数の注釈を指定できます。

  • 1つのDDL文を使用して、一度に複数の注釈をスキーマ・オブジェクトに追加できます。同様に、1つのDDL文で複数の注釈をスキーマ・オブジェクトから削除できます。

  • 注釈は、注釈を追加するデータベース・オブジェクトに対する下位要素として表されます。注釈は、データベース内に新しいオブジェクト・タイプを作成しません。

  • 自分が所有しているか、スキーマ・オブジェクトに対する変更権限あれば、注釈をサポートする任意のスキーマ・オブジェクトに注釈を追加できます。注釈名をスキーマ修飾する必要はありません。

  • ディクショナリ・ビューに対してSQL問合せを発行して、名前と値およびスキーマ・オブジェクトでの使用を含め、すべての注釈を取得できます。

10.1.2 注釈とコメント

COMMENTコマンドを使用して、表や表の列などのデータベース・オブジェクトに注釈を付けることもできます。スキーマ・オブジェクトに関連付けられたコメントは、オブジェクトのメタデータとともにデータ・ディクショナリに格納されます。

注釈は、コメントよりも使用しやすく、範囲が広くなります。コメントと注釈の主な違いは次のとおりです。

  • コメントは、表や列などの特定のスキーマ・オブジェクトにのみメタデータを追加するために使用されるコメント・メカニズムです。他のスキーマ・オブジェクト(索引、プロシージャ、トリガーなど)にはコメントを使用できません。

  • コメントには名前がなく、自由形式の値しかありません。

  • コメントは付加的ではありません。つまり、同じオブジェクトに複数のコメントを追加することはできません。新しいコメントを指定すると、対応する表または列に関する前のコメントが上書きされます。

  • コメントには別々のDDL文が必要であるのに対し、複数の注釈を結合して1つのDDL文にできます。

  • エンティティごとに個別のディクショナリ・ビュー・セットが存在します。たとえば、表コメント用のビューと列コメント用の別のビューがあります。一方、注釈は、すべてのオブジェクト・タイプで統一されているため、問合せおよび使用が簡単になります。

関連項目:

COMMENTSの使用方法の詳細は、コメントを参照してください。

10.1.3 サポートされているデータベース・オブジェクト

注釈は、次のデータベース・オブジェクトでサポートされています。

  • 表および表の列

  • ビューおよびビューの列

  • マテリアライズド・ビューおよびマテリアライズド・ビューの列

  • 索引

10.1.4 注釈の使用に必要な権限

注釈を追加または削除するには、CREATEまたはALTER DDL文で注釈が指定されているスキーマ・オブジェクトに対するCREATEまたはALTER権限が必要です。

注釈を明示的に作成または削除することはできません。注釈は、初回使用時に自動的に作成されます。注釈は、注釈が定義されているデータベース・オブジェクト内の下位要素として格納されるため、注釈を追加してもデータベース内に新しいオブジェクト・タイプは作成されません。

10.1.5 注釈のDDL文

この項では、注釈の構文を説明し、表、表の列、ビュー、マテリアライズド・ビューおよび索引について注釈を定義または変更するためのDDL文を示します。

トピック:

10.1.5.1 注釈の構文

次のスニペットは、表、表の列、ビュー、マテリアライズド・ビューおよび索引について注釈を定義するためにDDL文で使用される注釈構文を示しています。

annotations
         ::= 'ANNOTATIONS' '(' annotations_list ')'

annotations_list
         ::= ( 'ADD' ('IF NOT EXISTS' | 'OR REPLACE' )? | 'DROP' 'IF EXISTS'? | REPLACE)?
 annotation ( ',' ( 'ADD' ('IF NOT EXISTS' | 'OR REPLACE' )? | 'DROP' 'IF EXISTS'? | REPLACE)?
 annotation )*

annotation
         ::= annotation_name annotation_value?

annotation_name
         ::= identifier

annotation_value
         ::= character_string_literal

<annotation_value>は、最大4000文字を保持できる文字列リテラルです。

<annotation_name>は識別子であり、次の要件があります。

  • 識別子は1024文字まで指定できます。

  • 識別子が予約語である場合は、注釈名を二重引用符で囲む必要があります。

  • 二重引用符で囲まれた識別子には、空白文字を含めることができます。

  • 空白文字のみが含まれる識別子は使用できません。

10.1.5.2 表に注釈を付けるDDL文

次のDDL文を使用して、表を作成または変更するときに表に注釈を付けることができます。

CREATE TABLE文の使用方法

次に、注釈を指定したCREATE TABLE文の例を示します。

次の例では、JSON値の注釈Operationと、もう1つのスタンドアロンで値のない注釈Hiddenを追加します。 

CREATE TABLE Table1 (
  T NUMBER)
  ANNOTATIONS(Operations '["Sort", "Group"]', Hidden);

注釈をするときには、その前にADDキーワードを使用できます。すべての指定を省略すると、ADDキーワードがデフォルトの操作とみなされます。

次の例では、オプションのADDキーワードを使用して、Hidden注釈(同様にスタンドアロン)をTable2に追加します。 

CREATE TABLE Table2 (
  T NUMBER)
  ANNOTATIONS (ADD Hidden);

ADDキーワードは、注釈を定義するときの暗黙的な操作であり、省略できます。

ALTER TABLE文の使用方法

次の例では、ALTER TABLEコマンドによって、注釈名OperationsおよびHiddenのすべての注釈値が削除されます。 

ALTER TABLE Table1
  ANNOTATIONS(DROP Operations, DROP Hidden);

次の例のALTER TABLEコマンドでは、Join値の注釈JoinOperationsを追加して、注釈名Hiddenを削除します。注釈を削除するときには、DROPコマンドに注釈名のみを含める必要があります。 

ALTER TABLE Table1
  ANNOTATIONS(ADD JoinOperations 'Join', DROP Hidden);

前の文ではHidden注釈が削除されているため、この出力は「ORA-11553: 注釈名'HIDDEN'はオブジェクト'Table1'には存在しません」となります。注釈が存在しないときのこのエラーを回避するには、IF EXISTS句を使用します。 

ALTER TABLE Table1 ANNOTATIONS(ADD JoinOperations 'Join', DROP IF EXISTS Hidden);

1つのDDL文に複数のADDおよびDROPキーワードを指定できます。

同じオブジェクト(オブジェクト・レベルの注釈の場合)または同じ列(列レベルの注釈の場合)に、値が異なる注釈を再追加しようとするとエラーが発生します。たとえば、次の文は失敗します:
ALTER TABLE Table1
  ANNOTATIONS(ADD JoinOperations 'Join Ops');

出力は次のとおりです。

ORA-11552: Annotation name 'JOINOPERATIONS' already exists for the object 'TABLE1'.
そのかわりとして、注釈構文では、REPLACEキーワードを使用して注釈値を置換できます。次の文では、JoinOperationsの値を'Join Ops'に置き換えます:
ALTER TABLE Table1
  ANNOTATIONS(REPLACE JoinOperations 'Join Ops');

出力は次のとおりです

Table altered.
また、すでに注釈が存在しているときのエラーを回避するために、IF NOT EXISTS句を使用することもできます。次の文では、JoinOperations注釈が存在しない場合にのみ、その注釈を追加します。その注釈が存在する場合、注釈値は変更されず、エラーは発生しません。
ALTER TABLE Table1
  ANNOTATIONS(ADD IF NOT EXISTS JoinOperations 'Join Ops');
同様に、存在しない注釈を削除するとエラーが発生します:
ALTER TABLE Table1 ANNOTATIONS(DROP Title);

出力は次のとおりです。

ORA-11553: Annotation name 'TITLE' does not exist.
このエラーを回避するために、次のようにIF EXISTS句を使用できます。
ALTER TABLE Table1
  ANNOTATIONS(DROP IF EXISTS Title);

出力は次のとおりです。

Table altered.

関連項目:

句の完全な変更および定義については、『SQL言語リファレンス』のCREATE TABLEおよびALTER TABLE。

10.1.5.3 表の列に注釈を付けるDDL文

次のDDL文を使用して、表を作成または変更するときに表の列に注釈を付けることができます。

CREATE TABLE文の使用方法

CREATE TABLE文を使用して列レベルの注釈を追加するには、column_definition句の一部として注釈を指定します。注釈は、末尾のインライン制約の後に指定されます。

次の例では、表作成時に列の注釈を指定します。

CREATE TABLE Table1
  (T NUMBER ANNOTATIONS(Operations 'Sort', Hidden));

CREATE TABLE Table2
  (T NUMBER ANNOTATIONS (Hidden));

次の例では、Employee表に表レベルと列レベルの注釈を指定します。 

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');

前の例のEmployee表には、列レベルとオブジェクト・レベルの注釈Displayがあります。この注釈は、列レベルとオブジェクト・レベルで定義されています。新しい注釈は、それに対応するオブジェクトと列のペアが異なっていれば同じ名前で定義できます。たとえば、このEmployee表について、このDisplay名が付いた別の注釈を定義することはできませんが、このEmployee表のどの列にも、Display名が付いた新しい注釈を定義できます。Sal列に他の注釈("Group"など)を定義することもできます。注釈"Group"は、予約語であるため二重引用符で囲む必要があります。

ALTER TABLE文の使用方法

ALTER TABLE文を使用して列レベルの注釈を追加するには、modify_col_properties句の一部として注釈を指定します。注釈は、末尾のインライン制約の後に指定されます。

次の例では、Table1表の列Tに、新しいIdentity注釈を追加します。 

ALTER TABLE Table1
  MODIFY T ANNOTATIONS(Identity 'ID');

次の例では、Label注釈を追加して、Identity注釈を削除します。 

ALTER TABLE Table1
  MODIFY T ANNOTATIONS(ADD Label, DROP Identity);

関連項目:

句の完全な変更および定義については、『SQL言語リファレンス』のCREATE TABLEおよびALTER TABLE。

10.1.5.4 ビューおよびマテリアライズド・ビューに注釈を付けるDDL文

次のDDL文を使用して、ビューおよびマテリアライズド・ビューに注釈を付けることができます。

ビューおよびマテリアライズド・ビューは、ビュー・レベルおよび列レベルで注釈をサポートしています。列レベルの注釈は、列別名定義句の一部として表のビューでのみサポートされています。

CREATE VIEW文の使用方法

次の例では、ビュー・レベルおよび列レベルの注釈を示します。

CREATE OR REPLACE VIEW HighWageEmp  
(
  Id ANNOTATIONS(Identity, Display 'Employee ID', "Group" 'Emp_Info'),
  Ename ANNOTATIONS (Display 'Employee Name',  "Group" 'Emp_Info'),
  Sal  ANNOTATIONS (Display 'Emp Salary')  
)
ANNOTATIONS (Title 'High Wage Employee View')
AS SELECT * FROM EMPLOYEE WHERE Sal > 100000;

CREATE MATERIALIZED VIEW文の使用方法

次の例では、Materialized View文でビュー・レベルの注釈を追加します: 

CREATE MATERIALIZED VIEW MView1
  ANNOTATIONS (Title 'Tab1 MV1', ADD Snapshot)
  AS SELECT * FROM Table1;

次の例では、Materialized View文でビュー・レベルおよび列レベルの注釈を追加します: 

CREATE MATERIALIZED VIEW MView1(
  T ANNOTATIONS (Hidden)) 
 ANNOTATIONS (Title 'Tab1 MV1', ADD Snapshot)
 AS SELECT * FROM Table1;

ALTER VIEW文の使用方法

注釈をサポートするために、ALTER VIEW文に新しい副句が追加され、ビュー・レベルで注釈を変更できます。ALTER VIEW文でサポートされている他の副句には、ビューの制約の変更、再コンパイルの有効化およびEDITIONABLEプロパティの変更があります。

ビューの列レベルの注釈は変更できません。以前に追加された列レベルの注釈は、ビューを削除し、新しいものを再作成することによってのみ削除できます。

次の例は、Title注釈を削除して、ビュー・レベルでIdentity注釈を追加するALTER VIEW文です。 

ALTER VIEW HighWageEmp
  ANNOTATIONS(DROP Title, ADD Identity);

ALTER MATERIALIZED VIEW文の使用方法

ALTER MATERIALIZED VIEW文には、マテリアライズド・ビュー・レベルで注釈をグローバルに変更するために追加された新しい副句があります。列レベルの注釈は、マテリアライズド・ビューを削除して再作成することによってのみ削除できます。

次のALTER MATERIALIZED VIEW文では、MView1からSnapshot注釈を削除します。 

ALTER MATERIALIZED VIEW MView1
  ANNOTATIONS(DROP Snapshot);

関連項目:

句の完全な変更および定義については、『SQL言語リファレンス』のCREATE VIEW、ALTER VIEW、CREATE MATERIALIZED VIEWおよびALTER MATERIALIZED VIEW。

10.1.5.5 索引に注釈を付けるDDL文

次のDDL文を使用して、索引に注釈を付けることができます。

CREATE INDEX文の使用方法

次に、索引レベルの注釈の作成例を示します。

CREATE TABLE DEPARTMENT(
  DEPT_ID NUMBER,
  UNIT NUMBER);

CREATE INDEX I_DEPT_ID ON DEPARTMENT(DEPT_ID)
  ANNOTATIONS(Display 'Department Index');

CREATE UNIQUE INDEX UI_UNIT ON DEPARTMENT(UNIT)
  ANNOTATIONS(Display 'Department Unique Index');

ALTER INDEX文の使用方法

次に、索引レベルの注釈の変更例を示します。

ALTER INDEX I_DEPT_ID
  ANNOTATIONS(DROP Display, ADD ColumnGroup 'Group1');

関連項目:

句の完全な変更および定義については、『SQL言語リファレンス』のCREATE INDEXおよびALTER INDEX。

10.1.6 ディクショナリ表およびディクショナリ・ビュー

ANNOTATIONS_USAGE$というディクショナリ表には、表やビューなどのスキーマ・オブジェクトでの注釈の使用がすべて含まれます。スキーマ・オブジェクトに新しい注釈名、値あるいはその両方を指定すると、ANNOTATIONS_USAGE$表に新しいエントリが作成されます。同様に、スキーマ・オブジェクトで注釈が削除されると、対応するエントリがANNOTATIONS_USAGE$表から削除されます。

次のディクショナリ・ビューでは、すべてのスキーマ・オブジェクトにわたって注釈とその使用のリストが追跡されます。

  • {DBA|USER|ALL|CDB}_ANNOTATIONS

  • {DBA|USER|ALL|CDB}_ANNOTATIONS_USAGE

  • {DBA|USER|ALL|CDB}_ANNOTATIONS_VALUES

10.1.6.1 ディクショナリ・ビューの問合せ

ディクショナリ・ビューに対して問合せを実行し、特定のスキーマ・オブジェクトに使用される注釈のリストを取得できます。

'EMP'表に対して発行された問合せ文の例を次に示します。

'EMP'表の表レベルの注釈を取得する場合:
SELECT * FROM USER_ANNOTATIONS_USAGE
  WHERE Object_Name = 'EMPLOYEE'
   AND Object_Type = 'TABLE'
   AND Column_Name IS NULL;
'EMP'表の列レベルの注釈を取得する場合:
SELECT * FROM USER_ANNOTATIONS_USAGE
  WHERE Object_Name = 'EMPLOYEE'
   AND Object_Type = 'TABLE'
   AND Column_Name IS NOT NULL;
列ごとに単一のJSONコレクションとして'EMP'表の列レベルの注釈を取得する場合:
SELECT  U.Column_Name, JSON_ARRAYAGG(JSON_OBJECT(U.Annotation_Name, U.Annotation_Value))
  FROM USER_ANNOTATIONS_USAGE U
  WHERE Object_Name = 'EMPLOYEE' AND Object_Type = 'TABLE' AND Column_Name IS NOT NULL
  GROUP BY Column_Name;