Struct StatementHandle 

pub struct StatementHandle { /* private fields */ }

Tracks one submitted query. Keep the handle to inspect progress, wait for results, or request cancellation.

Operation	Method
Read the last observed status without a request	Self::snapshot
Fetch the current status	Self::refresh
Wait for results	Self::wait
Request cancellation	Self::cancel

Dropping a wait or refresh future stops local waiting without cancelling execution. Terminal statuses are cached, so waiting again returns the result without another request. Retry temporary read failures on this handle rather than submitting another query.

Implementations

impl StatementHandle

pub fn statement_id(&self) -> Uuid

Examples found in repository

examples/statement.rs (line 28)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = common::client()?;

    let result = client.query("SELECT 1 AS ready").await?;
    let rows = result.into_objects()?;
    println!("rows: {rows:?}");

    // Keep the handle when an application needs progress, cancellation, or a
    // durable statement ID before waiting for the result.
    let mut handle = client.statement("SELECT 2 AS value").submit().await?;
    let statement_id = handle.statement_id();
    println!(
        "statement {statement_id} submitted: {:?}",
        handle.snapshot()
    );
    let status = handle.refresh().await?;
    println!("statement {statement_id}: {status:?}");
    let result = handle.wait().await?;
    println!("handle rows: {:?}", result.into_objects()?);
    Ok(())
}

pub fn snapshot(&self) -> Option<&StatementStatus>

Returns the status snapshot received by the most recent request without making a network request.

Examples found in repository

examples/statement.rs (line 31)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = common::client()?;

    let result = client.query("SELECT 1 AS ready").await?;
    let rows = result.into_objects()?;
    println!("rows: {rows:?}");

    // Keep the handle when an application needs progress, cancellation, or a
    // durable statement ID before waiting for the result.
    let mut handle = client.statement("SELECT 2 AS value").submit().await?;
    let statement_id = handle.statement_id();
    println!(
        "statement {statement_id} submitted: {:?}",
        handle.snapshot()
    );
    let status = handle.refresh().await?;
    println!("statement {statement_id}: {status:?}");
    let result = handle.wait().await?;
    println!("handle rows: {:?}", result.into_objects()?);
    Ok(())
}

pub async fn refresh(&mut self) -> Result<&StatementStatus, Error>

Fetches a status snapshot, or returns the cached terminal state. Requests on a handle are serialized through its mutable borrow.

Examples found in repository

examples/statement.rs (line 33)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = common::client()?;

    let result = client.query("SELECT 1 AS ready").await?;
    let rows = result.into_objects()?;
    println!("rows: {rows:?}");

    // Keep the handle when an application needs progress, cancellation, or a
    // durable statement ID before waiting for the result.
    let mut handle = client.statement("SELECT 2 AS value").submit().await?;
    let statement_id = handle.statement_id();
    println!(
        "statement {statement_id} submitted: {:?}",
        handle.snapshot()
    );
    let status = handle.refresh().await?;
    println!("statement {statement_id}: {status:?}");
    let result = handle.wait().await?;
    println!("handle rows: {:?}", result.into_objects()?);
    Ok(())
}

pub async fn wait(&mut self) -> Result<ResultSet, Error>

Waits for the statement to terminate and returns its result set. Dropping this future leaves the handle and server execution available.

Examples found in repository

examples/statement.rs (line 35)

async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = common::client()?;

    let result = client.query("SELECT 1 AS ready").await?;
    let rows = result.into_objects()?;
    println!("rows: {rows:?}");

    // Keep the handle when an application needs progress, cancellation, or a
    // durable statement ID before waiting for the result.
    let mut handle = client.statement("SELECT 2 AS value").submit().await?;
    let statement_id = handle.statement_id();
    println!(
        "statement {statement_id} submitted: {:?}",
        handle.snapshot()
    );
    let status = handle.refresh().await?;
    println!("statement {statement_id}: {status:?}");
    let result = handle.wait().await?;
    println!("handle rows: {:?}", result.into_objects()?);
    Ok(())
}

pub async fn cancel(&mut self) -> Result<StatementStatus, Error>

Requests cancellation and caches the observed status. Pending or Running means cancellation has not yet been observed; call wait() to settle it. A completion race returns the full result or original execution failure.

Trait Implementations

impl Debug for StatementHandle

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.