datadiffer

datadiffer

2 つのテーブルを比較します。何が変わったのか、その変化がデータのどの部分に集中しているのかを確認できます。

98.6% of modified rows have country = 'DE' (8.87x over-represented)

datadiffer は 2 つのテーブル（開発環境と本番環境、PR と main、ソースと宛先）を比較し、何が変わり、どこに集中しているのかを知らせます。追加・削除・変更された行、列ごとの変更率、セグメント別の要因を確認できます。

エージェントがパイプラインを作成し、その成果を誰かが確認しなければならない時代のために開発されました。アーカイブされた data-diff を引き継ぐ、メンテナンス継続中の MIT ライセンスの後継プロジェクトです。

60 秒で試す

認証情報も設定もアカウントも不要です。データは自動生成されます。

uvx datadiffer demo

datadiffer-demo/orders_prod.parquet vs datadiffer-demo/orders_dev.parquet
key: order_id (inferred from *_id naming)
rows: +800 added  -250 removed  ~432 modified  49318 unchanged
┏━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━━━━┓
┃column ┃ changed rows ┃ % of matched┃
┡━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━━━━┩
│amount │          432 │        0.87%│
└───────┴──────────────┴─────────────┘
-> 98.6% of modified rows have country = 'DE' (8.87x over-represented)
   93.2% of added rows have plan = NULL (63.19x over-represented)
sample changes:
  [order_id=0]  amount: 5.0 -> 7.1
  [order_id=1]  amount: 6.37 -> 6.38
  [order_id=117]  amount: 32.4 -> 34.5
  [order_id=234]  amount: 59.8 -> 61.9
  [order_id=351]  amount: 87.2 -> 89.3
DIFF FOUND

最後のブロックが重要です。差分ツールなら 432 行が変更されたことを知らせますが、datadiffer はそのほとんどがドイツの注文であることまで知らせます。「何かが変わった」と「VAT の変更が適用された」の違いです。

インストール

pip install datadiffer                      # local files: Parquet, CSV, DuckDB
pip install 'datadiffer[snowflake]'         # + Snowflake
pip install 'datadiffer[postgres]'          # + Postgres
pip install 'datadiffer[mcp]'               # + MCP server for AI agents

使い方

# local files
datadiffer diff prod.parquet dev.parquet

# DuckDB
datadiffer diff prod.duckdb:orders dev.duckdb:orders

# Postgres (attached read-only)
datadiffer diff orders orders_v2 --source "postgresql://user@host:5432/db"

# Snowflake, or anything in datadiffer.toml (run `datadiffer init` first)
datadiffer diff wh::analytics.orders wh::analytics_dev.orders

# cross-source: warehouse vs. a local file
datadiffer diff wh::orders orders_snapshot.parquet

# machine-readable, for scripts and CI
datadiffer diff a.parquet b.parquet --format json

終了コードは GNU diff の規約に準拠しています。差分なしは 0、差分ありは 1、運用エラーは 2 です。

便利なフラグ：--key（省略時は推定）、--where、--columns ／ --exclude-columns、--sample-limit、--no-attribution、-q。

プルリクエストで使う

datadiffer-action は、レポートを固定表示の PR コメントとして投稿します。

datadiffer：ANALYTICS.ORDERS と ANALYTICS_PR_482.ORDERS の比較で差分が見つかりました ❌

+800 件追加 · −250 件削除 · ~432 件変更 · 49,318 件変更なし（基準行の 2.96% に影響） ポリシー：変更行の割合が上限を超過：2.96% > 0.5%

列	変更された行	一致行に対する割合
amount	432	0.87%

変化の集中箇所： 変更された行の 98.6% は country = 'DE' です（実際の割合の 8.87 倍） 追加された行の 93.2% は plan = NULL です（実際の割合の 63.19 倍）

- uses: gauthierpiarrette/datadiffer-action@v1
  with:
    config: datadiffer.toml          # holds the warehouse connection
    table-a: wh::ANALYTICS.ORDERS
    schema-map: "ANALYTICS=ANALYTICS_PR_${PR_NUMBER}"
    max-changed-rows-pct: "0.5"
  env:
    SNOWFLAKE_PRIVATE_KEY: ${{ secrets.SNOWFLAKE_PRIVATE_KEY }}

dbt を実行していますか？docs/dbt-ci.md を使うと、dbt ls --select state:modified を、変更されたモデルごとの個別の差分に変換し、それぞれに専用のコメントを付けます。

AI エージェント向け（MCP）

コーディングエージェントが自身のデータ変更を検証できるようにします。

datadiffer init          # scaffold datadiffer.toml, then add the server to your client

{ "mcpServers": { "datadiffer": { "command": "datadiffer", "args": ["mcp"] } } }

どの MCP クライアントでも使えます。datadiffer init は、貼り付けて使えるサーバー設定を出力します。グローバルインストール不要のクライアント向けに uvx 形式も含まれます。

