Reactive queries
Keep a declared query's result current without polling, using durable per-query subscriptions, resumable deltas, held streams, and explicit rehydrates.
Reactive subscriptions keep a declared query’s result current for a client without polling. You register a query with bindings, receive the initial rows at a committed head, and then consume result deltas keyed to committed heads with an opaque per-subscription resume cursor. Every pushed result is a fresh execution of the query at that head. The correctness contract is parity with one-shot execution, and frames are byte-equal at identical cursors.
The subscription lifecycle
- Register by sending bindings to
POST /v1/queries/{name}/subscriptions. The response returns the subscription id, the initial rows, the committed head, the result digest, and the query’s transitive read set. Registrations are durable, store-backed leases that survive server restarts. - Consume updates by holding the SSE stream
(
GET /v1/queries/subscriptions/{id}/stream, resuming viaLast-Event-ID) or by fetching batches (GET /v1/queries/subscriptions/{id}/updates?since_update_id=N). Deltas carry the head, a per-subscription monotonic update id, adds and removes, and the result digest. - Rehydrate when told to. When history is unavailable (a stale cursor, a lost update log after restart, an oversized delta), the server sends an explicit full-replace rehydrate event. It does not go silent, and it does not fabricate a replay.
- Unsubscribe with
DELETE /v1/queries/subscriptions/{id}, which ends held streams and drops the lease. Expired leases reap to a non-disclosingquery.subscription_not_found, and the client re-registers.
Efficient by read set
Commits that touch only relations outside a subscription’s static read set do no work.
Touched subscriptions re-execute at the committed head, and unchanged results are
digest-suppressed. There is one exception: any commit that touches an access.* relation
re-executes every live subscription on the lineage, because authorization can change what
a subscriber may see without touching the read set. Authorization loss emits a terminal
revoked event. Subscription frames are row-filtered, so a policy-invisible tenant’s
append is also invisible in the delta stream.
Backpressure is always typed and reported to the client. Transient door pressure defers
pushes. A held-stream ring overflow closes the stream with fanout_buffer_full, which is
a resume signal and loses no data. Per-tenant ceilings deny with the typed
tenant_backpressure shape.
From the SDK
import { createTarskiClient } from '@tarski/client';
const client = createTarskiClient({ baseUrl: 'http://127.0.0.1:7411' });
for await (const item of client.subscribeQuery('workspace-board', {
bindings: { workspace_id: 'ws_1' },
})) {
switch (item.kind) {
case 'initial': render(item.rows); break;
case 'delta': apply(item.added, item.removed); break;
case 'rehydrate': render(item.rows); break; // full replace — rebuild state
case 'closed': break;
}
}
subscribeQuery prefers the held stream. If the stream fails to open, it falls back to
the batch resume loop and resumes from the last delivered per-subscription update id. In
the Team Tasks reference app, one workspace-board subscription is the board’s entire
data source. The initial result paints the board, deltas apply only the changed rows,
rehydrates replace everything, and writes do not re-read.
Resume, rehydrate, and coherent batches
The resume cursor is not a lineage head and is not shared across subscriptions. Persist
each subscription’s updateId only after applying its item. That update id resolves
duplicate delivery at a transport boundary. A cursor older than retained history produces
an explicit full-result rehydrate.
Several independently registered subscriptions may observe different committed heads.
When one render or export must describe a single worldview, use
client.api.executeQueryBatch() for those declared queries. The returned batch pins one
snapshot identity across every result. Use a coherent batch for snapshot-consistent reads
across several windows, and use reactive subscriptions for ongoing incremental updates.
Local serve tuning
tarski serve exposes subscription knobs as environment variables:
TARSKI_SUBSCRIPTION_STREAM_HEARTBEAT_MS, TARSKI_SUBSCRIPTION_STREAM_BUDGET,
TARSKI_SUBSCRIPTION_LEASE_TTL_MS, TARSKI_SUBSCRIPTION_LEASE_REAP_INTERVAL_MS,
TARSKI_TENANT_HELD_STREAM_CEILING, and TARSKI_TENANT_LIVE_SUBSCRIPTION_CEILING.