용어 사전
용어 사전은 조직 내에서 사용하는 데이터 관련 용어의 정의와 동의어를 관리합니다. Text-to-SQL 변환 시 질문과 의미가 가까운 용어를 골라 그 정의를 프롬프트에 함께 넣어, 조직 고유 약어를 LLM 이 이해하도록 돕습니다.
주요 기능
- 용어 CRUD: 비즈니스 용어를 생성, 조회, 수정, 삭제합니다 (쓰기는 analyst 이상)
- 동의어 관리: 각 용어에 동의어 목록을 등록합니다. 동의어는 임베딩 텍스트에 포함되어 시맨틱 매칭에 반영됩니다 — 다만 목록 화면의 검색창은 용어명·정의만 매칭합니다
- 벡터 임베딩: 용어명·정의·동의어를 한 문장으로 합쳐 벡터로 변환합니다. Text-to-SQL 이 코사인 유사도로 상위 5건을 선택합니다
- 테이블 매핑: 용어와 실제 테이블/컬럼 간의 매핑(
maps_to)을 그래프 엣지로 저장합니다 (API 전용)
용어 구성 항목
| 항목 | 필수 | 설명 |
|---|---|---|
| term | O | 용어명 (예: 매출액) |
| definition | O | 용어 정의 |
| synonyms | X | 동의어 배열 (예: ["매출", "revenue", "sales"]) |
| maps_to | X | 테이블/컬럼 매핑 객체 — {table, column, aggregation}. table 은 catalog.schema.table 3파트 형식이어야 하며 아니면 400 |
maps_to 는 UI 폼에 입력란이 없습니다. API 로만 등록할 수 있고, 현재 Text-to-SQL 프롬프트에는 반영되지 않습니다.
사용 방법
- 사이드바 지식 & 시맨틱 > 용어 사전 (
/ai/glossary) 으로 이동합니다 - 우측 상단 용어 추가 버튼을 클릭합니다 (analyst 이상만 활성화)
- 용어명, 정의, 동의어(쉼표 구분)를 입력하고 저장합니다
- 저장 시 벡터 임베딩이 자동으로 생성됩니다
- 이후 Text-to-SQL 이 질문과 유사한 용어의 정의를 프롬프트에 주입합니다
:::note 용어명은 나중에 바꿀 수 없습니다
수정 화면에서 정의와 동의어는 고칠 수 있지만 용어명 입력란은 잠겨 있습니다. 이름을 바꾸려면 삭제 후 다시 등록하세요 (PUT 으로 다른 이름을 보내면 400).
:::
권한
| 동작 | 필요 역할 |
|---|---|
| 목록·상세 조회 | viewer 이상 |
| 생성·수정·삭제 | analyst 이상 — 부족하면 403 |
API 엔드포인트
| Method | Path | Description |
|---|---|---|
| POST | /api/v1/ai/glossary | 용어 생성 (analyst, 중복 시 409) |
| GET | /api/v1/ai/glossary | 용어 목록 조회 → {items, total} |
| GET | /api/v1/ai/glossary/{term} | 용어 상세 조회 (maps_to 포함) |
| PUT | /api/v1/ai/glossary/{term} | 용어 수정 (analyst, 이름 변경 불가) |
| DELETE | /api/v1/ai/glossary/{term} | 용어 삭제 (analyst) |