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

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

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

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.