Run a read-only SQL query
queryUse this when the user asks a question about data they keep in LakehouseBox, or to check a table after changing it. Run ONE read-only DuckDB SQL statement on the server over the catalogs you can read (SELECT, WITH … SELECT, DESCRIBE, SUMMARIZE, EXPLAIN), in DuckDB's SQL dialect (https://duckdb.org/docs/stable/sql/introduction). Name tables catalog.namespace.table; another organisation's PUBLIC catalog by its alias, _ (open_public_catalog gives it, e.g. commons_pubdata.reference.countries), or "/" in double quotes when the alias is ambiguous or starts with a digit; name every table in full when one is public. Rows come back as one object per row keyed by column name (format='arrays': each row a list in columns order, about half the size, for long results); columns gives every column's name and type. DECIMAL values are numbers when a double holds them exactly (15 significant digits); longer decimals and integers past 2^53 come back as text, so no digit is lost. Results are capped (default 200 rows, at most 2,000, ~50,000 characters; truncated says so, max_rows_applied gives the cap used) and each query has 20 seconds of compute in one queue shared by every tenant (no quota): aggregate and filter in SQL rather than fetching raw rows. busy means the queue or a concurrency limit is full (limit names it), rate_limited that queries came too fast for one key: wait retry_after_seconds before sending again. Timestamps come back ISO 8601 in UTC. An answer that read tables names each one's snapshot and commit time (snapshots: how fresh the data is) and says whether it came from the result cache (cache.hit; cache.not_cached says why it was not kept): a repeat of a query on tables nobody has committed to since is answered from it, for at most 15 minutes, or 60 s when the query uses the clock (now(), current_date); system views and table functions always run. dry_run=true runs nothing and says what it would read (rows, files, bytes per table, an upper bound) and whether the cache would answer. Heavier work belongs in your own DuckDB (lhbox duckdb) when you can run commands and reach s3.lakehousebox.com; an answer that hit a limit carries local_compute, what to tell the person when you cannot.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| sql | Yes | one read-only statement in DuckDB SQL (https://duckdb.org/docs/stable/sql/introduction) | |
| engine | No | DuckDB engine version: '1.5' (DuckDB 1.5.6, default) or '2.0' (DuckDB 2.0 preview) | |
| format | No | objects (default): each row an object keyed by column name, what dashboards, BI tools and most code read; arrays: each row a list in `columns` order, about half the size | objects |
| dry_run | No | true: run nothing; say which tables it reads with their rows, data files and bytes (an upper bound from the metadata) and whether the cache would answer it | |
| max_rows | No | rows to return (default 200, at most 2000) |