Live queries | SurrealDB

Subscribe to changes on a table with the Mojo SDK and poll for live-query notifications.

A live query subscribes to a table and receives a notification whenever a matching record is created, updated, or deleted. Notifications arrive on the WebSocket transport out of band, and the SDK queues them as they come in.

Note

Live queries run over a stateful WebSocket session. WebSocket support is rolling out. On the HTTP transport, the engine reports live_queries=False and the SDK raises an UnsupportedFeatureError.

Starting a live query

live_query() subscribes to a table and returns the query id as a string. live_raw() returns the full RpcResponse if you need it.

var query_id = client.live_query("person")

Receiving notifications

The transport queues notifications as they arrive. Pull them out with poll_notifications(), which drains every queued notification across all live queries.

var notifications = client.poll_notifications()
for ref in notifications:
    print(ref[].query_id, ref[].action)

Each entry is a LiveNotificationRaw carrying the query id, the action, and the raw record bytes.

Stopping a live query

Stop a subscription with kill(), passing the query id returned by live_query().

client.kill(query_id)

See the method reference for live and kill.