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
Client SDK (client-sdk/web.md): use the user Session in browser scenarios; you can only receive events visible to the current identity under row-level/table-level permissions.
An initialized
Client(setEndpoint+setProject); the WebSocket endpoint is derived from the endpoint by default; special networks can override it withsetEndpointRealtime().Subscribing to TablesDB row channels requires the corresponding table/row to be readable by the current user (for the row-level/table-level permission model, see permissions documentation).
Usage workflow
Import
RealtimeandChannelfrom 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).
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.In the callback, handle payloads such as
create/update/deletebyevent.type/event.data.To end a single subscription use
await sub.unsubscribe()(keeping the connection for other subscriptions); to fully close the connection useRealtime.disconnect().Dynamic adjustment: the subscription object provides
update({ channels, queries }), which can replace channels and filter conditions without rebuilding the WebSocket.Console SDK scenario (admin panel):
realtime.forProject(region, channels, callback)orrealtime.forConsole(region, channels, callback), returning a cancel function.
Key parameters and returns
subscribe(channels, callback):channelsis a channel object/string or an array thereof; a channel object can be used as a string after.toString().Subscription object:
unsubscribe()(removes only this subscription),update(changes)(updates channel/query in place on the server),close()(a compatibility alias forunsubscribe+ automatic disconnect when the last subscription is removed).Callback events:
RealtimeResponseEvent, containing the event type and data payload; connection-level control (createSocket/closeSocket/disconnect) is managed internally by the SDK.Row subscriptions support query filters: pass
queries(an array of Query strings) when constructing the subscription to receive only row events matching the conditions.
Errors and boundaries
Client row-level permission boundary: rows the caller cannot read will not have events pushed; permission strings such as
Role.label()/Role.guests()cannot be used to declare row permissions on the client (it would 401); they must be properly configured in table/row permissions and filtered by the server.Disconnections are automatically reconnected by the SDK; after reconnection, subscriptions are restored via a server-side session, but business logic should not assume "guaranteed delivery" — critical state should still be verified via API queries.
close()is a compatibility alias: preferunsubscribe()for single-subscription teardown anddisconnect()for full shutdown to avoid semantic confusion.The server Node SDK has no Realtime service: realtime push is a client (browser) and Console panel capability.
SDK Category Differences
Client SDK (client-sdk/web.md): full
Realtime+Channelcapability (rows/files/account, multiple channels, query filters, presence updates).Console SDK (console-sdk/nodejs.md):
realtime.forProject()/realtime.forConsole()wrappers, for realtime refresh in admin panels.Server SDK (server-sdk/nodejs.md): no Realtime service; use Webhooks for the server to perceive changes (misc/webhooks.md).
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.)
- Web (user session)
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.)
- Web (user session)
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.)
- Web (user session)
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 subscriptionDynamic adjustment
update({ channels, queries }) replaces channels and filter conditions without rebuilding the WebSocket (updated in place on the server). (Web client surface only.)
- Web (user session)
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
JavaScript (subscribing to row/file/account channels in the browser): examples/javascript.md