Repository navigation
docs(skill): document SQL writes through hotdata query - #354
Conversation
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
| `query` also writes: `INSERT`, `CREATE TABLE`, `CREATE TABLE AS` and | ||
| `DROP TABLE` run against the current database's own tables (API key with the | ||
| `write` permission) and print one row, `rows_affected`. `UPDATE`/`DELETE` are | ||
| not supported in SQL yet — use `hotdata load --mode update|delete|upsert`. |
There was a problem hiding this comment.
Replace hotdata load with hotdata databases load (or hotdata databases tables load). The CLI has no top-level load subcommand. src/cli.rs defines only auth, workspaces, databases, query, jobs, ingest, search, manage, support, usage, completions, upgrade, skills. A user who follows this line gets an unrecognized-subcommand error.
| not supported in SQL yet — use `hotdata load --mode update|delete|upsert`. | |
| not supported in SQL yet — use `hotdata databases load --mode update|delete|upsert`. |
| - **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; writes follow the same rules as `hotsql`) — details in **`hotdata-analytics`**. | ||
| - **SQL writes.** `query` runs `INSERT INTO t [(cols)] VALUES …|SELECT …` (append only), `CREATE TABLE t (col TYPE, …)`, `CREATE TABLE t AS SELECT …`, and `DROP TABLE [IF EXISTS] t` against the **current database's own tables**; attached databases stay read-only. The API key needs the `write` permission. The result is one row, `rows_affected`. Each `INSERT` is a full publish (write lock, new generation, index maintenance), so **batch rows into one statement** and use `hotdata load` for anything of size. Refused: `UPDATE`/`DELETE` (*"not supported yet"* — use `hotdata load --mode update|delete|upsert` by key), `INSERT OVERWRITE`/`OR REPLACE`/`ON CONFLICT`/`RETURNING`, column constraints on `CREATE TABLE` (`NOT NULL`, `DEFAULT`, `PRIMARY KEY`, `UNIQUE` — every column is nullable), `ALTER`, views, `COPY`, transactions. A table with a vector index must be inserted into with a column list that omits the generated embedding column. Table layout (`--key`, partition, sort) is declared with `databases tables add`, not in SQL. |
There was a problem hiding this comment.
Replace both hotdata load references with hotdata databases load. The CLI has no top-level load subcommand (src/cli.rs). The rest of this skill uses hotdata databases load (lines 123, 159–179). An agent that follows this bullet runs a command that fails with an unrecognized-subcommand error.
|
|
||
| - **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(...)`). Writes follow the same rules as `hotsql`. | ||
| - **Writes:** `INSERT` (append only), `CREATE TABLE`, `CREATE TABLE AS SELECT`, and `DROP TABLE` run through `query` against the current database's own tables and return one row, `rows_affected`; `UPDATE`/`DELETE` are not supported in SQL yet (use keyed `hotdata load --mode update|delete|upsert`). Rules and refusals in the **`hotdata`** skill → Execute SQL Query. |
There was a problem hiding this comment.
Replace hotdata load with hotdata databases load. The CLI has no top-level load subcommand (src/cli.rs). An agent that follows this bullet runs a command that fails with an unrecognized-subcommand error.
There was a problem hiding this comment.
Review — Blocking Issues
README.md:106,skills/hotdata/SKILL.md:273,skills/hotdata/subskills/analytics/SKILL.md:26: the docs namehotdata load. The CLI has no top-levelloadsubcommand (src/cli.rs). Users and agents that follow these lines get an unrecognized-subcommand error.
Action Required
Replace every hotdata load --mode update|delete|upsert with hotdata databases load --mode update|delete|upsert. The command hotdata databases tables load is also valid. The skill already uses hotdata databases load elsewhere (skills/hotdata/SKILL.md:123).
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
1 participant
hotdata querycan now run INSERT, CREATE TABLE, CREATE TABLE AS and DROP TABLE against the current database's own tables (runtimedb removed thesql_writesflag). Documents the rules and refusals in the README, the hotdata skill, and the analytics subskill. UPDATE/DELETE are documented as not supported yet, with keyedloadmodes as the alternative.