Implementation:TobikoData Sqlmesh API Table Diff

Knowledge Sources	TobikoData_Sqlmesh
Domains	Web_Server, REST_API
Last Updated	2026-02-07 20:00 GMT

Overview

Concrete tool for computing table differences (schema and row-level) provided by the SQLMesh web server.

Description

This module exposes a FastAPI endpoint that calculates differences between two tables. It performs schema diff to identify added, removed, and modified columns, and row diff to compute statistics on data differences. The row diff includes column-level statistics, sample data showing differences, and source-only/target-only rows. The endpoint processes sample data into a column-centric structure for UI display, comparing cell values and filtering to non-identical rows.

Usage

This endpoint is called by the SQLMesh web UI when users compare table versions or validate plan changes. The schema diff helps users understand structural changes. The row diff with sample data allows users to review data-level differences before applying changes. The endpoint supports filtering by model/snapshot and WHERE clauses for targeted comparisons.

Code Reference

Source Location

Repository: TobikoData_Sqlmesh
File: web/server/api/endpoints/table_diff.py

Signature

@router.get("")
def get_table_diff(
    source: str,
    target: str,
    on: t.Optional[str] = None,
    model_or_snapshot: t.Optional[str] = None,
    where: t.Optional[str] = None,
    temp_schema: t.Optional[str] = None,
    limit: int = 20,
    context: Context = Depends(get_loaded_context),
) -> t.Optional[TableDiff]

Import

from web.server.api.endpoints.table_diff import router

I/O Contract

Inputs

Endpoint	Method	Parameters	Description
/api/table_diff	GET	source, target, on, model_or_snapshot, where, temp_schema, limit	Computes schema and row differences between tables

Outputs

Endpoint	Response Type	Description
/api/table_diff	TableDiff	Schema diff, row diff with stats, and processed sample data

Usage Examples

# Compare two tables
import httpx
response = httpx.get(
    "http://localhost:8000/api/table_diff",
    params={
        "source": "dev.my_schema.my_model",
        "target": "prod.my_schema.my_model",
        "on": "id",
        "limit": 50
    }
)
diff = response.json()
# {
#   "schema_diff": {
#     "added": ["new_column"],
#     "removed": ["old_column"],
#     "modified": {"column_name": {"old_type": "INT", "new_type": "BIGINT"}}
#   },
#   "row_diff": {
#     "source_count": 1000,
#     "target_count": 1050,
#     "count_pct_change": 5.0,
#     "stats": {...},
#     "processed_sample_data": {
#       "column_differences": [...],
#       "source_only": [...],
#       "target_only": [...]
#     }
#   }
# }

# Compare with WHERE filter
response = httpx.get(
    "http://localhost:8000/api/table_diff",
    params={
        "source": "table_v1",
        "target": "table_v2",
        "on": "user_id",
        "where": "created_at >= '2024-01-01'"
    }
)

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment