11. Views

A view is a named read query kept in the _views collection, one document per version. Views are how a data model is written in OGML: each view reads collections or other views, and queries, reports and other views read it like a collection.

define view sales.paid
| description "Paid orders with their total"
| exec
  | on orders | where status == "paid" | derive total = price * qty
| end
| end

{"name":"sales.paid","version":1,"state":"active","description":"Paid orders with their total",
 "query":"on orders | where status == \"paid\" | derive total = price * qty",
 "parameters":[],"reads":["orders"],"materialized":false,"createdBy":"…","createdAt":…}

11.1 define view

Definition. Writes a new version of a view.

Syntax

define view <name>
[| description "<text>"]
[| materialized]
| exec
  | <query>
| end
| end

define view <name> | description "<text>" | end      -- a new version, another description
define view <name> | version <n> | end               -- restores version n as a new version
define view <name> | end                            -- a new version, identical

Written without | (3.2), the view of the chapter opening reads:

define view sales.paid
description "Paid orders with their total"
exec
  on orders
  where status == "paid"
  derive total = price * qty
end
end

Its query keeps that text, line breaks included.

Behavior

• <name> is identifiers joined by dots: ledger.cube, sales.by_month.
• exec is the last clause; the body runs from exec to the two final end (the body’s own end stay in it).
• Each define writes a new version and marks the previous active one superseded. Without description, the description is kept; without materialized, a restore or a copy keeps the flag of the version it copies.
• The body is checked when defined: planned with its parameters read as 1, and refused when it writes (view.invalid: a view only reads: its query cannot insert, set, delete or load), when it reads a view that does not exist, or when it makes a cycle.
• The definition records:

• History is never rewritten: every version stays in _views.

Who may define views. In a Place, its Owner. Outside a Place, a standard view, which needs the right to write _views. explain define view … checks without writing.

Errors and limits

11.2 undefine view

undefine view <name>

Marks the active version deleted. The standard view of the same name, if any, is read again by the Place. The cache of a materialized view leaves with it.

11.3 Reading a view

on view <name> [version <n>] [as <alias>]
lookup view <name> [version <n>] as <alias> | … | end
lookup view <name> as <alias> on <joined field> == <outer field> into <field>
union | on view <name> | … | end
let $rows = (on view <name> | …)

Behavior

• The view’s query replaces the source before the query is planned: the plan, explain and authorization see the collections it reads, and the stages that follow are optimized with it (a filter after a view reaches the view’s source, 14.2).
• In a Place, the Place’s view is read, else the standard view of that name; its active version, or version <n>.
• lookup view needs a view whose source is a bare on <collection> or on values […]; as <alias> names the view’s source, which must not have one already.
• Views are resolved by the query service (the query.execute operation), not by the bare pipeline layer of the engine library.

Examples

on view sales.paid | group | by region | sum total | end
on view ledger.cube version 1 | union | on view ledger.cube | end
on orders | lookup view catalog.products as c on c.code == product into product

11.4 Parameters

A view’s parameters are the $name its body reads without declaring. They are bound by the reading query: request params, or its let variables.

define view sales.since | exec | on orders | where month >= $since | end | end

let $since = "2026-02" | on view sales.since

• let $name ?= <default> in the body gives a default, used when the reader binds nothing:

define view orders.big | exec | let $min ?= 2 | on orders | where qty >= $min | end | end

on view orders.big | count                     -- {"count":4}
let $min = 4 | on view orders.big | count      -- {"count":2}

• The view’s own let stay local: they may shadow a variable of the reading query, which cannot read them.
• An unbound parameter fails the reading query: $scenario is not bound.
• A materialized view takes no parameter: its body binds them with let.

11.5 Listing views

on _views | where state == "active" | select name, version, parameters, reads, materialized
on _views | where name == "sales.paid" | sort version | select version, state, createdAt, query

In a Place, _views shows only that Place’s views and the standard ones; only define and undefine write it.

11.6 Standard views

A view defined outside any Place is a standard view: every Place reads it, unless the Place defines a view of the same name, which then takes its place for that Place. Standard views suit definitions shared by every Place (a calendar, a reference classification); Place views suit what one Place models for itself.

Never assume a standard view exists: a node may hold none. Read on _views first, or define what you need.

11.7 Views and Places

A view never reads across Places: whichever view is read, its sources read the rows of the Place running the query.