Queries and live queries

A query is a read. live: true makes it subscribable. Never writes, never enqueues, never sends mail.

As of 2026-08-23. Stable API — semver from here (Upgrading). All three tiers of Realtime ship. Tier 3 (local-first) shipped in 21.0.0, opt-in: persist is an entity() option, read by realtime's IndexedDB store and one outbox (Realtime). persist is not a field query() accepts; writing it is a TS2353 excess property.

The canonical shape

// query
export const liveFeed = query({
  input: t.object({ orgId: t.uuid }),
  policy: can('feed:read'),
  live: true,
  sql: ({ orgId }) => db.posts.where({ orgId }).orderBy('createdAt').limit(50),
});

Fields

Nothing else is a query field. Sorting, paging, and filtering are input fields consumed by sql.

The fluent surface

Every projection this package owns is a method on the query — liveFeed.live(input), never toLiveQuery(liveFeed, input) — and every declared field is lifted onto it. The MCP read tool is @ultimat3/mcp's one projection, toolFrom(liveFeed) (As of 25.0.0 there is no .tool()). A query has no .def.

sql is unreachable by design. The declaration lives in a private store inside read.ts and @ultimat3/query exports no reader for it, so sourceFor is the only thing that can build a source — one read path and one authz path, structurally rather than by convention. A hand-rolled object with kind: 'query' is X_QUERY_FOREIGN, never a registered read.

isLive is the declared boolean; live() is the subscription itself. Every projection needs the name defineApi({ queries }) stamps on at boot — before that, X_QUERY_UNREGISTERED.

Five projections

The read hook, precisely

One read hook, useQuery, in 21.0.0. useLive and liveHookFor are deleted. Live-ness belongs to the query declaration, not to the hook an island picks.

import { useQuery } from '@ultimat3/realtime';

type FeedRow = { id: string; title: string };
declare const orgId: string;

const feed = useQuery<FeedRow>({ name: 'liveFeed', live: true }, { orgId });
// feed(): AsyncState<readonly FeedRow[]>; feed.refetch(); feed.release()

The HTTP GET, precisely

Mounted for every registered query by x dev and by a container, from one composition — nothing to wire in the app.

A read with a validator — etag: true

// `postRecord` in examples/dummy: the like island re-reads it on every load of /posts/{id}.
import { can } from '@ultimat3/policy';
import { from, query, t } from '@ultimat3/query';

interface PostRow {
  readonly id: string;
  readonly orgId: string;
  readonly likeCount: number;
}
declare const posts: readonly PostRow[];

export const postRecord = query({
  input: t.object({ orgId: t.uuid, postId: t.uuid }),
  policy: can('post:read'),
  etag: true,
  sql: ({ orgId, postId }) =>
    from<PostRow>('posts', posts).where({ orgId, id: postId }).orderBy('id').limit(1),
});
// GET /_x/query/post-record?…                      → 200, ETag: "…", cache-control: private, no-cache
// GET /_x/query/post-record?…  If-None-Match: "…"  → 304, no body (same actor, same bytes)

A read of one object — single: true

export const postById = query({
  input: t.object({ id: t.uuid }),
  policy: can('post:read'),
  single: true,
  sql: ({ id }) => db.posts.where({ id }).limit(1),
});
// GET /_x/query/post-by-id?id=…  → 200 { id, title, … }  ·  404 X_NOT_FOUND
// await postById.client({ baseUrl })({ id })  → Promise<Row>
// await postById({ id })                       → readonly Row[]  (unchanged in process)

Two spellings of that client, one URL

.client({ baseUrl }) binds one read; queryClient<Api['queries']>({ baseUrl }) binds every registered read at once, the way rpc<Api['actions']> does for writes. Both run queryClientMethodFor, so the URL cannot differ between them.

// apps/web/shared/client.ts — the app's one place for both
export const client = rpc<Api['actions']>({ baseUrl });         // writes
export const queries = queryClient<Api['queries']>({ baseUrl }); // reads

