Semantic metadata는 Database Management 항목에 속합니다. 물리 데이터베이스 schema를 변경하지 않고 schema discovery가 물리 구조를 설명하는 방식을 보강합니다.
Entity metadata
Entity record는 테이블 전체 또는 테이블 내부의 특정 컬럼 하나를 대상으로 할 수 있습니다.
| 필드 | 의미 |
|---|---|
DbManagementId | semantic record를 소유하는 Database Management 항목 |
SchemaName | 선택적 schema |
TableName | 필수 물리 테이블 이름 |
ColumnName | 선택 사항. 생략하면 테이블 수준 metadata |
DisplayName | 사람이 읽기 쉬운 이름 |
Description | 비즈니스 또는 운영 설명 |
Synonyms | 해당 테이블/컬럼을 표현하는 대체 용어 |
Synonym은 빈 값을 제거하고 대소문자를 무시해 중복을 제거하며 record당 최대 100개를 유지하도록 정규화됩니다.
관계
Relationship metadata는 두 물리 컬럼의 관계를 설명합니다.
| 필드 | 의미 |
|---|---|
Name | 안정적인 관계 이름 |
SourceSchema / SourceTable / SourceColumn | source 측 |
TargetSchema / TargetTable / TargetColumn | target 측 |
Cardinality | 기본값 many-to-one |
Direction | 기본값 source-to-target |
Description | 선택적 운영/비즈니스 설명 |
Schema discovery는 관계에 참여하는 두 테이블이 모두 인증된 MCP 키의 table whitelist에서 허용될 때만 관계 설명을 노출합니다.
지표
Metric metadata는 테이블 범위의 비즈니스 measure를 설명할 수 있습니다.
| 필드 | 의미 |
|---|---|
Name | 안정적인 metric identifier |
DisplayName | 사람이 읽기 쉬운 이름 |
Description | 비즈니스 설명 |
Formula | formula metadata |
Aggregation | 기본값 custom; 의도된 aggregation 설명 |
Grain | 선택적 grain metadata |
Filter | 선택적 filter metadata |
Synonyms | metric의 대체 용어 |
Executable | 2.0.2 모델에서는 false |
MCP schema discovery에서의 활용
공식 MCP schema tool은 계속 get_schemas, get_tables, get_columns입니다.
키에 바인딩된 Database Management 항목에 semantic metadata가 있으면 다음처럼 보강됩니다.
get_tables는 table display name, description, synonym, 해당 테이블의 metric description을 추가할 수 있습니다.get_columns는 column display name, description, synonym, 관련 relationship description을 추가할 수 있습니다.- table whitelist 규칙은 여전히 물리 테이블 가시성과 relationship context를 필터링합니다.
즉 semantic metadata는 탐색을 풍부하게 할 뿐 키가 접근할 수 있는 범위를 넓히지 않습니다.
Admin API 표면
2.0.2 Admin API는 api/DbSemantic 아래에서 semantic management를 제공합니다.
| 작업 | 권한 |
|---|---|
| 데이터베이스의 entity record 조회 | /runtime/db-management/semantic → view |
| 통합 entity/relationship/metric model 조회 | /runtime/db-management/semantic → view |
| entity metadata upsert | /runtime/db-management/semantic → edit |
| entity metadata 삭제 | /runtime/db-management/semantic → edit |
| relationship upsert/delete | /runtime/db-management/semantic → edit |
| metric upsert/delete | /runtime/db-management/semantic → edit |
모델링 지침
여러 에이전트와 운영자에게 지속적으로 도움이 될 만큼 안정적인 용어를 semantic metadata로 관리하십시오.
- 실제 table/column 이름과 다른 비즈니스 이름
- 약어 및 도메인 동의어
- Query 생성에 중요한 관계
- 공식과 grain을 명확히 하는 metric 정의
Credential, 런타임 지시문, authorization 결정을 schema description에 숨겨 넣는 용도로 사용하면 안 됩니다. Access control은 별도의 강제 계층으로 유지됩니다.