Docs
Contents

Realtime subscriptions

Overview and use cases

Realtime pushes data changes within a project to the browser over WebSocket: subscribe to a single row, all rows of a table, file changes, or account events, and refresh the UI immediately upon receiving events (e.g., dashboards, collaboration lists, upload progress). The client SDK establishes the WebSocket connection and dispatches events by channel; server/Console scenarios are provided by the Console SDK's realtime wrapper.

Prerequisites

Usage workflow

  1. Import Realtime and Channel from the SDK and construct channels:

    • Rows: Channel.tablesdb('DATABASE_ID').table('TABLE_ID').row('ROW_ID'); omitting the row ID (.row()) subscribes to all rows of that table.

    • Files: Channel.files() (all file changes).

    • Account: Channel.account() (events related to the current account).

  2. Subscribe: await realtime.subscribe(channelOrChannels, callback) — the input can be a single channel or an array of channels (subscribe to multiple channels at once); returns the subscription object.

  3. In the callback, handle payloads such as create / update / delete by event.type / event.data.

  4. To end a single subscription use await sub.unsubscribe() (keeping the connection for other subscriptions); to fully close the connection use Realtime.disconnect().

  5. Dynamic adjustment: the subscription object provides update({ channels, queries }), which can replace channels and filter conditions without rebuilding the WebSocket.

  6. Console SDK scenario (admin panel): realtime.forProject(region, channels, callback) or realtime.forConsole(region, channels, callback), returning a cancel function.

Key parameters and returns

Errors and boundaries

SDK Category Differences

Examples by language

The following provides examples by language, item by item along the usage workflow; each card can switch languages (synced across the page).

Subscription channels and event handling

Construct channels from Channel — row channels .row('<rowId>') for a single row, omitting the row ID subscribes to all rows of that table, plus files Channel.files() and account Channel.account(); subscribe accepts a single channel or an array of channels, and callbacks handle create / update / delete payloads by event.type / event.data. (Web client surface only: Server SDK has no Realtime service and REST has no realtime endpoints, so neither has tabs.)

import { Realtime, Channel } from 'agentbase-web-sdk';   // Prerequisite: the user is logged in and the client is initialized

const realtime = new Realtime(client);
const sub = await realtime.subscribe(
    [
        Channel.tablesdb('app-db').table('tasks').row(),   // All rows; .row('<rowId>') for a single row
        Channel.files(),                                   // File changed
        Channel.account()                                  // Current account events
    ],
    (event) => {
        console.log(event.type, event.data);               // create / update / delete payloads, etc.
    }
);

Query filters

Row channels support queries filters (an array of Query strings) to receive only matching row events; filter conditions are set in place with the subscription object's update, no reconnection needed. (Web client surface only.)

import { Query } from 'agentbase-web-sdk';

await sub.update({
    queries: [Query.equal('status', 'open')]   // Only push row events with status=open
});

Teardown and shutdown

Use unsubscribe() to tear down a single subscription (the connection is kept for other subscriptions); use Realtime.disconnect() to fully close. close() is a compatibility alias: equivalent to unsubscribe, and it automatically disconnects when the last subscription is removed. (Web client surface only.)

await sub.unsubscribe();   // Detach a single subscription (keep the connection for other subscriptions)
Realtime.disconnect();     // Close the entire connection
// sub.close() is a compatibility alias: unsubscribe + automatic disconnect on the last subscription

Dynamic adjustment

update({ channels, queries }) replaces channels and filter conditions without rebuilding the WebSocket (updated in place on the server). (Web client surface only.)

await sub.update({
    channels: [Channel.tablesdb('app-db').table('tasks').row()],   // Switch channels (e.g., to full-table rows)
    queries: [Query.equal('status', 'done')]                       // Change filters at the same time
});

Example Guide