0sql: 시맨틱-투-SQL 엔진이 에이전트 기반 쿼리에 결정론과 보안을 추가하는 방법

자연어에서 SQL 생성 시 발생하는 문제 해결: 0sql의 역할

에이전트가 자연어로부터 SQL을 생성할 때, 비결정적인(non-deterministic) 쿼리 구성과 데이터베이스 직접 노출이라는 두 가지 문제가 발생합니다. 0sql은 에이전트와 웨어하우스 사이에 위치하는 시맨틱 레이어(semantic layer) 역할을 하며, 비즈니스 용어 명세(business-term specifications)를 통제된(governed) SQL 구문으로 번역합니다.

핵심 원리는 간단합니다. Claude나 Copilot에게 원시 SQL을 작성하도록 맡기는 대신, 에이전트는 {projections: [{field: "Web Net Paid"}]}와 같은 명세(spec)를 가지고 plan_query 엔드포인트를 호출합니다. 그러면 엔진은 통제된 모델에 대해 계획된 단일 SQL 문을 반환합니다. 동일한 명세는 매번 동일한 구문을 보장합니다.

순수 시맨틱-투-SQL이 의미하는 것

0sql은 자연어를 직접 파싱하지 않습니다. 대신, 필드(field), 필터(filter), 집계(aggregation)를 그들의 시맨틱 이름으로 참조하는 JSON 명세라는 구조화된 입력을 기대합니다. 에이전트의 역할은 사용자 의도를 이 명세에 매핑하는 것입니다. 엔진의 역할은 그 명세를 SQL로 컴파일하는 것입니다.

작업 흐름:

1. 에이전트가 사용자 쿼리를 받습니다: "지난 30일간 EMEA 수익을 보여줘"
2. 에이전트는 일치하는 측정값(measures)과 차원(dimensions)을 찾기 위해 search_fields 도구를 호출합니다.
3. 에이전트가 명세를 구성합니다: {projections: [{field: "Profit"}], filters: [{field: "Region", operator: "=", value: "EMEA"}, {field: "Date", operator: ">=", value: "30d"}]}
4. 에이전트는 이 명세와 함께 plan_query를 호출합니다.
5. 엔진은 시맨틱 모델을 기반으로 계획된 SQL을 반환합니다.

시맨틱 모델은 측정값(집계), 차원(그룹화 키), 그리고 조인(joins)을 정의합니다. 엔진은 이 명세를 해당 정의를 준수하는 SQL 문으로 번역합니다. 만약 모델이 "Profit"이 sum(sales.profit)이며 region.name과 조인된다고 정의한다면, 엔진은 적절한 SELECT, JOIN, 그리고 WHERE 절을 생성합니다.

보안 경계 (Security Boundaries)

보안 모델은 세 가지 계층으로 구성되어 있습니다:

모델 레벨 거버넌스(Model-level governance): 시맨틱 모델은 어떤 필드가 존재하며 어떻게 집계되는지를 정의합니다. 만약 필드가 모델에 포함되어 있지 않다면, 에이전트는 해당 필드를 쿼리할 수 없습니다. 이는 에이전트가 원시 컬럼(raw columns)에 접근하거나 임의의 조인을 구성하는 것을 방지합니다.

매개변수화된 출력 (Parameterized output): 엔진은 사용자 제공 값에 대한 플레이스홀더가 포함된 SQL을 반환합니다. 에이전트는 절대로 문자열을 SQL에 보간(interpolate)하지 않습니다. 이는 쿼리 구성 계층에서 주입(injection) 위험을 제거합니다.

행 수준 보안 (Row-level security): 모델은 행 수준 필터(row-level filters)를 인코딩할 수 있습니다. 만약 사용자가 자신의 지역 데이터만 볼 수 있어야 한다면, 모델은 모든 쿼리에 해당 제약 조건을 포함시킵니다. 에이전트는 이러한 규칙에 대해 알 필요가 없습니다.

결정론 및 캐싱 (Determinism and Caching)

엔진은 동일한 명세(spec)가 동일한 SQL을 생성함을 보장합니다. 이는 세 가지 이유로 중요합니다:

디버깅 (Debugging): 에이전트가 잘못된 쿼리를 생성하더라도, 명세를 재실행하여 이를 재현할 수 있습니다. LLM 대화 전체를 다시 재생(replay)할 필요가 없습니다.

캐싱 (Caching): 명세 해시(spec hash)로 SQL 구문을 캐싱할 수 있습니다. 에이전트가 같은 질문을 두 번 요청하더라도, 계획(planning) 단계를 건너뛰고 캐시된 구문을 반환합니다.

감사 추적 (Auditing): SQL 대신 명세(specs)를 기록으로 남길 수 있습니다. 명세는 더 작고, 가독성이 높으며, 스키마 세부 정보를 유출하지 않습니다.

