Live Queries

@kalamdb/client supports realtime subscriptions via WebSocket.

The client has exactly three realtime entry points:

• live(sql, onRows, options?) for materialized rows from any supported SELECT.
• liveTable(tableName, onRows, options?) for materialized rows from SELECT * FROM table.
• liveEvents(sql, onEvent, options?) for low-level protocol events.

Which Mode Should I Choose?

Use simple when you want the latest rows.

Use advanced when you want to own the subscription lifecycle and event handling.

Simple Mode

• Read: Simple Realtime Mode
• Start with live() or liveTable().
• The SDK reconciles inserts, updates, and deletes into one current row set.

1const unsub = await client.live(2  "SELECT id, room, body, created_at FROM support.inbox WHERE room = 'main'",3  (rows) => renderInbox(rows),4  {5    limit: 100,6    lastRows: 100,7  },8);

Advanced Mode

• Read: Advanced Realtime Mode
• Start with liveEvents() for raw events.
• This mode exposes change_type, rows, old_values, _seq, subscription_id, and batch_control directly.

1const stop = await client.liveEvents(2  'SELECT * FROM app.messages WHERE conversation_id = 42',3  (event) => {4    if (event.type === MessageType.InitialDataBatch) {5      renderBatch(event.rows);6    }7  },8  {9    batchSize: 5,10    autoFetchBatches: false,11  },12);

Shared Subscription Rules

• Live SQL must stay within the strict supported shape: SELECT ... FROM ... WHERE ....
• Do not include ORDER BY or LIMIT inside live() or liveEvents() SQL.
• batchSize chunks the initial snapshot coming from the server.
• lastRows controls how much history to rewind before live changes begin.
• from resumes from a known SeqId checkpoint.
• limit applies only to the high-level materialized row set that live() keeps after startup.

Next Reads

• Simple Realtime Mode
• Advanced Realtime Mode
• TypeScript SDK Overview