Struct Query 

pub struct Query<T> { /* private fields */ }

A compile-time-checked query paired with its inferred result type T.

query! expands to one of these, carrying the already-validated query text, the parameters bound at the call site, and a T that is the inferred response rendered as a nameless struct.

Implementations

impl<T> Query<T>

pub const fn text(&self) -> &'static str

The validated SurrealQL text.

pub const fn statements(&self) -> usize

The number of top-level statements, which is also the number of result slots the server returns.

pub fn bound(&self) -> Vec<&str>

The names of the parameters bound at the call site, in bind order.

pub fn decode(&self, values: Vec<Value>) -> Result<T>

Decodes one Value per statement into the inferred result type.

This is the whole typed surface with the runtime feature off, and the seam the fetch* methods go through — a response obtained any other way can be decoded with it. values must hold one entry per statement, in source order.

Errors

Returns ErrorKind::Decode if a statement’s value does not match the type inferred for it.

impl<T> Query<T>

pub async fn fetch<C: Connection>(self, db: &Surreal<C>) -> Result<T>

Runs the query and returns exactly the type the analyzer inferred.

This is the shape-preserving verb: a SELECT gives a Vec of rows, a RETURN gives the value, SELECT … FROM ONLY gives an Option, and a multi-statement query gives a tuple. When the result is a row set, fetch_all and friends read better.

Errors

Returns ErrorKind::Database if the query failed, or ErrorKind::Decode if the response does not match the inferred type.

pub async fn execute<C: Connection>(self, db: &Surreal<C>) -> Result<()>

Runs the query and discards its result.

Errors

Returns ErrorKind::Database if the query failed.

impl<T> Query<T>

The row-set verbs.

T: Rows is a bound on each method rather than on the impl block on purpose: an unsatisfied method bound is an E0277, which honours the #[diagnostic::on_unimplemented] note on Rows, whereas an unsatisfied impl-block bound is an E0599 that reports only i64: Rows and no guidance.

pub async fn fetch_all<C: Connection>( self, db: &Surreal<C>, ) -> Result<Vec<T::Row>>

where T: Rows,

Runs the query and returns every row.

Errors

Returns ErrorKind::Database if the query failed, or ErrorKind::Decode if a row does not match its inferred type.

pub async fn fetch_one<C: Connection>(self, db: &Surreal<C>) -> Result<T::Row>

where T: Rows,

Runs the query and returns its first row, failing if there are none.

Errors

Returns ErrorKind::RowNotFound if the query matched nothing, plus the errors fetch_all returns.

pub async fn fetch_optional<C: Connection>( self, db: &Surreal<C>, ) -> Result<Option<T::Row>>

where T: Rows,

Runs the query and returns its first row, if any.

Errors

Returns ErrorKind::Database if the query failed, or ErrorKind::Decode if a row does not match its inferred type.

Trait Implementations

impl<T> Debug for Query<T>

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

Formats the value using the given formatter.