Live queries

A LIVE SELECT statement creates a session that keeps track of changes to a table in real time. Inside the Rust SDK, this is accomplished by appending .live() to the end of a .select() query.

Getting started

Start a running database using the following command:

surreal start --user root --pass root

To follow along interactively, connect using Surrealist or the following command to open up the CLI:

surrealdb % surreal sql --user root --pass root --ns namespace --db database --pretty

Then use the cargo add command to add four crates: surrealdb and tokio, the futures crate for the StreamExt trait needed to use the async stream, as well as with serde with the “serde_derive” feature (cargo add serde --features serde_derive). The dependencies inside Cargo.toml should look something like this:

cargo add serde —features serde_derive

[dependencies]
futures = "0.3.31"
serde = { version = "1.0.214", features = ["serde_derive"] }
surrealdb = "2.0.4"
tokio = "1.41.0"

The example code below shows a live select that keeps track of changes made to a sample of records from the account table. By adding the .range() method, it can be restricted to certain record IDs, in this case any record IDs in between the letters a and g.

The stream from the .live() method returns a stream of Notifications. These contain an action (an Action::Create, Action::Update, or Action::Delete), and a field called data that contains anything that can be deserialized. In this case, the data field will deserialize into a struct that we create called Account. It also contains a query_id field that contains the ID of the live query itself, for record keeping or to cancel using the KILL statement.

Once the following code is run, the Rust client will continue to listen for changes to the account table indefinitely.

use futures::StreamExt;
use serde::Deserialize;
use surrealdb::engine::remote::ws::Ws;
use surrealdb::opt::auth::Root;
use surrealdb::{RecordId, Surreal};

const ACCOUNT: &str = "account";

#[derive(Debug, Deserialize)]
struct Account {
    id: RecordId,
    balance: f64,
}

#[tokio::main]
async fn main() -> surrealdb::Result<()> {
    let db = Surreal::new::<Ws>("localhost:8000").await?;

    db.signin(Root {
        username: "root",
        password: "root",
    })
    .await?;

    db.use_ns("namespace").use_db("database").await?;

    let mut sample_accounts = db.select(ACCOUNT).range("a"..="g").live().await?;

    while let Some(result) = sample_accounts.next().await {
        match result {
            Ok(notification) => {
                let action = notification.action;
                let account: Account = notification.data;
                let id = notification.query_id;
                println!("{action:?} from live ID {id}:\n  {account:#?}\n");
            }
            Err(error) => eprintln!("{error}"),
        }
    }

    Ok(())
}

We can now move to Surrealist or the CLI to execute a few queries and see what happens. The following queries create, update, and delete ten account records.

FOR $_ IN 0..10 { CREATE account SET balance = 10 };
UPDATE account SET balance += 1000;
DELETE account;

The Rust client will keep track for any with a record ID in between a and g, returning an output similar to the following.

Create from live ID 63853ee1-aa9b-4e04-a54a-3b900a3cbaaa:
  Account {
    id: Thing {
        tb: "account",
        id: String(
            "cjk4pk2am5chjs4hxjpz",
        ),
    },
    balance: 10.0,
}

Create from live ID 63853ee1-aa9b-4e04-a54a-3b900a3cbaaa:
  Account {
    id: Thing {
        tb: "account",
        id: String(
            "dp98mide1w91fnjoezf0",
        ),
    },
    balance: 10.0,
}

Update from live ID 63853ee1-aa9b-4e04-a54a-3b900a3cbaaa:
  Account {
    id: Thing {
        tb: "account",
        id: String(
            "cjk4pk2am5chjs4hxjpz",
        ),
    },
    balance: 1010.0,
}

Update from live ID 63853ee1-aa9b-4e04-a54a-3b900a3cbaaa:
  Account {
    id: Thing {
        tb: "account",
        id: String(
            "dp98mide1w91fnjoezf0",
        ),
    },
    balance: 1010.0,
}

Delete from live ID 63853ee1-aa9b-4e04-a54a-3b900a3cbaaa:
  Account {
    id: Thing {
        tb: "account",
        id: String(
            "cjk4pk2am5chjs4hxjpz",
        ),
    },
    balance: 1010.0,
}

Delete from live ID 63853ee1-aa9b-4e04-a54a-3b900a3cbaaa:
  Account {
    id: Thing {
        tb: "account",
        id: String(
            "dp98mide1w91fnjoezf0",
        ),
    },
    balance: 1010.0,
}