Scherlok

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

手元にデータベースがありませんか？デモでは、データベースにデータを投入して学習し、データを壊して異常を検出するまで、約1秒です。

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
鮮度アラート	テーブルが12時間更新されていません（通常は2時間ごと）	CRITICAL
スキーマの変化	カラムが削除された、または型が変わった	CRITICAL
NULL の急増	NULL 率が2％から45％に上昇	WARNING
分布の変化	カラムの平均値が3標準偏差以上変化（Shewhart 方式の管理限界）	INFO、5σを超えると WARNING
カーディナリティの急増	status カラムの値が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

3つのコマンド。5分。これで完了です。（パイプラインでは scherlok ci <url> を実行すると、3つすべてを1ステップで実行できます。）

有効なプロファイルが5件以上になると、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 コマンドなら 1 行で実行できます。

# 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 はどちらも、CI パーサー向けに --output json を受け付けます。標準出力には単一の JSON ドキュメントのみが出力され、それ以外は出力されません。

対応アダプター： postgres、bigquery、snowflake、mysql、duckdb。その他の場合は、--connection-string を明示的に渡してください。

📖 詳細なドキュメント：dbt 統合ガイド →

dbt パッケージ — ネイティブテスト

dbt の中だけで完結させたいですか？Scherlok を dbt パッケージとしてインストールすれば、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 — 自動学習（シューハート管理限界）： volume_anomaly、null_anomaly — ベースライン履歴を構築するには scherlok_metrics モデルが必要です。

📖 詳細なドキュメント：dbt パッケージの README →

HTML ダッシュボード

scherlok dashboard --out report.html

自己完結型の HTML ファイル 1 つ（約 28 KB）に、KPI、初回検出時刻ごとにグループ化されたテーブル別のインシデント、+／−／~ で示すスキーマ差分、スパークライン、すべての異常履歴が含まれています。prefers-color-scheme によってダーク／ライトテーマが自動で切り替わります。

📖 詳細なドキュメント：ダッシュボードガイド →

AI エージェントから使用する（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" }
    }
  }
}

エージェントは、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 を1 回だけ呼び出し、短い根本原因の仮説を同じ Slack／Discord／Teams／メール／JSON アラートに追加します。

watch、ci、check、dbt、dbt-run-and-watch で動作します。dbt プロジェクトでは仮説がリネージを考慮します。manifest.json の上流にある親モデルをプロンプトに含めるため、連鎖的な障害を個々の下流の症状ごとにアラートするのではなく、発生元のモデルまでたどれます。

• 費用 — 実行ごとに 1 回（異常ごとではありません）呼び出します。デフォルトでは Claude Haiku 4.5 を使用し、1 回あたり 1 セント未満です（約 $0.003）。SCHERLOK_EXPLAIN_MODEL でモデルを変更できます。異常が 0 件の実行では、API を呼び出しません。
• 送信する情報 — 集計情報のみです。アラートにすでに含まれる異常の種類／重大度／メッセージ文字列、dbt モデル名、検出時刻を送信します。ウェアハウスの行、セルの値、認証情報を送信することは決してありません。テストスイートでは、この仕様を契約として固定しています。
• 無効にする方法 — オプトイン方式のため、--explain を指定しなければ無効です。API 呼び出しに失敗した場合（キーがない、タイムアウト、レート制限など）、元のアラートは変更されず、1 行のメモが添えられて配信されます。LLM の応答待ちでアラートがブロックされることはありません。

📖 詳細なドキュメント：説明ガイド →

メールアラート

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 チェック	宣言する Expectation	製品内でモニターを設定
無料プランでベースラインを学習	はい、自動で学習	はい、テストごとの設定が必要	いいえ（Soda Library + Cloud が必要）	いいえ（宣言された Expectation を検証）	該当なし
dbt なしで動作	はい	いいえ	はい	はい	はい
セルフホスト可能	はい	OSS は可、Cloud はマネージド	Core は可、Cloud はマネージド	Core は可、Cloud はマネージド	いいえ
料金	無料	OSS は無料、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を参照）
• 異常検出の改善
• ドキュメントとサンプル

スター履歴

ライセンス

MIT — Robson Bayer Müller が開発