Realtime data streaming
You can use the SurrealDB 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.
.ListenLive<T>()
Listen responses from an existing live query.
Method Syntax
db.ListenLive<T>(queryUuid)
Arguments
| Arguments | Description |
|---|
queryUuid required | The UUID of the live query to consume. |
Example usage
await using var liveQuery = db.ListenLive<Person>(queryUuid);
You can then consume the live query using either an IAsyncEnumerable or an Observable.
Using an IAsyncEnumerable
:::note NOTE: This will block the current thread until the query is killed. :::
Option 1: Consume the live query via an IAsyncEnumerable
await foreach (var response in liveQuery)
{
if (response is SurrealDbLiveQueryOpenResponse)
{
}
if (response is SurrealDbLiveQueryCreateResponse<Person> create)
{
}
if (response is SurrealDbLiveQueryUpdateResponse<Person> update)
{
}
if (response is SurrealDbLiveQueryDeleteResponse<Person> delete)
{
}
if (response is SurrealDbLiveQueryCloseResponse)
{
}
}
Using an Observable
Option 2: Consume the live query via an Observable
liveQuery
.ToObservable()
.Subscribe((response) =>
{
if (response is SurrealDbLiveQueryOpenResponse)
{
}
if (response is SurrealDbLiveQueryCreateResponse<Person> create)
{
}
if (response is SurrealDbLiveQueryUpdateResponse<Person> update)
{
}
if (response is SurrealDbLiveQueryDeleteResponse<Person> delete)
{
}
if (response is SurrealDbLiveQueryCloseResponse)
{
}
});
You can also use the OfType operator to filter the responses.
liveQuery
.ToObservable()
.OfType<SurrealDbLiveQueryCreateResponse<Person>>()
.Select(response => response.Result)
.Subscribe((record) =>
{
});
Note that this pattern is already simplified via methods available on the SurrealDbLiveQuery object. You can learn more about these methods in the LiveQuery methods section.
.LiveQuery<T>()
Initiate a live query from a SurrealQL statement.
Method Syntax
await db.LiveQuery<T>(sql)
Arguments
| Arguments | Description |
|---|
sql required | Specifies the SurrealQL statements. |
cancellationToken optional | The cancellationToken enables graceful cancellation of asynchronous operations. |
Example usage
const string table = "person";
await using var liveQuery = await db.LiveQuery<Person>($"LIVE SELECT * FROM type::table({table});");
SurrealDbLiveQuery methods
The SurrealDbLiveQuery object provides the following methods:
GetResults()
Returns an enumerator that iterates asynchronously through the collection of results (all actions CREATE, UPDATE and DELETE, except OPEN and CLOSE).
Arguments
| Arguments | Description |
|---|
cancellationToken optional | The cancellationToken enables graceful cancellation of asynchronous operations. |
Example usage
await using var liveQuery = await db.
LiveRawQuery<Person>(
"LIVE SELECT * FROM person;");
await foreach (var response in liveQuery.GetResults())
{
if (
response is SurrealDbLiveQueryCreateResponse<Person> create)
{
}
if (
response is SurrealDbLiveQueryUpdateResponse<Person> update)
{
}
if (
response is SurrealDbLiveQueryDeleteResponse<Person> delete)
{
}
}
GetCreatedRecords()
Returns an enumerator that iterates asynchronously through the collection of created records.
Arguments
| Arguments | Description |
|---|
cancellationToken optional | The cancellationToken enables graceful cancellation of asynchronous operations. |
Example usage
await using var liveQuery = await db.
LiveRawQuery<Person>(
"LIVE SELECT * FROM person;");
await foreach (var record in liveQuery.GetCreatedRecords())
{
}
GetUpdatedRecords()
Returns an enumerator that iterates asynchronously through the collection of updated records.
Arguments
| Arguments | Description |
|---|
cancellationToken optional | The cancellationToken enables graceful cancellation of asynchronous operations. |
Example usage
await using var liveQuery = await db.
LiveRawQuery<Person>(
"LIVE SELECT * FROM person;");
await foreach (var record in liveQuery.GetUpdatedRecords())
{
}
GetDeletedRecords()
Returns an enumerator that iterates asynchronously through the collection of deleted records.
Arguments
| Arguments | Description |
|---|
cancellationToken optional | The cancellationToken enables graceful cancellation of asynchronous operations. |
Example usage
await using var liveQuery = await db.
LiveRawQuery<Person>(
"LIVE SELECT * FROM person;");
await foreach (var record in liveQuery.GetDeletedRecords())
{
}
KillAsync()
Kills the underlying live query.
Method Syntax
await liveQuery.KillAsync(cancellationToken)
Arguments
| Arguments | Description |
|---|
cancellationToken optional | The cancellationToken enables graceful cancellation of asynchronous operations. |
Example usage
var liveQuery = await db.
LiveRawQuery<Person>(
"LIVE SELECT * FROM person;");
await liveQuery.KillAsync();
.LiveRawQuery<T>()
Initiate a live query from a SurrealQL statement, based on a raw SurrealQL query.
Method Syntax
await db.LiveRawQuery<T>(sql, params)
Arguments
| Arguments | Description |
|---|
sql required | Specifies the SurrealQL statements. |
params optional | Assigns variables which can be used in the query. |
cancellationToken optional | The cancellationToken enables graceful cancellation of asynchronous operations. |
Example usage
await using var liveQuery = await db.LiveRawQuery<Person>("LIVE SELECT * FROM person;");
.LiveTable<T>()
Initiate a live query from a table.
Method Syntax
await db.LiveTable<T>(table, diff)
Arguments
| Arguments | Description |
|---|
table required | The table name to listen for changes for. |
diff optional | If set to true, live notifications will include an array of JSON Patch objects, rather than the entire record for each notification. |
cancellationToken optional | The cancellationToken enables graceful cancellation of asynchronous operations. |
Example usage
await using var liveQuery = await db.LiveTable<Person>("person");
.Kill()
Kills a running live query by it’s UUID.
Method Syntax
await db.Kill(queryUuid)
Arguments
| Arguments | Description |
|---|
queryUuid required | The UUID of the live query you wish to kill. |
cancellationToken optional | The cancellationToken enables graceful cancellation of asynchronous operations. |
Example usage
await db.Kill(queryUuid);
Live Actions
A live query event can be one of the following:
| Action | Result | Description |
|---|
OPEN
| N/A | Emitted when the live query is opened in the server. |
CLOSE
| SocketClosed or QueryKilled
| 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 |
CREATE
| Result
| Emitted when a record within your subscription gets deleted |
