# Big SQL (Athena)

Query a large CSV with SQL from a single API call — for datasets past the ceiling of the in-process [`/v1/data/sql`](/docs/data-sql) (DuckDB) op. You supply the file; it becomes a table named **`input`**; you send SELECT-only SQL; the query runs on **AWS Athena** and returns rows. Pricing is **metered on bytes scanned** and **settles at the actual** scan — you authorize a ceiling and pay what the query actually read.

```bash
curl -X POST https://api.relaystation.ai/v1/data/sql-large \
  -H 'Authorization: Bearer rs_live_<key>' \
  -H 'Idempotency-Key: sql-large-20260707' \
  -H 'Content-Type: application/json' \
  -d '{ "file": { "inputKey": "<key from upload-url>" },
        "sql": "SELECT category, COUNT(*) AS n FROM input GROUP BY category ORDER BY n DESC" }'
```

Or on the lodestone path — no account, a signed x402 payment instead of an API key:

```bash
curl -X POST https://api.relaystation.ai/v1/data/sql-large \
  -H 'X-Payment: <base64 EIP-3009 authorization>' \
  -H 'Idempotency-Key: sql-large-20260707' \
  -H 'Content-Type: application/json' \
  -d '{ "file": { "inputKey": "<key from upload-url>" },
        "sql": "SELECT * FROM input WHERE amount > 1000 LIMIT 100" }'
```

## Request

`POST /v1/data/sql-large`:

| Field | Type | Notes |
|---|---|---|
| `file` | input source, required | a **CSV** file, header row required. `{ "inline": "<base64>" }` ≤ 4 MiB, or `{ "inputKey": "..." }` for larger files (the usual reason to reach for this op) |
| `sql` | string, required | **SELECT-only** (or `WITH … SELECT`); 1–20000 chars. Your file is the table named `input`. A trailing semicolon is tolerated |
| `format` | enum | result shape: `csv` or `json` |

**SELECT / WITH only.** Anything else (INSERT, DDL, PRAGMA, …) is rejected pre-charge with a `422` — this is a read-only query surface. Your CSV's header row becomes the column names (lowercased, `[a-z0-9_]`-safe). For a large file, mint a presigned upload with `POST /v1/cputools/upload-url` and pass `{"inputKey":"..."}` — see [Passing & receiving files](/docs/receiving-outputs).

## Response

The query result comes back in the uniform JSON output envelope, plus a **scan / billing receipt** — the actual `dataScannedBytes`, the billed increments, the charged amount, and the ceiling. That receipt is why the price is auditable: you see exactly how many bytes Athena scanned.

## Caps and the sync window

- **Scan cap** — the query's scan is bounded by `data.sql_large.max_scan_mb` (seed 500 MB). The authorized ceiling is computed from the input size (an upper bound on any single-file scan) and the operator cap.
- **Synchronous window** — the call holds the connection while Athena runs, bounded by `data.sql_large.sync_window_ms`. A query that can't finish in the window fails and the charge is reversed.
- **Failure discipline** — user-caused failures (bad SQL, an unreadable CSV, a timeout) return a `422` and reverse the charge; infrastructure failures (throttle / upstream 5xx) return a `502` and reverse the charge. You pay only for a delivered result.

## Billing

Metered on **bytes scanned** (per 100 MB increments), **settle-at-actual**: you authorize a ceiling at submit and pay the actual scan, never more than the ceiling. Priced per scanned unit; see [Pricing](/pricing) for the current rate, or send an unauthenticated `POST` to read the exact price from the `402` challenge. Every billable call needs an `Idempotency-Key`; a same-key retry returns the cached result without re-charging.

## Which SQL op?

- **In-process, smaller data** → [`/v1/data/sql`](/docs/data-sql) (DuckDB) — fast, no scan-metering, for files within its ceiling.
- **Large data, scan-metered** → `/v1/data/sql-large` (Athena) — this op, for CSVs past the DuckDB ceiling.

## MCP tools

Callable over MCP at `https://api.relaystation.ai/mcp` as `data_sql_large`. Same auth, same pricing as the HTTP route.

## Next

[Data & SQL tools](/docs/data-sql) · [Passing & receiving files](/docs/receiving-outputs) · [Pricing](/pricing) · [x402 wire format](/docs/x402) · [API reference](/api-reference)