A file at a signed URL — download:

As of 2026-10-31. A read whose answer is bytes — a recording, an export, an attachment, a sealed object decrypted on the way out — is a query with download: instead of sql:. Same input, same policy, same name, same route; never a base64 string inside a JSON answer.

import { open } from '@ultimat3/core';
import { can } from '@ultimat3/policy';
import { query, queryClient, t } from '@ultimat3/query';
import { disk } from '@ultimat3/storage';

export const runRecording = query({
  input: t.object({ runId: t.uuid }),
  policy: can('recording:watch'),
  download: {
    expiresInMs: 600_000, // 1 000 … 3 600 000; default 300 000
    async handle({ input }) {
      const key = `runs/${input.runId}/recording`;
      const { bytes } = await disk('debug').get(key);
      const plain = await open(new TextDecoder().decode(bytes), { purpose: `run-debug:${key}` });
      return { body: plain, contentType: 'video/mp4', filename: `run-${input.runId}.mp4` };
    },
  },
});

// an island: mint, then hand the URL to the element that plays or saves it
declare const video: { src: string };
const client = queryClient<{ runRecording: typeof runRecording }>({ baseUrl: '' });
const { url } = await client.runRecording.url({ runId: '00000000-0000-4000-8000-000000000001' });
video.src = url;

handle answers { body: Uint8Array | Blob | ReadableStream, contentType, filename, disposition?, size? }, or body: (range?) => BodyInit with size required. A Uint8Array or a Blob (a Bun.file, sliced lazily) is always range-served; a stream only with size, else whole with accept-ranges: none, and a window of one reads and drops its prefix. The function form opens only the window: (range) => range === undefined ? disk.stream(key) : disk.streamRange(key, [range.start, range.end]). A sealed object cannot take it, since an envelope opens whole. A sealed object is one AES-GCM envelope, so it is read with get() (bounded by maxGetBytes) and opened whole before a byte is served.

.live(), .page(), .as(), sourceFor and an MCP tool are X_QUERY_DOWNLOAD_ONLY; the manifest marks the read download: true (rows ↔ download is breaking), and x routes lists it on the read's own GET /_x/query/<kebab>. In-process, await runRecording(input, { ctx }) is the DownloadFile and await runRecording.url(input, { ctx }) the path.

Owns / never

live: true requires deterministic, bounded SQL

x verify rejects a live query without both an orderBy and a limit.

A patched row lands where order by returns it (As of 2026-10). The matcher, from()'s in-memory execution and the cursor fallback compare two values by the column's DECLARED kind, through @ultimat3/entity's own comparator — @ultimat3/query has none. A bigint() or decimal() column orders by its digits (its row value is decimal text: '9' before '10'), a uuid() is a value whatever its case, a timestamp() is an instant. The kinds resolve from the entity declared on the table from(name, …) names; a relation no entity declares has none, and its digits compare as text — as a text column's do. A custom SqlSource calling compareRows, matchesFilter or isAfterKey passes kindsOf(shape.entity); compareValues is gone.

A page is served order by <declared keys>, "id" asc, and so is a live window — As of 2026-08, the initial window, the matcher's patch positions and the keyset re-read a reconnect resumes with are one ordering. A row tied on every declared key lands where its id puts it, not after the tie group, and not wherever the database happened to return it. x queries show <name> --json prints the order. A row that reaches the matcher with no id is X_QUERY_NOT_PAGEABLE, never a patch aimed at a position no client holds.

A non-live query has none of these constraints — it is just a read.

A sealed column never rides on a row

Nothing parses a query's row on its way out: a declared rows: is published as the row's structure, never applied to the row. A .sealed() column stays behind because the repository row does not enumerate it (Sealed columns), As of 2026-10.

Row-level policy filtering

Policy is not a subscribe-time gate that then trusts the stream.

One authz system. A live query cannot become a second door into your data — that is the failure mode that killed the allow/deny generation of frameworks (The eight primitives).

NULL

