Add diff-queries command to list queryable tables and SQL templates for a diff run

Author: luisggoncalves

README.md

@@ -58,12 +58,11 @@ That command prints a **diff_id**. Use it for follow-up analysis:
 sqlcompare inspect <diff_id> --stats
 sqlcompare inspect <diff_id> --column revenue --limit 100
 sqlcompare inspect <diff_id> --missing-current
+sqlcompare diff-queries <diff_id>
 sqlcompare inspect <diff_id> --save summary
 sqlcompare inspect <diff_id> --save complete --file-path ./reports/full_diff.xlsx
 ```
 
----
-
 ## Inspect report export (XLSX)
 
 You can export inspect results as a multi-tab Excel report using `--save`.
@@ -94,6 +93,23 @@ Notes:
 
 ---
 
+## diff-queries (AI-friendly metadata)
+
+Use `diff-queries` to get a JSON payload describing the queryable tables and ready-to-run SQL templates for a given `diff_id`. This is especially useful for AI agents that need structured context before running analysis queries.
+
+```bash
+sqlcompare diff-queries <diff_id>
+```
+
+Output (JSON):
+
+* `diff_id`, `resolved_diff_id`, `connection`
+* `index_columns`, `common_columns`
+* `tables`: previous/current/join table names and their columns
+* `queries`: SQL templates for row-only checks and per-column diffs
+
+---
+
 ## Example outputs
 
 See [`examples/`](examples/) for datasets, commands, and captured outputs.

sqlcompare/cli.py

@@ -3,6 +3,7 @@
 import typer
 
 from sqlcompare.dataset import dataset_cmd
+from sqlcompare.diff_queries import diff_queries_cmd
 from sqlcompare.run_cmd import run_cmd
 from sqlcompare.inspect import inspect_cmd
 from sqlcompare.list_diffs import list_diffs_cmd
@@ -16,6 +17,7 @@
 app.command("table")(table_cmd)
 app.command("run")(run_cmd)
 app.command("inspect")(inspect_cmd)
+app.command("diff-queries")(diff_queries_cmd)
 app.command("stats")(stats_cmd)
 app.command("list-diffs")(list_diffs_cmd)
 app.command("query")(query_cmd)

sqlcompare/diff_queries.py

@@ -0,0 +1,176 @@
+from __future__ import annotations
+
+import json
+import typer
+
+from sqlcompare.analysis.utils import find_diff_file, find_diff_run, list_available_diffs
+from sqlcompare.log import log
+
+
+def list_diff_queries(diff_id: str) -> None:
+    """List queryable tables for a diff run along with their contents."""
+    run = find_diff_run(diff_id)
+    if not run:
+        diff_file = find_diff_file(diff_id)
+        if diff_file:
+            log.error(
+                "❌ Diff data found, but it is a pickle-based diff without queryable tables."
+            )
+        else:
+            log.error(f"❌ Diff data with ID '{diff_id}' not found.")
+        log.info("💡 Available diff IDs:")
+        list_available_diffs()
+        return
+
+    resolved_id = run.get("id", diff_id)
+    tables = run.get("tables")
+    if not tables:
+        log.error("❌ Diff metadata missing table definitions.")
+        return
+
+    conn_label = run.get("conn")
+    duckdb_file = run.get("duckdb_file")
+    if duckdb_file:
+        connection_display = f"duckdb:///{duckdb_file}"
+    else:
+        connection_display = conn_label or "(default connection)"
+
+    cols_prev = run.get("cols_prev", [])
+    cols_new = run.get("cols_new", [])
+    index_cols = run.get("index_cols", [])
+    common_cols = run.get("common_cols")
+
+    payload = _build_llm_payload(
+        diff_id=diff_id,
+        resolved_id=resolved_id,
+        connection_display=connection_display,
+        tables=tables,
+        cols_prev=cols_prev,
+        cols_new=cols_new,
+        index_cols=index_cols,
+        common_cols=common_cols,
+    )
+    log.info(json.dumps(payload, indent=2))
+
+
+def _format_columns(columns: list[str]) -> list[str]:
+    return columns
+
+
+def _build_llm_payload(
+    *,
+    diff_id: str,
+    resolved_id: str,
+    connection_display: str,
+    tables: dict[str, str],
+    cols_prev: list[str],
+    cols_new: list[str],
+    index_cols: list[str],
+    common_cols: list[str] | None,
+) -> dict[str, object]:
+    join_columns = [f"{col}_previous" for col in cols_prev] + [
+        f"{col}_new" for col in cols_new
+    ]
+    entries = [
+        {
+            "name": tables.get("previous"),
+            "role": "previous",
+            "content": "Previous dataset (original table)",
+            "columns": _format_columns(cols_prev),
+        },
+        {
+            "name": tables.get("new"),
+            "role": "current",
+            "content": "Current dataset (new table)",
+            "columns": _format_columns(cols_new),
+        },
+        {
+            "name": tables.get("join"),
+            "role": "join",
+            "content": "Full outer join on index columns with _previous/_new suffixes",
+            "columns": _format_columns(join_columns),
+        },
+    ]
+    queries = _build_queries(tables, index_cols)
+    return {
+        "diff_id": diff_id,
+        "resolved_diff_id": resolved_id,
+        "connection": connection_display,
+        "index_columns": index_cols,
+        "common_columns": common_cols or [],
+        "tables": entries,
+        "queries": queries,
+    }
+
+
+def _build_queries(tables: dict[str, str], index_cols: list[str]) -> list[dict[str, str]]:
+    join_table = tables.get("join")
+    if not join_table or not index_cols:
+        return []
+
+    prev_null_cond = " AND ".join([f'\"{c}_previous\" IS NULL' for c in index_cols])
+    new_null_cond = " AND ".join([f'\"{c}_new\" IS NULL' for c in index_cols])
+    idx_expr = ", ".join(
+        [f'COALESCE(\"{c}_new\", \"{c}_previous\") AS \"{c}\"' for c in index_cols]
+    )
+    col_placeholder = "<column>"
+    diff_cond = (
+        f'NOT (\"{col_placeholder}_previous\" = \"{col_placeholder}_new\" OR '
+        f'(\"{col_placeholder}_previous\" IS NULL AND \"{col_placeholder}_new\" IS NULL))'
+        f" AND NOT ({prev_null_cond}) AND NOT ({new_null_cond})"
+    )
+
+    def _query(name: str, sql: str) -> dict[str, str]:
+        return {"name": name, "sql": sql}
+
+    return [
+        _query(
+            "rows_only_in_current",
+            f"SELECT * FROM {join_table} WHERE {prev_null_cond};",
+        ),
+        _query(
+            "rows_only_in_previous",
+            f"SELECT * FROM {join_table} WHERE {new_null_cond};",
+        ),
+        _query(
+            "count_rows_only_in_current",
+            f"SELECT COUNT(*) AS rows_only_in_current FROM {join_table} WHERE {prev_null_cond};",
+        ),
+        _query(
+            "count_rows_only_in_previous",
+            f"SELECT COUNT(*) AS rows_only_in_previous FROM {join_table} WHERE {new_null_cond};",
+        ),
+        _query(
+            "rows_with_column_differences",
+            f"SELECT {idx_expr}, '{col_placeholder}' AS \"COLUMN\", "
+            f'CAST(\"{col_placeholder}_previous\" AS VARCHAR) AS \"BEFORE\", '
+            f'CAST(\"{col_placeholder}_new\" AS VARCHAR) AS \"CURRENT\" '
+            f"FROM {join_table} WHERE {diff_cond};",
+        ),
+        _query(
+            "count_column_differences",
+            f"SELECT COUNT(*) AS diff_count FROM {join_table} WHERE {diff_cond};",
+        ),
+        _query(
+            "top_10_diff_samples",
+            f"""SELECT {idx_expr}, "COLUMN", "BEFORE", "CURRENT"
+FROM (
+  SELECT {idx_expr}, '{col_placeholder}' AS "COLUMN",
+    CAST("{col_placeholder}_previous" AS VARCHAR) AS "BEFORE",
+    CAST("{col_placeholder}_new" AS VARCHAR) AS "CURRENT"
+  FROM {join_table} WHERE {diff_cond}
+) AS diffs
+LIMIT 10;""",
+        ),
+    ]
+
+
+def diff_queries_cmd(
+    diff_id: str = typer.Argument(..., help="Diff run ID"),
+) -> None:
+    """List queryable tables and SQL templates for a diff run.
+
+    Examples:
+        sqlcompare diff-queries <diff_id>
+    """
+    list_diff_queries(diff_id)

sqlcompare/table.py

@@ -101,7 +101,8 @@ def compare_table(
     )
     log.info(
         "💡 Tips: --stats for per-column counts, --missing-current/--missing-previous for row-only, "
-        "--column <name> to filter, --list-columns to inspect available fields."
+        "--column <name> to filter, --list-columns to inspect available fields, "
+        f"and sqlcompare diff-queries {diff_id} for queryable tables and SQL templates (useful for AI agents)."
     )
 
 

tests/test_cli_diff_queries.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import json
+
+from typer.testing import CliRunner
+
+from sqlcompare.cli import app
+from sqlcompare.config import load_test_runs
+from tests.cli_helpers import seed_duckdb, set_cli_env
+
+
+def _create_diff(tmp_path: Path, monkeypatch) -> str:
+    db_path = tmp_path / "sqlcompare.duckdb"
+    seed_duckdb(db_path)
+    config_dir = tmp_path / "config"
+    set_cli_env(
+        monkeypatch,
+        config_dir,
+        "duckdb_test",
+        f"duckdb:///{db_path}",
+    )
+    runner = CliRunner()
+    result = runner.invoke(
+        app,
+        [
+            "table",
+            "previous",
+            "current",
+            "id",
+            "--connection",
+            "duckdb_test",
+        ],
+    )
+    assert result.exit_code == 0, result.output
+    runs = load_test_runs()
+    assert len(runs) == 1
+    return next(iter(runs.keys()))
+
+
+def test_diff_queries_lists_queryable_tables(tmp_path, monkeypatch) -> None:
+    diff_id = _create_diff(tmp_path, monkeypatch)
+    runner = CliRunner()
+
+    result = runner.invoke(app, ["diff-queries", diff_id])
+    assert result.exit_code == 0, result.output
+    payload = json.loads(result.output)
+    assert payload["diff_id"] == diff_id
+    assert payload["tables"]
+    table_names = [entry["name"] for entry in payload["tables"]]
+    assert "previous" in table_names
+    assert "current" in table_names
+    assert any(name and name.endswith("_join") for name in table_names)
+    assert payload["index_columns"] == ["id"]
+    assert "name" in payload["common_columns"]
+    assert "value" in payload["common_columns"]
+    join_entry = next(entry for entry in payload["tables"] if entry["role"] == "join")
+    assert "id_previous" in join_entry["columns"]
+    assert "value_new" in join_entry["columns"]
+    assert payload["queries"]