계획 시간은 빠릅니다. 예시에서는 3개 필드 쿼리에 대해 70 마이크로초가 소요됩니다. 이는 에이전트 루프의 핵심 경로(hot path)에 배치하기에 충분히 빠른 속도입니다.

CLI 통합 패턴 (CLI Integration Pattern)

0sql은 HTTP API를 감싸는 CLI(zsql)와 함께 제공됩니다. 이는 셸 명령을 실행할 수 있는 코딩 에이전트를 위해 설계되었습니다.

zsql sql --expr "web net paid, web sold date, net paid"

CLI는 SQL을 표준 출력(stdout)으로 반환합니다. 에이전트는 이를 쿼리 실행기(query executor)로 파이프하거나 검토를 위해 기록할 수 있습니다.

함수 호출(function calling)을 사용하는 에이전트(OpenAI, Anthropic)의 경우, HTTP API를 도구(tool)로 노출합니다. 에이전트는 사용 가능한 필드를 검색하기 위해 search_fields를 호출하고, SQL을 생성하기 위해 plan_query를 호출합니다.

{
  "name": "plan_query",
  "description": "Generate SQL from a business-term specification"
...
}

에이전트는 명세를 구성하고, 도구를 호출하며, SQL을 받습니다. 에이전트가 직접 SQL을 작성하는 경우는 없습니다.

Cube 및 MetricFlow와의 비교 (Comparison to Cube and MetricFlow)

0sql은 BI 툴(BI tools)을 위한 시맨틱 레이어(semantic layers)를 정의하는 Cube와 MetricFlow와 경쟁합니다. 주요 차이점들은 다음과 같습니다:

아키텍처 구조 (Architecture Shape)

이 엔진은 상태가 없습니다(stateless). Git 브랜치에서 시맨틱 모델을 읽고(0sql 클라우드에 저장됨), 요청 시 쿼리를 계획합니다. CLI를 자체 모델 리포지토리를 가리키도록 설정하여 셀프 호스팅할 수 있습니다.

┌─────────────────┐
│  Agent (Claude) │
└────────┬────────┘
...

시맨틱 모델은 다음을 정의합니다:

• 측정값 (Measures): sum(profit), count(orders)와 같은 집계 함수
• 차원 (Dimensions): region.name, date와 같은 그룹화 키
• 조인 (Joins): 테이블 연결 방식
• 필터 (Filters): 행 수준 보안 규칙

엔진은 이를 SQL로 컴파일합니다. 쿼리를 실행하지는 않습니다. 에이전트가 데이터 웨어하우스(warehouse)에 대해 SQL을 실행할 책임이 있습니다.

실패 모드 (Failure Modes)

모델 드리프트 (Model drift): 시맨틱 모델이 데이터 웨어하우스 스키마와 동기화되지 않으면, 엔진은 유효하지 않은 SQL을 생성합니다. 모델을 데이터 웨어하우스와 검증하는 CI 파이프라인이 필요합니다.

모호한 필드 이름 (Ambiguous field names): 모델이 유사한 이름을 가진 두 개의 필드(

OpenAI 함수 호출 에이전트에서 0sql을 도구로 노출하는 방법은 다음과 같습니다:

import openai
import requests

...

에이전트는 사용자 의도로부터 사양(spec)을 구성하고, 해당 도구를 호출한 다음, SQL을 받습니다. 에이전트가 직접 SQL을 작성하는 경우는 없습니다.

기술 검토 (Technical Verdict)

0sql을 사용해야 하는 경우:

• 에이전트 기반 분석(agent-driven analytics)을 구축하고 SQL 인젝션을 방지해야 할 때
• 캐싱 및 디버깅을 위해 결정론적 쿼리 생성이 필요할 때
• 시맨틱 레이어에서 행 수준 보안(row-level security)이 적용되어야 할 때
• HTTP API 호출이나 셸 명령어 실행이 가능한 코딩 에이전트와 통합하는 경우

0sql을 피해야 하는 경우:

• 대시보드 및 시각화가 포함된 전체 BI 플랫폼이 필요한 경우 (Cube 또는 Metabase 사용)
• 쿼리가 시맨틱 모델로 표현하기에 너무 복잡한 경우 (매개변수화(parameterization)를 사용하여 원본 SQL 사용)
• 밀리초 단위의 쿼리 계획이 필요한 경우 (HTTP 왕복 시간으로 인해 지연 시간이 추가됨)
• 모델 저장소 관리 없이 자체 호스팅하려는 경우

핵심 가치는 쿼리 구성 레이어에서의 결정론성과 보안입니다. 에이전트가 직접 SQL을 작성하면 인젝션 위험과 비재현성(non-reproducible) 쿼리가 발생합니다. 에이전트가 0sql을 사용하면 명확한 감사 추적(audit trail)을 가진 관리되는(governed) SQL을 얻게 됩니다. 트레이드오프는 표현력입니다. 시맨틱 모델이 정의하는 것만 쿼리할 수 있습니다.

참고 링크 (Source Links)

• 0sql.io
• Hacker News 토론