From 872b06ffae7de77e60903af64be8475efe4a6981 Mon Sep 17 00:00:00 2001 From: ZdenekSrotyr Date: Sat, 11 Apr 2026 11:11:10 +0200 Subject: [PATCH] docs: add hybrid query usage instructions to CLAUDE.md Co-Authored-By: Claude Opus 4.6 (1M context) --- CLAUDE.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index 96eb49e..1f17e78 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -154,6 +154,22 @@ Before computing any business metric, look up the canonical definition: Never invent metric calculations — always use the canonical definitions. +## Hybrid Queries (BigQuery + Local) + +For tables too large to sync locally, use hybrid queries that JOIN local data with on-demand BigQuery results: + +```bash +da query --sql "SELECT o.*, t.views FROM orders o JOIN traffic t ON o.date = t.date" \ + --register-bq "traffic=SELECT date, SUM(views) as views FROM dataset.web WHERE date > '2026-01-01' GROUP BY 1" +``` + +The `--register-bq` flag executes a BigQuery subquery, loads the result into memory, and makes it available as a DuckDB view for the final SQL. Multiple `--register-bq` flags can be used for multiple BQ sources. + +For complex SQL, use stdin mode: +```bash +echo '{"register_bq": {"traffic": "SELECT ..."}, "sql": "SELECT ..."}' | da query --stdin +``` + ## Extensibility ### Data Sources (extract.duckdb contract)