Scherlok

pip install scherlok
scherlok ci postgres://user:pass@host/db   # profiles on the first run, detects anomalies on every run after

手头没有数据库？演示会创建数据库、学习其模式、制造异常并将其捕获，整个过程大约只需一秒：

uvx --from "scherlok[duckdb]" scherlok demo

适用于 PostgreSQL、BigQuery、Snowflake、MySQL、DuckDB 和 dbt。告警可发送到 Slack、Discord、Teams、电子邮件，或通过 CI 退出代码发出。

---

问题

每个数据团队都面临同样的噩梦：

某个源 API 悄无声息地把美元改成了美分。收入仪表板上的数字错了，3 周后才有人发现。

某列开始返回 NULL。某张表停止更新。某个星期二，行数下降了 40%。直到 CEO 问报告为什么看起来不对劲，才有人发现。

现有工具（Great Expectations、Soda、dbt tests）要求你先定义“正确”是什么样子，才能检测出问题。数百条规则、数十个 YAML 文件。而你仍会漏掉问题——因为你无法为尚未想到的问题编写规则。

可捕获的异常

异常	发生情况	严重级别
数据量骤降	行数在一夜之间下降了 40%	CRITICAL
数据量激增	行数是正常值的 3 倍	WARNING
新鲜度告警	表已有 12h 未更新（通常每 2h 更新一次）	CRITICAL
架构漂移	列被移除或类型发生变化	CRITICAL
NULL 激增	NULL 比率从 2% 跃升至 45%	WARNING
分布偏移	列均值偏移了 3 个或更多标准差（Shewhart 式控制限）	INFO，高于 5σ 时为 WARNING
基数激增	状态列的取值从 5 个增至 500 个	CRITICAL

每个异常都会自动评定级别：INFO、WARNING 或 CRITICAL。无需配置阈值。

工作原理

Scherlok 采用与基于规则的工具相反的方法：先学习，再检测。

scherlok connect postgres://user:pass@host/db   # connect once
scherlok investigate                              # learn your data
scherlok watch                                    # detect anomalies

三条命令，五分钟，搞定。（对于流水线，scherlok ci <url> 会一步运行全部三条命令。）

积累五个有效的配置文件后，Scherlok 会基于最新的 30 个配置文件，使用稳健的历史基线学习各项指标的变化范围，涵盖数据量、数值均值偏移、NULL 比率和不同值计数。在冷启动阶段或历史数据不可用时，则沿用保守的固定默认值。

1. investigate — 学习模式

$ scherlok investigate

  Profiling 12 tables...
  ✓ users         — 45,231 rows, 8 columns
  ✓ orders        — 1,203,847 rows, 15 columns
  ✓ products      — 892 rows, 12 columns
  ...
  Done. Profiles saved.

Scherlok 会分析每张表的配置：行数、列类型、NULL 比率、值分布、更新频率和基数，并将所有数据存储在本地 SQLite 中。

2. watch — 检测异常

$ scherlok watch

  Checking 12 tables against learned profiles...

  🔴 CRITICAL  orders    volume_drop     Row count dropped 52% (1,203,847 → 578,412)
  🟡 WARNING   users     null_increase   Column "email": NULL rate 2.1% → 18.7%
  🔵 INFO      products  distribution    Column "price": mean shifted 3.2σ

  3 anomalies detected. Exit code: 1

3. 告警 — Slack、CI/CD，或两者兼有

# Slack
scherlok watch --webhook https://hooks.slack.com/services/...

# Discord
scherlok watch --webhook https://discord.com/api/webhooks/...

# Microsoft Teams
scherlok watch --webhook https://outlook.office.com/webhook/...

# Any endpoint (generic JSON payload)
scherlok watch --webhook https://my-api.com/alerts

# CI/CD gate (fails pipeline on CRITICAL)
scherlok watch --exit-code --fail-on critical

根据 URL 自动检测 Slack、Discord 和 Teams，并据此设置载荷格式。其他 URL 会收到通用 JSON 载荷。

CI/CD 集成

将 Scherlok 用作数据质量关卡。ci 命令只需一行即可完成：

# GitHub Actions
- name: Data quality check
  run: |
    pip install scherlok
    scherlok config --store s3://my-bucket/scherlok/profiles.db
    scherlok ci ${{ secrets.DATABASE_URL }} \
      --webhook ${{ secrets.SLACK_WEBHOOK }} \
      --fail-on critical

如果 Scherlok 检测到严重异常，流水线就会失败。坏数据绝不会进入生产环境。

与 dbt 搭配使用

已经在运行 dbt？Scherlok 可通过自动异常检测补充 dbt test，无需编写规则。

pip install scherlok[dbt]

# After `dbt run`, point Scherlok at your project
scherlok dbt --project-dir ./my_dbt_project

Scherlok 会读取 target/manifest.json，发现每个已物化模型（table、incremental、view），从 profiles.yml 自动解析连接，并分析每个模型：