読み取り専用ツールは 4 つです：list_connections、schema_diff、diff_summary（低コストの事前確認）、diff_tables（完全なレポート）。認証情報がモデルを経由することはありません。 ツールが受け取るのは、ローカルの datadiffer.toml に登録された接続名であり、DSN ではありません。上限を超えるリクエストには、修正方法を含む構造化された拒否が返されるため、エージェントは処理を失敗させずに自ら修正できます。

違い

ほとんどの差分ツールは、2 つのテーブルが一致するかどうかを答えます。datadiffer は、何がどこで変わったか、つまり、どの列が移動したのか、またデータのどの部分に変更が集中しているのかを示します。

ツール	こちらを使うケース
Datafold	数十億行のデータベース間照合、コラボレーション UI、リネージ／影響分析、サポート契約が必要な場合。
SQLMesh table_diff	すでに SQLMesh を実行していて、単一のゲートウェイ内で差分を取る場合（データベース間の差分は Tobiko Cloud の機能です）。
Recce	dbt ネイティブの PR レビュー UI を求めていて、ワークフロー全体が dbt の場合。
Google DVT	17 種類のウェアハウス間で移行を検証し、YAML 設定による合否判定を求めている場合。
datacompy	1 つのプロセス内で 2 つの pandas／Spark／Polars DataFrame を比較する場合。

datadiffer は、その中間のケース向けです。コマンド 1 つで、プラットフォームは不要です。ターミナル、CI、エージェントから使えて、結果の根拠も説明します。

data-diff / reladiff からの移行

用途は同じで、フラグが異なります。

data-diff / reladiff	datadiffer
data-diff DB1 table1 DB2 table2	datadiffer diff <a> <b>（ロケーター、または --source／--target）
-k、--key-columns	--key（複数回指定、またはカンマ区切り）
-c、--columns	--columns
-w、--where	--where（検証あり：単一のブール式。サブクエリは不可）
--json	--format json（安定した schema v1）
-l、--limit	--sample-limit

知っておくべき違い：--key を省略すると、宣言済みの制約または *_id の規則からキーが推定されます。フィルター内の不明な列名はエラーとなり、黙って無視されることはありません。また、終了コード 1 は「差分あり」を意味し（2 は運用エラー用です）、CI で区別できます。

まだ移植されていない機能： reladiff の主要機能である、非常に大規模なデータベース間差分向けのチェックサム二分探索 hashdiff と、MySQL、Oracle、ClickHouse、Trino、およびその他のコネクターです。現時点でこれらが必要な場合は、reladiff をお使いください。二分探索の移植は v0.2 ロードマップの最優先項目で、作者へのクレジットも記載します。

コマンドの完全な対応表と動作の違い： docs/migrating-from-data-diff.md。

対象範囲と制限（v0.1）

• ウェアハウス： Snowflake、Postgres、DuckDB、Parquet、CSV。次は BigQuery（v0.1.1）です。
• すべての差分処理はローカルの DuckDB で実行されます。 Postgres は読み取り専用でアタッチされ、その場でスキャンされます。Snowflake は必要な列のみを Arrow 経由で一度取得します。どちらも片側あたり 5,000 万行、10 GiB が上限のため、--where で比較対象を絞り込んでください。比較処理をウェアハウス内で実行することと、チェックサム二分探索によるこの上限の撤廃が、次の 2 つの作業項目です。
• Postgres の読み取りはスナップショットを使用しません（レポートの execution.snapshot にその旨が記載されます）。Snowflake の取得には、一貫性のある単一の SELECT を使用します。
• セグメントの帰属分析は単一列のカテゴリ別で、説明的なものです。因果関係は示さず、「過剰に表れている」と示します。

プロジェクト

MIT、CLA なし、テレメトリーなし。レポートスキーマ は v1 で固定され、契約テストも行われているため、それを解析するパイプラインやエージェントはリリース後も引き続き動作します。依存関係は意図的に少数に絞っています：DuckDB、PyArrow、sqlglot、click、rich。

今後の予定

まず BigQuery、次にチェックサム二分探索 hashdiff を実装し、大規模なデータベース間差分で行数上限が不要になるようにします（reladiff にクレジットを記載して移植します）。その後、コネクターを追加します。 issues で進捗を管理しています。必要な項目にコメントすると、優先順位が上がります。

コントリビューション

git clone https://github.com/gauthierpiarrette/datadiffer && cd datadiffer
uv sync --group dev
uv run pytest -q            # warehouse tests skip unless credentials are set
uv run ruff check .

先行する取り組みに感謝します。data-diff および reladiff（Erez Shinan）のチェックサム二分探索設計 v0.2 を移植します。また、帰属スコアリングを提供する Adtributor（Microsoft Research）と、これらすべてを十分に高速化し、当たり前のように使えるようにする DuckDB にも感謝します。

ライセンス

MIT