Logical views#

A logical view is a named, parameter-free typesql query. Supernova expands it into the calling query before type checking, policy admission, snapshot selection, or execution.

select customer_id, revenue
from finance.customer_revenue
where revenue > 1000

What a logical view is#

A logical view is reusable query text. It is not an Iceberg view and does not materialize data. Each reference expands to a parenthesized derived query with an unambiguous alias.

Definitions use 2-part [schema, view] or 3-part [catalog, schema, view] names. Matching is ASCII-case-insensitive by part, but the caller supplies one closed, authorized definition set.

Expansion guarantees#

Every supplied definition must contain exactly one query and no positional, named, or question-mark parameter. Expansion understands relation and qualification scopes; it does not use text substitution. A correlated subquery cannot capture a generated alias accidentally.

The expansion artifact records the authored query, expanded SQL, every used view, and a SHA-256 digest of each exact definition. That provenance participates in downstream identity.

Diagnostics and limits#

TS0800 reports an invalid environment or definition. TS0801 reports a cycle. TS0802 reports a bound exceeded. TS0803 reports an invalid logical-view document.

The environment admits up to 4,096 views and 64 expansion levels. The raw root SQL and decoded view SQL are bounded before expansion so an invalid environment fails without publishing a partial result.

Use a model when you need a durable table. Use a logical view when reuse and type checking matter but materialization does not.