はじめに
LLMを活用した自然言語によるSQLクエリ生成の精度を向上させる策の１つに、表や列にアノテーション（注釈）を定義することがあります。
Oracle SQL Developer for VS Codeの新機能「AIエンリッチメント(Enrichment)」を活用することでGUI(VS Code)でデータベース・オブジェクト(スキーマ、表および列)のアノテーションの管理ができます。
AIエンリッチメントで定義されたアノテーションの確認は、user_tab_commentsやuser_col_commentsのディクショナリではなく、AIエンリッチメントによって作成されるビュー METADATA_ANNOTATIONS_GROUPS、METADATA_ANNOTATIONS_GROUP_MEM、METADATA_ANNOTATIONS_USAGE で行います。
事前作業
- 次のソフトウェア
Visual Studio Code、バージョン1.101.0以上
Oracle SQL Developer for VS Code、バージョン25.3.0以上 - Oracle Databaseへの接続情報
- 次のデータベース権限
CREATE VIEW
CREATE TABLE
CREATE SEQUENCE
CREATE PROCEDURE - 表領域に対する割当て制限
AIエンリッチメントの有効化
接続の作成
Oracle SQL Developer for VS Codeで接続を作成します（詳細は省略）
エンリッチメント・メタデータを格納するために必要なオブジェクトを作成
- Oracle SQL Developer for VS Codeで、「接続」パネルを展開
- データベース接続ツリーを展開し、「AIエンリッチメント」フォルダをクリック
- 表示されたダイアログ・ボックスで、「はい」をクリックしてAIエンリッチメント・オブジェクトの作成を確認
この作業で接続しているユーザ/スキーマでAIエンリッチメント機能が使用可能になります。
AIエンリッチメント・ダッシュボードの理解
AIエンリッチメント・ダッシュボードは、スキーマ・エンリッチメント・アクティビティを管理するための中心的なハブです。
ダッシュボードを開く
「AIエンリッチメント」ノードを右クリックし、「AIエンリッチメント・ダッシュボード」を選択し、ダッシュボードを開きます。
ダッシュボード構成
- About this schema（このスキーマについて）
スキーマの高度な説明を入力 - Table groups（表グループ）
関連する表を論理的にグループ化し、スキーマ内の既存のグループを表示 - Database Enrichment Percentage（データベース・エンリッチメント率）
スキーマで注釈付けまたはエンリッチされたオブジェクト(表や列など)の割合が表示
このデータは、進捗の追跡と、特定のスキーマ内での広範囲なエンリッチメントの適用状況の測定に役立つ - Suggestions detected（検出された提案）
最も必要とされるエンリッチメントを追加するためのインテリジェントな提案を提供
データベース・スキーマのエンリッチ
スキーマのビジネス・コンテキストの定義
スキーマに概要レベルの説明の追加
-
ユーザやLLMがスキーマのビジネス・コンテキスト、目的、キー・エンティティをすぐに理解するのに役立つ情報を入力
-
「About this schema（このスキーマについて）」セクションに明確で簡潔な説明を追加
たとえば、人事(HR)スキーマの場合、次のように説明を入力 ： 「このスキーマは、従業員、部門、ロールなどのコアHRデータを管理」
表グループの操作
表グループは、関連する表の論理的な集合です。
表をグループ化することで、LLMに対して、特定のビジネス・ドメインに属する表など、外部キーによって明示的に定義されていない関係を提供します。
表グループの作成
新しい表グループを作成ステップ
-
「AIエンリッチメント」ダッシュボードで、「Table groups(表グループ)」 セクション内の「Add Group (グループの追加)」をクリック
「表グループの作成」パネルが開きます。 -
グループの名前と説明(Description)を入力
-
このグループに含めるテーブルを選択
-
「Apply(適用)」をクリック
表への説明(Description)の追加
AIエンリッチメント・ダッシュボードで、「表グループ」を選択し、定義されている表に欠落している説明(Description)を入力
Descriptionセルをクリックすることで入力が可能です。
列への説明(Description)の追加
AIエンリッチメント・ダッシュボードの「表グループ」を選択し、定義されている表を選択。結果の「表」ビューで、「列」セクションをレビューして、欠落している説明(Description)を入力
Descriptionセルをクリックすることで入力が可能です。
列へのアノテーションの追加
AIエンリッチメント・ダッシュボードの「表グループ」を選択し、定義されている表を選択。結果の「表」ビューで、「列」セクションで、ターゲット列の「...」をクリック
「Manage Annotations(アノテーションの管理)」パネルが開きます。
アノテーションを定義するには、「New annotaion」および「Annotation Value」フィールドにそれぞれキーと値のペアを入力
「Add(追加)」をクリックし、「Apply(適用)」をクリック
「表」ビューで「Enrichment Complete(エンリッチメント完了)」チェック・ボックスを選択することで、AIエンリッチメント・ダッシュボードに表示される全体的なデータベース・エンリッチメント率の表が含まれます。
そのほかの作業
以下の作業が可能です。
- 表グループへのアノテーションの追加
- グループへの既存の表の追加
- 複数のグループへの表の割当て
- 表へのアノテーションの追加
AIエンリッチメント関連VIEW
Oracle SQL Developer Extension for VSCode バージョン25.3.2では、エンリッチメント・メタデータは以下の４つのVIEWで確認が可能です。
- METADATA_ANNOTATIONS_GROUPS (表グループ)
| 列名 | 補足 |
|---|---|
| GROUP_NAME | 表グループ名 |
| CREATION_TIME | 表グループ作成日時 |
- METADATA_ANNOTATIONS_GROUP_MEM (表グループ内の表リスト)
| 列名 | 補足 |
|---|---|
| GROUP_NAME | 表グループ名 |
| ANNOTATION_TYPE | アノテーションタイプ(表、表列、スキーマ） |
| USER_NAME | スキーマ名(Owner) |
| OBJECT_NAME | オブジェクト名 |
| OBJECT_TYPE | オブジェクトタイプ |
| COLUMN_NAME | 列名 |
| PROCEDURE_NAME | プロシージャ名 |
| FUNCTION_NAME | ファンクション名 |
- METADATA_ANNOTATIONS_USAGE (定義したアノテーションのリスト、値)
| 列名 | 補足 |
|---|---|
| ANNOTATION_TYPE | アノテーションタイプ(表、表列、スキーマ） |
| USER_NAME | スキーマ名(Owner) |
| OBJECT_NAME | オブジェクト名 |
| OBJECT_TYPE | オブジェクトタイプ |
| COLUMN_NAME | 列名 |
| PROCEDURE_NAME | プロシージャ名 |
| FUNCTION_NAME | ファンクション名 |
| GROUP_NAME | |
| ANNOTATION_NAME | アノテーション名 |
| ANNOTATION_VALUE | アノテーション値 |
- METADATA_PREBUILT_ANNOTATIONS (事前定義のアノテーション)
| ANNOTATION_NAME | DESCRIPTION | CATEGORY |
|---|---|---|
| AI_SECURITY_PII | Personally Identifiable Information | SECURITY |
| AI_SECURITY_SENSITIVE | Sensitive personal information | SECURITY |
| AI_SECURITY_LEVEL | Access level | SECURITY |
| AI_ANALYTICS_DIMENSION | Dimension | ANALYTICS |
| AI_ANALYTICS_AGG | Aggregation | ANALYTICS |
| AI_RELATIONSHIP_FOREIGN_KEY | Foreign Key | RELATIONSHIP |
| AI_RELATIONSHIP_PRIMARY_KEY | Primary Key | RELATIONSHIP |
| AI_RELATIONSHIP_JOIN | Join column | RELATIONSHIP |
補足：アノテーションのベスト・プラクティス
明確な言語を使う
各データベース・オブジェクトのビジネス上の意味を正確に表すために、すべてのアノテーションをドメイン固有の明確な英語で記述
効果的なDESCRIPTION(説明)を書く
DESCRIPTIONラベルを使用してアノテーションを作成し、表や列などのデータベース・オブジェクトの目的を明確にする
データベース・オブジェクトの別名のリスト
ALIASESラベルを使用して、データベース・オブジェクトの共通シノニムまたは代替名を指定
EMP_IDという列は、従業員番号、個人番号または就業者IDと呼ばれます。
- 次のようにアノテーションを定義します。
Common aliases for this column include employee number, worker id, and person number.
数値データの測定単位の指定
数値データを含む列の場合は、LLMによる値の誤解釈が防止する目的でUNITSアノテーションを使用して測定単位を指定
- salary_amount列に「Expressed in United States Dollars (USD)」というアノテーションを付けることで、LLMモデルで通貨タイプが正しく識別される
- 距離列の場合、「Units: kilometers」というアノテーションを付けて、LLMモデルが正確な変換または集計を実行するようにする
結合ロジックの定義
表を結合する場合は、JOIN COLUMNラベルを使用して、列の優先結合パートナを指定
LLMによる自動SQL生成では、結合ロジックに苦労することが多いため、この注釈はモデルを正しい結合へと導く
- EMPLOYEE.DEPT_NO列に次のアノテーションを定義します。
This column is most commonly joined with DEPARTMENT.DEPT_NO and represents the employee's home department.
サンプル値の列挙
VALUESラベルを使用して、LLMに列の例または個別値を指定
LLMモデルが、フィルタリング機能を直接改善するのに役立ちます。
- status_code列に次のアノテーションを定義します。
Typical values for status_code include A (active), I (inactive), and T (terminated).
グループ関連表
アプリケーション・ドメインと連携するグループに表を編成し、グループにアノテーションを付けます。
表をグループ化することで、LLMが外部キーによって明示的に定義されていない関係を理解するのに役立ちます。
- 人事管理(HR)に関連するすべての表をHR_TableGrpという名前のグループに編成し、次のようにアノテーションを定義します。
This group contains all tables related to Human Resources (HR).
おわりに
Oracle SQL Developer for VS CodeのAIエンリッチメント(Enrichment)を活用することでGUI(VS Code)でデータベース・オブジェクト(スキーマ、表および列)のアノテーションの管理ができました。