Quick Start

Upload and query data from the terminal, a Python notebook, or inside an AI agent. Follow the steps below to authenticate and run your first query.

CLI

Python SDK

Fast path: create, load, and query

hotdata databases create \
  --name airbnb \
  --catalog airbnb \
  --table listings

hotdata databases load \
  --catalog airbnb \
  --table listings \
  --url https://hotdata.dev/data/sf-airbnb-listings.parquet

hotdata query \
  "SELECT COUNT(id) AS total_rows FROM airbnb.public.listings"

1) Install the CLI

Install walkthrough (YouTube):

curl -fsSL https://hotdata.dev/install | sh

Verify the installation:

hotdata --help

2) Authenticate

Authenticate via browser:

hotdata auth login

A browser window will open for you to sign in and authorize the CLI. Verify you're logged in:

hotdata auth status

3) Instant databases

Instant databases are Hotdata-owned catalogs you populate by loading csv, json, or parquet files. Create them on demand, load data, query immediately, and delete when done.

Instant database tutorial (YouTube):

Create a database and declare the tables you plan to load:

hotdata databases create \
  --name mydb \
  --catalog mydb \
  --table orders \
  --table customers

Load a csv, json, or parquet file from a local path or URL. The format comes from the extension, and --format overrides it:

# From a local file
hotdata databases load \
  --catalog mydb \
  --table orders \
  --file orders.csv

# From a URL
hotdata databases load \
  --catalog mydb \
  --table orders \
  --url https://hotdata.dev/data/sf-airbnb-listings.parquet

Query the loaded table — managed tables are addressed as <catalog>.<schema>.<table>, where <catalog> is the alias you set with --catalog:

hotdata query \
  "SELECT * FROM mydb.public.orders LIMIT 10"

List databases and their tables:

hotdata databases list
hotdata databases tables mydb

Delete a table or the whole database when you're done:

hotdata databases tables remove orders --database mydb
hotdata databases remove mydb

4) Query your data

Basic query

hotdata query "SELECT id FROM mydb.public.orders LIMIT 5"

The database is resolved automatically from the catalog-qualified table name (mydb.public.orders), so no extra flag is needed. Use -o table|json|csv to change the output format, or --database <id> to target a specific instant database by its id.

Analytical functions

Window functions for rankings, running totals, and row comparisons:

hotdata query "
  SELECT id, amount,
    sum(amount) OVER (
      ORDER BY id
      ROWS BETWEEN UNBOUNDED PRECEDING
        AND CURRENT ROW
    ) AS running_total
  FROM mydb.public.orders
  LIMIT 10
"

hotdata query "
  SELECT date, symbol, price,
    lag(price) OVER (
      PARTITION BY symbol
      ORDER BY date
    ) AS prev_price
  FROM mydb.public.stock_prices
"

Full-text search

Create a full-text index on the text column, then search it by name — the search type is inferred from the index:

hotdata search create articles_body \
  --type text \
  --from mydb.public.articles \
  --column body

hotdata search "machine learning" \
  --index articles_body \
  --select id,title,body \
  --limit 10

Vector search

Create a vector index — --provider auto-embeds the text column server-side. Then search it by name; the server resolves the embedding model from the index metadata:

Vector search demo (YouTube):

hotdata search create documents_body \
  --type vector \
  --from mydb.public.documents \
  --column body \
  --provider <embedding_provider_id>

hotdata search "documents about machine learning" \
  --index documents_body \
  --limit 10

An auto-embedding vector index has to be the only index on its table, so this example indexes documents rather than adding a second index to the articles table used above. If you try both on one table, whichever you create second is rejected. See vector indexes.

Equivalent SQL, embedding the query text with the same provider:

hotdata query "
  SELECT id, title,
    vector_distance(body, 'documents about machine learning') AS dist
  FROM mydb.public.documents
  ORDER BY dist ASC LIMIT 10
"

The index stores the generated embeddings in a new column, body_embedding by default. If you already have a query vector, search that column with the distance function matching the index's metric: l2_distance, cosine_distance or negative_dot_product. See distance functions.