Glossary
The words these docs use, defined as they are used here. Each entry says what a thing is and what it guarantees, not how it is implemented.
Plans and queries
| Term | Meaning |
|---|---|
| Ultra IR | The query plan language every request passes through, whether it starts as SQL, a search or an AI request. A plan is a small graph of typed operators (scan, filter, project, join, aggregate, sort, limit, the security operators and a result sink). See Ultra IR. |
| Plan | One Ultra IR graph, built by the gateway from a SQL statement and sent to the data node in its canonical binary form. The plan is what gets optimized, cached, verified and run. |
| Verifier | The small component on every data node that checks each plan before it runs: its types, and that it isolates the tenant, applies the access policy and hides restricted fields. A plan it accepts returns only data the requester may see, whoever produced the plan. See Security model. |
| Reference interpreter | A deliberately simple evaluator of Ultra IR that defines the right answer. The fast executor and every optimizer rewrite must match it. |
| Canonical encoding (UCE) | The rule that one plan or value has exactly one byte string: protocol buffers with extra constraints (fields in order, defaults omitted, shortest integers, one NaN, minimal decimals, sorted maps). Decoders reject every other encoding. Rust and Go produce byte-identical output. |
| Fingerprint | A BLAKE3 hash of a plan's canonical encoding, with a domain prefix so it can never be confused with another hash. Plans that mean the same thing share a fingerprint. A request fingerprint adds parameters, tenant, policy version and snapshot. |
| Plan cache | Reuse of an already optimized plan, keyed by its fingerprint together with the catalog and policy versions. A cached plan is still verified by the node before it runs. |
| Catalog version | A counter the node advances when the schema changes. A plan carries the version it was built against; a plan built against an older catalog is refused so the gateway rebuilds it. |
| Policy version | A counter for the access policy in force. It is part of the query environment and the request fingerprint, so a plan authorized under one policy is not reused under another. |
Tenants and access
| Term | Meaning |
|---|---|
| Tenant | The unit of isolation: one workspace, team or customer. Every table holds rows of many tenants, a query reads only its own tenant's rows, and primary keys are unique per tenant. The tenant comes only from the verified token, never from a header or a column a client sets. |
| Key range | The contiguous span of keys in the storage engine that holds one tenant's rows of one collection. Tenant isolation is a key range, not a filter: a plan reads that range and nothing outside it. |
| Clearance | The level a requester holds: public, internal, confidential or restricted (default internal), carried in the token as uf_clearance. Columns classified above it are hidden from that requester. |
| Field mask | The security operator that hides the fields a requester's clearance does not cover. An UPDATE that would touch a masked field is refused rather than write the hidden value back. |
| Operator credential | A separate kind of token (uf_operator: true, no tenant) for the application's operator. It can create tables and make node-wide requests, and can never read or write tenant rows. An ordinary tenant token, even with an admin role, can never manage the schema. |
| Declared-leakage register | A planned public list of the channels the isolation guarantee does not cover, such as timing and result size, each with its bound and mitigation. Owning and reviewing it is an open governance question in the specification. |
Storage
| Term | Meaning |
|---|---|
Node (ufd) | The server that owns one storage engine and runs the verifier and executor. It serves a local Unix socket only and never listens on the network. See Node protocol v0. |
Gateway (ufgw) | The Go process that speaks the PostgreSQL protocol to clients, verifies tokens, parses SQL with PostgreSQL's own parser and binds each statement into a plan for the node. It is treated as an untrusted plan author: the node checks everything it sends. |
| Row collection | A table stored row by row under its primary key. The default; supports INSERT, UPDATE and DELETE, and point lookups read one row. |
| Columnar collection | A table created WITH (storage = columnar): append-only, stored column by column for analytic scans. Inserting an existing key fails; there is no update or delete. The five TPC-H queries measured run 2.5 to 7 times faster on it than on row storage (indicative, shared host). |
| Row group | The unit of columnar storage: up to 4,096 rows of one tenant written as one chunk per column, with per-chunk bounds so scans can skip groups that cannot match. |
| Delta | The rows of a columnar collection that have arrived since its last compaction, kept row by row until enough have accumulated to form a row group. |
| Marker | A small record left behind when a row moves from the delta into a row group, so that a duplicate key is still detected by one point lookup, and kept apart from row data so delta scans never read moved rows' values. |
| Snapshot isolation | The transaction model of the engine: a transaction reads from one snapshot and sees a consistent state as of that moment. Serializable isolation comes with the distributed phase. |
| First committer wins | The conflict rule under snapshot isolation: a transaction commits only if no other transaction committed a write to the same keys after its snapshot; otherwise it fails and must retry. |
| GC horizon | The timestamp before which old row versions may be discarded. It advances on its own after the retention window (default 60 seconds); reading at a snapshot older than the horizon is an explicit error. |
| Idempotency key | A client-chosen key stored with a write. Retrying the same key returns the original outcome instead of writing twice; retrying it with a different batch is an error. |
Testing and process
| Term | Meaning |
|---|---|
| Differential testing | Running the same workload against two implementations and comparing every answer: the storage engine against RocksDB and a simple model, the executor and every rewrite against the reference interpreter, and SQL against DuckDB. See How we test. |
| Noninterference check | The tenant-isolation test: for a generated query, a second database is built that differs only in what the requester may not see, and both must give the same answer. Roughly one million such checks ran in the ten-million-query campaign with no failure. |
| Mutation testing | Changing the code on purpose (dropping a check, flipping a comparison) and confirming the tests fail. A surviving mutant becomes a new test or is shown to be equivalent. |
| Phase gate | The checklist a phase must pass before the next one starts, written down in advance. A missed gate is recorded in an architecture decision record and re-scoped, never waved through. |
| Indicative measurement | Any number measured on the shared development host (3 CPUs, 6 GB cap, other services running). It shows direction, not a promise. Performance targets count as met only on a dedicated, idle host, which the project does not have yet. |