Skip to Content
Live Subscriptions

Live Subscriptions

Flags

OptionDescription
--subscribe <SQL>Run a live query subscription.
--subscription-timeout <SECONDS>Idle timeout after initial data (0 = no timeout).
--initial-data-timeout <SECONDS>Max wait for initial data batch (0 = no timeout).
--list-subscriptionsPrint current subscription model/capabilities.

Interactive commands

CommandDescription
\live <SQL>, \subscribe <SQL>Start live subscription (\subscribe is an alias).

Both routes send a SELECT plus optional trailing OPTIONS (...) to the WebSocket subscription path.

OPTIONS clauses

ClauseEffect
OPTIONS (batch_size=<n>)Limits each initial snapshot batch to at most n rows.
OPTIONS (last_rows=<n>)Rewinds the newest n rows as one startup batch.
OPTIONS (from=<seq_id>)Starts live delivery after a sequence id (from_seq_id alias accepted).

Combine options: OPTIONS (last_rows=20, batch_size=5, from=1234).

Examples

BASH
kalam --subscribe "SELECT * FROM app.messages WHERE conversation_id = 7 OPTIONS (batch_size=5)"kalam --subscribe "SELECT * FROM app.messages OPTIONS (last_rows=20)" --subscription-timeout 15kalam --subscribe "SELECT * FROM app.messages OPTIONS (last_rows=20, batch_size=5, from=1234)"
TEXT
kalam> \live SELECT * FROM app.messages OPTIONS (batch_size=5);kalam> \subscribe SELECT * FROM app.messages OPTIONS (last_rows=20);kalam> \live SELECT * FROM app.messages OPTIONS (last_rows=20, batch_size=5, from_seq_id=1234);

Verifying batching

  • The CLI prints BATCH <n> for each startup snapshot page.
  • With OPTIONS (batch_size=5) and 20 rows, expect four startup batches of 5.
  • Startup batches run oldest-to-newest in normal batch mode.
  • last_rows is a single-batch rewind of the newest rows, not paginated history.

Example output:

TEXT
[12:00:00.123] ✓ SUBSCRIBED [sub_...] 0 total rows, batch 1 (loading...), 3 columns[12:00:00.124] BATCH 1 [sub_...] 5 rows (more pending)  {"id":1,"message":"hello 1"}[12:00:00.130] BATCH 2 [sub_...] 5 rows (more pending)...[12:00:00.145] BATCH 4 [sub_...] 5 rows (complete)
Last updated on
Querying & SQLTopic Consumers