질의 템플릿
AI → 시맨틱 레이어 → 질의 템플릿에서 반복되는 질문의 슬롯과 검증된 서브 쿼리를 저장합니다. 하나의 자산 안에 여러 템플릿 항목을 둘 수 있습니다.
자산과 템플릿 항목
- 이름·별칭·컬렉션·설명·태그를 입력합니다. 컬렉션은 필수입니다.
- 템플릿 항목 추가를 누릅니다.
- 항목마다 고유한 이름, 설명과 하나 이상의 질문 예시를 입력합니다.
- 슬롯, 하나 이상의 서브 쿼리와 계산 코드를 구성합니다.
항목 배열은 구조화 / JSON 모드로 편집합니다. 모드를 바꾸면 현재 값을 변환하며 잘못된 JSON은 저장하지 않습니다.
슬롯 정의
슬롯은 질문에서 추출해 쿼리의 {{slot}} 자리에 넣습니다.
| 종류 | 용도 |
|---|---|
| 문자 | 일반 문자열 |
| 숫자 | 정수 또는 실수 |
| 값 | 값 사전 링킹에 사용할 표면형 |
| 리스트 | 여러 값을 받아 값마다 서브 쿼리 프레임 생성 |
각 슬롯에는 이름·설명·필수 여부·기본값을 설정합니다. 리스트 기본값은 JSON 배열이어야 합니다.
서브 쿼리 구성
각 서브 쿼리는 항목 안에서 고유한 이름, 같은 컬렉션의 대상 시맨틱 테이블, 도구와 쿼리 JSON을 가집니다.
- 메트릭: 하나 이상의 메트릭을 선택합니다.
- 행 조회: 소스 테이블과 하나 이상의 출력 컬럼을 선택합니다.
리스트 슬롯은 한 서브 쿼리에서 최대 하나만 사용할 수 있으며 = 조건의 단일 값 위치에서 참조합니다. 리스트가 확장되면 프레임 이름은 {서브쿼리이름}__{원소} 형식이 됩니다.
결과 계산
서브 쿼리 결과는 이름을 키로 한 DataFrame 묶음으로 run(frames)에 전달됩니다. 계산 코드는 최상위 Python 함수 run(frames)를 정의하고 최종 결과를 반환해야 합니다. 서브 쿼리가 하나면 선택한 프레임을 그대로 반환하는 기본 코드가 채워집니다.
시맨틱 테이블 참조
오른쪽 시맨틱 테이블 참조에서 선택한 테이블의 ID·컬럼·메트릭·필터를 확인하고 ID를 복사합니다. 다른 컬렉션의 테이블은 연결하지 않습니다.
저장 오류 확인
저장할 때 다음 항목을 검사합니다.
- 질문 예시와 슬롯 이름 중복
- 선언되지 않은
{{slot}} - 시맨틱 테이블 존재와 조회 권한
- 쿼리 JSON과 도구별 필수 메트릭·컬럼
- 필터·정렬·누적 메트릭 규칙
- 최상위
run(frames)함수 구조
오류가 있으면 해당 템플릿 항목이나 서브 쿼리로 이동해 수정합니다. 서버도 렌더링한 쿼리를 시험 컴파일하고 계산 코드를 검증합니다.