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

Arguments		Description
tableREQUIRED		The table name to listen for changes for
callbackOPTIONAL		A callback function that processes live notifications. Consult the Live Actions for a list of all possible values being returned.
diffOPTIONAL		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);
	}
)

.listenLive()

Registers a callback function for a running live query.

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

Arguments

Arguments		Description
queryUuidREQUIRED		The UUID of a running live query
callbackREQUIRED		A callback function that processes live notifications. Consult the Live Actions for a list of all possible values being returned.

Example usage

await db.listenLive(
	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

Arguments		Description
queryUuidREQUIRED		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 .listenLive().
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.

Action	Result	Description
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

What's on your mind?

Create GitHub Issue

Quickest way to alert
our team of a problem.