Sqlsure: 為 AI 生成的 SQL 提供確定性語義檢查

Sqlsure: 為 AI 生成的 SQL 提供確定性語義檢查

Sqlsure 透過驗證查詢語義來防止靜默 SQL 錯誤

Sqlsure 是一個確定性的語義檢查器，旨在捕捉「靜默」SQL 錯誤——即語法正確且能執行但返回數學上錯誤結果的查詢。它針對 AI 生成 SQL 中的常見錯誤，例如由 join 造成的收入重複計算（fan-out）或對平均值等非加性指標進行求和。

與傳統的 linter 或基於 LLM 的審查不同，Sqlsure 作為一個確定性引擎運行。它使用針對已宣告語義模型的字典查找，在不需要網路呼叫或資料庫存取的情況下，約 0.1 ms 內即可提供判定結果。

核心語義規則與錯誤檢測

Sqlsure 會根據一組預定義的規則來評估 SQL，以識別結構與語義風險。當引擎無法驗證特定操作時，它會報告「無法驗證」而非假設查詢是安全的。

關鍵錯誤

  • FANOUT: 檢測在進行一對多 join 之後對加性指標進行求和或計數，這通常會導致重複計算。
  • CHASM: 識別會使結果集倍增、進而加劇錯誤的多個 fan-out join。
  • ADDITIVITY: 捕捉對速率或平均值等非加性指標進行求和的操作。
  • SEMI_ADDITIVE: 檢測在快照維度上對餘額或普查數據進行求和。
  • JOIN_KEY: 標記在與語義模型中任何宣告的關係都不匹配的列上進行的 join。
  • CROSS_JOIN: 標記在沒有謂詞的情況下進行的 join。

警告與策略違規

  • WEIGHTED_AVG: 當平均值因 fan-out join 而被靜默地重新加權時，發出警告。
  • UNDECLARED_JOIN: 當使用的 join 沒有宣告的關係（無法驗證）時，發出警告。
  • SENSITIVE_COLUMN: 一項策略檢查，標記查詢輸出中暴露了 PHI/PII 列。

整合與實作模式

Sqlsure 可以透過三個主要入口點整合到資料流水線中：

  1. CI/CD Gates: 它可以作為 CLI 工具使用，如果發現查詢在語義上不正確，則阻斷 pull request。
  2. MCP Server: 作為 Model Context Protocol (MCP) 伺服器，它允許 AI agent 在執行查詢之前通過檢查，實現「草稿 $\rightarrow$ 檢查 $\rightarrow$ 修復 $\rightarrow$ 執行」的循環。
  3. Library Integration: check() 函數可以直接嵌入到 text-to-SQL 框架（例如 Vanna 或 WrenAI）中，作為 NL2SQL 輸出的語義閘口或評估指標。

語義模型來源

Sqlsure 不需要新的語言來進行配置。它從現有的元數據來源生成其規則集：

  • dbt: 它可以攝取 manifest.json 或 schema.yml 檔案，將 dbt 的 unique 測試轉換為粒度定義，並將 relationships 測試轉換為 join 基數。
  • Live Databases: sqlsure.introspect 模組可以利用 SQLite PRAGMAs 或 PostgreSQL 與 MySQL 的 information_schema 從資料庫目錄構建模型。
  • Semantic Layers: 它包含 OSI 和 WrenAI MDL 的載入器。
  • Custom JSON: 使用者可以透過 JSON 規範定義自己的語義模型。

信任與安全屬性

Sqlsure 專為高安全性環境設計，具有以下屬性：

  • Deterministic: 相同的 SQL 與規則集總是會產生相同的結果。
  • Offline and Private: 該工具完全在離線狀態下運行，零網路呼叫；SQL 查詢永遠不會離開本地機器。
  • No Data Access: Sqlsure 解析的是查詢文本本身，從不連接到實際的資料庫數據。
  • No Telemetry: 該工具不收集使用者的任何數據。

性能與驗證

在 BIRD 和 Spider text-to-SQL 基準測試的審核中，Sqlsure 在 2,568 個專家編寫的查詢中識別出了 45 個標記，且零誤報。這包括識別出一個 BIRD dev gold answer 因 fan-out bug 而導致結果錯誤達 8 倍，以及識別出隨後被提交至上游的 schema 缺陷。

Sources