Guides

SQL warehouses

A SQL warehouse is a VM provisioned in your cloud with two sidecars, DuckDB (reads) and Spark (writes & maintenance). It starts on demand and stops itself when idle, so you only pay while querying.

Lifecycle

State	Meaning
`stopped`	No VM running. No cost.
`starting`	VM provisioning + sidecars booting (~3 min).
`running`	Ready to serve queries.
`stopping`	Auto-stop or manual stop in progress.

Start a warehouse

polnor sql warehouse start analytics
# or via API
POST /api/v1/sql/warehouses/{id}/start

Execute SQL

Send a query to a running warehouse. Polnor routes reads to DuckDB and writes to Spark automatically.

curl -s https://api.polnor.net/api/v1/sql/execute \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"SELECT * FROM acme.sales.orders LIMIT 10",
       "warehouse_id":"wh_…"}'

Stop a warehouse

Stop manually to release the VM immediately, or let auto-stop handle it.

polnor sql warehouse stop analytics

Cost control. Idle warehouses auto-stop, and a reconciler reaps any VM stuck in starting beyond its window, so a failed provision never leaves a billable VM running silently.

Lineage

Every statement records the tables it read and wrote into the run's data-access log, surfaced as lineage. The sidecars return a lineage field that the control plane persists per statement.