Python Live Queries

The Python SDK has the same three realtime concepts as TypeScript and Dart, with Pythonic snake_case names.

Materialized rows

Use live() when your app wants current rows instead of raw change events.

python

1live_rows = await client.live(2    "SELECT id, body FROM chat.messages WHERE thread_id = 1",3    last_rows=20,4    limit=20,5    key_columns=["id"],6    on_checkpoint=lambda checkpoint: save_resume_token(checkpoint["last_seq_id"]),7)8 9async for rows in live_rows:10    render(rows)

Use live_table() when SELECT * FROM table is enough.

python

1tasks = await client.live_table(2    "app.tasks",3    last_rows=20,4    key_columns=["id"],5)6 7async for rows in tasks:8    render_tasks(rows)

Low-level events

Use live_events() when you need the protocol frames directly.

python

1events = await client.live_events(2    "SELECT * FROM chat.messages WHERE thread_id = 1",3    batch_size=100,4    last_rows=50,5    on_checkpoint=lambda checkpoint: save_resume_token(checkpoint["last_seq_id"]),6    on_error=lambda event: log_live_error(event),7)8 9async for event in events:10    kind = event.get("type")11    if kind == "subscription_ack":12        print("opened", event["subscription_id"])13    elif kind == "initial_data_batch":14        hydrate(event["rows"])15    elif kind == "change":16        apply_change(event["change_type"], event.get("rows"), event.get("old_values"))17    elif kind == "error":18        break

Options

Option	Applies to	Meaning
`batch_size`	all live methods	Max rows per initial snapshot batch
`last_rows`	all live methods	Include the last N rows before live changes begin
`from_`	all live methods	Resume from a known sequence ID
`auto_fetch_batches`	all live methods	Ask for remaining startup batches automatically
`limit`	`live()`, `live_table()`	Cap the materialized row set kept by the SDK
`key_columns`	`live()`, `live_table()`	Stable row identity columns when the query does not expose `id`
`on_checkpoint`	all live methods	Persist the latest applied sequence ID
`on_error`	`live_events()`	Receive low-level error frames separately

The checkpoint object contains subscription_id and last_seq_id strings. Feed last_seq_id back into from_ on the next session to resume.