From 6f8122825c40e6cb97abc7364ccd766bcec07317 Mon Sep 17 00:00:00 2001 From: Eddie A Tejeda <669988+eddietejeda@users.noreply.github.com> Date: Mon, 24 Aug 2026 17:42:11 -0700 Subject: [PATCH 1/2] docs: rename user-facing term "managed database" to "instant database" Help text, README, skill docs, and code comments now say "instant database(s)". Command names, flags, and server wire-format values (e.g. the managed_load job type) and Rust identifiers keep the existing "managed" naming intentionally. --- CHANGELOG.md | 6 ++ README.md | 14 ++--- skills/hotdata/SKILL.md | 42 +++++++------- .../hotdata/references/DATA_MODEL.template.md | 8 +-- skills/hotdata/references/MODEL_BUILD.md | 14 ++--- skills/hotdata/references/WORKFLOWS.md | 26 ++++----- skills/hotdata/subskills/analytics/SKILL.md | 8 +-- .../analytics/references/WORKFLOWS.md | 6 +- skills/hotdata/subskills/geospatial/SKILL.md | 4 +- skills/hotdata/subskills/search/SKILL.md | 4 +- .../subskills/search/references/INDEXES.md | 6 +- src/cli.rs | 4 +- src/client/ingest.rs | 4 +- src/client/sdk.rs | 4 +- src/commands/connections.rs | 4 +- src/commands/databases.rs | 56 +++++++++---------- src/commands/datasource.rs | 4 +- src/commands/indexes.rs | 34 +++++------ src/commands/ingest.rs | 2 +- src/commands/query.rs | 4 +- src/commands/search.rs | 12 ++-- tests/common/mod.rs | 2 +- tests/query_async_polling.rs | 2 +- 23 files changed, 138 insertions(+), 132 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 84246b1..4d998e7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,9 @@ +## [Unreleased] + +### πŸ“š Documentation + +- Rename the user-facing term "managed database" to "instant database" across help text, README, and skill docs. Command names, flags, and server wire-format values (such as the `managed_load` job type) are intentionally unchanged. + ## [0.27.1] - 2026-08-22 ### πŸ› Bug Fixes diff --git a/README.md b/README.md index fa8bf1e..fc78a14 100644 --- a/README.md +++ b/README.md @@ -37,7 +37,7 @@ hotdata databases load --catalog demo --table trips \ hotdata query "SELECT count(*) FROM demo.public.trips" ``` -The core loop: create a **managed database**, put data in it, query it with +The core loop: create an **instant database**, put data in it, query it with PostgreSQL-dialect SQL. Everything else builds on that. ## Getting your data in @@ -62,7 +62,7 @@ hotdata ingest run --wait # show one attempt; exits 0 don ``` `ingest sources update-config` rotates credentials; `ingest pause|resume|schedule` -control a scheduled ingest. Data lands in a managed database β€” query it like any +control a scheduled ingest. Data lands in an instant database β€” query it like any other. ## Query and explore @@ -88,7 +88,7 @@ with `hotdata databases queries list`. ## Join across sources -Attach another catalog to a managed database and join its live tables directly, +Attach another catalog to an instant database and join its live tables directly, no copying: ```sh @@ -134,10 +134,10 @@ The full command surface. The top level has eight groups β€” `auth`, `workspaces | `auth status` | Show authentication status | | `workspaces list` | List all workspaces | | `workspaces use` | Set the default workspace | -| `databases list` | List managed databases in the workspace | -| `databases count` | Count managed databases in the workspace | -| `databases show` | Show details for a managed database | -| `databases create` | Create a new managed database | +| `databases list` | List instant databases in the workspace | +| `databases count` | Count instant databases in the workspace | +| `databases show` | Show details for an instant database | +| `databases create` | Create a new instant database | | `databases fork` | Fork a database into a new, independent database | | `databases attach` | Attach a catalog so its tables are queryable | | `databases detach` | Detach a previously attached catalog | diff --git a/skills/hotdata/SKILL.md b/skills/hotdata/SKILL.md index 2eba602..ea1301f 100644 --- a/skills/hotdata/SKILL.md +++ b/skills/hotdata/SKILL.md @@ -1,6 +1,6 @@ --- name: hotdata -description: Use this skill when the user wants to run core hotdata CLI commands β€” auth, workspaces, managed databases, tables, basic SQL query, database context (context:DATAMODEL), jobs, datasources/ingests/runs (pull external data), and skill install. Activate for "run hotdata", "list workspaces", "list databases", "managed database", "load parquet", "list tables", "show table columns", "execute a query", "database context", "context:DATAMODEL", "ingest", "datasource", "ingest run", "show a run", "schedule an ingest", "import data from", "connect a data source", "connector", "pull data from postgres/mysql/an API/S3 buckets/Iceberg", or general Hotdata CLI usage. This skill bundles three specialized guides under subskills/, loaded on demand: read subskills/search/SKILL.md for full-text/vector search and retrieval indexes, subskills/analytics/SKILL.md for OLAP analytics, query history, stored results, and Chain materializations, and subskills/geospatial/SKILL.md for geospatial/GIS. +description: Use this skill when the user wants to run core hotdata CLI commands β€” auth, workspaces, instant databases, tables, basic SQL query, database context (context:DATAMODEL), jobs, datasources/ingests/runs (pull external data), and skill install. Activate for "run hotdata", "list workspaces", "list databases", "instant database", "load parquet", "list tables", "show table columns", "execute a query", "database context", "context:DATAMODEL", "ingest", "datasource", "ingest run", "show a run", "schedule an ingest", "import data from", "connect a data source", "connector", "pull data from postgres/mysql/an API/S3 buckets/Iceberg", or general Hotdata CLI usage. This skill bundles three specialized guides under subskills/, loaded on demand: read subskills/search/SKILL.md for full-text/vector search and retrieval indexes, subskills/analytics/SKILL.md for OLAP analytics, query history, stored results, and Chain materializations, and subskills/geospatial/SKILL.md for geospatial/GIS. version: 0.27.1 --- @@ -69,11 +69,11 @@ These are **patterns** built from the commands belowβ€”not separate CLI subcomma - **History / Chain / OLAP SQL** β€” See **`hotdata-analytics`** and [references/WORKFLOWS.md](references/WORKFLOWS.md). - **Search / retrieval indexes** β€” See **`hotdata-search`**. -Catalog, skill decision tree, epic flows (onboard, chain, retrieval), and managed databases: [references/WORKFLOWS.md](references/WORKFLOWS.md). +Catalog, skill decision tree, epic flows (onboard, chain, retrieval), and instant databases: [references/WORKFLOWS.md](references/WORKFLOWS.md). ## Available Commands -Top-level subcommands (each detailed below): **`auth`**, **`query`**, **`workspaces`**, **`databases`**, **`jobs`**, **`ingest`**, **`search`**, **`manage`**. Managed databases nest `databases tables`, `databases queries`, `databases results`, and `databases context`; `ingest` nests `ingest sources`, runs, and logs; `manage` nests `usage`, `completions`, `upgrade`, and `skills`. Search (bm25/vector), indexes, and embedding providers are documented in **`hotdata-search`**; query history, results, Chain, and OLAP patterns in **`hotdata-analytics`**. +Top-level subcommands (each detailed below): **`auth`**, **`query`**, **`workspaces`**, **`databases`**, **`jobs`**, **`ingest`**, **`search`**, **`manage`**. Instant databases nest `databases tables`, `databases queries`, `databases results`, and `databases context`; `ingest` nests `ingest sources`, runs, and logs; `manage` nests `usage`, `completions`, `upgrade`, and `skills`. Search (bm25/vector), indexes, and embedding providers are documented in **`hotdata-search`**; query history, results, Chain, and OLAP patterns in **`hotdata-analytics`**. Global CLI options: **`--api-key`**, **`-v` / `--version`**, **`-h` / `--help`**, **`--no-input`** (disable interactive prompts; commands that require input will error instead β€” useful in CI or non-TTY environments). Hidden developer flag: **`--debug`** (verbose HTTP logs). @@ -83,9 +83,9 @@ hotdata workspaces list [--output table|json|yaml] ``` Returns workspaces with `public_id`, `name`, `active`, `favorite`, `provision_status`. Table output marks the default workspace with `*`. -### Managed databases (`databases`) +### Instant databases (`databases`) -**Managed databases** are Hotdata-owned catalogs you create and populate yourself β€” no remote source to sync. Query them in SQL as **`..`**. Prefer **`hotdata databases`** for this workflow. +**Instant databases** are Hotdata-owned catalogs you create and populate yourself β€” no remote source to sync. Query them in SQL as **`..
`**. Prefer **`hotdata databases`** for this workflow. **Parquet only:** `databases tables load` accepts **parquet** files (local `--file`, remote `--url`, or a pre-staged `--upload-id`). @@ -116,19 +116,19 @@ hotdata databases tables load
[--database ] [--schema public] (--fil hotdata databases tables remove
[--database ] [--schema public] [--workspace-id ] ``` -- `list` β€” all managed databases in the workspace. Active database is marked with `*` under the DEFAULT column; CREATED shows when each database was made. -- `count` β€” the total number of managed databases in the workspace, across **all** pages (`list` shows one page). Prints a bare integer by default so it drops straight into scripts (`$(hotdata databases count)`); `--output json|yaml` render `{"count": N}` / `count: N`. -- `create` β€” creates a new managed database. `--name` is an optional human-readable display name. `--catalog` sets the SQL alias used in queries (`SELECT … FROM .schema.table`); must be `[a-z_][a-z0-9_]*`. `--expires-at` accepts relative durations (`24h`, `7d`, `90m`) or an RFC 3339 timestamp; omitting means no expiry. Repeat `--table` to declare tables up front. -- `fork` β€” creates a new managed database that is an independent deep copy of an existing one (same schemas, tables, and data); the source is left unchanged and the two diverge freely afterwards. The source defaults to the active database; pass the database `` to fork another. `--name` defaults to `-fork` (so the two stay distinguishable in `list`); `--expires-at` accepts a relative duration or RFC 3339 timestamp, and when omitted a still-future source expiry is carried over. The fork becomes the active database on success. The fork answers to the **same catalog alias** as its source inside its own scope; catalogs attached to the source are **re-attached** to the fork, but indexes are **not** carried over. Only databases created with the current (DuckLake) storage engine can be forked β€” older parquet-backed databases return an error. +- `list` β€” all instant databases in the workspace. Active database is marked with `*` under the DEFAULT column; CREATED shows when each database was made. +- `count` β€” the total number of instant databases in the workspace, across **all** pages (`list` shows one page). Prints a bare integer by default so it drops straight into scripts (`$(hotdata databases count)`); `--output json|yaml` render `{"count": N}` / `count: N`. +- `create` β€” creates a new instant database. `--name` is an optional human-readable display name. `--catalog` sets the SQL alias used in queries (`SELECT … FROM .schema.table`); must be `[a-z_][a-z0-9_]*`. `--expires-at` accepts relative durations (`24h`, `7d`, `90m`) or an RFC 3339 timestamp; omitting means no expiry. Repeat `--table` to declare tables up front. +- `fork` β€” creates a new instant database that is an independent deep copy of an existing one (same schemas, tables, and data); the source is left unchanged and the two diverge freely afterwards. The source defaults to the active database; pass the database `` to fork another. `--name` defaults to `-fork` (so the two stay distinguishable in `list`); `--expires-at` accepts a relative duration or RFC 3339 timestamp, and when omitted a still-future source expiry is carried over. The fork becomes the active database on success. The fork answers to the **same catalog alias** as its source inside its own scope; catalogs attached to the source are **re-attached** to the fork, but indexes are **not** carried over. Only databases created with the current (DuckLake) storage engine can be forked β€” older parquet-backed databases return an error. - `use` β€” saves the database **id** as the active database. Subsequent `databases tables` and `databases context` commands use it automatically. Note that a successful `fork` also updates this: the fork becomes the active database. - `unset` β€” clears the active database from config. - `` β€” inspect one database (returns id, catalog, name, expires_at). -- `remove` β€” removes the managed database; clears the active-database config if it matched. +- `remove` β€” removes the instant database; clears the active-database config if it matched. - `load` (top-level shorthand) β€” loads parquet into `--catalog.--schema.--table`. Accepts `--file`, `--url`, `--upload-id`, or `--result-id` (load a saved query result by id β€” from `hotdata databases results` or a query's `[result-id: …]` footer β€” instead of a file; the result must belong to the target database). If the table was not declared at create time, the CLI automatically deletes and recreates the database with the table declared, then retries the load. - `tables list` β€” lists tables with `TABLE` (`..
`), `SYNCED`, `LAST_SYNC`. Uses active database when `--database` is omitted. -- `tables load` β€” publishes to a managed-database table (with **replace** mode) from a local parquet file (`--file`), a remote parquet URL (`--url`), a pre-staged upload (`--upload-id`), or a saved query result (`--result-id`, must belong to the target database). -- `tables remove` β€” drops a table from the managed database. -- `attach` β€” attaches a **catalog** to a managed database, so the catalog's **live** tables become visible inside that database's query scope. Defaults to the active database; target another with `--database`. `--alias` sets the SQL name the catalog answers to (defaults to the catalog's name). This is how you query an attached catalog's tables and **join across catalogs** β€” see [Querying across catalogs](#querying-across-catalogs-attach). +- `tables load` β€” publishes to an instant-database table (with **replace** mode) from a local parquet file (`--file`), a remote parquet URL (`--url`), a pre-staged upload (`--upload-id`), or a saved query result (`--result-id`, must belong to the target database). +- `tables remove` β€” drops a table from the instant database. +- `attach` β€” attaches a **catalog** to an instant database, so the catalog's **live** tables become visible inside that database's query scope. Defaults to the active database; target another with `--database`. `--alias` sets the SQL name the catalog answers to (defaults to the catalog's name). This is how you query an attached catalog's tables and **join across catalogs** β€” see [Querying across catalogs](#querying-across-catalogs-attach). - `detach` β€” removes an attached catalog. Accepts the catalog name/id **or** the alias you attached it under. Defaults to the active database. - `create --attach [=]` β€” attach one or more catalogs at creation time (repeatable), e.g. `--attach github --attach salesdb=sales`. @@ -142,9 +142,9 @@ hotdata query "SELECT count(*) FROM airbnb.public.listings" #### Querying across catalogs (attach) -**A `hotdata query` runs inside exactly one managed database** β€” the active database (`hotdata databases use `) or the one named by `--database`. With none set, the query fails with *"a database is required."* That database's query scope sees **only its own catalog plus any catalogs explicitly attached to it** β€” a workspace catalog is **not** visible just because it exists. Referencing an unattached catalog fails with *"table '\.\.\' not found."* +**A `hotdata query` runs inside exactly one instant database** β€” the active database (`hotdata databases use `) or the one named by `--database`. With none set, the query fails with *"a database is required."* That database's query scope sees **only its own catalog plus any catalogs explicitly attached to it** β€” a workspace catalog is **not** visible just because it exists. Referencing an unattached catalog fails with *"table '\.\.\' not found."* -To query an attached catalog's tables, or **join a managed table against an attached catalog's table in one query**, attach the catalog to the database first. The catalog's data stays **live** (synced) β€” this is not a copy: +To query an attached catalog's tables, or **join an instant database's table against an attached catalog's table in one query**, attach the catalog to the database first. The catalog's data stays **live** (synced) β€” this is not a copy: ``` # Attach the 'github' catalog (live) to the active database under alias 'gh' @@ -153,7 +153,7 @@ hotdata databases attach github --alias gh # Now both the database's own tables and the attached catalog are in scope: hotdata query "SELECT * FROM gh.github.issues WHERE state = 'OPEN' LIMIT 10" -# Cross-catalog join: a managed table JOINed against the live attached-catalog table +# Cross-catalog join: an instant database's table JOINed against the live attached-catalog table hotdata query " SELECT t.id, i.title FROM mycatalog.public.tickets t @@ -181,7 +181,7 @@ hotdata databases tables show [--output tabl **`databases tables show`** - Fetches column definitions (`COLUMN`, `DATA_TYPE`, `NULLABLE`) for a single table. -- **`catalog.schema.table`** β€” three-part form; the catalog resolves to a managed database or an attached source by name. +- **`catalog.schema.table`** β€” three-part form; the catalog resolves to an instant database or an attached source by name. - **`schema.table`** β€” two-part form; uses the active database (errors if none is set). - Copy the name directly from `databases tables list` output β€” both forms match what `list` prints. - **Always use `databases tables show` to inspect columns before writing queries.** @@ -212,7 +212,7 @@ hotdata query status ``` - Default output is `table` (row count and execution time). -- **A query runs inside one managed database** (active database or `--database`); with none set it fails *"a database is required."* The scope sees the database's own catalog **plus any attached catalogs only**. To query an attached catalog's tables or join across catalogs, attach the catalog first β€” see [Querying across catalogs (attach)](#querying-across-catalogs-attach). +- **A query runs inside one instant database** (active database or `--database`); with none set it fails *"a database is required."* The scope sees the database's own catalog **plus any attached catalogs only**. To query an attached catalog's tables or join across catalogs, attach the catalog first β€” see [Querying across catalogs (attach)](#querying-across-catalogs-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 active database's scope.) - **PostgreSQL dialect.** Quote non-lowercase columns with double quotes. - 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. @@ -233,7 +233,7 @@ hotdata jobs [--workspace-id ] [--output table|json|yaml] ### Ingest external data (`ingest sources`, `ingest`) -Pull data from external sources (SQL databases, APIs, S3/GCS/Azure buckets, Iceberg catalogs, Kafka) into managed databases. **Three nouns, three ids, and an id is always what goes on the wire** β€” the service has no name lookup, because a display name is a label and nothing stops two rows sharing one: +Pull data from external sources (SQL databases, APIs, S3/GCS/Azure buckets, Iceberg catalogs, Kafka) into instant databases. **Three nouns, three ids, and an id is always what goes on the wire** β€” the service has no name lookup, because a display name is a label and nothing stops two rows sharing one: - **source** (`ds_…`) β€” what a credential opens: a server, a bucket root, a catalog, a cluster. Holds config + credentials, loads no data. Managed under `ingest sources`. - **ingest** (`ing_…`) β€” a saved load definition: `source + selector + destination + type/schedule`. One source can back many ingests. @@ -368,7 +368,7 @@ Agent tips: - Prefer `-o json` plus the `ingest run` exit codes for scripting; poll `ingest run` rather than holding a terminal open. - Tables print oldestβ†’newest; `-o json` is newest-first (`[0]` = latest). - Errors carry a stable code alongside the message, e.g. `HTTP 409: … (destination_table_conflict)`. Branch on the code, not the sentence. -- Once a run has succeeded, the destination is a regular managed DB: query it with `hotdata query --database "SELECT … FROM public.
"`. +- Once a run has succeeded, the destination is a regular instant DB: query it with `hotdata query --database "SELECT … FROM public.
"`. ### Usage ``` @@ -424,4 +424,4 @@ hotdata auth logout # Remove saved auth for the default profile ## Workflows -End-to-end recipes β€” onboard a workspace, run a query, build a managed database (parquet), chain/materialize, add retrieval indexes β€” live in [references/WORKFLOWS.md](references/WORKFLOWS.md). The command sections above are the per-command reference; the workflows stitch them into sequences. +End-to-end recipes β€” onboard a workspace, run a query, build an instant database (parquet), chain/materialize, add retrieval indexes β€” live in [references/WORKFLOWS.md](references/WORKFLOWS.md). The command sections above are the per-command reference; the workflows stitch them into sequences. diff --git a/skills/hotdata/references/DATA_MODEL.template.md b/skills/hotdata/references/DATA_MODEL.template.md index 026b9c9..3e7d514 100644 --- a/skills/hotdata/references/DATA_MODEL.template.md +++ b/skills/hotdata/references/DATA_MODEL.template.md @@ -52,7 +52,7 @@ For each business entity: Document safe join paths and caveats (fan-out, timing, different refresh cadence, type mismatches). -> A cross-catalog join runs inside one managed database; each catalog it touches must be **attached** to that database (`hotdata databases attach `) so its live tables are in query scope. Note here which catalogs a join requires attached, and the alias each is attached under. See **`hotdata`** skill β†’ Querying across catalogs. +> A cross-catalog join runs inside one instant database; each catalog it touches must be **attached** to that database (`hotdata databases attach `) so its live tables are in query scope. Note here which catalogs a join requires attached, and the alias each is attached under. See **`hotdata`** skill β†’ Querying across catalogs. ## Search & index summary (optional) @@ -60,9 +60,9 @@ Document safe join paths and caveats (fan-out, timing, different refresh cadence |-------|--------|--------------------------|--------------|-------| | | | | | | -_Use `hotdata search list` (no flags β€” covers catalog tables **and** managed databases; see **hotdata-search** skill). Record text/vector indexes here; sorted indexes for OLAP filters in **hotdata-analytics**._ +_Use `hotdata search list` (no flags β€” covers catalog tables **and** instant databases; see **hotdata-search** skill). Record text/vector indexes here; sorted indexes for OLAP filters in **hotdata-analytics**._ -## Managed databases (uploaded) +## Instant databases (uploaded) Catalog from `hotdata databases list` / `hotdata databases tables list`: @@ -72,7 +72,7 @@ Catalog from `hotdata databases list` / `hotdata databases tables list`: ## Derived tables (Chain) -Stable `.public.*` tables built for **Chain** workflows (materialized into managed databases): +Stable `.public.*` tables built for **Chain** workflows (materialized into instant databases): | Table name | Built from | Purpose | Owner / TTL | |------------|------------|---------|-------------| diff --git a/skills/hotdata/references/MODEL_BUILD.md b/skills/hotdata/references/MODEL_BUILD.md index 25236c0..cf8163f 100644 --- a/skills/hotdata/references/MODEL_BUILD.md +++ b/skills/hotdata/references/MODEL_BUILD.md @@ -10,14 +10,14 @@ Optional **deep pass** for a single authoritative markdown document stored as ** ## 1. Discover catalogs and tables -List the catalogs you can query β€” managed databases you own and any attached catalogs β€” and the tables they expose: +List the catalogs you can query β€” instant databases you own and any attached catalogs β€” and the tables they expose: ```bash -hotdata databases list # managed databases (catalogs you own) +hotdata databases list # instant databases (catalogs you own) hotdata databases tables list # every workspace table, as ..
``` -For each catalog, record its name and the tables it exposes. (Pulling *new* external data into a managed database is a separate step β€” see the `ingest sources` and `ingest` commands in the core skill.) +For each catalog, record its name and the tables it exposes. (Pulling *new* external data into an instant database is a separate step β€” see the `ingest sources` and `ingest` commands in the core skill.) --- @@ -31,14 +31,14 @@ A datasource's schema is discovered when it is added. If the source schema may h hotdata databases tables list --schema --table
``` -**Managed databases:** +**Instant databases:** ```bash hotdata databases list hotdata databases tables list ``` -Capture schema for each managed-database table (columns, types) from the table listing. +Capture schema for each instant-database table (columns, types) from the table listing. You can also re-check a datasource's discovered schema after enumeration if you suspect drift: @@ -95,7 +95,7 @@ Per table when you only need one: hotdata search list --schema --table
[-w ] ``` -Managed-database indexes are included in the no-flag whole-workspace `search list` (shown under the internal `__db_..
` label); narrow to one with `--schema` / `--table` as above. +Instant-database indexes are included in the no-flag whole-workspace `search list` (shown under the internal `__db_..
` label); narrow to one with `--schema` / `--table` as above. Note: @@ -113,7 +113,7 @@ This Markdown body is what you store as **context:DATAMODEL** (`hotdata database - **Overview** β€” Domains and what the workspace is for. - **Per catalog** β€” Optional subsection per source; for **deep** models, **repeat** one block per `catalog.schema.table` (grain, column table with name/type/nullable/PK-FK/notes, relationships, queryability, caveats)β€”the template’s single `####` heading is a pattern to copy for each table. -- **Managed databases** β€” Same treatment as catalog tables where relevant. +- **Instant databases** β€” Same treatment as catalog tables where relevant. - **Cross-catalog joins** β€” Keys, semantics, type caveats. - **Search / index summary** β€” Table, column, index status, intended use. diff --git a/skills/hotdata/references/WORKFLOWS.md b/skills/hotdata/references/WORKFLOWS.md index e86eba6..2a1dd8d 100644 --- a/skills/hotdata/references/WORKFLOWS.md +++ b/skills/hotdata/references/WORKFLOWS.md @@ -11,7 +11,7 @@ The `hotdata` skill is always loaded first (auth and workspace setup). The three | User goal | Skill | Key commands | |-----------|--------|----------------| | Login, workspaces, datasources, tables, context | **`hotdata`** | `auth`, `workspaces`, `ingest sources`, `ingest`, `databases tables`, `databases context` | -| Load parquet files into a managed database | **`hotdata`** | `databases create` + `databases load` | +| Load parquet files into an instant database | **`hotdata`** | `databases create` + `databases load` | | SQL analytics, aggregations, history, Chain | **`hotdata-analytics`** (`subskills/analytics/SKILL.md`) | `query`, `databases queries`, `databases results` | | BM25 / vector search, retrieval indexes | **`hotdata-search`** (`subskills/search/SKILL.md`) | `search`, `search create`, `search embeddings` | | Geospatial / PostGIS-style SQL | **`hotdata-geospatial`** (`subskills/geospatial/SKILL.md`) | `query` with `ST_*`, WKB columns | @@ -19,7 +19,7 @@ The `hotdata` skill is always loaded first (auth and workspace setup). The three | Concept | Where documented | |--------|------------------| | **Model** | This file β€” [Model](#model) | -| **Upload path (managed databases)** | This file β€” [Managed databases](#managed-databases) | +| **Upload path (instant databases)** | This file β€” [Instant databases](#instant-databases) | | **History / Chain** | **`hotdata-analytics`** β€” [WORKFLOWS.md](../subskills/analytics/references/WORKFLOWS.md) | | **Search indexes** | **`hotdata-search`** β€” [INDEXES.md](../subskills/search/references/INDEXES.md) | | **Epic flows** | This file β€” [Epic flows](#epic-flows) | @@ -42,14 +42,14 @@ End-to-end checklists. Use the linked sections for command detail and guardrails 6. [ ] (Optional) `hotdata databases context list` β€” if `DATAMODEL` is listed, `hotdata databases context show DATAMODEL`; else skip `show` 7. [ ] (Optional) Bootstrap **context:DATAMODEL** β€” [Model](#model), [DATA_MODEL.template.md](DATA_MODEL.template.md) -**Next:** upload data ([Managed databases](#managed-databases)) or run analytics (**Chain** below). +**Next:** upload data ([Instant databases](#instant-databases)) or run analytics (**Chain** below). ### Chain (materialize then query) **Skill:** **`hotdata-analytics`** (catalog via **`hotdata`**) 1. [ ] Run base SQL: `hotdata query "SELECT …"` β€” poll `hotdata query status ` if async -2. [ ] Materialize into a managed database: `hotdata databases create --catalog --table ` then `hotdata databases load --catalog --table --file ./….parquet` +2. [ ] Materialize into an instant database: `hotdata databases create --catalog --table ` then `hotdata databases load --catalog --table --file ./….parquet` 3. [ ] Query with the catalog-qualified name `.public.` 4. [ ] Chain: `hotdata query "SELECT … FROM .public. WHERE …"` 5. [ ] Record stable chains in **context:DATAMODEL** when they should outlive the session @@ -63,7 +63,7 @@ End-to-end checklists. Use the linked sections for command detail and guardrails 1. [ ] `hotdata databases tables list` (filter with `--schema`/`--table`) β€” pick text column (BM25) or embedding/text column (vector) 2. [ ] `hotdata search list` β€” avoid duplicate text/vector indexes on the same column 3. [ ] Create index (address by name): - - [ ] **Managed DB only:** `hotdata search create _--type text --from .public. --column ` (vector: `--type vector [--provider

]`). An external catalog must be attached to a managed database first (`hotdata databases attach`). + - [ ] **Instant DB only:** `hotdata search create _

--type text --from .public. --column ` (vector: `--type vector [--provider

]`). An external catalog must be attached to an instant database first (`hotdata databases attach`). - [ ] Large build: add `--async`, then `hotdata jobs ` 4. [ ] Search (address the index by name): - [ ] `hotdata search "…" --index _

` @@ -75,9 +75,9 @@ End-to-end checklists. Use the linked sections for command detail and guardrails **Skill:** **`hotdata`** -A `hotdata query` runs inside **one** managed database; its scope sees that database's own catalog plus **attached** catalog catalogs only. To query a catalog's tables β€” or join a managed table against a live catalog table in one query β€” attach the catalog. (No managed database set β†’ *"a database is required."*; an unattached catalog β†’ *"table not found."*) +A `hotdata query` runs inside **one** instant database; its scope sees that database's own catalog plus **attached** catalog catalogs only. To query a catalog's tables β€” or join an instant database's table against a live catalog table in one query β€” attach the catalog. (No instant database set β†’ *"a database is required."*; an unattached catalog β†’ *"table not found."*) -1. [ ] Pick/create the managed database that will be the query context (`hotdata databases use ` or `databases create --catalog `) +1. [ ] Pick/create the instant database that will be the query context (`hotdata databases use ` or `databases create --catalog `) 2. [ ] Attach the catalog(s) you need (live, sync intact): `hotdata databases attach [--alias ]` - Or attach at creation: `hotdata databases create --catalog --attach [=]` 3. [ ] Confirm scope: `hotdata databases ` lists attached catalogs @@ -88,11 +88,11 @@ A `hotdata query` runs inside **one** managed database; its scope sees that data --- -## Managed databases +## Instant databases -**Managed databases** land queryable tables you own in the workspace, addressed in SQL as `..
` where the catalog is the `--catalog` alias. +**Instant databases** land queryable tables you own in the workspace, addressed in SQL as `..
` where the catalog is the `--catalog` alias. -| | **Managed databases** | +| | **Instant databases** | |---|------------------------| | **Best for** | Parquet files you own; catalog-style `alias.schema.table` | | **SQL prefix** | `..
` where catalog = `--catalog` alias | @@ -101,9 +101,9 @@ A `hotdata query` runs inside **one** managed database; its scope sees that data | **Parquet file uploads** | `databases load --file` / `--url` / `--upload-id` | | **Refresh** | Replace via `databases load` again | -**Rule of thumb:** Parquet files you control as **`mydb.public.orders`** β†’ **managed databases**. +**Rule of thumb:** Parquet files you control as **`mydb.public.orders`** β†’ **instant databases**. -### Workflow: managed database (parquet) +### Workflow: instant database (parquet) 1. Create the database with a catalog alias: @@ -127,7 +127,7 @@ A `hotdata query` runs inside **one** managed database; its scope sees that data hotdata query "SELECT count(*) FROM sales.public.orders" ``` -For **Chain** materializations into managed databases, see **`hotdata-analytics`**. +For **Chain** materializations into instant databases, see **`hotdata-analytics`**. ### Workflow: fork before risky changes diff --git a/skills/hotdata/subskills/analytics/SKILL.md b/skills/hotdata/subskills/analytics/SKILL.md index 648b58f..5b8f19a 100644 --- a/skills/hotdata/subskills/analytics/SKILL.md +++ b/skills/hotdata/subskills/analytics/SKILL.md @@ -1,6 +1,6 @@ --- name: hotdata-analytics -description: Use this skill when the user wants OLAP-style SQL analytics in Hotdata β€” aggregations, GROUP BY, JOINs, reporting, exploratory queries, query run history, stored results, or materialized follow-up tables (Chain into managed databases). Activate for "analyze", "aggregate", "rollup", "pivot", "report", "metrics", "GROUP BY", "query history", "past queries", "query runs", "stored results", "materialize", "chain", "intermediate table", or sorted indexes for filters/range scans. Do not load for BM25/vector search or geospatial SQL β€” use hotdata-search or hotdata-geospatial. Requires the core hotdata skill for tables and auth. +description: Use this skill when the user wants OLAP-style SQL analytics in Hotdata β€” aggregations, GROUP BY, JOINs, reporting, exploratory queries, query run history, stored results, or materialized follow-up tables (Chain into instant databases). Activate for "analyze", "aggregate", "rollup", "pivot", "report", "metrics", "GROUP BY", "query history", "past queries", "query runs", "stored results", "materialize", "chain", "intermediate table", or sorted indexes for filters/range scans. Do not load for BM25/vector search or geospatial SQL β€” use hotdata-search or hotdata-geospatial. Requires the core hotdata skill for tables and auth. version: 0.27.1 --- @@ -25,7 +25,7 @@ hotdata query status - **`--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. - Use **`hotdata databases tables list`** for schema discovery β€” not `information_schema` via `query`. - Fully qualified names: `..
`, `..
`. -- **Query scope:** every query runs inside one managed database (active or `--database`); it sees that database's own catalog plus **attached** catalogs only. To query an attached catalog's table, or **join a managed table against an attached catalog's table**, attach the catalog first: `hotdata databases attach ` β€” see **`hotdata`** skill β†’ [Querying across catalogs](../../SKILL.md#querying-across-catalogs-attach). No managed database set β†’ *"a database is required."* +- **Query scope:** every query runs inside one instant database (active or `--database`); it sees that database's own catalog plus **attached** catalogs only. To query an attached catalog's table, or **join an instant database's table against an attached catalog's table**, attach the catalog first: `hotdata databases attach ` β€” see **`hotdata`** skill β†’ [Querying across catalogs](../../SKILL.md#querying-across-catalogs-attach). No instant database set β†’ *"a database is required."* - Long-running queries may return `query_run_id` β†’ poll with **`query status`** (exit `2` = still running). Do not re-run identical heavy SQL while polling. - For **workspace-wide** joins and naming, load **context:DATAMODEL** when listed (`hotdata databases context list` β†’ `show DATAMODEL`) β€” see **`hotdata`** skill. @@ -34,7 +34,7 @@ hotdata query status Typical analytics SQL (all via `hotdata query`): - **Aggregations:** `COUNT`, `SUM`, `AVG`, `MIN`, `MAX` with `GROUP BY` -- **Joins:** `INNER` / `LEFT JOIN` across `..
` names β€” every referenced catalog (the managed database's own or an attached one) must be in the active database's scope; attach catalogs first (`hotdata databases attach`) +- **Joins:** `INNER` / `LEFT JOIN` across `..
` names β€” every referenced catalog (the instant database's own or an attached one) must be in the active database's scope; attach catalogs first (`hotdata databases attach`) - **Filtering:** `WHERE` on partition-friendly columns (consider **sorted** indexes below) - **Ordering:** `ORDER BY` on metrics or dimensions - **Bounded exploration:** always `LIMIT` while iterating; widen once validated @@ -82,7 +82,7 @@ hotdata databases results get [--workspace-id ] [--out hotdata query status # if async ``` -2. **Materialize** into a managed database (parquet) +2. **Materialize** into an instant database (parquet) ```bash hotdata databases create --catalog analytics diff --git a/skills/hotdata/subskills/analytics/references/WORKFLOWS.md b/skills/hotdata/subskills/analytics/references/WORKFLOWS.md index 19040ea..76987b1 100644 --- a/skills/hotdata/subskills/analytics/references/WORKFLOWS.md +++ b/skills/hotdata/subskills/analytics/references/WORKFLOWS.md @@ -2,7 +2,7 @@ OLAP-style SQL, **History** (query runs and stored results), and **Chain** (materialized follow-ups). Requires **`hotdata`** for auth, workspaces, and catalog commands. -**Related:** **`hotdata-search`** ([`../../search/SKILL.md`](../../search/SKILL.md)) for BM25/vector indexes and `hotdata search`; **`hotdata`** [WORKFLOWS.md](../../../references/WORKFLOWS.md) for managed databases. +**Related:** **`hotdata-search`** ([`../../search/SKILL.md`](../../search/SKILL.md)) for BM25/vector indexes and `hotdata search`; **`hotdata`** [WORKFLOWS.md](../../../references/WORKFLOWS.md) for instant databases. --- @@ -64,7 +64,7 @@ hotdata query "SELECT ..." ### 2. Materialize -Land a smaller table in a **managed database** (parquet β†’ `..
`): +Land a smaller table in an **instant database** (parquet β†’ `..
`): ```bash hotdata databases create --catalog chain_db @@ -92,4 +92,4 @@ hotdata query "SELECT * FROM chain_db.public.revenue_slice WHERE ..." - Materialize when the base scan is large and the follow-up runs many times. - Keep Chain tables focused; avoid wide `SELECT *` materializations when a narrow projection suffices. -- For managed-database uploads, see **`hotdata`** WORKFLOWS β€” [Managed databases](../../../references/WORKFLOWS.md#managed-databases). +- For instant-database uploads, see **`hotdata`** WORKFLOWS β€” [Instant databases](../../../references/WORKFLOWS.md#instant-databases). diff --git a/skills/hotdata/subskills/geospatial/SKILL.md b/skills/hotdata/subskills/geospatial/SKILL.md index f81b04d..7a07d60 100644 --- a/skills/hotdata/subskills/geospatial/SKILL.md +++ b/skills/hotdata/subskills/geospatial/SKILL.md @@ -18,9 +18,9 @@ All SQL below runs through the core CLI: hotdata query "" [--workspace-id ] [--database ] [--output table|json|csv] ``` -- **Fully qualify tables** as `..
` (or `..
` for a managed database) β€” every `
` placeholder below means a qualified name. +- **Fully qualify tables** as `..
` (or `..
` for an instant database) β€” every `
` placeholder below means a qualified name. - **PostgreSQL dialect:** double-quote any non-lowercase identifier (e.g. `"GeoID"`). -- Discover candidate tables/columns with **`hotdata databases tables list`** (filter with `--schema`/`--table`) or **`hotdata databases tables list`** (tables inside a managed database) β€” see core skill. +- Discover candidate tables/columns with **`hotdata databases tables list`** (filter with `--schema`/`--table`) or **`hotdata databases tables list`** (tables inside an instant database) β€” see core skill. --- diff --git a/skills/hotdata/subskills/search/SKILL.md b/skills/hotdata/subskills/search/SKILL.md index c10f97b..44372db 100644 --- a/skills/hotdata/subskills/search/SKILL.md +++ b/skills/hotdata/subskills/search/SKILL.md @@ -47,13 +47,13 @@ hotdata search "" --in ## Indexes (text and vector) -Indexes are a **managed-database** concept. Create names the index (positional) and attaches to a table on a managed database via `--from` β€” `catalog.schema.table` (the managed database's catalog), or `schema.table` with an active database set. A plain connection catalog is rejected. `list` narrows to the **active database** when one is set; without one it scans the whole workspace. `show`/`remove` resolve the index by name in the active database (or `--database `). +Indexes are an **instant-database** concept. Create names the index (positional) and attaches to a table on an instant database via `--from` β€” `catalog.schema.table` (the instant database's catalog), or `schema.table` with an active database set. A plain connection catalog is rejected. `list` narrows to the **active database** when one is set; without one it scans the whole workspace. `show`/`remove` resolve the index by name in the active database (or `--database `). ```bash # List β€” active-database scope when a DB is set, else whole-workspace scan hotdata search list [--workspace-id ] [--output table|json|yaml] -# Create β€” index name is positional; --from is a managed database's table +# Create β€” index name is positional; --from is an instant database's table hotdata search create --type text|vector --from \ --column \ [--metric l2|cosine|dot] [--async] \ diff --git a/skills/hotdata/subskills/search/references/INDEXES.md b/skills/hotdata/subskills/search/references/INDEXES.md index 34b60a3..7369c45 100644 --- a/skills/hotdata/subskills/search/references/INDEXES.md +++ b/skills/hotdata/subskills/search/references/INDEXES.md @@ -25,11 +25,11 @@ High-cardinality **text** (`title`, `body`, …) β†’ **bm25**. **Embedding** / f hotdata search list ``` -With no filters, this is a whole-workspace scan that **includes managed-database indexes** (shown under the internal `__db_..
` label). Skip duplicates (same table, column, and purpose). +With no filters, this is a whole-workspace scan that **includes instant-database indexes** (shown under the internal `__db_..
` label). Skip duplicates (same table, column, and purpose). ## 3. Create indexes -For managed databases (`--from` catalog alias β€” auto-selects the active database catalog): +For instant databases (`--from` catalog alias β€” auto-selects the active database catalog): ```bash hotdata search create
_body --type text \ @@ -39,7 +39,7 @@ hotdata search create
_embedding_vec --type vector \ --from ..
--column embedding --metric cosine ``` -Indexes are created on **managed databases** only. To index a table that lives in an external catalog, attach the catalog to a managed database first (`hotdata databases attach `), then create the index with the managed database's catalog in `--from` β€” a bare connection/catalog is rejected. +Indexes are created on **instant databases** only. To index a table that lives in an external catalog, attach the catalog to an instant database first (`hotdata databases attach `), then create the index with the instant database's catalog in `--from` β€” a bare connection/catalog is rejected. Large builds: `--async`, then `hotdata jobs list` / `hotdata jobs `. diff --git a/src/cli.rs b/src/cli.rs index a1187f3..f84ae6f 100644 --- a/src/cli.rs +++ b/src/cli.rs @@ -25,7 +25,7 @@ pub enum Commands { command: WorkspaceCommands, }, - /// Managed databases, plus the tables, queries, results, and context inside them + /// Instant databases, plus the tables, queries, results, and context inside them Databases { /// Database id or name (omit to use a subcommand) name_or_id: Option, @@ -51,7 +51,7 @@ pub enum Commands { #[arg(long, short = 'w')] workspace_id: Option, - /// Run against a specific managed database (defaults to the current database set via `databases use`) + /// Run against a specific instant database (defaults to the current database set via `databases use`) #[arg(long, short = 'd')] database: Option, diff --git a/src/client/ingest.rs b/src/client/ingest.rs index 92ebdcf..6fe6238 100644 --- a/src/client/ingest.rs +++ b/src/client/ingest.rs @@ -376,7 +376,7 @@ impl IngestClient { // --- datasources ----------------------------------------------------- /// Validate a datasource config without persisting a datasource, config - /// version, managed database, or secret. The credentials are used for the + /// version, instant database, or secret. The credentials are used for the /// validation request only, so this route takes a session JWT too. pub fn validate_datasource( &self, @@ -444,7 +444,7 @@ impl IngestClient { /// Soft-delete a datasource. The server returns `409 /// active_ingests_exist` while any non-deleted ingest references it β€” - /// destination tables and managed databases are never touched. + /// destination tables and instant databases are never touched. pub fn delete_datasource(&self, datasource_id: &str) -> Result { self.send( self.authed( diff --git a/src/client/sdk.rs b/src/client/sdk.rs index 004fd20..1638bc9 100644 --- a/src/client/sdk.rs +++ b/src/client/sdk.rs @@ -609,7 +609,7 @@ impl Api { /// The active database scope, or exit with actionable guidance when none is /// set. /// - /// Results and query runs are scoped to a managed database (the required + /// Results and query runs are scoped to an instant database (the required /// `X-Database-Id` header). Commands that hit those endpoints call this to /// resolve the scope β€” set via `--database`, `HOTDATA_DATABASE`, or /// `databases set` β€” and to fail with a hint rather than surfacing the raw @@ -620,7 +620,7 @@ impl Api { eprintln!("{}", "error: no active database.".red()); eprintln!( "{}", - "Results and query runs are scoped to a managed database. Set one with \ + "Results and query runs are scoped to an instant database. Set one with \ `hotdata databases use `, or pass `--database `." .dark_grey() ); diff --git a/src/commands/connections.rs b/src/commands/connections.rs index 4195f0a..8259ffc 100644 --- a/src/commands/connections.rs +++ b/src/commands/connections.rs @@ -5,7 +5,7 @@ use crate::client::sdk::{Api, block, none_if_404}; /// /// If `name_or_id` looks like a raw connection ID (starts with "conn"), tries /// `GET /connections/{id}` directly first to avoid listing the full workspace. -/// Falls back to listing and matching by name, then to managed-database catalog +/// Falls back to listing and matching by name, then to instant-database catalog /// aliases. Only the "no match" outcome is an `Err`; a transport/API failure /// during resolution still exits (the API is unreachable β€” not "this name is /// wrong"), preserving the auth-aware error from [`ApiError::exit`]. @@ -47,7 +47,7 @@ pub fn try_resolve_connection_id(api: &Api, name_or_id: &str) -> Result..
`, or `..
` when @@ -124,7 +124,7 @@ pub enum DatabasesCommands { alias: Option, }, - /// Detach a previously attached catalog from a managed database. + /// Detach a previously attached catalog from an instant database. Detach { /// Catalog name or id to detach catalog: String, @@ -144,14 +144,14 @@ pub enum DatabasesCommands { /// Clear the current database Unset, - /// Delete a managed database and its tables + /// Delete an instant database and its tables #[command(name = "remove")] Delete { - /// Managed database id or name + /// Instant database id or name name_or_id: String, }, - /// Load a parquet file or a saved query result into a managed database table + /// Load a parquet file or a saved query result into an instant database table Load { /// SQL catalog alias of the target database (e.g. `--catalog airbnb`) #[arg(long)] @@ -185,7 +185,7 @@ pub enum DatabasesCommands { result_id: Option, }, - /// Manage tables inside a managed database + /// Manage tables inside an instant database Tables { /// Database id or name β€” shorthand for `tables list` when no subcommand is given database: Option, @@ -196,7 +196,7 @@ pub enum DatabasesCommands { /// Sync database context with local Markdown Context { - /// Managed database to scope to (defaults to the current database) + /// Instant database to scope to (defaults to the current database) #[arg(long, short = 'd', global = true)] database: Option, @@ -209,7 +209,7 @@ pub enum DatabasesCommands { /// SQL query string (omit when using a subcommand) sql: Option, - /// Managed database to run against (defaults to the current database) + /// Instant database to run against (defaults to the current database) #[arg(long, short = 'd')] database: Option, @@ -231,7 +231,7 @@ pub enum DatabasesCommands { /// Query run ID to show details id: Option, - /// Managed database to scope to (defaults to the current database) + /// Instant database to scope to (defaults to the current database) #[arg(long, short = 'd', global = true)] database: Option, @@ -248,7 +248,7 @@ pub enum DatabasesCommands { /// Result ID (omit to use a subcommand) result_id: Option, - /// Managed database to scope to (defaults to the current database) + /// Instant database to scope to (defaults to the current database) #[arg(long, short = 'd', global = true)] database: Option, @@ -264,7 +264,7 @@ pub enum DatabasesCommands { /// Subcommands for `hotdata databases tables`. #[derive(clap::Subcommand)] pub enum DatabaseTablesCommands { - /// List tables in a managed database + /// List tables in an instant database List { /// Database id or name (defaults to current database) #[arg(long)] @@ -334,7 +334,7 @@ pub enum DatabaseTablesCommands { result_id: Option, }, - /// Delete a table from a managed database + /// Delete a table from an instant database #[command(name = "remove")] Delete { /// Database id or name (defaults to current database) @@ -527,12 +527,12 @@ fn list_database_summaries(api: &Api) -> Result, ApiError> .map(|dbs| dbs.into_iter().map(DatabaseSummary::from).collect()) } -/// List the ids of every managed database in the workspace. +/// List the ids of every instant database in the workspace. /// -/// Exposed for the whole-workspace `indexes list` scan (#168): a managed +/// Exposed for the whole-workspace `indexes list` scan (#168): an instant /// database's connection is hidden from `connections list` and its tables are /// absent from the unscoped `information_schema` enumeration, so that scan -/// rediscovers managed databases here and resolves each one's +/// rediscovers instant databases here and resolves each one's /// `default_connection_id` via [`get_database`]. The list summary omits the /// connection id, hence ids only. /// @@ -807,7 +807,7 @@ fn upload_parquet_path(api: &Api, path: &Path, size: u64) -> Result String { if !is_parquet_path(path) { eprintln!( - "error: managed table loads require a parquet file (got '{}'). \ + "error: instant database table loads require a parquet file (got '{}'). \ Convert your data to parquet first.", path ); @@ -828,7 +828,7 @@ fn upload_parquet_file(api: &Api, path: &str) -> String { fn upload_parquet_url(api: &Api, url: &str) -> String { if !is_parquet_path(url) { eprintln!( - "error: managed table loads require a parquet URL ending in .parquet (got '{url}')." + "error: instant database table loads require a parquet URL ending in .parquet (got '{url}')." ); std::process::exit(1); } @@ -1077,7 +1077,7 @@ struct DatabaseCount { count: i64, } -/// Total number of managed databases in the workspace. +/// Total number of instant databases in the workspace. /// /// One request. The list endpoint's `count` field is a page size, not a /// workspace total, so this used to drain every page and take the length β€” @@ -1172,7 +1172,7 @@ pub fn get(workspace_id: &str, id_or_name: &str, format: &str) { } } -/// Attach a connection as a queryable catalog on a managed database, so its +/// Attach a connection as a queryable catalog on an instant database, so its /// live tables are visible inside that database's query scope (cross-source /// joins without exporting data). Defaults to the current database. pub fn attach(workspace_id: &str, catalog: &str, database: Option<&str>, alias: Option<&str>) { @@ -1214,7 +1214,7 @@ pub fn attach(workspace_id: &str, catalog: &str, database: Option<&str>, alias: } } -/// Detach a previously attached catalog from a managed database. +/// Detach a previously attached catalog from an instant database. /// Defaults to the current database. pub fn detach(workspace_id: &str, catalog: &str, database: Option<&str>) { use crossterm::style::Stylize; @@ -1857,7 +1857,7 @@ pub fn tables_load( } }; let _ = crate::config::save_current_database("default", workspace_id, &new_db.id); - // Managed databases have no add-table endpoint, so declaring a new table + // Instant databases have no add-table endpoint, so declaring a new table // is a delete + recreate β€” which mints a NEW database id. Surface that // explicitly: the id printed by `databases create` is now stale, and // id-based automation (e.g. `databases delete `) would @@ -1873,7 +1873,7 @@ pub fn tables_load( "{}", format!( "note: table '{table}' was not declared β€” recreated database '{catalog}' to add it \ - (id {} β†’ {}). Managed databases are recreated when a new table is loaded; \ + (id {} β†’ {}). Instant databases are recreated when a new table is loaded; \ reference them by catalog ('{catalog}'), not the create-time id.", db.id, new_db.id ) diff --git a/src/commands/datasource.rs b/src/commands/datasource.rs index 65777eb..79df02e 100644 --- a/src/commands/datasource.rs +++ b/src/commands/datasource.rs @@ -52,7 +52,7 @@ use crate::util; pub enum DatasourceCommands { /// Check a config and credentials without creating anything /// - /// Persists no datasource, config version, managed database, or secret β€” + /// Persists no datasource, config version, instant database, or secret β€” /// run it before `create` to see what the credentials can reach. The /// response carries family-specific discovery (schemas/tables, topics, …). /// @@ -158,7 +158,7 @@ pub enum DatasourceCommands { /// Delete a datasource (its ingests must be deleted first) /// /// Soft-delete. Returns 409 while any non-deleted ingest references it β€” - /// destination tables, their data, and managed databases are never touched. + /// destination tables, their data, and instant databases are never touched. #[command(name = "remove")] Delete { /// Datasource id (from `hotdata ingest sources list`) diff --git a/src/commands/indexes.rs b/src/commands/indexes.rs index ddb390b..a3d10f3 100644 --- a/src/commands/indexes.rs +++ b/src/commands/indexes.rs @@ -104,14 +104,14 @@ fn scan_connection_id<'a>( /// One table to scan for indexes, paired with the connection id its per-table /// index call must address. The `table.connection` field carries the display -/// label (a connection name, or a managed database's internal `__db_*` label), +/// label (a connection name, or an instant database's internal `__db_*` label), /// which can differ from the real `conn_id` used for the API call. struct ScanTarget { conn_id: String, table: InfoTable, } -/// Resolve the `default_connection_id` of every managed database in the +/// Resolve the `default_connection_id` of every instant database in the /// workspace, in parallel. /// /// These are exactly the connections the whole-workspace `information_schema` @@ -135,11 +135,11 @@ fn managed_db_connection_ids(api: &Api) -> Result, ApiError> { /// list`. /// /// The workspace-wide `information_schema` enumeration returns only -/// regular-connection tables β€” managed-database catalogs never appear there, and -/// `connections list` hides their connections (#168). So managed databases are +/// regular-connection tables β€” instant-database catalogs never appear there, and +/// `connections list` hides their connections (#168). So instant databases are /// discovered separately via [`managed_db_connection_ids`] and each is scanned /// with a connection-scoped `information_schema` call, exactly like the -/// `--connection-id` path. The two table sets are disjoint: a managed database's +/// `--connection-id` path. The two table sets are disjoint: an instant database's /// connection is never returned by `connections list`. fn workspace_scan_targets( api: &Api, @@ -157,7 +157,7 @@ fn workspace_scan_targets( }) .collect(); - // Managed databases: discover their hidden connections, then scan each + // Instant databases: discover their hidden connections, then scan each // scoped (the per-connection enumeration is what surfaces `__db_*` tables). let db_conns = managed_db_connection_ids(api)?; let managed: Result>, ApiError> = db_conns @@ -184,7 +184,7 @@ fn workspace_scan_targets( /// With a `--connection-id`, enumerates that connection's tables and fetches /// each table's indexes against it (the database-scoped case fixed in #161). /// Without one, [`workspace_scan_targets`] assembles the list across both -/// regular connections and managed databases (#168). Skipped connections / +/// regular connections and instant databases (#168). Skipped connections / /// missing tables surface as no rows for that table, not an error. fn collect_connection_wide( api: &Api, @@ -511,7 +511,7 @@ pub fn create( } } -/// A search index located by name within a managed database, for `search`'s +/// A search index located by name within an instant database, for `search`'s /// by-name addressing. Carries the database's real ids (never a `__db_*` label). pub struct LocatedIndex { pub database_id: String, @@ -525,7 +525,7 @@ pub struct LocatedIndex { pub metric: Option, } -/// Find a search index by name within a managed database. +/// Find a search index by name within an instant database. /// /// The database is required and addressed by id β€” an explicit `--database`, or /// the active one set via `hotdata databases use `. There is no @@ -702,7 +702,7 @@ mod tests { #[test] fn scan_connection_id_prefers_supplied_id_over_label_map() { - // #161: a managed database's catalog surfaces under an internal + // #161: an instant database's catalog surfaces under an internal // `__db_*` label that `connections list` hides, so the nameβ†’id map is // empty for it. The supplied --connection-id must win regardless. let empty = HashMap::new(); @@ -734,7 +734,7 @@ mod tests { #[test] fn collect_connection_wide_uses_supplied_id_for_db_scoped_label() { - // #161 regression: information_schema reports a managed database's + // #161 regression: information_schema reports an instant database's // catalog under an internal `__db_*` label, but the per-table index // call must use the supplied --connection-id. The indexes endpoint is // mocked ONLY for the real id (`conn-real`); had the scan used the @@ -777,11 +777,11 @@ mod tests { #[test] fn collect_connection_wide_unscoped_discovers_managed_db_indexes() { - // #168: unscoped `indexes list` in a managed-only workspace (the real + // #168: unscoped `indexes list` in an instant-database-only workspace (the real // production shape β€” `connections list` is empty because it hides // database-scoped connections, and the workspace-wide - // `information_schema` returns no managed tables). The scan must - // rediscover the managed database via `databases list` β†’ `databases get` + // `information_schema` returns no instant-database tables). The scan must + // rediscover the instant database via `databases list` β†’ `databases get` // β†’ default_connection_id, then a connection-scoped `information_schema` // surfaces its `__db_*` table and the per-table indexes call resolves. let mut server = mockito::Server::new(); @@ -801,7 +801,7 @@ mod tests { .with_header("content-type", "application/json") .with_body(r#"{"count":0,"limit":100,"tables":[],"has_more":false,"next_cursor":null}"#) .create(); - // The managed database is discovered here. + // The instant database is discovered here. let dbs = server .mock("GET", "/v1/databases") .with_status(200) @@ -819,7 +819,7 @@ mod tests { "default_connection_id":"conn-managed","attachments":[]}"#, ) .create(); - // Connection-scoped enumeration surfaces the managed table. + // Connection-scoped enumeration surfaces the instant database's table. let info_scoped = server .mock("GET", "/v1/information_schema") .match_query(mockito::Matcher::UrlEncoded( @@ -864,7 +864,7 @@ mod tests { #[test] fn collect_connection_wide_unscoped_unions_regular_and_managed() { // The unscoped scan unions regular-connection tables (workspace-wide - // enumeration, label = connection name mapped to its id) with managed + // enumeration, label = connection name mapped to its id) with instant // databases (discovered separately, #168). The two sets are disjoint, so // both indexes appear exactly once. let mut server = mockito::Server::new(); diff --git a/src/commands/ingest.rs b/src/commands/ingest.rs index 56b422f..d3a1e48 100644 --- a/src/commands/ingest.rs +++ b/src/commands/ingest.rs @@ -209,7 +209,7 @@ pub enum IngestCommands { )] destination: Option, - /// Destination managed database id + /// Destination instant database id #[arg(long = "database-id")] database_id: Option, diff --git a/src/commands/query.rs b/src/commands/query.rs index d351af2..69db1c7 100644 --- a/src/commands/query.rs +++ b/src/commands/query.rs @@ -383,7 +383,7 @@ fn incomplete_preview(resp: hotdata::models::QueryResponse, note: &str) -> Query /// `databases set` / `databases attach`. Pure string inspection of the server /// error so it's unit-testable and adds no network round-trip on success. /// -/// A `query` runs inside exactly one managed database; that context exposes the +/// A `query` runs inside exactly one instant database; that context exposes the /// database's own catalog plus any *attached* connection catalogs. The two /// failure modes a user hits when they don't know this are "a database is /// required" (no context set) and "table '..
' not @@ -392,7 +392,7 @@ fn cross_source_hint(error_msg: &str) -> Option { let lower = error_msg.to_lowercase(); if lower.contains("a database is required") { return Some( - "Tip: a query runs inside one managed database. Set one with `hotdata databases \ + "Tip: a query runs inside one instant database. Set one with `hotdata databases \ use `, then attach any catalog whose tables you need: `hotdata databases \ attach `. See available catalogs and tables with `hotdata databases \ tables list`." diff --git a/src/commands/search.rs b/src/commands/search.rs index ab2bb82..b13b5d9 100644 --- a/src/commands/search.rs +++ b/src/commands/search.rs @@ -147,7 +147,7 @@ pub fn dispatch(workspace_id: &str, command: SearchCommands) { } } -/// The managed database an index create targets, as named by `--from`. +/// The instant database an index create targets, as named by `--from`. enum FromTarget { /// A `schema.table` `--from`: the active database, already resolved by id. /// Carry the resolved database so `create` does **not** re-resolve it by @@ -155,7 +155,7 @@ enum FromTarget { /// is ambiguous even though the active-database id is unambiguous. Database(Box), /// A `catalog.schema.table` `--from`: an explicit catalog alias still to be - /// resolved to a managed database. + /// resolved to an instant database. Catalog(String), } @@ -259,8 +259,8 @@ fn create( }; let (target, schema, table) = parse_table(workspace_id, from); let api = Api::new(Some(workspace_id)); - // Indexes are a managed-database concept (a plain connection is a legacy - // concept being removed), so create must land on a managed database β€” the + // Indexes are an instant-database concept (a plain connection is a legacy + // concept being removed), so create must land on an instant database β€” the // same scope `search show`/`search remove` address. The active-database path // is already resolved; only an explicit catalog still needs resolving, and // its own error (e.g. an ambiguous forked-catalog alias) is surfaced as-is. @@ -272,8 +272,8 @@ fn create( eprintln!( "{}", format!( - "error: {e}\nSearch indexes are created on managed databases β€” pass a \ - managed database's catalog or id, or 'schema.table' with an active \ + "error: {e}\nSearch indexes are created on instant databases β€” pass a \ + instant database's catalog or id, or 'schema.table' with an active \ database set via 'hotdata databases use '." ) .red() diff --git a/tests/common/mod.rs b/tests/common/mod.rs index 84b583a..db50093 100644 --- a/tests/common/mod.rs +++ b/tests/common/mod.rs @@ -194,7 +194,7 @@ pub fn parse_json(bytes: &[u8], args: &[&str]) -> serde_json::Value { }) } -/// Find-or-create the shared `sdkci-shared` managed database and return its id. +/// Find-or-create the shared `sdkci-shared` instant database and return its id. /// /// Queries require a database scope (the `-d` flag / `X-Database-Id` header); /// a bare query returns 400 "a database is required". Mirroring sdk-python's diff --git a/tests/query_async_polling.rs b/tests/query_async_polling.rs index 7b9e4cb..67146cd 100644 --- a/tests/query_async_polling.rs +++ b/tests/query_async_polling.rs @@ -7,7 +7,7 @@ //! `queries list`, and `results `. //! //! Queries require a database scope, so we target the shared `sdkci-shared` -//! managed database (otherwise the server returns 400 "a database is required"). +//! instant database (otherwise the server returns 400 "a database is required"). mod common; From c32b5b9c830a0feb19d89732117784ad05260db5 Mon Sep 17 00:00:00 2001 From: Eddie A Tejeda <669988+eddietejeda@users.noreply.github.com> Date: Mon, 24 Aug 2026 20:19:29 -0700 Subject: [PATCH 2/2] Keep 'managed table' wording for the managed-table API surface 'Managed table' names the managed-table load endpoints and stays as-is per the cross-repo convention; only the 'managed database' -> 'instant database' product rename is in scope for this PR. --- skills/hotdata/SKILL.md | 4 ++-- skills/hotdata/references/WORKFLOWS.md | 2 +- skills/hotdata/subskills/analytics/SKILL.md | 2 +- src/commands/databases.rs | 4 ++-- src/commands/indexes.rs | 4 ++-- 5 files changed, 8 insertions(+), 8 deletions(-) diff --git a/skills/hotdata/SKILL.md b/skills/hotdata/SKILL.md index ea1301f..f9ae65b 100644 --- a/skills/hotdata/SKILL.md +++ b/skills/hotdata/SKILL.md @@ -144,7 +144,7 @@ hotdata query "SELECT count(*) FROM airbnb.public.listings" **A `hotdata query` runs inside exactly one instant database** β€” the active database (`hotdata databases use `) or the one named by `--database`. With none set, the query fails with *"a database is required."* That database's query scope sees **only its own catalog plus any catalogs explicitly attached to it** β€” a workspace catalog is **not** visible just because it exists. Referencing an unattached catalog fails with *"table '\.\.\' not found."* -To query an attached catalog's tables, or **join an instant database's table against an attached catalog's table in one query**, attach the catalog to the database first. The catalog's data stays **live** (synced) β€” this is not a copy: +To query an attached catalog's tables, or **join a managed table against an attached catalog's table in one query**, attach the catalog to the database first. The catalog's data stays **live** (synced) β€” this is not a copy: ``` # Attach the 'github' catalog (live) to the active database under alias 'gh' @@ -153,7 +153,7 @@ hotdata databases attach github --alias gh # Now both the database's own tables and the attached catalog are in scope: hotdata query "SELECT * FROM gh.github.issues WHERE state = 'OPEN' LIMIT 10" -# Cross-catalog join: an instant database's table JOINed against the live attached-catalog table +# Cross-catalog join: a managed table JOINed against the live attached-catalog table hotdata query " SELECT t.id, i.title FROM mycatalog.public.tickets t diff --git a/skills/hotdata/references/WORKFLOWS.md b/skills/hotdata/references/WORKFLOWS.md index 2a1dd8d..dece853 100644 --- a/skills/hotdata/references/WORKFLOWS.md +++ b/skills/hotdata/references/WORKFLOWS.md @@ -75,7 +75,7 @@ End-to-end checklists. Use the linked sections for command detail and guardrails **Skill:** **`hotdata`** -A `hotdata query` runs inside **one** instant database; its scope sees that database's own catalog plus **attached** catalog catalogs only. To query a catalog's tables β€” or join an instant database's table against a live catalog table in one query β€” attach the catalog. (No instant database set β†’ *"a database is required."*; an unattached catalog β†’ *"table not found."*) +A `hotdata query` runs inside **one** instant database; its scope sees that database's own catalog plus **attached** catalog catalogs only. To query a catalog's tables β€” or join a managed table against a live catalog table in one query β€” attach the catalog. (No instant database set β†’ *"a database is required."*; an unattached catalog β†’ *"table not found."*) 1. [ ] Pick/create the instant database that will be the query context (`hotdata databases use ` or `databases create --catalog `) 2. [ ] Attach the catalog(s) you need (live, sync intact): `hotdata databases attach [--alias ]` diff --git a/skills/hotdata/subskills/analytics/SKILL.md b/skills/hotdata/subskills/analytics/SKILL.md index 5b8f19a..674d785 100644 --- a/skills/hotdata/subskills/analytics/SKILL.md +++ b/skills/hotdata/subskills/analytics/SKILL.md @@ -25,7 +25,7 @@ hotdata query status - **`--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. - 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 **attached** catalogs only. To query an attached catalog's table, or **join an instant database's table against an attached catalog's table**, attach the catalog first: `hotdata databases attach ` β€” see **`hotdata`** skill β†’ [Querying across catalogs](../../SKILL.md#querying-across-catalogs-attach). No instant database set β†’ *"a database is required."* +- **Query scope:** every query runs inside one instant database (active or `--database`); it sees that database's own catalog plus **attached** catalogs only. To query an attached catalog's table, or **join a managed table against an attached catalog's table**, attach the catalog first: `hotdata databases attach ` β€” see **`hotdata`** skill β†’ [Querying across catalogs](../../SKILL.md#querying-across-catalogs-attach). No instant database set β†’ *"a database is required."* - Long-running queries may return `query_run_id` β†’ poll with **`query status`** (exit `2` = still running). Do not re-run identical heavy SQL while polling. - For **workspace-wide** joins and naming, load **context:DATAMODEL** when listed (`hotdata databases context list` β†’ `show DATAMODEL`) β€” see **`hotdata`** skill. diff --git a/src/commands/databases.rs b/src/commands/databases.rs index f523d6c..f87066b 100644 --- a/src/commands/databases.rs +++ b/src/commands/databases.rs @@ -807,7 +807,7 @@ fn upload_parquet_path(api: &Api, path: &Path, size: u64) -> Result String { if !is_parquet_path(path) { eprintln!( - "error: instant database table loads require a parquet file (got '{}'). \ + "error: managed table loads require a parquet file (got '{}'). \ Convert your data to parquet first.", path ); @@ -828,7 +828,7 @@ fn upload_parquet_file(api: &Api, path: &str) -> String { fn upload_parquet_url(api: &Api, url: &str) -> String { if !is_parquet_path(url) { eprintln!( - "error: instant database table loads require a parquet URL ending in .parquet (got '{url}')." + "error: managed table loads require a parquet URL ending in .parquet (got '{url}')." ); std::process::exit(1); } diff --git a/src/commands/indexes.rs b/src/commands/indexes.rs index a3d10f3..510b9cb 100644 --- a/src/commands/indexes.rs +++ b/src/commands/indexes.rs @@ -780,7 +780,7 @@ mod tests { // #168: unscoped `indexes list` in an instant-database-only workspace (the real // production shape β€” `connections list` is empty because it hides // database-scoped connections, and the workspace-wide - // `information_schema` returns no instant-database tables). The scan must + // `information_schema` returns no managed tables). The scan must // rediscover the instant database via `databases list` β†’ `databases get` // β†’ default_connection_id, then a connection-scoped `information_schema` // surfaces its `__db_*` table and the per-table indexes call resolves. @@ -819,7 +819,7 @@ mod tests { "default_connection_id":"conn-managed","attachments":[]}"#, ) .create(); - // Connection-scoped enumeration surfaces the instant database's table. + // Connection-scoped enumeration surfaces the managed table. let info_scoped = server .mock("GET", "/v1/information_schema") .match_query(mockito::Matcher::UrlEncoded(