As of 2026-08, one rule for the generated SQL, the in-memory source behind from() and the live matcher alike. null and a column the row omits are the same absence.

where({ deletedAt: null }) emits "deletedAt" is null and binds no parameter. = $1 with a NULL argument is unknown in Postgres and unknown is never true, so before this the same read matched every row from a memory source and no row from a driver. A cursor across a nullable sort key had the defect one page later: page two stopped at the first NULL, and the rows behind it were unreachable. x queries show <name> --json prints the SQL that says so.

Both pagination systems now answer this the same way, As of 2026-08-24. @ultimat3/entity's repo cursor used to refuse a nullable sort key outright rather than answer where a NULL sorts; it now writes the same two orderings down (asc nulls last / desc nulls first), carries the absence in the cursor and reaches it in the seek. One answer, per axiom 1. What entity still refuses is narrower and is not about ordering: a nullable primary-key column used as the tiebreak — null = null is unknown, so two rows sharing a sort value are indistinguishable to the seek and one of them is served twice or never (Entities and migrations).

Request memo (tier 1) dedupe

Three components on one page calling liveFeed({ orgId }) resolve one query.

Streamed <Hole>s (Routes and render modes) are the common case: independent holes, one round trip to Postgres. The same memo is what keeps an uncached lookup called once per row of a list to one round trip — As of 2026-08, per row is what it used to cost.

The memo collapses the same read asked twice. Fifty different row lookups collapse one layer down, in the repo: findById issued across one microtask of a request is one where "id" in (…) (Entities and migrations → Point lookups batch themselves) — or, named on the chain instead of inferred from a loop, one preload() per relation (Entities and migrations → Preload states a relation the loop would infer).

Fifty counts collapse neither way — one count() per row is fifty different questions, so nothing above the repo can batch them. The repo answers them in one statement instead: db.likes.where({ orgId }).andWhere('postId', 'in', ids).countBy('postId') is a map keyed by the column's values, biggest group first, with a value nothing matched absent rather than 0 (Entities and migrations → A count per row is one grouped count).

Audit: who saw what

query({ audit: true }) writes one record per call into the sink an action's audit: true writes to — one contract, @ultimat3/core's AuditRecord / AuditSink, one installed sink — the auditSink adapter port, set as auditSink: in apps/<app>/runtime.ts (Adapters; 31.0.0 deleted setAuditSink). As of 2026-10.

Every cached query carries a tag

The contract. Not yet a gate — As of 2026-08 X_CACHE_UNTAGGED_QUERY is reserved: no code path raises it, and x errors explain X_CACHE_UNTAGGED_QUERY refuses it (Error codes → Reserved codes).

Until it is a gate, tag coverage is a review item, not a build error. Declare the entity tag — tags() / entityTag() in Caching and invalidation.

Subscription caps

Load shedding is a decision with a typed error, not a fall-over.

Verbatim shapes: packages/realtime/src/errors.ts. Full index: Error codes.

Testing

x test live — its own runner, its own fixture shape. Runs against a cloned Postgres plus an in-process replicator and in-process NATS.

Every query({ live: true }) emits a test covering snapshot + one patch + one policy-filtered row, green on the first run. Extend it as the query grows — an untested live query is a red build.

x test live --json
x verify              # runs all six test types

Introspection

Rules

• One query per read shape. Two queries differing by a boolean is one query with a boolean input field.
• Filter rows in sql; decide yes/no in policy. Never mix.
• live: true needs orderBy + limit, always.
• Presence, typing indicators, and cursors are tier 1 channels forever — never model ephemeral state as rows (Realtime).
• A cache miss must be correct and merely slower. No query may depend on a hit.
• NULL is a value to =/!=/in, unknown to >/<, and the largest value to orderBy. Never write a filter that reads a NULL a fourth way.
• One order, three readers: the generated SQL, the cursor and the live matcher all serve <declared keys>, "id" asc. Never sort a window by the declared keys alone.
• Cache keys are framework-generated. A hand-built key is a rejected PR.