Live Queries

Reactive WebSocket subscriptions that push updated query results whenever matching CRDTs change.

Live Queries extend the Query Engine with a WebSocket push model. Instead of polling client.query(), you subscribe once — the server re-executes the query and pushes a new result every time a matching CRDT changes.

How it works

1. Client sends SubscribeQuery over the existing WebSocket connection with a query spec and a query_id.
2. Server executes the query immediately and pushes a first QueryResult frame.
3. Whenever a CRDT in the namespace changes, the server checks all active live query subscriptions. Queries whose from glob matches the changed CRDT (and whose optional type filter matches) are re-executed, and a new QueryResult is pushed.
4. Client sends UnsubscribeQuery to cancel. The server also cleans up automatically on disconnect.

The connection uses the same WebSocket established by the SDK — no additional socket is opened.

---

SDK — client.liveQuery()

const handle = client.liveQuery({
  from: "gc:views-*",
  aggregate: "sum",
});

handle.onResult(result => {
  console.log("live total:", result.value);   // updated on every matching delta
  console.log("matched:", result.matched);    // number of CRDTs in the result
});

// Later — cancel the subscription
handle.close();

LiveQueryHandle

Method	Description
onResult(listener)	Register a listener. Returns an unsubscribe function. Multiple listeners can be registered.
close()	Cancel the subscription and notify the server.

LiveQueryResult

Field	Type	Description
value	unknown	Aggregated result. Same shape as the HTTP Query Engine. null when nothing matched.
matched	number	Number of CRDTs that contributed to the result.

---

React — useLiveQuery()

import { useMemo } from "react";
import { useLiveQuery } from "meridian-react";

function LiveTotal() {
  // Stabilize with useMemo — changing spec reference re-subscribes.
  const spec = useMemo(
    () => ({ from: "gc:views-*", aggregate: "sum" as const }),
    []
  );

  const { data, loading, error } = useLiveQuery(spec);

  if (loading) return <span>Connecting…</span>;
  if (error) return <span>Error: {error.message}</span>;

  return <span>Live views: {String(data?.value)}</span>;
}

The hook subscribes on mount, updates data on every push, and unsubscribes on unmount. loading is true until the first result arrives.

State	Type	Description
data	LiveQueryResult | null	Most recent result. null until first push.
loading	boolean	true until the first result arrives.
error	Error | null	Set if the subscription setup throws.

---

Supported query specs

Live Queries accept the same spec as client.query():

Field	Type	Required	Description
from	string	✓	Glob pattern matched against CRDT IDs.
type	string	—	Filter by CRDT type. Prevents re-execution for unrelated types.
aggregate	string	✓	Same aggregation functions as the HTTP endpoint.
where	object	—	contains (ORSet) or updatedAfter (LwwRegister).

See the aggregation table for supported operations per CRDT type.

---

Performance notes

Type filter skips unrelated deltas. When you set type: "gcounter", the server skips re-execution entirely when an ORSet or LwwRegister changes — even if the glob pattern would match the key. Always set type when your pattern is cross-type.

// Without type filter — re-executes on any delta matching "gc:views-*"
client.liveQuery({ from: "gc:views-*", aggregate: "sum" });

// With type filter — only re-executes on GCounter deltas
client.liveQuery({ from: "gc:views-*", type: "gcounter", aggregate: "sum" });

Reconnect resilience. The SDK re-sends all active SubscribeQuery frames automatically after a WebSocket reconnect. No manual re-subscription is needed.

Multiple handles per spec. Each liveQuery() call creates an independent subscription with its own query_id. If you need multiple listeners on the same query, use handle.onResult() multiple times on a single handle instead of calling liveQuery() twice.

---

Difference from useQuery

	useQuery	useLiveQuery
Transport	HTTP POST	WebSocket push
When it updates	On spec change (re-fetch)	On every matching CRDT delta
scanned / execution_ms	Available	Not available (push model)
Use case	One-shot reads, low-frequency data	Dashboards, live counters, reactive aggregates