LIVE SELECT statement

The LIVE SELECT statement can be used to initiate a real-time selection from a table, including the option to apply filters.

In practical terms, when you execute a LIVE SELECT query, it triggers an ongoing session that captures any subsequent changes to the data in real-time. These changes are then immediately transmitted to the client, ensuring that the client is consistently updated with the latest data modifications.

Statement syntax

SurrealQL Syntax
LIVE SELECT
	[
		[ VALUE ] @fields [ AS @alias ]
		| DIFF
	]
	FROM @targets
	[ WHERE @conditions ]
	[ FETCH @fields ... ]
;

Note

Support for FETCH is not yet available, but we are working on it.

Example usage

Basic usage

By default, SurrealDB will push the entire record over the websocket when created or updated, and just the record’s ID when deleted.

LIVE SELECT * FROM person;

['b1f1d115-ad0f-460d-8cbf-dbc7ce48851c']

The result of the above query will be a UUID. This UUID is the Live Query Unique ID, and is used to differentate between different Live Queries. You will want to keep track of this ID, so that you can differentiate between different notifications being received after this query. You can also use this UUID to KILL (stop) the Live Query. The protocol will then send messages that are of a Notification format.

You can find an example of such a message in the Live Query WebSocket protocol description.

Diff

When using the DIFF mode, updates will be sent in the form of an array with JSON Patch messages.

LIVE SELECT DIFF FROM person;

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

Filter the live query

You can optionally apply filters with the WHERE clause.

LIVE SELECT * FROM person WHERE age > 18;

Consistency Guarantees

When using Live Queries, it is important to understand the ordering of messages and events when many clients and transactions are running in paralllel. Notifications on live queries are only published for committed transactions.

While a best effort is made to assure ordering is correct, a strict correctness is not yet in place for a full guarantee. As such that some messages may be received out of order from their commit order. However, transactions that are committed from the same client will always be in order.

Security enforcement is always evaluated per notification and will reflect the value of authorisation at the time of publishing the notification. This means that if a transaction is committed, after which the authorisation immediately changes for the live query receiver, the receiver will get the notification under the new rules.

Other notes

Currently, it is not possible to use parameters inside of Live Queries.

LIVE SELECT * FROM person WHERE $field > $value

It is possible to have parameters for the table reference.

LIVE SELECT * FROM $table WHERE field > 50