Investigating 4 dbt models in ./my_dbt_project (postgres)
  ✓ stg_customers                  (12,345 rows)
  ✓ stg_orders                     (98,765 rows)
  ✗ fct_orders                     CRITICAL: Row count dropped 42% (98,765 → 57,283)
  ✓ dim_customers_inc              (12,300 rows)

Summary: 4 profiled, 1 anomalies (1 critical, 0 warning)

在 dbt run 后将其用作 CI 关卡：

- run: dbt run --target prod
- run: scherlok dbt --project-dir . --target prod --fail-on critical

也可以用包装器将两个步骤合并为一步：

- run: scherlok dbt-run-and-watch --project-dir . --target prod --fail-on critical

包装器默认运行 dbt run，并使用记录在 target/run_results.json 中的成功模型节点，因此部分运行时只会分析 dbt 实际构建的模型。使用 --build 可运行 dbt build；如果测试失败导致后续模型被跳过，但 dbt 通过处理失败路径（退出码为 1）正常结束，成功模型仍会接受分析，同时包装器会保留 dbt build 的退出码。未处理的失败会立即终止，不会读取构建产物。

dbt 和 dbt-run-and-watch 都接受 --output json，供 CI 解析器使用——stdout 上只输出一个 JSON 文档，不输出其他内容。

支持的适配器：postgres、bigquery、snowflake、mysql、duckdb。其他适配器请显式传入 --connection-string。

📖 完整文档：dbt 集成指南 →

dbt Package — 原生测试

更喜欢留在 dbt 中？将 Scherlok 安装为 dbt Package，即可使用原生数据质量测试，无需 Python CLI。

# packages.yml
packages:
  - git: https://github.com/rbmuller/scherlok.git
    revision: v1.0.5

dbt Package Hub 列表发布后（dbt-labs/hubcap#456），这里将改为 package: rbmuller/scherlok，并使用 version: [">=1.0.0", "<2.0.0"]。

# schema.yml
models:
  - name: fct_orders
    tests:
      - scherlok.volume_anomaly:
          sensitivity: 3.0
      - scherlok.row_count_between:
          min_value: 100
    columns:
      - name: email
        tests:
          - scherlok.not_null_proportion:
              max_rate: 0.01
      - name: updated_at
        tests:
          - scherlok.recency:
              days: 2

第 1 层 — 即时检测（无需设置）：not_null_proportion、row_count_between、recency、unique_proportion

第 2 层 — 自动学习（Shewhart 控制限）：volume_anomaly、null_anomaly——需要构建 scherlok_metrics 模型来生成基线历史数据。

📖 完整文档：dbt Package README →

HTML 仪表板

scherlok dashboard --out report.html

一个独立的 HTML 文件（约 28 KB）：包含 KPI、按表分组并标注首次发现时间的事件、使用 +/−/~ 标记的架构漂移差异、迷你趋势图和完整的异常历史记录。通过 prefers-color-scheme 自动切换深色/浅色主题。

📖 完整文档：仪表板指南 →

在 AI Agent 中使用（MCP）

让 Claude Code / Claude Desktop 直接运行数据质量检查。

**Claude Desktop：**从最新版本下载 scherlok-<version>.mcpb 并打开。只需单击一次，并设置一个选项（连接字符串会作为密钥存储）。

其他客户端：

pip install scherlok   # scherlok-mcp ships built-in since v0.7.0

{
  "mcpServers": {
    "scherlok": {
      "command": "scherlok-mcp",
      "env": { "SCHERLOK_CONNECTION": "postgresql://user:pass@host/db" }
    }
  }
}

Agent 可将 list_tables、investigate、watch、status、history 和 check 用作工具。凭据由服务端解析（绝不会传给模型），所有操作对数据仓库均为只读，并且不提供任意 SQL 工具。

📖 完整文档：MCP 服务指南 →

AI 解释告警（--explain）

告警会告诉你发生了什么。--explain 会补充为什么发生，以及接下来该检查什么。

pip install 'scherlok[explain]'
export ANTHROPIC_API_KEY=sk-ant-...

scherlok watch --webhook https://hooks.slack.com/... --explain

发生异常时，Scherlok 会针对整批异常只调用一次 Claude，并在同一条 Slack/Discord/Teams/电子邮件/JSON 告警中附上一段简短的根因假设：

适用于 watch、ci、check、dbt 和 dbt-run-and-watch。对于 dbt 项目，假设会感知数据血缘：manifest.json 中的上游父模型会加入提示词，因此级联故障会追溯到源模型，而不是对每个下游症状分别告警。

