sqlverdict
Text-to-SQL 결과를 규칙으로 채점하고, 어디를 고쳐야 하는지 알려주는 오픈소스 라이브러리. 에러 없이 실행되지만 결과가 틀린 SQL(silent_wrong)을 잡는 것이 목표다.
- 무료:
pip install sqlverdict로 바로 쓰고, 서버나 API 비용이 없다. - LLM 없이 채점: 판정은 규칙이라 같은 결과를 넣으면 항상 같은 판정이 나온다.
- AI와 쓰면 더 빠르게: AI가 골든셋 초안을 만들고 결과를 읽어 고칠 곳을 찾는다. 정답 확정은 사람이 한다.
English summary — sqlverdict is a rule-based scorer for Text-to-SQL results. It compares the result set produced by your model's SQL with a verified golden result (SQLite / MySQL / PostgreSQL / Oracle) and flags silent_wrong answers: queries that run without error but return wrong numbers, such as a duplicate join that triples a count. No LLM and no server: verdicts are deterministic and come with fix hints. CLI messages and docs are currently in Korean.
silent_wrong이란
질문: "2024년에 주문한 고객은 몇 명?"
| SQL | 결과 | |
|---|---|---|
| 정답 | SELECT COUNT(DISTINCT customer_id) FROM orders WHERE … |
312 |
| 예측 | SELECT COUNT(o.customer_id) FROM orders o JOIN order_items i ON … WHERE … |
936 |
에러도 없고 숫자도 그럴듯하다. 실행 성공률만 보면 맞은 것으로 집계된다.
sqlverdict는 이것을 silent_wrong으로 판정하고 값이 정확히 3배: 중복 조인·필터 누락 의심이라고 알려준다.
설치
pip install sqlverdict
Python 3.10 이상. 런타임 의존성은 PyYAML 하나다. sqlverdict는 DB에 접속하지 않는다. SQL 실행은 사용자 쪽에서 하고, 그 결과만 받아 채점한다.
빠른 시작
sqlverdict init # evals/ 에 예시 golden.yaml · predictions.yaml · AGENTS.md 생성
sqlverdict check evals/golden.yaml evals/predictions.yaml
sqlverdict score evals/golden.yaml evals/predictions.yaml
정확도 40.0% (correct 2 / 채점 5 / 전체 6)
판정 correct 2 · correct_approx 1 · extra_columns 0 · silent_wrong 1 · error 1
제외 skipped_unverified 1 · unscorable 0 · missing_prediction 0
…
id 판정 level trap 질문 안내
Q002 silent_wrong L2 dup_join 2024년에 주문한 고객은 몇 명? 값이 정확히 3배: 중복 조인·필터 누락 의심
Q003 error L3 unique_id 2024년 매출 상위 3명 고객의 i… 실행 실패: no such column: c.nm
Q004 correct_approx L3 biz_term 2024년 활성 고객의 평균 주문 … 허용 오차 안에서만 같음: 반올림·자료형(FLOAT/DECIMAL) 차이 의심
예시의 숫자는 가상 데이터다. 실제로 쓰려면:
golden.yaml의 질문을 우리 DB에 맞게 바꾸고,gold_sql을 실행해expected를 채운다.snapshot은 그날 날짜로 적는다.- 예시 문항은
verified: true로 되어 있다. 사람이 확인한 문항만 true로 두고, 나머지는 false로 바꾼다. - Text-to-SQL이 만든 SQL을 실행해 결과를
predictions.yaml에 적는다. 또는 파이썬 API로 바로 비교한다. check→score
판정
| 판정 | 뜻 | 예 | 정확도에 포함 |
|---|---|---|---|
correct |
계산 오차(1e-9)만 빼고 같음 | 조건 표현은 달라도 같은 건수 | O |
correct_approx |
허용 오차(기본 0.1%) 안에서만 같음 | 평균 152340.3333 vs 152340.33 | 따로 표시 |
extra_columns |
정답 컬럼 값은 같지만 필요 없는 컬럼까지 가져옴 | SELECT *로 20개 컬럼 |
X |
silent_wrong |
실행됐는데 결과가 다름 | 중복 조인으로 건수가 3배 | X |
error |
사용자 쪽 실행이 실패함 | 없는 컬럼 이름 | X |
정확도 = correct ÷ 채점한 문항. 반올림 비교를 쓰는 다른 도구와 견줄 때는 correct + correct_approx를 보면 된다.
채점하지 않은 문항은 판정이 아니라 상태로 따로 센다.
| 상태 | 뜻 |
|---|---|
skipped_unverified |
verified: false — 사람이 확인하기 전 (--include-unverified로 포함) |
unscorable |
골든셋·예측 형식 오류로 비교 불가 (사유가 함께 나옴) |
missing_prediction |
이 문항의 예측이 없음 |
비교 규칙
- 컬럼 매칭: 이름이 같으면(대소문자 무시) 그 컬럼끼리, 다르면 위치로(1번째↔1번째). 값이 비슷한 컬럼을 찾아다니지 않는다 — 우연히 같은 값이 맞은 것으로 잡히지 않게.
- 행 순서: 기본은 정렬한 뒤 비교.
ordered: true문항만 순서까지 본다. - 컬럼 수: 예측이 더 많으면
extra_columns(정답으로 치지 않음, Spider·BIRD 관례). 필요한 컬럼이 없으면silent_wrong.
파일 형식
골든셋은 고정하고, 예측은 실행(프롬프트 버전 등)마다 따로 쌓는다. 둘은 id로 짝을 맞춘다.
골든셋 golden.yaml
dialect: mysql # sqlite | mysql | postgresql | oracle
snapshot: 2026-11-13 # 정답을 DB에서 뽑은 날짜 (30일 지나면 경고)
items:
- id: q007
question: 2018년 고객별 주문 건수 상위 5명은?
level: L4
trap: dup_join
why: orders와 order_items를 조인하면 주문이 상품 수만큼 늘어남
verified: true
ordered: true
gold_sql: SELECT customer_id, COUNT(*) AS order_count FROM orders WHERE …
expected:
columns: [customer_id, order_count]
rows: [[A, 12], [B, 9], [C, 7], [D, 6], [E, 5]]
- id: q008
question: 2018년 주문이 가장 많은 날짜는?
level: L2
trap: none
verified: true
expected: {columns: [order_date], rows: [[2018-11-23]]}
| 필드 | 필수 | 설명 |
|---|---|---|
id, question, level, trap, expected |
O | level은 L1~L4, trap은 dup_join / unique_id / biz_term / empty_ok / none |
why |
trap≠none이면 O | 무엇을 시험하는지 + 정답 근거. 사람은 이것만 읽고 검증 |
verified |
기본 false (채점 제외) | |
ordered |
행 순서까지 비교 | |
compare_columns |
이 컬럼만 비교 | |
allow_extra_columns |
예측의 추가 컬럼 허용 | |
tolerance |
이 문항의 허용 오차 (상대값, 0이면 엄격 비교만) | |
empty_ok |
빈 결과가 정답 | |
gold_sql |
정답 SQL. 실행하지 않고 check의 검사·다시 뽑기용 |
작성 규칙(함정 섞기, 닫힌 과거 기간만 묻기 등)은 init이 만드는 evals/AGENTS.md에 있고, 기계로 확인 가능한 것은 check가 검사한다.
예측 predictions.yaml
run_name: prompt-v2
dialect: postgresql # 선택: 안 적으면 골든셋 dialect (DB 마이그레이션 검증 때만)
items:
- id: q007
pred_sql: SELECT … # 선택: SELECT * 같은 힌트용
result:
columns: [customer_id, cnt]
rows: [[A, 24], [B, 18], [C, 14], [D, 12], [E, 10]]
- id: q008
error: "Unknown column 'order_dt'" # 실행 실패면 result 대신
날짜는 따옴표 없이 쓴다.
2024-01-01은 날짜로 읽혀 DB별 규칙을 타지만,"2024-01-01"은 그냥 문자열이다. 에러 메시지처럼:가 들어간 값은 따옴표로 감싼다. YAML 앵커·별칭(&이름,*이름,<<:)은 쓸 수 없다. 작은 파일이 거대한 데이터로 펼쳐지는 공격을 막기 위해서다.
CLI
sqlverdict init [폴더] # 기본 evals/. 파일이 있으면 중단 (--force로 덮어쓰기)
sqlverdict check golden.yaml [predictions.yaml] [--format table|json]
sqlverdict score golden.yaml predictions.yaml [옵션]
| score 옵션 | 설명 |
|---|---|
--format table|json|html |
기본 table (터미널 표) |
-o 경로 |
파일로 저장. 없으면 화면(stdout) 출력 |
--tolerance 0.001 |
전체 허용 오차 (상대값, 0.001 = 0.1%) |
--baseline 이전.json |
이전 실행과 비교: 새로 틀린 문항 / 새로 맞은 문항 |
--fail-on 판정 |
해당 판정·상태가 하나라도 있으면 종료 코드 1. 반복 가능 |
--head N |
예측 결과 값을 N행까지 포함 (기본 0) |
--include-expected |
정답 결과 값 포함 (디버깅용) |
--include-unverified |
verified: false 문항도 채점 |
종료 코드: 0 정상 · 1 --fail-on에 걸림 또는 check error · 2 입력 오류(파일 없음, YAML 형식, 잘못된 옵션)
이전 실행과 비교
sqlverdict score golden.yaml preds_v1.yaml --format json -o v1.json
sqlverdict score golden.yaml preds_v2.yaml --baseline v1.json
이전에 맞던 문항이 한꺼번에 여러 개 틀리면, SQL 문제가 아니라 DB 데이터가 바뀌어 정답이 낡았을 수 있다는 경고가 나온다.
CI에서 배포 막기 (GitHub Actions 예)
- run: pip install sqlverdict
- run: python scripts/run_text2sql.py --out evals/predictions.yaml # 우리 Text-to-SQL 실행 (사용자 코드)
- run: sqlverdict check evals/golden.yaml evals/predictions.yaml
- run: sqlverdict score evals/golden.yaml evals/predictions.yaml --fail-on silent_wrong --fail-on error --format html -o report.html
- uses: actions/upload-artifact@v7
if: always()
with: {name: sqlverdict-report, path: report.html}
보고서를 먼저 쓴 뒤 종료 코드를 정하므로, 실패한 실행에서도 report.html이 남는다.
파이썬 API
DB 드라이버가 준 값을 그대로 넘기면 Decimal·날짜 객체가 원래 모양으로 들어와 정규화가 가장 정확하다.
from sqlverdict import compare, to_result
cur.execute(gold_sql)
expected = to_result(cur) # DB-API 커서 → Result (실행은 하지 않음, 남은 행을 모두 읽음)
cur.execute(pred_sql)
got = to_result(cur)
v = compare(expected, got, dialect="mysql", pred_sql=pred_sql)
v.label # 'silent_wrong'
v.detail # {'expected_rows': 2, 'got_rows': 2, 'matched_by': 'position',
# 'column_map': {'order_count': 'cnt'}, 'differing_columns': ['order_count'], 'ratio': 2.0}
v.hints # ['값이 정확히 2배: 중복 조인·필터 누락 의심',
# '이름이 달라 위치로 비교함: 컬럼 이름을 맞추거나 compare_columns 지정 권장']
{"columns": [...], "rows": [[...]]}형태의 dict도 그대로 넘길 수 있다.- DB 마이그레이션 검증처럼 정답과 예측의 DB가 다르면
expected_dialect="mysql", got_dialect="postgresql". - 그 밖의 인자:
ordered,compare_columns,allow_extra_columns,tolerance(골든셋 필드와 같은 뜻).
DB별 값 처리 규칙
정답과 예측의 값을 DB마다 하나의 표준형으로 바꾼 뒤 비교한다. 아래 규칙은 MySQL 8.4 · PostgreSQL 17 · Oracle 23ai Free에서 pymysql · psycopg 3 · python-oracledb(thin)로 확인했다.
| 값 | 표준형 |
|---|---|
| 숫자 (Decimal · float · bool) | 정수로 떨어지면 int, 아니면 float. true/false → 1/0 |
| 날짜 | 2024-01-01. 시간대 없는 자정 datetime(Oracle DATE)도 날짜로 |
| 날짜+시각 | 2024-01-01 12:00:00.5 (소수 초는 0이 아니면 유지) |
| 시간대 있는 시각 | UTC로 바꿔 2024-01-01 03:00:00+00:00. 시간대 없는 값과는 다르게 본다 |
| 시각 (PG TIME · MySQL TIME) | 12:30:00 |
| 기간 (INTERVAL) | 파이썬 timedelta 표기 (1 day, 0:00:00) |
| UUID · JSON · 배열 | 문자열. JSON은 키를 정렬 |
| NaN | 'NaN' (NaN끼리 같고, NULL과는 다름) |
| Oracle 빈 문자열 | NULL (Oracle은 ''를 NULL로 저장) |
알려진 한계
틀린 답을 맞다고 하는 쪽(false correct)은 막았다. 남은 것은 대부분 맞는 답이 틀렸다고 나오는 쪽이라 판정에 드러나고, SQL에서 맞추면 된다. 마지막 두 줄은 판정 밖의 한계다.
- CHAR(n) 공백: PostgreSQL · Oracle은
'A '처럼 공백을 채워 준다 →RTRIM사용 - Oracle TIMESTAMP WITH TIME ZONE: python-oracledb thin 모드는 시간대를 버리고 준다 →
SYS_EXTRACT_UTC(col)로 뽑기 - 단정밀도 실수 교차 비교: MySQL FLOAT · Oracle BINARY_FLOAT와 다른 DB를 비교하면
correct_approx - JSON 교차 비교: MySQL은 JSON 키를 자체 순서로 내보내 PostgreSQL과 문자열이 다를 수 있다
- 문자열로 온 값은 그대로: 대문자 UUID 문자열, YAML에서 따옴표 친 날짜는 변환하지 않는다
- 시간대 있는 TIME(timetz): 시간대를 무시한다
- 허용 오차 안의 값끼리 정렬 순서가 뒤바뀌면 다른 행끼리 비교될 수 있다 (근사값이 많은 비정렬 문항)
SELECT *힌트는 정규식이라 주석 안의SELECT *도 잡는다 (판정에는 영향 없음)- 기계로 못 잡는 것은 사람이 확인: 상위 N 문항의 경계 동점, 질문의 애매함,
gold_sql을 고친 뒤verified를 false로 되돌리기
데이터와 보안
- 결과 값은 기본으로 보고서에 나오지 않는다. 정답 값은 AI가 보면 답을 외워 점수만 올리고(시험 문제 유출), 예측 값에는 고객 정보 같은 실무 데이터가 섞인다.
--head,--include-expected로 켠 보고서는 공유에 주의. - 예측
error메시지는 300자까지 보고서에 포함된다. DB 에러 메시지에 값이 섞일 수 있다. - 예측을 만드는 쪽이
golden.yaml을 읽지 못하게 한다.expected와gold_sql이 그대로 들어 있다. - HTML 보고서는 단일 파일이고, 모든 값을 이스케이프하며 CSP로 스크립트·외부 자원을 막는다.
- sqlverdict는 DB나 네트워크에 접속하지 않는다.
개발
uv sync
uv run pytest # 기본 (DB 없이)
docker compose -f tests/db/docker-compose.yml up -d --wait # MySQL + PostgreSQL
uv sync --group db
uv run pytest -m db # 실제 드라이버 값 테스트
uv run python tests/db/probe.py # 드라이버가 주는 타입 보기
docker compose -f tests/db/docker-compose.yml --profile oracle down
Oracle은 메모리 때문에 따로 띄운다: docker compose -f tests/db/docker-compose.yml --profile oracle up -d --wait oracle, pytest -m db에서 접속할 수 없는 DB는 건너뛴다.
라이선스
MIT
Metadata
Release files for sqlverdict 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| sqlverdict-0.1.0.tar.gz | 89.6 kB | With provenance | Details for sqlverdict-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| sqlverdict-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for sqlverdict-0.1.0-py3-none-any.whl |
Total release size: 121.1 kB
Release files / sqlverdict-0.1.0.tar.gz
| Download URL | sqlverdict-0.1.0.tar.gz |
|---|---|
| Size | 89.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
45b4612650266a34a6ec78d853fc3db5b2607a2f6f56624c51a19e235a43edef
|
|
BLAKE2b-256 checksum How to use checksums |
7c38baecf685d3a1dc1b02c0b9aaf4b50e32945b40dbb05817159fdfc1fd991a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.
Transparency logRelease files / sqlverdict-0.1.0-py3-none-any.whl
| Download URL | sqlverdict-0.1.0-py3-none-any.whl |
|---|---|
| Size | 31.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
82d368e82b988c264054a0069d1da97869e04537dc436963192d41f79c42d92f
|
|
BLAKE2b-256 checksum How to use checksums |
446d8c4d94c92913dc53d5a90d406c30557d93a1937b6672743f65958407c2a6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.
Transparency logSecurity for sqlverdict 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for sqlverdict-0.1.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.