SurrealDB Docs Logo

Enter a search query

Live Queries

You can use the SurrealDB JavaScript SDK to create live queries that listen for changes in the database and automatically update your application when changes occur. This feature is useful for building real-time applications that need to respond to changes in the database.

.live()

Initiates a live query.

Method Syntax
async db.live<T>(table, callback, diff)

Arguments

ArgumentsDescription
table required

The table name to listen for changes for

callback optional

A callback function that processes live notifications. Consult the Live Actions for a list of all possible values being returned.

diff optional

If set to true, live notifications will include an array of JSON Patch objects, rather than the entire record for each notification.

Example usage

// The uuid of the live query will be returned const queryUuid = await db.live( "person", // The callback function takes two arguments: the 'action' and 'result' properties ( action, result ) => { // action can be: 'CREATE', 'UPDATE', 'DELETE' or 'CLOSE' if (action === 'CLOSE') return; // result contains either the entire record, or a set of JSON patches when diff mode is enabled processSomeLiveQueryUpdate(result); } )

.subscribeLive()

Registers a callback function for a running live query.

Method Syntax
async db.subscribeLive<T>(queryUuid, callback)

Arguments

ArgumentsDescription
queryUuid required

The UUID of a running live query

callback required

A callback function that processes live notifications. Consult the Live Actions for a list of all possible values being returned.

Example usage

await db.subscribeLive( queryUuid, // The callback function takes an object with the "action" and "result" properties ( action, result ) => { // action can be: "CREATE", "UPDATE", "DELETE" or "CLOSE" if (action === 'CLOSE') return; // result contains either the entire record, or a set of JSON patches when diff mode is enabled processSomeLiveQueryUpdate(result); } )

.kill()

Kills a running live query by it’s UUID

Method Syntax
async db.kill(queryUuid)

Arguments

ArgumentsDescription
queryUuid required

The UUID of the live query you wish to kill

Example usage

await db.kill(queryUuid)

Live Actions

For CREATE, UPDATE and DELETE, the type Result is the generic argument passed to .live() or .subscribeLive().
It extends either Record<string, unknown> or Patch.

It’s generally recommended to handle the CLOSE action first, as that clears out the type for the result parameter.

ActionResultDescription

CLOSE

killed or disconnected

Emitted when the live query is closed due to it either being killed or the connection being disconnected.

CREATE

Result

Emitted when a record within your subscription gets created

UPDATE

Result

Emitted when a record within your subscription gets updated

DELETE

Result

Emitted when a record within your subscription gets deleted

© SurrealDB GitHub Discord Community Cloud Features Releases Install