Sqlsure：用于 AI 生成 SQL 的确定性语义检查

Sqlsure：用于 AI 生成 SQL 的确定性语义检查

Sqlsure 通过验证查询语义防止静默的 SQL 失败

Sqlsure 是一种确定性的语义检查器，旨在捕获“静默”SQL 错误——这些查询在语法上有效且能够运行而不报错，但返回的结果在数学上不正确。它针对 AI 生成 SQL 中常见的失败场景，例如由于连接（fan‑out）导致的收入重复计数，或对非可加度量（如平均值）进行求和。

不同于传统的 linter 或基于 LLM 的审查，Sqlsure 作为确定性引擎运行。它通过对声明的语义模型进行字典查找，在约 0.1 ms 内给出判定，无需网络调用或数据库访问。

核心语义规则与错误检测

Sqlsure 根据一组预定义规则评估 SQL，以识别结构性和语义风险。当引擎无法验证某个具体操作时，会报告“无法验证”，而不是假设查询是安全的。

严重错误

  • FANOUT：检测在一对多连接后对可加度量进行求和或计数，这通常会导致重复计数。
  • CHASM：识别多个 fan‑out 连接导致结果集被多次放大，错误叠加。
  • ADDITIVITY：捕获对非可加度量（如比率或平均值）的求和。
  • SEMI_ADDITIVE：检测在快照维度上对余额或人口普查数据进行求和。
  • JOIN_KEY：标记在语义模型中未声明任何关系的列上的连接。
  • CROSS_JOIN：标记没有谓词的笛卡尔积连接。

警告与策略违规

  • WEIGHTED_AVG：当平均值在 fan‑out 连接后被静默重新加权时发出警告。
  • UNDECLARED_JOIN：当使用了未在模型中声明关系的连接（不可验证）时发出警告。
  • SENSITIVE_COLUMN：策略检查，标记查询输出中暴露的 PHI/PII 列。

集成与实现模式

Sqlsure 可以在数据管道的三个主要入口点进行集成：

  1. CI/CD 门禁：可作为 CLI 工具使用，在发现查询语义错误时阻止 Pull Request 合并。
  2. MCP 服务器：作为 Model Context Protocol（MCP）服务器，允许 AI 代理在执行查询前通过检查，实现 “草稿 → 检查 → 修正 → 执行” 循环。
  3. 库集成：check() 函数可直接嵌入文本到 SQL 的框架（如 Vanna 或 WrenAI），充当语义门或 NL2SQL 输出的评估指标。

语义模型来源

Sqlsure 不需要新语言进行配置。它从已有的元数据源生成规则库：

  • dbt：可导入 manifest.json 或 schema.yml 文件，将 dbt 的 unique 测试转换为粒度定义，将 relationships 测试转换为连接基数。
  • 实时数据库：sqlsure.introspect 模块可使用 SQLite PRAGMA 或 PostgreSQL、MySQL 的 information_schema 从数据库目录构建模型。
  • 语义层：内置 OSI 与 WrenAI MDL 的加载器。
  • 自定义 JSON：用户可通过 JSON 规范自行定义语义模型。

信任与安全属性

Sqlsure 为高安全环境设计，具备以下特性：

  • 确定性：相同的 SQL 与规则库始终产生相同的结果。
  • 离线且私密：工具完全离线运行，零网络调用；SQL 查询永不离开本地机器。
  • 无数据访问：Sqlsure 仅解析查询文本，从不连接实际数据库数据。
  • 无遥测：工具不收集任何用户数据。

性能与验证

在对 BIRD 与 Spider 文本到 SQL 基准的审计中，Sqlsure 在 2,568 条专家编写的查询中识别出 45 条标记，且未出现误报。其中包括发现一条 BIRD 开发集金标准答案因 fan‑out 错误导致结果偏差高达 8 倍的案例，以及识别出随后在上游提交的模式缺陷。

Sources