Docs/AI Assistants (MCP)

Cross-source validation with federated queries

A real session run through DBConvert Streams MCP with Claude Haiku 4.5.

Scenario: You exported a PostgreSQL users table to Parquet last week. You want to know whether the export is still in sync with the live table, without loading the Parquet into a database first.

The conversation

You: I have a Postgres users table and a Parquet export of it from last week. Run a federated query joining the live table and the Parquet file, and find any rows present in one but missing from the other.

The AI:

  1. dbconvert_list_connections — finds the Postgres connection and the local-files connection
  2. dbconvert_describe_table — gets the live users schema
  3. dbconvert_get_file_schema — gets the Parquet schema
  4. dbconvert_explain_federated_select — sanity-checks the join plan
  5. dbconvert_run_federated_select — actually runs the diff

AI: Both sides have compatible id, email, created_at columns. The Parquet has 1,847 rows; the live table has 1,891. Diff:

  • 44 rows present in Postgres, missing from Parquet. These are all newer than the Parquet's max created_at, so they're new signups since the export.
  • 0 rows present in Parquet, missing from Postgres. No deletions.

The federated SQL I ran:

SELECT pg.id, pg.email, pg.created_at, 'in_pg_only' AS source
FROM pg1.public.users pg
LEFT JOIN read_parquet('users_2026_05_24.parquet') pq
     ON pg.id = pq.id
WHERE pq.id IS NULL
UNION ALL
SELECT pq.id, pq.email, pq.created_at, 'in_parquet_only' AS source
FROM read_parquet('users_2026_05_24.parquet') pq
LEFT JOIN pg1.public.users pg
     ON pq.id = pg.id
WHERE pg.id IS NULL;

If the export was meant to be a snapshot, this looks fine — just new arrivals. If it was meant to be the source of truth for downstream systems, you'll want to re-export.

What this demonstrates

  • DuckDB-backed federated SQL spans a live database and a local file in one query, no intermediate import.
  • The AI knows to use read_parquet() for file sources rather than trying to attach the file as a database.
  • The explain step happens automatically — you get a sanity check on the join plan before the actual scan.
  • File schemas are inspected via the same MCP tool surface as database tables.

What's next

PreviousExample: SQL explorationNextTools Reference