Live queries

Live queries are SurrealDB's way to push changes to a client. Running a LIVE SELECT opens a subscription that sends notifications whenever matching records appear, change, or disappear, without needing to directly poll the database to do so.

That fits interactive UIs, dashboards, and small collaboration features. For replaying history or catching up a batch pipeline, use changefeeds and SHOW CHANGES instead.

The full grammar and edge cases live under LIVE SELECT in the reference. Below is how to think about subscriptions and what to watch for in production.

Starting a subscription

By default, creates and updates deliver the full record; deletes return nothing unless you add a clause like RETURN BEFORE. You receive a UUID as soon as the live query is registered. This UUID can later be passed in to a KILL statement when you want to stop.

LIVE SELECT * FROM person;

-- u'b1f1d115-ad0f-460d-8cbf-dbc7ce48851c'

Message layout on the wire is described in the live query / WebSocket protocol section.

DIFF mode

If you prefer patches instead of whole documents on update, use DIFF. Updates arrive as JSON Patch-style arrays, which can be smaller and easier to merge on the client when records are large.

LIVE SELECT DIFF FROM person;

-- 'b87cbb0d-ca15-4f0a-8f86-caa680672aa5'

Filtering with WHERE

You can narrow the subscription the same way you would a normal SELECT: only rows that match your predicate participate.

LIVE SELECT * FROM person WHERE age > 18;

Consistency and security

Notifications reflect committed work, so a live event will not take place if a transaction is rolled back.

Under heavy concurrency, the system makes a best effort to preserve sensible ordering, but you should not assume a total order across all writers that matches commit order in every edge case.

Parameters in live queries

From v3.0.0 onwards you can use session parameters in live queries, such as by binding names with LET before you open the subscription.

LET $table = 'measurement';
LET $location = 'Tallinn';
LIVE SELECT * FROM type::table($table) WHERE location == $location;

Where to read more

• •

  LIVE SELECT reference

• •

  Changefeeds — replay and SHOW CHANGES

• •

  Real-time best practices — wider event-driven patterns