From c24f897ced30c47b51b72d1c2b6829d874ec1c20 Mon Sep 17 00:00:00 2001 From: Eddie A Tejeda <669988+eddietejeda@users.noreply.github.com> Date: Tue, 13 Oct 2026 22:03:58 -0700 Subject: [PATCH] docs(query): dialect writes follow the same rules as hotsql --- README.md | 2 +- skills/hotdata/SKILL.md | 2 +- skills/hotdata/subskills/analytics/SKILL.md | 2 +- src/cli.rs | 3 ++- src/commands/databases.rs | 3 ++- 5 files changed, 7 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 121bddf..dc94993 100644 --- a/README.md +++ b/README.md @@ -87,7 +87,7 @@ hotdata query "" [-o table|json|csv] # HotSQL (PostgreSQL dialect) Write SQL in another dialect and the server transpiles it to HotSQL — `--dialect` accepts `hotsql` (default), `duckdb`, `postgres`, `snowflake` -(read-only for a non-default dialect): +(writes follow the same rules as `hotsql`): ```sh hotdata query "SELECT IFF(n > 0, 'pos', 'neg') FROM t" --dialect snowflake diff --git a/skills/hotdata/SKILL.md b/skills/hotdata/SKILL.md index 6c2651a..2b59281 100644 --- a/skills/hotdata/SKILL.md +++ b/skills/hotdata/SKILL.md @@ -264,7 +264,7 @@ hotdata databases query status - **`-o id`** prints only the query's stored `result_id` and downloads no rows — use it to feed `--result-id` loads: `RID=$(hotdata query "" -o id)`. Exits `1` if the query left no stored result. - **A query runs inside one instant database** (current database or `--database`); with none set it fails *"a database is required."* The scope sees the database's own catalog **plus whatever is attached to it only**. To read another database's tables or join across databases, attach it first — see [Querying across databases (attach)](#querying-across-databases-attach). - Use `hotdata databases tables list` and `hotdata databases tables show` for discovery — not `information_schema` via `query`. (Discovery lists every workspace table; queryability still requires the table's catalog to be in the current database's scope.) -- **PostgreSQL dialect.** Quote non-lowercase columns with double quotes. To write DuckDB/Postgres/Snowflake SQL instead, pass `--dialect` (server-side transpile, read-only queries) — details in **`hotdata-analytics`**. +- **PostgreSQL dialect.** Quote non-lowercase columns with double quotes. To write DuckDB/Postgres/Snowflake SQL instead, pass `--dialect` (server-side transpile; writes follow the same rules as `hotsql`) — details in **`hotdata-analytics`**. - Async runs return `query_run_id` → poll with `query status ` (do not re-run the same heavy SQL). `query status` exit codes: `0` succeeded, `1` failed, `2` still running (poll again), `3` succeeded but the result is a truncated/incomplete preview. - **Large results: `-o csv` / `-o json` are complete, `-o table` is capped.** The server returns inline rows only up to a bounded cap and persists the full set under a `result_id`. For `csv` and `json` the CLI **streams** that full result batch by batch, so output size is unbounded and memory stays flat — pipe a big result to a file with `-o csv`/`-o json`, never `table`. For `table` the CLI fetches at most **10,000 rows** and the footer says `N of TOTAL rows — INCOMPLETE PREVIEW` (with `?` when the server sent no total); the process exits **3** so a pipeline cannot mistake it for the whole set. Same rules for `hotdata databases results get`. A result the server is still writing is waited for (up to 5 minutes, honoring `Retry-After`) rather than returned partial. If the full result can't be retrieved, the CLI prints the inline preview, a `warning:` to stderr, and exits 3. `-o json` carries `row_count`, `total_row_count`, and `truncated` — branch on `truncated`, not on the row count. - **Numbers print exactly.** A `DECIMAL(38,2)` or other wide number is printed with every digit the service sent, in every output format; `-o json` emits it as an unquoted JSON number. One consequence: a list or struct cell prints on a single line in `-o json` (re-indenting would mean re-parsing and rounding it); scalars are unaffected. diff --git a/skills/hotdata/subskills/analytics/SKILL.md b/skills/hotdata/subskills/analytics/SKILL.md index 8eeb674..8c743dd 100644 --- a/skills/hotdata/subskills/analytics/SKILL.md +++ b/skills/hotdata/subskills/analytics/SKILL.md @@ -22,7 +22,7 @@ hotdata query status ``` - **PostgreSQL dialect.** Quote mixed-case identifiers: `"CustomerName"`. -- **`--dialect`** (default `hotsql`): write SQL in `duckdb`/`postgres`/`snowflake` and the server transpiles it to HotSQL before running (e.g. Snowflake `IFF(...)`, DuckDB `len(...)`). Read-only queries only for a non-`hotsql` dialect. +- **`--dialect`** (default `hotsql`): write SQL in `duckdb`/`postgres`/`snowflake` and the server transpiles it to HotSQL before running (e.g. Snowflake `IFF(...)`, DuckDB `len(...)`). Writes follow the same rules as `hotsql`. - Use **`hotdata databases tables list`** for schema discovery — not `information_schema` via `query`. - Fully qualified names: `..`, `..
`. - **Query scope:** every query runs inside one instant database (active or `--database`); it sees that database's own catalog plus whatever is **attached** to it only. To read another database's table, or **join your own table against one**, attach that database first: `hotdata databases attach ` — see **`hotdata`** skill → [Querying across databases](../../SKILL.md#querying-across-databases-attach). No instant database set → *"a database is required."* diff --git a/src/cli.rs b/src/cli.rs index 6b55c06..e7c6389 100644 --- a/src/cli.rs +++ b/src/cli.rs @@ -57,7 +57,8 @@ pub enum Commands { database: Option, /// SQL dialect the query is written in — a non-`hotsql` dialect is - /// transpiled to HotSQL server-side before it runs (read-only only) + /// transpiled to HotSQL server-side before it runs (writes follow the same + /// rules as hotsql) #[arg(long, default_value = "hotsql", value_parser = ["hotsql", "duckdb", "postgres", "snowflake"])] dialect: String, diff --git a/src/commands/databases.rs b/src/commands/databases.rs index e6cd393..aa638a8 100644 --- a/src/commands/databases.rs +++ b/src/commands/databases.rs @@ -282,7 +282,8 @@ pub enum DatabasesCommands { database: Option, /// SQL dialect the query is written in — a non-`hotsql` dialect is - /// transpiled to HotSQL server-side before it runs (read-only only) + /// transpiled to HotSQL server-side before it runs (writes follow the same + /// rules as hotsql) #[arg(long, default_value = "hotsql", value_parser = ["hotsql", "duckdb", "postgres", "snowflake"])] dialect: String,