Subscriptions & Live Queries

KalamDB’s real-time engine pushes data changes to connected clients over WebSocket. This eliminates the need for polling and separate pub/sub infrastructure.

For the runtime architecture, table-type delivery behavior, and cluster fan-out path, see /docs/server/architecture/live-query.

Subscribe to a table for real-time change notifications:

SQL

1SUBSCRIBE TO <namespace>.<table_name>2[WHERE <condition>]3[OPTIONS (last_rows=<n>, batch_size=<n>, from=<n>)];

Options

Option	Description
`last_rows=<n>`	Receive the last N rows as initial data
`batch_size=<n>`	Maximum rows per notification batch
`from=<n>`	Resume from a specific sequence ID

Examples

SQL

1-- Subscribe to all messages in a conversation2SUBSCRIBE TO chat.messages3WHERE conversation_id = 14OPTIONS (last_rows=50);5 6-- Subscribe to typing events with batching7SUBSCRIBE TO chat.typing_events8WHERE conversation_id = 19OPTIONS (last_rows=10, batch_size=5);10 11-- Resume from a specific point12SUBSCRIBE TO chat.messages13WHERE conversation_id = 114OPTIONS (from=1234);

KILL LIVE QUERY

Cancel an active subscription:

SQL

1KILL LIVE QUERY '<subscription_id>';

Using Subscriptions via SDK

The recommended way to use real-time subscriptions is via the TypeScript SDK:

typescript

1import { createClient, Auth } from '@kalamdb/client';2 3const client = createClient({4  url: 'http://localhost:2900',5  authProvider: async () => Auth.basic('admin', 'AdminPass123!')6});7 8// Open live events with a SQL WHERE clause9const unsub = await client.liveEvents(10  'SELECT * FROM chat.messages WHERE conversation_id = 1',11  (event) => {12    if (event.type === 'change') {13      console.log('New message:', event.rows);14    }15  },16  { batchSize: 50 }17);18 19// Simple table event stream20const unsubTyping = await client.liveEvents(21  'SELECT * FROM chat.typing_events',22  (event) => {23    console.log('Typing:', event.change_type, event.rows);24  }25);26 27// Check active subscription count28console.log(`Active: ${client.getSubscriptionCount()}`);29 30// Cleanup31await unsub();32await unsubTyping();33await client.disconnect();

Using Subscriptions via CLI

In the interactive CLI, use \live or \subscribe:

BASH

1kalam> \live SELECT * FROM chat.messages WHERE conversation_id = 1 OPTIONS (last_rows=20);

Both forms start the same live query flow. Press Ctrl+C to stop the subscription.

How It Works

Client sends a SUBSCRIBE TO statement (via SQL, SDK, or WebSocket)
KalamDB registers the subscription with filter conditions
On every INSERT, UPDATE, or DELETE matching the filter, a change event is pushed
Events are delivered over the persistent WebSocket connection
Client can cancel with KILL LIVE QUERY or disconnect

UPDATE notification payload

For UPDATE events, the notification includes:

rows: All non-null columns from the updated row, plus the primary key and _seq. This provides a full snapshot of the current row state without requiring a re-query.
old_values: Only the columns that actually changed (plus PK and _seq), with their previous values.

This design makes tables usable as change triggers — when any column is updated, subscribers receive every non-null value, not just the diff.