語意中繼資料會綁定到 Database Management 項目。它用來豐富 schema discovery 對實體資料庫的描述，但不會修改真正的資料庫 schema。
實體中繼資料
一筆實體紀錄可以描述整張資料表，也可以描述資料表中的單一欄位。
| 欄位 | 意義 |
|---|---|
DbManagementId | 擁有這筆語意紀錄的 Database Management 項目 |
SchemaName | 選用的 schema |
TableName | 必填的實體資料表名稱 |
ColumnName | 選用；未填時代表資料表層級的中繼資料 |
DisplayName | 易讀的顯示名稱 |
Description | 業務或維運說明 |
Synonyms | 描述該資料表或欄位的替代名稱 |
Synonyms 會去除前後空白，並以不分大小寫的方式去重；單筆紀錄最多保留 100 個值。
關聯
關聯中繼資料描述兩個實體欄位之間的關係。
| 欄位 | 意義 |
|---|---|
Name | 穩定的關聯名稱 |
SourceSchema / SourceTable / SourceColumn | 來源端 |
TargetSchema / TargetTable / TargetColumn | 目標端 |
Cardinality | 預設 many-to-one |
Direction | 預設 source-to-target |
Description | 選用的管理或業務說明 |
只有在已驗證 MCP 金鑰的資料表白名單同時允許關聯兩端的資料表時，schema discovery 才會把這項關聯說明提供給用戶端。
指標
指標中繼資料綁定到資料表，可用來描述業務指標：
| 欄位 | 意義 |
|---|---|
Name | 穩定的指標識別名稱 |
DisplayName | 易讀的顯示名稱 |
Description | 業務說明 |
Formula | 公式中繼資料 |
Aggregation | 預設 custom；描述預期的彙總方式 |
Grain | 選用的粒度資訊 |
Filter | 選用的篩選條件 |
Synonyms | 指標的替代名稱 |
Executable | hs-sql-agent 模型固定為 false |
MCP schema discovery 如何使用語意資料
正式的 MCP schema 工具仍是 get_schemas、get_tables、get_columns。
當金鑰綁定的 Database Management 項目具有語意中繼資料時：
get_tables可以附加資料表顯示名稱、說明、同義詞與該資料表範圍內的指標說明；get_columns可以附加欄位顯示名稱、說明、同義詞與關聯說明；- 資料表白名單仍會限制實體資料表的可見範圍與可提供的關聯資訊。
因此，語意中繼資料只會豐富探索結果，不會擴大 MCP 金鑰原本可存取的資料範圍。
管理端 API
hs-sql-agent Admin API 在 api/DbSemantic 提供語意資料管理：
| 操作 | 權限 |
|---|---|
| 讀取資料庫實體紀錄 | /runtime/db-management/semantic → view |
| 讀取實體 / 關聯 / 指標的整合模型 | /runtime/db-management/semantic → view |
| upsert 實體中繼資料 | /runtime/db-management/semantic → edit |
| delete 實體中繼資料 | /runtime/db-management/semantic → edit |
| upsert / delete 關聯 | /runtime/db-management/semantic → edit |
| upsert / delete 指標 | /runtime/db-management/semantic → edit |
建模建議
適合放進語意中繼資料的內容，應該是夠穩定、能同時幫助多個 Agent 與管理者理解資料的領域知識：
- 和實體資料表或欄位名稱不同的業務名稱；
- 縮寫與領域同義詞；
- 對查詢產生很重要的資料關聯；
- 能說清楚公式與粒度的指標定義。
不要把憑證、執行階段指令或授權決策塞進 schema 說明。存取控制仍是獨立、且由伺服器強制執行的安全層。