Running queries#

When you run a query, Supernova validates one read-only statement, resolves every lake table, fixes the snapshots it will read, and records a durable result. The same SQL therefore reads one coherent set of table snapshots even if a sync commits while it runs.

select count(*) as active_customers
from titan.stripe.customers
where not _deleted

Before the run starts#

TypeSQL parsing and analysis identify table references, annotations, parameters, and unsupported statements. The admission boundary accepts one statement. Lake-changing statements such as insert, update, delete, drop, attach, and copy are refused before data credentials are available to the query.

The catalog then resolves titan.<schema>.<table> to exact snapshots. A failed resolution stops the request; Supernova never substitutes a newer table silently.

While it runs#

Ad hoc queries have a 600-second runtime limit. The query page can cancel an active run. Memory pressure may retry eligible work with a larger memory budget, but the query text and selected snapshots do not change.

The durable result is Parquet. Interactive surfaces may show only a bounded preview; see Query limits for the exact cap on each surface. A preview cap is not a truncation of the Parquet result.

Results and export#

Use the query page for inspection and download the result when you need every row. The API returns signed Parquet files by default and can return paginated inline JSON for bounded integrations.

An order by is required whenever row order matters. Without it, neither the preview nor a later read of the result promises an order.

Failures#

A failure records its class and message with the run. TypeSQL diagnostics use stable TS#### codes and source locations. Resource limits say which ceiling was reached. A cancellation is distinct from a failed query, so automation can decide whether to retry.