07 · Tables A→ZG · Read & explore
Run arbitrary SQL
Use execute_sql for joins, subqueries, CTEs, and window functions - with backtick-quoted names.
execute_sql runs raw SQL (powered by DataFusion) for anything
query_rows and aggregate
can't express - joins, subqueries, CTEs, window functions.
Query
SELECT p.`category`, COUNT(*) AS cnt
FROM `eddytor`.`cfg_xxx`.`<uuid>_products` p
WHERE p.`status` = 'active'
GROUP BY p.`category`
HAVING COUNT(*) > 5eddytor query "SELECT category, COUNT(*) AS cnt FROM \`eddytor\`.\`sales\`.\`orders\` GROUP BY category" --limit 100Quote every name component
Heads up
Backtick-quote each FQN component - the SQL is passed
straight to the engine untransformed, so an unquoted dot is a parse error.
Correct:
FROM `eddytor`.`cfg_xxx`.`products`. Wrong: FROM eddytor.cfg_xxx.products. Get exact names from
list_tables. (Over Flight SQL / ADBC,
identifiers use double quotes instead: "catalog"."schema"."table".)When to reach for it
| Need | Tool |
|---|---|
| Read with filters, sort, paginate | query_rows |
| Count / sum / avg with grouping | aggregate |
| Joins, subqueries, CTEs, windows | execute_sql |
execute_sql is read-oriented analysis - for mutations use
merge_rows.