LIVE statement
The LIVE 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 SyntaxLIVE 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, you want to understand the ordering of messages and events when many clients and transactions are running in paralllel. We only publish notifications on live queries for committed transactions.
We make a best effort to assure ordering is correct, but don't have a strict correctness in place yet to guarantee that fully. This means that some messages may be received out of order from their commit order. However, transactions that are committed from the same client, are always going to 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, then immediately the authorisation 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