セマンティックメタデータ

エンティティ テーブルとカラムに表示名、説明、同義語を設定します。

リレーション カーディナリティと方向を持つ、名前付きの source-to-target カラム関係を定義します。

メトリクス formula、aggregation、grain、filter、synonym を持つ、スコープ付きメトリクスメタデータを定義します。

セマンティックメタデータは Database Management エントリに属します。物理スキーマ自体を変更せずに、スキーマ探索で物理データベースをどのように説明するかを補強します。

エンティティメタデータ

エンティティレコードは、テーブル全体またはテーブル内の 1 カラムを対象にできます。

フィールド	意味
`DbManagementId`	セマンティックレコードを所有する Database Management エントリ
`SchemaName`	任意のスキーマ
`TableName`	必須の物理テーブル名
`ColumnName`	任意。テーブル単位のメタデータでは省略
`DisplayName`	人が理解しやすい名前
`Description`	業務／運用上の説明
`Synonyms`	テーブル／カラムを表す別名

同義語は、空の値を除去し、大文字小文字を区別せずに重複を排除したうえで、1 レコードにつき最大 100 件まで保持します。

リレーションメタデータは、2 つの物理カラムがどのように関連するかを表します。

フィールド	意味
`Name`	安定したリレーション名
`SourceSchema` / `SourceTable` / `SourceColumn`	source 側
`TargetSchema` / `TargetTable` / `TargetColumn`	target 側
`Cardinality`	既定値は `many-to-one`
`Direction`	既定値は `source-to-target`
`Description`	任意の運用／業務上の説明

スキーマ探索でリレーションの説明が表示されるのは、関係する両方のテーブルが認証済み MCP キーのテーブルホワイトリストで許可されている場合だけです。

メトリクスメタデータはテーブル単位でスコープされ、業務指標を記述できます。

正式な MCP スキーマツールは引き続き get_schemas、get_tables、get_columns です。

キーに紐付いた Database Management エントリへセマンティックメタデータが登録されている場合、次の情報を補足できます。

つまりセマンティックメタデータは探索情報を豊かにしますが、キーがアクセスできる範囲を広げるものではありません。

2.0.2 の Admin API は api/DbSemantic 配下でセマンティック管理機能を公開します。

操作	権限
データベースのエンティティレコードを取得	`/runtime/db-management/semantic` → `view`
エンティティ／リレーション／メトリクスを統合したモデルを取得	`/runtime/db-management/semantic` → `view`
エンティティメタデータを upsert	`/runtime/db-management/semantic` → `edit`
エンティティメタデータを削除	`/runtime/db-management/semantic` → `edit`
リレーションを upsert／削除	`/runtime/db-management/semantic` → `edit`
メトリクスを upsert／削除	`/runtime/db-management/semantic` → `edit`

複数のエージェントや運用者が継続的に利用できる、十分に安定した用語をセマンティックメタデータとして登録してください。

認証情報、ランタイムへの指示、認可判断をスキーマ説明へ埋め込む用途には使わないでください。アクセス制御は別の強制レイヤーとして維持されます。