# Query every backend through one SQL surface

Source: https://www.hotdata.dev/use-cases/unified-sql
Site index: https://www.hotdata.dev/llms.txt

Most teams don't want a different tool for every backend. Register your sources once and query databases, SaaS apps, and uploads from the same SQL surface without bouncing between consoles or dialects.

## How it works

### Step 1: Query Postgres through `hotdata query`

Here `postgres.public.orders`. GitHub-backed tables use the same `connection.schema.table` pattern (confirm names with `hotdata databases tables list`).

**Claude**

```
Our app database and GitHub are already linked here. Give me every open order with just order id and dollar total, up to 100 rows.
```

**CLI**

```bash
hotdata query "SELECT order_id, total FROM postgres.public.orders WHERE status = 'open' LIMIT 100" --workspace-id <workspace_id>
```

**Python SDK**

```python
import hotdata

query_api = hotdata.QueryApi(api_client)
query_api.query(
    hotdata.QueryRequest(
        sql=(
            "SELECT order_id, total FROM postgres.public.orders "
            "WHERE status = 'open' LIMIT 100"
        ),
    ),
)
```

Heavy or routed queries sometimes return async metadata instead. The engine would rather give you a run id than hold the connection until everything finishes.

### Step 2: Query instant-database tables like connection tables

Instant-database tables sit in the same SQL namespace as `postgres` and `github` (for example `default.public.*`).

**Claude**

```
Pull the first 50 rows from my partner_accounts table with every column included.
```

**CLI**

```bash
hotdata query "SELECT * FROM default.public.partner_accounts LIMIT 50"
```

**Python SDK**

```python
import hotdata

query_api = hotdata.QueryApi(api_client)
query_api.query(
    hotdata.QueryRequest(sql="SELECT * FROM default.public.partner_accounts LIMIT 50"),
)
```

### Step 3: Mirror everything in the CLI for debugging

**Claude**

```
Run the open-orders check again, then show the 50 most recently updated GitHub issues (number, title, state). After that, list recent query activity so support can match what was tried.
```

**CLI**

```bash
hotdata query "SELECT order_id, total FROM postgres.public.orders WHERE status = 'open' LIMIT 100" --workspace-id <workspace_id>
hotdata query "SELECT number, title, state FROM github.github.issues ORDER BY updated_at DESC LIMIT 50" --workspace-id <workspace_id>
hotdata databases queries list
```

**Python SDK**

```python
import hotdata

query_api = hotdata.QueryApi(api_client)
query_api.query(
    hotdata.QueryRequest(
        sql=(
            "SELECT order_id, total FROM postgres.public.orders "
            "WHERE status = 'open' LIMIT 100"
        ),
    ),
)
query_api.query(
    hotdata.QueryRequest(
        sql=(
            "SELECT number, title, state FROM github.github.issues "
            "ORDER BY updated_at DESC LIMIT 50"
        ),
    ),
)
runs = hotdata.QueryRunsApi(api_client)
runs.list_query_runs(limit=20)
```

### Step 4: Guardrails with database context

Optional shared docs (like **`DATAMODEL`**) spell out joins and naming beyond what the raw catalog shows. See [Database context](/docs/api-reference/database-context).

## Who uses this

- Teams shipping one SQL interface to multiple apps or dashboards.
- Products that run agent tools against the same SQL surface across several backends.
- Internal platforms that want one workspace and one governed path for queries.