From 2e7304ed77c26d55a9b297498a17887be1b58d03 Mon Sep 17 00:00:00 2001 From: Eddie A Tejeda <669988+eddietejeda@users.noreply.github.com> Date: Sun, 18 Oct 2026 18:41:35 -0700 Subject: [PATCH 1/4] docs(readme): reorganize for end users --- README.md | 288 +++++++++++++++++++++++++++--------------------------- 1 file changed, 143 insertions(+), 145 deletions(-) diff --git a/README.md b/README.md index d780241..69e2a28 100644 --- a/README.md +++ b/README.md @@ -12,9 +12,9 @@ --- -Query, search, and join your data from one place — external databases, APIs, -cloud storage, Iceberg catalogs, and files you upload — with plain SQL and a few -commands. +Load your data into a Hotdata database, then query, join, and search it with +plain SQL. Data can come from files on your machine, a URL, or an external +source such as Postgres, S3, Iceberg, Kafka, or one of ~150 API services. ## Install @@ -22,192 +22,192 @@ commands. curl -fsSL https://hotdata.dev/install | sh ``` -The script uses Homebrew (`brew install hotdata-dev/tap/cli`) when `brew` is -present and otherwise drops a prebuilt binary into `~/.hotdata/cli`. It then -installs the agent skill for Claude Code and friends. Set `HOTDATA_NO_BREW=1` -to skip Homebrew, `HOTDATA_NO_SKILLS=1` to skip the skill. To build from -source instead: `cargo install --path .` (requires Rust). +That's it. The installer uses Homebrew if you have it +(`brew install hotdata-dev/tap/cli`) and also installs the Hotdata skill for AI +coding agents such as Claude Code. You can also download a binary from +[Releases](https://github.com/hotdata-dev/hotdata-cli/releases). -Or grab a binary from [Releases](https://github.com/hotdata-dev/hotdata-cli/releases). -Stay current with `hotdata manage upgrade`: in an interactive terminal the CLI -checks for a new release before API commands and offers to upgrade (set -`HOTDATA_NO_UPDATE_CHECK=1` to skip). Enable tab completion with -`hotdata manage completions bash|zsh|fish`. - -### Claude Code plugin - -To get the agent skill through Claude Code's plugin manager instead, which -updates it with each release: - -``` -/plugin marketplace add hotdata-dev/claude-plugins -/plugin install hotdata-cli@hotdata -``` - -Self-hosted marketplaces don't auto-update by default. To get each release -automatically, open `/plugin`, go to **Marketplaces**, select `hotdata`, and -choose **Enable auto-update**. Otherwise run `/plugin marketplace update hotdata` -when a new version ships. - -Use either the plugin or the installer's skill, not both: if you installed the -CLI with the script above, install it with `HOTDATA_NO_SKILLS=1` or Claude Code -will list the skill twice. - -What the plugin runs, sends, and fetches: - -- **SessionStart hook** (`hooks/check-cli.sh`, Claude Code and Cowork only): - checks whether `hotdata` is on `PATH` or in `~/.hotdata/cli`. If it's only in - `~/.hotdata/cli`, it adds that folder to `PATH` for the session. If it's - missing, it asks Claude to offer to install the CLI. The hook makes no - network requests, installs nothing, and sends no data. -- **Installer**, only after you agree: `curl -fsSL https://hotdata.dev/install | - HOTDATA_NO_SKILLS=1 sh` downloads the CLI from this repository's GitHub - releases, or installs it with Homebrew if `brew` is present. -- **The skill** teaches Claude to run `hotdata` commands. Those commands talk to - the Hotdata API (`https://api.hotdata.dev/v1`, or `HOTDATA_API_URL`) with your - Hotdata credentials, and send the queries, files, and data source settings - you ask Claude to work with. `hotdata auth login` opens - `https://app.hotdata.dev` in your browser, and the CLI checks this - repository's GitHub releases for new versions (`HOTDATA_NO_UPDATE_CHECK=1` - turns that off). Neither the plugin nor the CLI collects telemetry. +The CLI tells you when a new version is out; upgrade with +`hotdata manage upgrade`. ## Quickstart ```sh -hotdata auth login # or: hotdata auth register +# 1. Log in (or create an account with: hotdata auth register) +hotdata auth login + +# 2. Create a database and make it your current one hotdata databases create --catalog demo -hotdata databases use demo # make it current (create does not switch) +hotdata databases use demo + +# 3. Load some data hotdata databases load --catalog demo --table trips \ --url https://d37ci6vzurychx.cloudfront.net/trip-data/yellow_tripdata_2024-01.parquet + +# 4. Query it hotdata query "SELECT count(*) FROM demo.public.trips" ``` -The core loop: create an **instant database**, put data in it, query it with -PostgreSQL-dialect SQL. Everything else builds on that. +Tables are addressed as `catalog.schema.table`. Here the catalog is `demo` and +the default schema is `public`. -## Getting your data in +## Load your data -**Upload a file** directly — csv, json, or parquet: +**From a file or URL** (CSV, JSON, or Parquet): ```sh hotdata databases load --catalog demo --table listings --file ./listings.csv ``` -The format comes from the extension; pass `--format csv|json|parquet` when the -extension is missing or misleading. json is read whatever shape it arrives in — -an array of objects, a pretty-printed document, or one object per line. - -A load **replaces** the table by default. `--mode append` adds rows to an -existing table instead: +A load replaces the table. To add rows instead, use `--mode append`: ```sh -hotdata databases load --catalog demo --table listings --file ./more-listings.parquet --mode append +hotdata databases load --catalog demo --table listings --file ./more.csv --mode append ``` -**Import from an external source** — Postgres/MySQL, S3/GCS buckets, Iceberg, -Kafka, ~150 API services — via a datasource (`ds_…`) and a saved ingest (`ing_…`): +To change existing rows by key, use `--mode update`, `--mode delete`, or +`--mode upsert` with `--key `. -```sh -hotdata ingest sources types # browse source types and families -hotdata ingest sources fields sql # config/credentials/selector a family takes -hotdata ingest sources add # create a datasource (prompts, or --config @src.json) - -hotdata ingest create --source "prod postgres" --table orders --database-id db_123 -hotdata ingest logs # attempts for an ingest, newest first -hotdata ingest run --wait # show one attempt; exits 0 done / 1 failed / 2 in flight -``` - -`ingest sources update-config` rotates credentials; `ingest pause|resume|schedule` -control a scheduled ingest. Data lands in an instant database — query it like any -other. - -## Query and explore +**From an external source** such as Postgres, MySQL, S3, GCS, Iceberg, Kafka, +or an API service: first save the connection details as a *datasource*, then +create an *ingest* that copies data into your database once or on a +schedule. ```sh -hotdata databases tables list # every queryable table -hotdata databases tables show # columns and types -hotdata query "" [-o table|json|csv] # HotSQL (PostgreSQL dialect) +hotdata ingest sources types # see what you can connect to +hotdata ingest sources add # save a datasource (you'll be prompted) +hotdata ingest create --source "prod postgres" --table orders --database-id +hotdata ingest list # check on your ingests ``` -Write SQL in another dialect and the server transpiles it to HotSQL — -`--dialect` accepts `hotsql` (default), `duckdb`, `postgres`, `snowflake` -(writes follow the same rules as `hotsql`): +## Query ```sh -hotdata query "SELECT IFF(n > 0, 'pos', 'neg') FROM t" --dialect snowflake +hotdata databases tables list # what can I query? +hotdata databases tables show demo.public.trips # columns and types +hotdata query "SELECT * FROM demo.public.trips LIMIT 10" ``` -`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 databases load --mode update|delete|upsert`. +SQL is PostgreSQL-style. Add `-o json` or `-o csv` to change the output format. +If you prefer another dialect, pass `--dialect duckdb`, `postgres`, or +`snowflake` and the query is translated for you. + +You can also write with SQL. `INSERT`, `CREATE TABLE`, `CREATE TABLE AS`, and +`DROP TABLE` work on your current database's tables (your API key needs the +`write` permission): ```sh hotdata query "CREATE TABLE events (id BIGINT, kind TEXT)" hotdata query "INSERT INTO events VALUES (1, 'signup'), (2, 'login')" ``` -Long queries go async and print a `query_run_id` — poll with -`hotdata query status ` (exit `0` done / `1` failed / `2` running / `3` done -but the printed result is a truncated preview). Re-fetch -past results with `hotdata databases results get `; browse history -with `hotdata databases queries list`. +`UPDATE` and `DELETE` aren't supported in SQL yet; use `databases load` with +`--mode update`, `--mode delete`, or `--mode upsert` instead. + +Long-running queries finish in the background. The CLI prints an id you can +check with `hotdata query status `. ## Join across databases -Attach another instant database and join its live tables directly, no copying: +Attach another of your databases to query its tables alongside your own. No +data is copied: ```sh -hotdata databases attach prod-replica --alias prod -hotdata query "SELECT t.id, o.total FROM demo.public.tickets t - JOIN prod.public.orders o ON o.ticket_id = t.id" +hotdata databases attach sales --alias sales +hotdata query "SELECT t.id, o.total + FROM demo.public.tickets t + JOIN sales.public.orders o ON o.ticket_id = t.id" ``` -The attached database is read-only here: loads still go to your own database, -and `detach` withdraws visibility without deleting anything. `--alias` is -required when the other database kept the stock `default` catalog name. +Attached tables are read-only. `hotdata databases detach sales` removes the +link without deleting anything. ## Search -Create an index once, then search server-side. Vector search auto-embeds the -column and the query — no embedding keys or client setup: +Build a search index on a column, then search it: ```sh -hotdata search create trips_notes --type text --from demo.public.trips --column notes -hotdata search "airport surcharge dispute" --index trips_notes +hotdata search create trip_notes --type text --from demo.public.trips --column notes +hotdata search "airport surcharge dispute" --index trip_notes ``` -Use `--type vector` for semantic search; add `--algorithm ivf` for a table -too large for the default in-memory `hnsw` index. `--type sorted` builds a -sorted index that speeds up `WHERE` filters and range scans on a column. Indexes resolve in the current database -(`hotdata databases use `); pass `-d/--database ` to target another. -Bring your own model with `hotdata search embeddings add`. +- `--type text` is full-text (keyword) search. +- `--type vector` is semantic search. Hotdata creates the embeddings for you, + so you don't need an embeddings API key. +- `--type sorted` speeds up `WHERE` filters and range queries on a column. -## Use it from scripts and agents +## Your current workspace and database -- Every listing command takes `-o json|yaml`; `query status` and `ingest run` - expose script-friendly exit codes. -- Authenticate non-interactively with `--api-key`, or `HOTDATA_API_KEY` in the - environment or a `.env` file. -- `hotdata manage skills install` installs bundled agent skills — Markdown - playbooks that teach AI coding agents (Claude Code and friends) the full CLI. -- `hotdata databases context push|show DATAMODEL` stores your data model as - shared, server-side Markdown so humans and agents query with the same map. +Most commands run against your *current* workspace and database, so you don't +have to name them every time. -## Getting help +- Switch with `hotdata workspaces use` and `hotdata databases use`. +- Target a different one for a single command with `-w ` or + `-d `. `-d` accepts a database's name, catalog, or id. +- `workspaces list` and `databases list` mark the current one with `*`. -File a support ticket without leaving the terminal: +Your choice is saved on this machine and survives logging out and back in. + +## Scripts, CI, and AI agents + +- Add `-o json` or `-o yaml` to any listing for machine-readable output. +- Authenticate without a browser using an API key: `--api-key `, or + `HOTDATA_API_KEY` in your environment or a `.env` file. +- `hotdata query status` and `hotdata ingest run` return exit codes scripts can + check: `0` done, `1` failed, `2` still running. +- `hotdata databases context push DATAMODEL` stores a Markdown description of + your data model in Hotdata, so teammates and agents work from the same map. + +### Claude Code plugin + +The installer already sets up the Hotdata skill. If you'd rather get it through +Claude Code's plugin manager, which updates it with each release: -```sh -hotdata support report -m "Queries against work_abc have been timing out for an hour" --subject "Queries timing out" -hotdata support report --logs ./stderr.txt --context env=staging ``` +/plugin marketplace add hotdata-dev/claude-plugins +/plugin install hotdata-cli@hotdata +``` + +Use the plugin *or* the installer's skill, not both. If you use the plugin, +install the CLI with `curl -fsSL https://hotdata.dev/install | HOTDATA_NO_SKILLS=1 sh` +so Claude Code doesn't list the skill twice. To get plugin updates +automatically, open `/plugin` → **Marketplaces** → `hotdata` → +**Enable auto-update**. + +
+What the plugin runs, sends, and fetches + +- **SessionStart hook** (`hooks/check-cli.sh`, Claude Code and Cowork only): + checks whether `hotdata` is on `PATH` or in `~/.hotdata/cli`. If it's only in + `~/.hotdata/cli`, it adds that folder to `PATH` for the session. If it's + missing, it asks Claude to offer to install the CLI. The hook makes no + network requests, installs nothing, and sends no data. +- **Installer**, only after you agree: `curl -fsSL https://hotdata.dev/install | + HOTDATA_NO_SKILLS=1 sh` downloads the CLI from this repository's GitHub + releases, or installs it with Homebrew if `brew` is present. +- **The skill** teaches Claude to run `hotdata` commands. Those commands talk to + the Hotdata API (`https://api.hotdata.dev/v1`, or `HOTDATA_API_URL`) with your + Hotdata credentials, and send the queries, files, and data source settings + you ask Claude to work with. `hotdata auth login` opens + `https://app.hotdata.dev` in your browser, and the CLI checks this + repository's GitHub releases for new versions (`HOTDATA_NO_UPDATE_CHECK=1` + turns that off). Neither the plugin nor the CLI collects telemetry. -Omit `-m` in an interactive terminal to compose the report in `$EDITOR` instead. Replies go to the email on your HotData account. +
-## Commands +## Getting help + +- `hotdata --help` shows every option for a command. +- File a support ticket from the terminal; replies go to your account email: + + ```sh + hotdata support report -m "Queries have been timing out since 2pm" --subject "Query timeouts" + ``` -The full command surface. The top level has nine groups — `auth`, `workspaces`, `databases`, `query`, `jobs`, `ingest`, `search`, `manage`, and `support`. Run `hotdata --help` for full flags on any command. +## Reference + +
+All commands | Command | What it does | | :-- | :-- | @@ -280,23 +280,14 @@ The full command surface. The top level has nine groups — `auth`, `workspaces` | `manage skills install` | Install/update the agent skill into agent directories | | `manage skills status` | Show the agent skill's installation status | | `manage skills list` | List installed skills (alias for `status`) | -| `support report` | File a support ticket with the HotData team | +| `support report` | File a support ticket with the Hotdata team | -## Current workspace and database +
-The CLI saves a current workspace and, per workspace, a current database on -this machine. Commands use them when you don't name one. They survive -`auth logout` / `auth login`, so a new session resumes where you left off. +
+Configuration and environment variables -- `hotdata workspaces use` and `hotdata databases use` are the only commands - that switch. `databases create` and `databases fork` do not. -- `--workspace-id` / `-w` and `--database` / `-d` apply to one command only - and do not change the current selection. -- `workspaces list` and `databases list` mark the current one with `*`. - -## Configuration - -Config lives at `~/.hotdata/config.yml` (profile-keyed). Environment variables: +Config lives at `~/.hotdata/config.yml`. | Variable | Description | Default | | :-- | :-- | :-- | @@ -309,7 +300,13 @@ Config lives at `~/.hotdata/config.yml` (profile-keyed). Environment variables: | `HOTDATA_API_URL` | API base URL | `https://api.hotdata.dev/v1` | | `HOTDATA_APP_URL` | App URL for browser login | `https://app.hotdata.dev` | -API-key precedence, lowest to highest: config file → `HOTDATA_API_KEY` → `--api-key`. +An API key is taken from, in order of priority: `--api-key`, then +`HOTDATA_API_KEY`, then the config file. + +Installer options: `HOTDATA_NO_BREW=1` skips Homebrew, `HOTDATA_NO_SKILLS=1` +skips the agent skill. Tab completion: `hotdata manage completions bash|zsh|fish`. + +
## Development @@ -317,4 +314,5 @@ API-key precedence, lowest to highest: config file → `HOTDATA_API_KEY` → `-- cargo build && cargo test ``` -Release process: see [docs/RELEASING.md](docs/RELEASING.md). +Build from source with `cargo install --path .` (requires Rust). Release +process: [docs/RELEASING.md](docs/RELEASING.md). From a02810536682fef9ad7fd7019a1457f3b4adf45a Mon Sep 17 00:00:00 2001 From: Eddie A Tejeda <669988+eddietejeda@users.noreply.github.com> Date: Sun, 18 Oct 2026 18:42:51 -0700 Subject: [PATCH 2/4] docs(skill): -d accepts a database name or catalog --- skills/hotdata/SKILL.md | 12 ++++++------ skills/hotdata/subskills/analytics/SKILL.md | 4 ++-- skills/hotdata/subskills/search/SKILL.md | 10 +++++----- 3 files changed, 13 insertions(+), 13 deletions(-) diff --git a/skills/hotdata/SKILL.md b/skills/hotdata/SKILL.md index 29366a2..4019cd2 100644 --- a/skills/hotdata/SKILL.md +++ b/skills/hotdata/SKILL.md @@ -99,7 +99,7 @@ Returns workspaces with `current`, `public_id`, `name`, `active`, `favorite`, `p - **"json in any shape" is the CLI's doing, not the API's.** `--file`/`--url` reshape an array or a pretty-printed document into newline-delimited json locally. The load API and the SDKs accept **newline-delimited json only** (`format: "json"`), so code that moves off the CLI must convert the file itself. - **Two json sources are refused before anything uploads — do not retry them unchanged.** `one object per row` means a row is a scalar or a list: reshape the file so every row is an object. `carries no json rows` means the source is `[]` or empty: there is nothing to load. -**Current database:** `hotdata databases use ` saves the current database to config (see [Current workspace and database](#current-workspace-and-database)). `databases tables list`/`load`/`remove`, `databases queries`/`results`, and all `databases context` commands default to the current database; pass **`--database `** to target another database for that command only. (`databases tables show` instead takes a fully-qualified `catalog.schema.table`.) +**Current database:** `hotdata databases use ` saves the current database to config (see [Current workspace and database](#current-workspace-and-database)). `databases tables list`/`load`/`remove`, `databases queries`/`results`, and all `databases context` commands default to the current database; pass **`--database `** to target another database for that command only (on `queries`, `results`, and `context`, a database name or catalog alias works too). (`databases tables show` instead takes a fully-qualified `catalog.schema.table`.) **Always select databases by id** (`dbid...`, from `databases list`). Display names and catalog aliases are not unique — several databases can share a name, and a fork answers to the same catalog as its source — so name-based selection is ambiguous. @@ -238,13 +238,13 @@ hotdata databases tables show [--output tabl ### Database context (named Markdown) -Reads and writes **database-scoped context API** documents. Context is tied to the **current database** (set via `hotdata databases use`); pass **`--database `** (short: **`-d`**) to target a specific database. **`show`** needs no local file; **`push`** / **`pull`** use **`./.md`** in the current directory only as the CLI transport format. See [Database context (API)](#database-context-api). +Reads and writes **database-scoped context API** documents. Context is tied to the **current database** (set via `hotdata databases use`); pass **`--database `** (short: **`-d`**; a name, catalog alias, or id) to target a specific database. **`show`** needs no local file; **`push`** / **`pull`** use **`./.md`** in the current directory only as the CLI transport format. See [Database context (API)](#database-context-api). ``` -hotdata databases context list [--database ] [--prefix ] [--output table|json|yaml] -hotdata databases context show [--database ] -hotdata databases context pull [--database ] [--force] [--dry-run] -hotdata databases context push [--database ] [--dry-run] +hotdata databases context list [--database ] [--prefix ] [--output table|json|yaml] +hotdata databases context show [--database ] +hotdata databases context pull [--database ] [--force] [--dry-run] +hotdata databases context push [--database ] [--dry-run] ``` - `list` — names, `updated_at`, and character counts for each stored context in the current database. Use `--prefix` to narrow names (case-sensitive). **Agents:** call **`list` before `show`** for `DATAMODEL` (or any stem) so you do not rely on `show` failing when the document does not exist yet. diff --git a/skills/hotdata/subskills/analytics/SKILL.md b/skills/hotdata/subskills/analytics/SKILL.md index 723f687..29a0e93 100644 --- a/skills/hotdata/subskills/analytics/SKILL.md +++ b/skills/hotdata/subskills/analytics/SKILL.md @@ -47,7 +47,7 @@ Column names from CSV uploads may be case-sensitive — use double quotes when n ## Query run history -Scoped to the **current database** (set with `hotdata databases use`); pass `-d/--database ` to target another, `-w/--workspace-id` for another workspace. +Scoped to the **current database** (set with `hotdata databases use`); pass `-d/--database ` (name, catalog alias, or id) to target another, `-w/--workspace-id` for another workspace. ```bash hotdata databases queries list [-d ] [--workspace-id ] [--limit ] [--cursor ] [--status ] [--output table|json|yaml] @@ -67,7 +67,7 @@ hotdata databases results list [-d ] [--workspace-id ] [--l hotdata databases results get [-d ] [--workspace-id ] [--output table|json|csv] ``` -- Prefer **`databases results get `** over re-running identical heavy queries. It renders like `query`: `csv`/`json` stream the whole result, `table` is capped at 10,000 rows and exits `3` when the result is larger. Results and query runs scope to the current database; pass `-d/--database ` to target another. +- Prefer **`databases results get `** over re-running identical heavy queries. It renders like `query`: `csv`/`json` stream the whole result, `table` is capped at 10,000 rows and exits `3` when the result is larger. Results and query runs scope to the current database; pass `-d/--database ` (name, catalog alias, or id) to target another. - Query footers may include `[result-id: rslt...]`; also available from `databases queries `. - `databases results list --limit` defaults to **100** (max **1000**) — unlike `databases queries list`, which defaults to **20**. diff --git a/skills/hotdata/subskills/search/SKILL.md b/skills/hotdata/subskills/search/SKILL.md index 52126ec..0fc2c2c 100644 --- a/skills/hotdata/subskills/search/SKILL.md +++ b/skills/hotdata/subskills/search/SKILL.md @@ -42,17 +42,17 @@ hotdata search "" --in - **`ivf` indexes:** an `ivf` index created over a text column with `--provider` is searched by text like any vector index: `search` embeds the text with the index's provider and runs `SELECT , vector_distance(, '') AS dist FROM
ORDER BY dist LIMIT `. It names the columns rather than using `*`, because an `ivf` index cannot serve a query that returns its vector column (`SELECT *` and `* EXCLUDE (...)` included); a `--select` you pass is used verbatim, so leave the generated `{column}_embedding` out of it. An `ivf` index over a column that already holds vectors has no model to embed the text, so `search` refuses it and prints the query to run instead: `hotdata query 'SELECT , (, ARRAY[]) AS dist FROM ORDER BY dist LIMIT '` (the function matches the index's metric). In hand-written SQL against an `ivf` index, name the columns to return the same way; `vector_search(...)` reads `hnsw` indexes only and is refused on `ivf`. - **Before search:** create the right index (`search create --type text` or `--type vector`). See [references/INDEXES.md](references/INDEXES.md). - Default `--limit` is 10. -- **Database:** the search commands resolve the index in the **current** database (`hotdata databases use `). Pass `-d/--database ` to target a different database explicitly — it is required when no current database is set. The same `-d/--database` works on `search show` and `search remove`. +- **Database:** the search commands resolve the index in the **current** database (`hotdata databases use `). Pass `-d/--database ` (name, catalog alias, or id) to target a different database explicitly — it is required when no current database is set. The same `-d/--database` works on `search show` and `search remove`. - **Current database:** with `hotdata databases use `, an index created with a `schema.table` `--from` resolves the current database's catalog automatically. Or create it with the full `catalog.schema.table` form. Do **not** use the internal `__db_` label or raw catalog ID prefix — `bm25_search`/`vector_distance` resolve a catalog attached to the current database, so an `__db_…` or `conn…` prefix errors with *catalog … is not attached*. --- ## Indexes (text and vector) -Indexes are an **instant-database** concept, and belong to the database's own tables — an attached database is read-only, so index its tables there rather than here. Create names the index (positional) and attaches to a table via `--from` — `catalog.schema.table` (the database's own catalog), or `schema.table` with a current database set. `list` narrows to `-d/--database `, else the **current database** when one is set; without either it scans the whole workspace. `show`/`remove` resolve the index by name in the current database (or `--database `). +Indexes are an **instant-database** concept, and belong to the database's own tables — an attached database is read-only, so index its tables there rather than here. Create names the index (positional) and attaches to a table via `--from` — `catalog.schema.table` (the database's own catalog), or `schema.table` with a current database set. `list` narrows to `-d/--database `, else the **current database** when one is set; without either it scans the whole workspace. `show`/`remove` resolve the index by name in the current database (or `--database `). ```bash -# List — -d/--database , else the current database, else whole-workspace scan +# List — -d/--database , else the current database, else whole-workspace scan hotdata search list [-d ] [--schema ] [--table
] \ [--workspace-id ] [--output table|json|yaml] @@ -65,10 +65,10 @@ hotdata search create --type text|vector --from \ [--vector-precision float64|float32|float16|float8|int8] \ [--provider ] [--dimensions ] [--output-column ] [--description ] -# Show — by index name, in the current database (or -d/--database ) +# Show — by index name, in the current database (or -d/--database ) hotdata search show [-d ] [--output table|json|yaml] -# Remove — by index name, in the current database (or -d/--database ) +# Remove — by index name, in the current database (or -d/--database ) hotdata search remove [-d ] ``` From 8ee42e83288ee9e45b4356a20f42ab6ef8f34847 Mon Sep 17 00:00:00 2001 From: Eddie A Tejeda <669988+eddietejeda@users.noreply.github.com> Date: Sun, 18 Oct 2026 18:45:14 -0700 Subject: [PATCH 3/4] docs(readme): keep the Claude Code plugin section verbatim --- README.md | 24 +++++++++++++----------- 1 file changed, 13 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 69e2a28..20036f2 100644 --- a/README.md +++ b/README.md @@ -155,27 +155,31 @@ Your choice is saved on this machine and survives logging out and back in. `HOTDATA_API_KEY` in your environment or a `.env` file. - `hotdata query status` and `hotdata ingest run` return exit codes scripts can check: `0` done, `1` failed, `2` still running. +- `hotdata manage skills install` installs bundled agent skills — Markdown + playbooks that teach AI coding agents (Claude Code and friends) the full CLI. - `hotdata databases context push DATAMODEL` stores a Markdown description of your data model in Hotdata, so teammates and agents work from the same map. ### Claude Code plugin -The installer already sets up the Hotdata skill. If you'd rather get it through -Claude Code's plugin manager, which updates it with each release: +To get the agent skill through Claude Code's plugin manager instead, which +updates it with each release: ``` /plugin marketplace add hotdata-dev/claude-plugins /plugin install hotdata-cli@hotdata ``` -Use the plugin *or* the installer's skill, not both. If you use the plugin, -install the CLI with `curl -fsSL https://hotdata.dev/install | HOTDATA_NO_SKILLS=1 sh` -so Claude Code doesn't list the skill twice. To get plugin updates -automatically, open `/plugin` → **Marketplaces** → `hotdata` → -**Enable auto-update**. +Self-hosted marketplaces don't auto-update by default. To get each release +automatically, open `/plugin`, go to **Marketplaces**, select `hotdata`, and +choose **Enable auto-update**. Otherwise run `/plugin marketplace update hotdata` +when a new version ships. -
-What the plugin runs, sends, and fetches +Use either the plugin or the installer's skill, not both: if you installed the +CLI with the script above, install it with `HOTDATA_NO_SKILLS=1` or Claude Code +will list the skill twice. + +What the plugin runs, sends, and fetches: - **SessionStart hook** (`hooks/check-cli.sh`, Claude Code and Cowork only): checks whether `hotdata` is on `PATH` or in `~/.hotdata/cli`. If it's only in @@ -193,8 +197,6 @@ automatically, open `/plugin` → **Marketplaces** → `hotdata` → repository's GitHub releases for new versions (`HOTDATA_NO_UPDATE_CHECK=1` turns that off). Neither the plugin nor the CLI collects telemetry. -
- ## Getting help - `hotdata --help` shows every option for a command. From cc6b2535e32a6311c38e62b9ce3e8d4509e21237 Mon Sep 17 00:00:00 2001 From: Eddie A Tejeda <669988+eddietejeda@users.noreply.github.com> Date: Sun, 18 Oct 2026 18:48:01 -0700 Subject: [PATCH 4/4] docs(readme): runnable examples and links to the docs --- README.md | 53 +++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 39 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index 20036f2..f6de534 100644 --- a/README.md +++ b/README.md @@ -16,6 +16,8 @@ Load your data into a Hotdata database, then query, join, and search it with plain SQL. Data can come from files on your machine, a URL, or an external source such as Postgres, S3, Iceberg, Kafka, or one of ~150 API services. +📖 Full documentation: [hotdata.dev/docs](https://www.hotdata.dev/docs) + ## Install ```sh @@ -49,20 +51,23 @@ hotdata query "SELECT count(*) FROM demo.public.trips" ``` Tables are addressed as `catalog.schema.table`. Here the catalog is `demo` and -the default schema is `public`. +the default schema is `public`. The examples below build on this `demo` +database. For a longer walkthrough, see the +[quick start guide](https://www.hotdata.dev/docs/quick-start). ## Load your data -**From a file or URL** (CSV, JSON, or Parquet): +**From a file or URL** (CSV, JSON, or Parquet). Point `--file` at your own +file, or `--url` at one online: ```sh -hotdata databases load --catalog demo --table listings --file ./listings.csv +hotdata databases load --catalog demo --table my_table --file ./my-data.csv ``` A load replaces the table. To add rows instead, use `--mode append`: ```sh -hotdata databases load --catalog demo --table listings --file ./more.csv --mode append +hotdata databases load --catalog demo --table my_table --file ./more-data.csv --mode append ``` To change existing rows by key, use `--mode update`, `--mode delete`, or @@ -80,6 +85,9 @@ hotdata ingest create --source "prod postgres" --table orders --database-id `. +Column names are case-sensitive: wrap names with capital letters in double +quotes, like `"PULocationID"`. See the [SQL reference](https://www.hotdata.dev/docs/sql) +for the supported syntax and functions. + ## Join across databases -Attach another of your databases to query its tables alongside your own. No -data is copied: +Keep reference data in its own database and attach it wherever you need it. No +data is copied. For example, load NYC's taxi zone names into a `zones` +database, attach it to `demo`, and find the busiest pickup zones: ```sh -hotdata databases attach sales --alias sales -hotdata query "SELECT t.id, o.total - FROM demo.public.tickets t - JOIN sales.public.orders o ON o.ticket_id = t.id" +hotdata databases create --catalog zones +hotdata databases load --catalog zones --table zones \ + --url https://d37ci6vzurychx.cloudfront.net/misc/taxi_zone_lookup.csv +hotdata databases attach zones + +hotdata query 'SELECT z."Zone", count(*) AS trips + FROM demo.public.trips t + JOIN zones.public.zones z ON z."LocationID" = t."PULocationID" + GROUP BY z."Zone" ORDER BY trips DESC LIMIT 5' ``` -Attached tables are read-only. `hotdata databases detach sales` removes the +Attached tables are read-only. `hotdata databases detach zones` removes the link without deleting anything. ## Search -Build a search index on a column, then search it: +Build a search index on a column, then search it. Using the `zones` table from +above: ```sh -hotdata search create trip_notes --type text --from demo.public.trips --column notes -hotdata search "airport surcharge dispute" --index trip_notes +hotdata search create zone_names --type text --from zones.public.zones --column Zone +hotdata search "airport" --index zone_names -d zones ``` +That returns JFK, LaGuardia, and Newark airports. An index lives in the same +database as its table, so pass `-d` when that isn't your current database. + - `--type text` is full-text (keyword) search. - `--type vector` is semantic search. Hotdata creates the embeddings for you, so you don't need an embeddings API key. @@ -199,6 +221,9 @@ What the plugin runs, sends, and fetches: ## Getting help +- [Documentation](https://www.hotdata.dev/docs), including the + [CLI reference](https://www.hotdata.dev/docs/cli-reference) and the + [agent skills guide](https://www.hotdata.dev/docs/agent-skills). - `hotdata --help` shows every option for a command. - File a support ticket from the terminal; replies go to your account email: