TarskiTarski/ docsJoin the waitlist

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

  1. 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.
  2. Consume updates by holding the SSE stream (GET /v1/queries/subscriptions/{id}/stream, resuming via Last-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.
  3. 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.
  4. Unsubscribe with DELETE /v1/queries/subscriptions/{id}, which ends held streams and drops the lease. Expired leases reap to a non-disclosing query.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.