Live queries

A live query is a server query whose result streams updates to the client. In React:

import { db } from "@pylonsync/react";

function Inbox() {
  const { data: messages, loading } = db.useQuery("Message", { where: { roomId } });
  if (loading) return null;
  return messages.map((m) => <Row key={m.id} msg={m} />);
}

When anyone inserts, updates, or deletes a Message row matching { roomId }, every subscribed client gets the new result — without writing a single line of WebSocket code.

How it works

Client opens a WebSocket to the Pylon server.
useQuery sends a subscribe frame with the entity and filter.
Server runs the query once, returns the initial result, and adds the subscription to its index.
On every mutation, Pylon’s change log walks all active subscriptions whose filter matches the changed row and pushes the diff.
Client applies the diff locally and React re-renders.

Filters

Filters map to indexed columns. Equality is always fast; inequality and range scans require an index on the queried columns.

db.useQuery("Issue", { where: { teamId, state: "open" } });
db.useQuery("Message", { where: { roomId } });
db.useQuery("User");              // full table (careful, scales O(N))

Typed queries

With codegen, db is fully typed to your schema:

const { data } = db.useQuery("Message", { where: { roomId } });
// data: Message[]

const { data: issue } = db.useQueryOne("Issue", issueId);
// issue: Issue | null

Type errors catch mismatched filter keys or wrong entity names at compile time.

Pagination

Live pagination works; each page is its own subscription:

const { data, hasMore, loadMore } = db.useInfiniteQuery("Message", {
  pageSize: 50,
});

Policies apply

Live queries respect policies. A subscribed client only receives rows it’s allowed to read. If a row becomes readable (or unreadable) due to a policy re-evaluation, the subscription updates.

Performance

Pylon maintains an index of active subscriptions keyed by entity + indexed filter fields. A write that affects N matching subscriptions is O(N), not O(all subscriptions). Practical numbers:

Tens of thousands of concurrent subscriptions per server
Sub-millisecond fan-out per subscriber
Writes stay fast because the subscription index is kept small via the schema’s declared indexes

See the bench example to measure for yourself.

Falling back to non-live

Sometimes you want a one-shot read without the subscription overhead. Call a query function once with db.fn (or callFn) instead of subscribing:

const rows = await db.fn("listMessages", { roomId });

Where listMessages is a server function:

// functions/listMessages.ts
import { query, v } from "@pylonsync/functions";

export default query({
  args: { roomId: v.id("Room") },
  async handler(ctx, args) {
    return ctx.db.query("Message", { roomId: args.roomId });
  },
});

Realtime overview

Every realtime primitive and which to use.

React SDK

All the hooks the client exposes.

Get started

Core concepts

SSR

Auth

Plugins

Clients

Operations

Compare

Live queries

How it works

Filters

Typed queries

Policies apply

Performance

Falling back to non-live

Next

Realtime overview

React SDK

​How it works

​Filters

​Typed queries

​Pagination

​Policies apply

​Performance

​Falling back to non-live

​Next

Realtime overview

React SDK

How it works

Filters

Typed queries

Pagination

Policies apply

Performance

Falling back to non-live

Next