시맨틱 레이어
시맨틱 레이어(Semantic Layer)에서 테이블·값 사전·질의 템플릿을 연결해 자연어 질문을 데이터 질의로 변환하는 데 필요한 정보를 정의합니다. 에이전트는 이 정보를 바탕으로 질문에 맞는 테이블과 값을 선택합니다.
시맨틱 레이어 자산은 사이드바 AI 섹션의 시맨틱 레이어 하위 메뉴에서 관리합니다.
- 시맨틱 테이블 — 자연어 질문에서 참조할 컬럼·메트릭·필터를 정의합니다.
- 값 사전 — 같은 대상을 가리키는 여러 표기를 하나의 정규값으로 연결합니다.
- 질의 템플릿 — 자주 쓰는 질문에 적용할 질의를 저장합니다.
세 자산은 모두 컬렉션 단위로 관리합니다. 만들 때 컬렉션을 지정하고 같은 컬렉션 안에서 서로 연결하거나 에이전트에 등록합니다.
시맨틱 테이블·값 사전·질의 템플릿 목록에서 여러 행을 선택하면 삭제를 순차 실행합니다. 검색·컬렉션 범위를 바꾸면 선택이 해제되며 일부 실패 시 성공·실패 수를 확인합니다. 공통 선택 규칙은 첫 화면의 관리 목록 공통 동작에서 확인합니다.
시맨틱 테이블
테이블에는 자연어 질문에서 참조할 컬럼·메트릭·필터를 정의합니다. 물리 데이터를 복사하지 않고 질문과 테이블을 연결하는 라우팅 설명을 등록합니다.
- 만들기: 목록 화면에서 시맨틱 테이블 만들기로 들어갑니다. 컬렉션과 데이터 연결을 선택하고 라우팅 설명을 하나 이상 입력합니다.
- 정의 항목: 편집 화면에서 라우팅·작성 지침, 관련 테이블, 컬럼, 메트릭과 필터를 정의합니다.
- 사용 범위: 에이전트에 등록한 시맨틱 테이블이 해당 에이전트의 텍스트-투-SQL 질의 범위가 됩니다.
백엔드와 데이터 연결, 컬럼 속성·값 사전·메트릭 설정은 시맨틱 테이블 만들기에서 확인합니다.
값 사전
값 사전은 컬럼 값의 여러 표기(동의어)를 하나의 정규값으로 연결합니다. 예를 들어 서울시, 서울특별시, Seoul을 같은 정규값에 연결하면 질문에 포함된 표기를 정규값으로 변환합니다. 같은 컬렉션의 여러 시맨틱 테이블이 하나의 값 사전을 함께 참조합니다.
기존 사전은 100개씩 페이지로 나뉩니다. 현재 페이지를 저장한 뒤 검색하거나 페이지를 이동합니다. 원시 값 가져오기, 값 링킹 미리보기와 병합·교체 정책은 값 사전 편집하기에서 확인합니다.
질의 템플릿
질의 템플릿에는 질문 예시와 슬롯, 하나 이상의 서브 쿼리와 결과 계산 코드를 정의합니다. 비슷한 질문이 들어오면 저장된 질의를 다시 사용합니다. 같은 컬렉션의 시맨틱 테이블만 연결하며 저장할 때 쿼리와 run(frames) 코드를 검증합니다. 질의 템플릿 만들기에서 슬롯과 복수 쿼리 작성 절차를 확인합니다.
가져오기와 내보내기
세 시맨틱 자산의 목록에서 정의 JSON을 가져오거나 내보냅니다. 값 사전의 CSV·TSV 원시 값 가져오기와 자산 정의 전체 가져오기는 다른 작업입니다. 파일 제한과 참조 연결 순서는 AI 자산 가져오기·내보내기에서 확인합니다.
에이전트에 등록
시맨틱 테이블과 질의 템플릿을 자연어 질의에 사용하려면 에이전트 빌더에서 해당 자산을 등록합니다.
- AI 에이전트 모드: 빌더의 역량(구성) 영역에서, 에이전트 컬렉션에 속한 시맨틱 테이블과 질의 템플릿을 골라 등록합니다.
- 워크플로우 모드: 에이전트 설정에서 같은 방식으로 등록합니다.
등록한 시맨틱 테이블이 해당 에이전트의 자연어 질의 범위가 됩니다. 하나의 시맨틱 테이블을 여러 에이전트에 각각 등록할 수 있습니다.
