텍스트-to-SQL 에이전트에 비즈니스 용어집을 적용해봤습니다. 버전별 성능 비교 결과

텍스트-to-SQL 에이전트는 테이블명과 컬럼명을 인식합니다. 하지만 회사에서 'revenue'가 billing_invoice.total_net을 의미하며, 심지어 status = 'issued'인 인보이스에 한해서만 해당된다는 사실은 알지 못합니다. 따라서 모델은 추측하고, 이 추측이 오류 없이 실행되어 잘못된 숫자를 반환하게 됩니다.

저는 schemagate 1.2.0 (오픈 소스, Apache-2.0)에 비즈니스 용어(business terms)를 추가하고 이것이 얼마나 도움이 되는지 측정해 보았습니다. 간단히 말하자면, 완전한 용어집은 큰 도움을 주었습니다. 하지만 다른 사람들의 질문에서 학습된 용어집은 전혀 도움이 되지 않았습니다. 두 가지 결과를 여기에 제시합니다.

용어의 형태

cat.concept(
    "revenue",
    synonyms=["turnover", "sales"]
... 

질문에서 'turnover'를 사용하면 두 가지 일이 발생합니다:

1. 모델이 볼 수 있는 몇 개의 테이블에 billing_invoice가 포함됩니다. 비록 어떤 테이블명도 'turnover'처럼 보이지 않더라도 말입니다.
2. DDL 위에 다음 내용의 줄이 프롬프트에 추가됩니다:

-- 이 질문의 비즈니스 용어 의미: 
-- revenue (turnover): billing_invoice.total_net; 규칙: billing_invoice.status = 'issued'

용어는 또한 더 포괄적이거나 좁은 범위의 용어를 가질 수 있습니다 ('net revenue'는 'revenue'의 한 종류). 이는 관련 테이블을 낮은 가중치로 가져옵니다.

이것들을 직접 타이핑할 필요는 없습니다. dbt semantic manifest, Snowflake semantic model, 또는 Collibra나 Purview에서 내보낸 CSV를 통해 가져올 수 있습니다:

schemagate ontology import semantic_manifest.json --from dbt --url $DB --config catalog.json --save

또는 과거의 (질문, SQL) 쌍으로부터 학습할 수도 있습니다. 만약 'refunds'가 billing_credit_note라는 SQL을 가진 질문에 계속 나타난다면, 그것이 제안되는 용어가 됩니다.

제가 신경 쓰는 부분: 접근 통제(access control)

schemagate의 주요 임무는 호출자가 읽지 않을 수 있는 테이블과 컬럼을 모델이 아무것도 보기 전에 숨기는 것입니다. 그런데 용어집은 이를 다시 누설할 수 있습니다. 'pay'가 hr_compensation.annual_amount를 의미한다고 알려주면, 급여 담당자에게 해당 컬럼이 존재한다는 것을 알려주는 셈입니다.

따라서 의미 라인(meaning line)은 자신이 언급하는 모든 테이블과 컬럼을 볼 수 없는 호출자(caller)에 대해서는 생략됩니다. 해당 용어 자체는 여전히 존재합니다. 다만 그 호출자가 자신의 라인을 얻지 못할 뿐입니다.

결과 (Results)

BIRD dev, 201개 질문, Claude Sonnet 5, 실행 정확도, 숨겨진 힌트 텍스트:

전체 용어집(glossary)은 28개의 질문에서 승리하고 '용어 없음' 대비 8개에서 패배했습니다 (McNemar p = 0.001). 이는 실제 결과입니다.

다른 질문에서 학습된 용어는 아무런 효과가 없었습니다: 46.8%로, 기준선(baseline)을 두 번 실행했을 때와 동일합니다. BIRD의 힌트는 대부분 일회성 공식("백분율 = x를 가진 카운트 / 총 카운트")이며, 한 질문에서 얻은 공식이 다음 질문에 적용되는 경우는 드뭅니다. 저는 용어집이 스스로 구축될 것이라고 예상할 경우 마주칠 결과이기 때문에 이 결과를 보고합니다.

검색(Retrieval), Spider 데이터셋, 876개 테이블 풀링: 절반의 질문에서 학습된 용어는 나머지 절반에 대한 recall@5를 73.3%에서 82.8%로 높였습니다 (49개 질문 개선, 0개 악화). 올바른 테이블을 찾는 데 있어서는 학습된 용어가 실제로 도움이 됩니다.

제가 얻은 교훈

• 사람들이 정말 논쟁하는 20~50개의 용어(매출액, 활성 고객, 이탈률 등)를 작성해 두세요. 여기서 10점의 가치가 나왔습니다.
• 학습된 용어는 테이블을 찾는 데는 좋지만, 공식을 가르치는 데는 적합하지 않습니다.
• 프롬프트에 무엇을 추가하든, 호출자의 권한(permissions) 측면에서도 확인해야 합니다.

직접 시도해 보기 (Try it)

pip install "schemagate[mcp]"
SCHEMAGATE_DATABASE_URL=demo python -m schemagate.mcp_server

Postgres, Oracle, MySQL, SQL Server 및 SQLite와 함께 파이썬 라이브러리, LangChain retriever, 또는 Claude 및 Cursor용 MCP 서버로 작동합니다.

GitHub: https://github.com/ashishsinha1602/schemagate · 인앱 데모: https://ashishsinha1602.github.io/schemagate/

실제 데이터 웨어하우스에 에이전트를 실행한다면: 추측을 멈추게 하기 위해 얼마나 많은 비즈니스 용어를 작성해야 할까요?