[AWS]Bedrockエージェントのスキーマ設定

Amazon BedrockでAIがデータベースを理解し、自然言語からSQLを自動生成するためのスキーマ定義ファイルの作成手順を解説します。JSON形式が推奨されており、テーブル名、カラム名、データ型、主キー、外部キーなどを正確に記述することが重要です。これにより、AIエージェントやナレッジベースの精度が飛躍的に向上し、データ分析の自動化が実現します。

基本概念の理解
ステップバイステップ手順
高度な設定例
1. パーティション情報の追加（BigQuery等）
2. ビュー定義の含め方
よくあるエラーと対策
自動生成ツール活用（オプション）

基本概念の理解

目的: Amazon Bedrockの「エージェント」や「ナレッジベース」がDB構造を理解し、適切なSQL生成を可能にする
対応形式: JSONまたはYAML（JSONが推奨）
対象DB: RDS, Aurora, Redshift, DynamoDB等（リレーショナルDBが中心）
必須要素: テーブル名、カラム名、データ型、主キー、外部キー、関係性

ステップバイステップ手順

STEP 1: メタデータの収集

対象データベースに接続
以下の情報を収集:
- 全テーブル名
- 各テーブルのカラム名とデータ型（例: customer_id INT）
- 主キー（Primary Key）
- 外部キー（Foreign Key）と参照先テーブル
- NULL制約、ユニーク制約
- インデックス情報（オプション）

STEP 2: ファイル形式の選択

推奨形式: JSON（構造化データに最適）
代替形式: YAML（読みやすいがネストに注意）

STEP 3: JSONスキーマの作成例

{
  "database": "ecommerce_db",
  "description": "ECサイトのデータベース",
  "tables": [
    {
      "table_name": "customers",
      "description": "顧客基本情報",
      "columns": [
        {
          "name": "customer_id",
          "type": "INT",
          "description": "顧客を一意に識別するID",
          "is_primary_key": true
        },
        {
          "name": "name",
          "type": "VARCHAR(100)",
          "description": "顧客の氏名"
        },
        {
          "name": "email",
          "type": "VARCHAR(255)",
          "description": "メールアドレス",
          "is_unique": true
        }
      ]
    },
    {
      "table_name": "orders",
      "description": "注文情報",
      "columns": [
        {
          "name": "order_id",
          "type": "INT",
          "is_primary_key": true
        },
        {
          "name": "customer_id",
          "type": "INT",
          "description": "customersテーブルへの外部キー",
          "is_foreign_key": true,
          "references": {
            "table": "customers",
            "column": "customer_id"
          }
        },
        {
          "name": "order_date",
          "type": "DATE"
        }
      ]
    }
  ]
}

STEP 4: ベストプラクティス

記述的メタデータの追加:
- 各テーブル・カラムにdescriptionを記載（AIの理解精度が向上）
- 例: "description": "注文ステータス（0:未処理, 1:発送済み）"
関係性の明文化:

   "relationships": [
     {
       "from_table": "orders",
       "from_column": "customer_id",
       "to_table": "customers",
       "to_column": "customer_id",
       "type": "one-to-many"
     }
   ]

データ型の正確性:
- 実際のDBのデータ型と一致させる（例: VARCHAR(255), TIMESTAMPTZ）
制約の明示:
- "is_primary_key": true/false
- "is_nullable": false（NOT NULL制約）
- "default_value": "CURRENT_TIMESTAMP"

STEP 5: ファイルの検証

JSONバリデーターで構文チェック:
- JSONLint を使用
必須フィールドの確認:
- database, tables, table_name, columns, name, type

STEP 6: Bedrockへのアップロード

AWSコンソール > Amazon Bedrock にログイン
ナレッジベース を選択
「データソースの追加」をクリック
作成したJSONファイルをアップロード
ベクトル変換設定 で「メタデータフィールド」を指定:

   "vectorEmbeddingMetadata": {
     "schemaType": "DATABASE_SCHEMA"
   }

高度な設定例

パーティション情報の追加（BigQuery等）

{
  "table_name": "sales",
  "partitions": {
    "field": "sale_date",
    "type": "DATE",
    "range": "DAILY"
  }
}

ビュー定義の含め方

{
  "table_name": "active_users",
  "is_view": true,
  "view_definition": "SELECT user_id, name FROM users WHERE last_login > NOW() - INTERVAL '30 days'"
}

よくあるエラーと対策

エラー内容	原因	解決策
`Invalid schema: missing table_name`	必須フィールド欠落	全テーブルに`table_name`を追加
`Unrecognized field "is_foreign_key"`	タイポ	フィールド名を`is_foreign_key` → `isForeignKey`に統一
`Vector embedding failed`	ファイルサイズ超過	ファイルを分割または不要メタデータを削除

自動生成ツール活用（オプション）

SQL → JSON コンバーター:
- DBML to JSON などのツールでDDLから変換
Pythonスクリプト例:

   import json
   from sqlalchemy import create_engine, MetaData

   engine = create_engine('postgresql://user:pass@host/db')
   metadata = MetaData()
   metadata.reflect(engine)

   schema = {"database": "my_db", "tables": []}
   for table in metadata.tables.values():
       # テーブル情報を抽出してschemaに追加
   with open('schema.json', 'w') as f:
       json.dump(schema, f, indent=2)