SurrealDB
SurrealDB Docs Logo

Enter a search query

Enter a search query

SDK methodslive

.live()

Initiates a live query.

db.live<T>(table: string, callback: (action: string, result: T) => void, diff?: boolean)

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);
	}
)

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

Edit this page on GitHub