HN 日本語サマリー

← 一覧へ戻る
プログラミング

Show HN: Sqlsure – AI生成SQLの決定論的セマンティックチェック

Show HN: Sqlsure – deterministic semantic checks for AI-generated SQL (github.com)

26 pointsby tejusarora5 コメント

要約

Sqlsureは、AIが生成したSQLクエリに対して、実行前に決定論的なセマンティックチェックを行うツールです。データベースやリンターが見逃すような、論理的な誤り(例:二重計上、誤った集計)を検出します。dbtテストやスキーマ定義などの既存の事実に基づいてルールを定義し、高速かつオフラインで動作します。

全文翻訳

sqlsure

[画像: CI] [画像: PyPI] [画像: License: Apache-2.0] [画像: Python]

AIがSQLを生成し、sqlsureがその正しさを保証します。

クエリは完全に有効で、エラーなく実行され、静かに間違った数値を返すことがあります — 例えば、結合によって収益が二重計上されたり、平均値が集計されたり、患者識別子が公開されたりします。データベースはこれを検出しません。リンターも検出しません。自身のSQLをレビューするLLMも検出しません。

sqlsureはこれを検出します — 決定論的に、0.1msで、クエリが実行される前に。

約束ではなく、証明: 私たちは、すべてのテキスト・トゥ・SQLモデルが評価される2つのベンチマークのゴールドアンサーに対してsqlsureを実行しました。2,568件の専門家が書いたクエリ、45件のフラグ、偽陽性ゼロ — これには、sqlsureがターゲットとするバグクラスによって8倍も間違っていることが証明されているBIRD devのゴールドアンサーや、すでにアップストリームに提出されたスキーマの欠陥も含まれます。

仕組み

sqlsureは、チームがすでに宣言した事実(dbtのuniqueテストは粒度として、relationshipsテストは結合カーディナリティとして、1行のmetaタグは集計しても安全なものをマークする)に対してSQLを評価します。学習すべき新しい言語はなく、手動でメンテナンスするモデルもありません。ルールは辞書ルックアップであり、LLM呼び出しではありません — 同じ入力、同じ判定、常に、オフラインで実行されます。

すべての拒否には機械が解釈可能なfixが付随するため、AIエージェントは自己修復します:ドラフト → チェック → 修正 → チェック → 実行。 私たちのベンチマークでは、修正をそのまま適用することで、10/10回パスするクエリが生成されました。

クイックスタート

pip install sqlsure
from sqlsure import SemanticModel, check
violations = check(sql, model)   # [] は意味的に安全であることを意味します

または、クローンして30秒のデモを実行してください:

python check.py                   # 5件の間違ったクエリが拒否され、1件が承認されました — 修正付き
python -m sqlsure.scan path/to/dbt-repo --report report.md   # 任意のdbtリポジトリを監査します

3つのドア、1つのエンジン

1. CIゲート — PRが二重計上した場合、マージをブロックします:

python -m sqlsure.cli --model model.json query.sql   # 違反があった場合に終了コード1を返します

2. MCPサーバー — AIエージェントは実行前に検査に合格する必要があります:

claude mcp add sqlsure -- python -m sqlsure.mcp_server --model /abs/path/model.json

ツールの参照とエージェントループパターンについては、docs/MCP.mdを参照してください。

3. ライブラリ — check()を任意のテキスト・トゥ・SQL製品またはエージェントフレームワークに組み込みます。SemanticGateはVanna/WrenAIスタイルのジェネレーターをラップし、semantic eval metricは実行精度が不明なNL2SQL出力をスコアリングします。

Agent Skillとしても利用可能 — エージェントが直接ロードする単一のSKILL.mdです。サーバープロセスは不要です。

ルール(v0.1)

