Struct QueryStream

pub struct QueryStream<'a> { /* private fields */ }

A set of Streams of QueryItem values, which can be either result metadata or a row.

The QueryStream needs to be polled empty before sending another query to the Client, failing to do so causes a flush before the next query, slowing it down in an undeterministic way.

Every stream starts with metadata, describing the structure of the incoming rows, e.g. the columns in the order they are presented in every row.

If after consuming rows from the stream, another metadata result arrives, it means the stream has multiple results from different queries. This new metadata item will describe the next rows from here forwards.

If having one set of results in the response, using into_row_stream might be more convenient to use.

The struct provides non-streaming APIs with into_results, into_first_result and into_row.

Example

let mut stream = client
    .query(
        "SELECT @P1 AS first; SELECT @P2 AS second",
        &[&1i32, &2i32],
    )
    .await?;

// The stream consists of four items, in the following order:
// - Metadata from `SELECT 1`
// - The only resulting row from `SELECT 1`
// - Metadata from `SELECT 2`
// - The only resulting row from `SELECT 2`
while let Some(item) = stream.try_next().await? {
    match item {
        // our first item is the column data always
        QueryItem::Metadata(meta) if meta.result_index() == 0 => {
            // the first result column info can be handled here
        }
        // ... and from there on from 0..N rows
        QueryItem::Row(row) if row.result_index() == 0 => {
            assert_eq!(Some(1), row.get(0));
        }
        // the second result set returns first another metadata item
        QueryItem::Metadata(meta) => {
            // .. handling
        }
        // ...and, again, we get rows from the second resultset
        QueryItem::Row(row) => {
            assert_eq!(Some(2), row.get(0));
        }
    }
}

Implementations

impl<'a> QueryStream<'a>

pub async fn columns(&mut self) -> Result<Option<&[Column]>>

The list of columns either for the current result set, or for the next one. If the stream is just created, or if the next item in the stream contains metadata, the metadata will be taken from the stream. Otherwise the columns will be returned from the cache and reflect on the current result set.

Example

let mut stream = client
    .query(
        "SELECT @P1 AS first; SELECT @P2 AS second",
        &[&1i32, &2i32],
    )
    .await?;

// Nothing is fetched, the first result set starts.
let cols = stream.columns().await?.unwrap();
assert_eq!("first", cols[0].name());

// Move over the metadata.
stream.try_next().await?;

// We're in the first row, seeing the metadata for that set.
let cols = stream.columns().await?.unwrap();
assert_eq!("first", cols[0].name());

// Move over the only row in the first set.
stream.try_next().await?;

// End of the first set, getting the metadata by peaking the next item.
let cols = stream.columns().await?.unwrap();
assert_eq!("second", cols[0].name());

pub async fn into_results(self) -> Result<Vec<Vec<Row>>>

Collects results from all queries in the stream into memory in the order of querying.

pub async fn into_first_result(self) -> Result<Vec<Row>>

Collects the output of the first query, dropping any further results.

pub async fn into_row(self) -> Result<Option<Row>>

Collects the first row from the output of the first query, dropping any further rows.

pub fn into_row_stream(self) -> BoxStream<'a, Result<Row>>

Convert the stream into a stream of rows, skipping metadata items.

Trait Implementations

impl<'a> Debug for QueryStream<'a>

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

Formats the value using the given formatter.

impl<'a> Stream for QueryStream<'a>

type Item = Result<QueryItem, Error>

Values yielded by the stream.

fn poll_next( self: Pin<&mut Self>, cx: &mut Context<'_>, ) -> Poll<Option<Self::Item>>

Attempt to pull out the next value of this stream, registering the current task for wakeup if the value is not yet available, and returning None if the stream is exhausted.

fn size_hint(&self) -> (usize, Option<usize>)

Returns the bounds on the remaining length of the stream.