• 费用——每次触发的运行调用一次（而非每个异常调用一次），默认使用 Claude Haiku 4.5：每次运行远低于 1 美分（约 $0.003）。可通过 SCHERLOK_EXPLAIN_MODEL 更换模型。没有异常的运行不会调用 API。
• 发送内容——仅汇总信息：告警中已有的异常类型/严重程度/消息字符串、dbt 模型名称和检测时间戳。绝不会发送数据仓库行、单元格值或凭据——测试套件将此作为约束进行验证。
• 关闭方式——此功能默认不启用；不要传入 --explain。如果 API 调用失败（缺少密钥、超时、达到速率限制），系统会照常发送原始告警，并附上一行说明。告警绝不会因等待大模型而阻塞。

📖 完整文档：解释器指南 →

电子邮件告警

export SCHERLOK_SMTP_HOST=smtp.gmail.com
export [email protected]
export SCHERLOK_SMTP_PASSWORD=app-specific-password

scherlok watch --email [email protected] --email [email protected]

连接器

# PostgreSQL
scherlok connect postgres://user:pass@host:5432/db

# BigQuery — see src/scherlok/connectors/bigquery.md for auth, billing, CI patterns
pip install scherlok[bigquery]
scherlok connect bigquery://project-id/dataset-name

# Snowflake
pip install scherlok[snowflake]
export SNOWFLAKE_USER=...
export SNOWFLAKE_PASSWORD=...
export SNOWFLAKE_WAREHOUSE=...
scherlok connect snowflake://account/database/schema

# MySQL
pip install scherlok[mysql]
scherlok connect mysql://user:pass@host:3306/dbname

# DuckDB
pip install scherlok[duckdb]
scherlok connect duckdb:///path/to/file.db

数据库	状态
PostgreSQL	可用
BigQuery	可用
Snowflake	可用
MySQL	可用
DuckDB	可用

远程存储

在 CI 运行和团队成员之间共享配置文件：

# AWS S3
scherlok config --store s3://my-bucket/scherlok/profiles.db

# Google Cloud Storage
scherlok config --store gs://my-bucket/scherlok/profiles.db

# Azure Blob Storage
scherlok config --store az://my-container/scherlok/profiles.db

对比

	Scherlok	Elementary	Soda	Great Expectations	Monte Carlo
开源核心	MIT	Apache-2.0 dbt 包 + CLI	Apache-2.0 Soda Core	Apache-2.0 GX Core	否（SaaS）
检测开始前的配置	无	每个异常测试都需配置 YAML	SodaCL YAML 检查项	声明的期望	在产品中配置监控项
免费层可学习基线	是，自动学习	是，需逐项配置	否（需要 Soda Library + Cloud）	否（验证已声明的期望）	不适用
无需 dbt 即可运行	是	否	是	是	是
可自托管	是	开源版可自托管；Cloud 为托管服务	Core 可自托管；Cloud 为托管服务	Core 可自托管；Cloud 为托管服务	否
定价	免费	开源版免费；Cloud 按席位和环境收费	Core 免费；Cloud 提供免费方案	Core 免费；Cloud 提供免费的 Developer 选项	按报价定价

每项对比均链接到其他工具自己的文档，详见完整对比。

CLI 参考

scherlok connect <url>          Connect to a database
scherlok investigate            Profile all tables (learn patterns)
scherlok watch [-w <url>] [-e <email>]  Detect anomalies and alert
scherlok ci <url> [opts]        All-in-one CI/CD command (connect + watch + exit code)
scherlok dbt [--project-dir .] [--output json]  Profile dbt models from manifest
scherlok dbt-run-and-watch [--build] [--output json]  Run dbt + profile in one step
scherlok status [--output json] Quick health dashboard
scherlok history [--days N] [--output json]  Timeline of past anomalies
scherlok report [--output json] Detailed profile summary
scherlok dashboard [--out .html] Generate self-contained HTML report
scherlok config --store <url>   Set remote storage
scherlok demo [--keep] [--output json]  Self-contained demo on a sample DuckDB (no database needed)
scherlok version                Show version

安装

pip install scherlok

# With BigQuery support
pip install scherlok[bigquery]

需要 Python 3.10+。

通过 Docker 运行

每次发布标签时，都会将包含所有数据仓库扩展（dbt、bigquery、snowflake）的预构建镜像发布到 GitHub Container Registry：

docker run --rm ghcr.io/rbmuller/scherlok:latest version

挂载项目目录，并像在 CI 中一样注入连接详情；入口点是 scherlok CLI：

docker run --rm \
  -v "$PWD:/work" -w /work \
  -e SCHERLOK_CONNECTION=postgres://... \
  ghcr.io/rbmuller/scherlok:latest watch

该镜像基于 python:3.12-slim 构建，并以非特权用户身份运行（USER scherlok）。

贡献

欢迎贡献！请参阅 CONTRIBUTING.md。

我们尤其欢迎以下贡献：

• 新的数据库连接器（例如 Databricks，参见 #37）
• 异常检测改进
• 文档和示例

Star 历史

许可证

MIT — 由 Robson Bayer Müller 开发