Ask (Text-to-SQL)

자연어 질문을 SQL로 변환하는 Text-to-SQL API입니다. AI 오케스트레이터를 통해 스키마 컨텍스트 기반 SQL을 생성합니다.

엔드포인트

`POST /api/v1/ai/ask`

설명: 자연어 질문을 SQL로 변환합니다. SQL만 반환하고 실행하지 않습니다.

요청 본문:

필드	타입	필수	설명
question	string	Y	자연어 질문
catalog	string	N	대상 카탈로그
max_retries	int	N	SQL 생성 재시도 횟수 (기본 `2`, 0–5)
conversation_history	array	N	이전 대화 맥락 (`role`/`content` 객체 목록)

응답 (AskApiResponse):

필드	타입	설명
sql	string	생성된 SQL
source	string	생성 출처 — `generated` / `cache` / `blocked` / `error`
explanation	string	SQL 설명
tables_used	string[]	참조된 테이블
join_paths	object[]	스키마 그래프에서 사용한 조인 경로
execution_success	bool \| null	실행 성공 여부 (`/ask` 에서는 `null`, `/ask/execute` 에서 채워짐)
error	string \| null	오류 메시지 (없으면 `null`)
security_filtered	int	SqlGuard 로 필터/차단된 항목 수 (기본 `0`)
cache_hit	bool	쿼리 캐시 히트 여부

{
  "sql": "SELECT ...",
  "source": "generated",
  "explanation": "이 SQL은...",
  "tables_used": ["tpch.tiny.orders"],
  "join_paths": [],
  "execution_success": null,
  "error": null,
  "security_filtered": 0,
  "cache_hit": false
}

인증

JWT Bearer 토큰이 필요합니다.

참고

스키마 그래프 인덱스가 구축되어 있으면 더 정확한 SQL을 생성합니다.
AI 제공자 설정은 서버 환경변수로 구성됩니다.

에러 코드

코드	설명
400	질문이 비어있거나 잘못된 요청
429	워크스페이스 AI 쿼터 초과 — `Retry-After: 3600` 헤더 포함
500	AI 제공자 호출 실패

엔드포인트​

POST /api/v1/ai/ask​

인증​

참고​

에러 코드​

엔드포인트

`POST /api/v1/ai/ask`

인증

참고

에러 코드