ルール重大度検知対象
FANOUTerror1対多結合後の加算可能なメジャーのSUM/COUNT
CHASMerror2つ以上のファナウト結合が相互に掛け合わされる
ADDITIVITYerror非加算可能なメジャー(レート、平均値)のSUM
SEMI_ADDITIVEerrorスナップショット次元にわたる残高/センサスの合計
JOIN_KEYerror宣言されたリレーションシップに一致しない列での結合
CROSS_JOINerror条件なしの結合
WEIGHTED_AVGwarningファナウトによって静かに再加重されたAVG
UNDECLARED_JOINwarning宣言されたリレーションシップのない結合(検証不能 ≠ 安全)
SENSITIVE_COLUMNpolicyクエリ出力で公開されたPHI/PII列

sqlsureが何かを検証できない場合、「検証できません」と報告します — 「問題なさそう」とは決して言いません。正直な不確実性は機能です。

信頼性プロパティ

  • 決定論的 — 同じSQL + 同じルールブック = 同じ判定、常に。ルールは辞書ルックアップであり、行ごとに監査可能です。
  • オフライン — ネットワーク呼び出しゼロ。あなたのSQLはあなたのマシンから離れません。
  • データアクセスなし — クエリテキストを解析します。データベースには接続しません。
  • テレメトリなし — 何も収集しません(SECURITY.md)。
  • サプライチェーン — リリースは、公開CI実行を持つタグ付きコミットから、PyPI Trusted Publishing(OIDC)を通じてのみ出荷されます。ランタイム依存関係は2つです。

ルールブックの出所

  • dbt(本日利用可能):manifest.jsonまたはschema.yml — チームがすでに書いたテストが、設定ゼロで強制可能なセマンティクスになります。

  • プレーンなPK/FK宣言(本日利用可能 — ベンチマーク監査を強化しました)。

  • ライブデータベース自体(本日利用可能):セマンティックレイヤーは全くありませんか?sqlsure.introspectはカタログからルールブックを構築します — SQLiteのPRAGMAまたはinformation_schemaのPK/FK(postgres/mysql)。BIRD自身のデータベースファイルからイントロスペクトすることで、ベンチマークの公開スキーマに見落とされていた外部キー2つを復元しました(bird-bench/mini_dev#37)。

    from sqlsure.introspect import model_from_sqlite
    model = model_from_sqlite("app.db")   # PK -> grain, FK -> join edges
    
  • 手書きJSON — model.example.json

  • OSIおよびWrenAI MDL(integrations/にローダーを実装中):OSIは仕様の公開例でデモンストレーションされ、WrenAI MDLはWrenAI自身の出荷済み例マニフェストでデモンストレーションされました — primaryKey → grain、リレーションシップjoinType + condition → join edges、キューブメジャー → 加算性。

  • Cube、Snowflake Semantic Views — ロードマップ上のアダプター。エンジンは常に1つのSemanticModelのみを参照します。

検証済み

  • 16/16のルールテスト、100%のリコール / 0%の偽陽性(ペアになったベンチマークで実施)(docs/METRICS.md)。
  • 実際のプロダクションリポジトリ(Mattermostのウェアハウス、Fivetranパッケージ、dbtのjaffle shop) — docs/TEST-REPORTS.md。
  • Spider + BIRDのゴールドクエリ — 上記のゼロノイズ外部監査。

詳細情報

  • docs/EVIDENCE.md — あなたのために何をするか、すべての主張は再実行可能な測定値にリンクされています。
  • docs/ARCHITECTURE.md — 物理的にどのように機能するか、ELI5からゴッドレベルまで、実際の中間出力付き。
  • docs/FOR-DUMMIES.md — すべての概念をゼロから。
  • docs/INTEGRATIONS.md — GitHub Action、pre-commit、MCP、Snowflake UDF / Cortex Agentツール、クエリ履歴監査。
  • docs/MCP.md — MCPサーバーのドキュメント。
  • CONTRIBUTING.md — ルールとローダーの追加。

Apache-2.0 · sqlsure.ai

mcp-name: io.github.sqlsure/sqlsure