# Quick Start

Source: https://www.hotdata.dev/docs/quick-start
Site index: https://www.hotdata.dev/llms.txt

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](/docs/cli-reference) [Python SDK](/docs/python-sdk) [Rust SDK](/docs/rust-sdk) [Agent Skills](/docs/agent-skills) [Ibis](/docs/ibis) [LangChain](/docs/langchain) [dlt](/docs/dlthub)

## Fast path: create, load, and query

```bash
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](https://youtu.be/LLo3A329FH4)):

```bash
brew install hotdata-dev/tap/cli
```

Verify the installation:

```bash
hotdata --help
```

## 2) Authenticate

Authenticate via browser:

```bash
hotdata auth login
```

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

```bash
hotdata auth status
```

## 3) Instant databases

**Instant databases** are Hotdata-owned catalogs you populate with parquet files. Create them on demand, load data, query immediately, and delete when done.

Instant database tutorial ([YouTube](https://www.youtube.com/watch?v=QMOURDIVgYo)):

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

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

Load a parquet file from a local path or URL:

```bash
# From a local file
hotdata databases load \
  --catalog mydb \
  --table orders \
  --file orders.parquet

# 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`:

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

List databases and their tables:

```bash
hotdata databases list
hotdata databases tables mydb
```

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

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

## 4) Query your data

### Basic query

```bash
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:

```bash
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
"
```

```bash
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](/docs/cli-reference#search) on the text column, then search it by name — the search type is inferred from the index:

```bash
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](/docs/cli-reference#search) — `--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](https://youtu.be/JEONO7N06-4)):

```bash
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](/docs/sql#vector-indexes).

Equivalent SQL when you already have a query vector:

```bash
hotdata query "
  SELECT id, title,
    l2_distance(embedding, ARRAY[0.1, -0.2, 0.5]) AS dist
  FROM mydb.public.documents
  ORDER BY dist ASC LIMIT 10
"
```

For cosine similarity, use `cosine_distance`; for inner product, use `negative_dot_product`.

## See also

- [CLI Reference](/docs/cli-reference) — Full CLI documentation
- [Agent Skills](/docs/agent-skills) — Let Claude Code and Cursor run hotdata commands for you
- [API Reference](/docs/api-reference) — HTTP API for automation and integrations
- [Pull Data](/docs/pull-data) — Supported ingest sources