Struct ResultSet

pub struct ResultSet { /* private fields */ }

The result of a database query.

This behaves essentially like a set of Rows, and each Row is a set of HdbValues.

In fact, result sets with a larger number of rows are not returned from the database in a single roundtrip. ResultSet automatically fetches outstanding data as soon as they are required.

The method try_into converts the data from this generic format in a singe step into your application specific format.

Due to the chunk-wise data transfer, which has to happen asynchronously, ResultSet cannot implement the synchronous trait std::iter::Iterator. Use method next_row() as a replacement.

Implementations

impl ResultSet

pub async fn try_into<'de, T>(self) -> Result<T, HdbError>

where T: Deserialize<'de>,

Conveniently translates the complete result set into a rust type that implements serde::Deserialize and has an adequate structure. The implementation of this method uses serde_db::de.

A result set is essentially a two-dimensional structure, given as a list of rows, where each row is a list of fields; the name of each field is given in the metadata of the result set.

The method supports a variety of target data structures, with the only strong limitation that no data loss is supported.

It depends on the dimension of the result set what target data structure you can choose for deserialization:

• You can always use a Vec<line_struct>, if the elements of line_struct match the field list of the result set.

• If the result set contains only a single line (e.g. because you specified TOP 1 in your select clause), then you can optionally choose to deserialize directly into a plain line_struct.

• If the result set contains only a single column, then you can optionally choose to deserialize directly into a Vec<plain_field>.

• If the result set contains only a single value (one row with one column), then you can optionally choose to deserialize into a plain line_struct, or a Vec<plain_field>, or a plain_field.

Also the translation of the individual field values provides flexibility.

• You can e.g. convert values from a nullable column into a plain field, provided that no NULL values are given in the result set.

• Vice versa, you can use an Option<plain_field>, even if the column is marked as NOT NULL.

• Similarly, integer types can differ, as long as the concrete values can be assigned without loss.

As usual with serde deserialization, you need to specify the type of your target variable explicitly, so that try_into() can derive the type it needs to instantiate:

#[derive(Deserialize)]
struct Entity {
    ...
}
let typed_result: Vec<Entity> = result_set.try_into()?;

Errors

HdbError::Deserialization if the deserialization into the target type is not possible.

pub async fn into_rows(self) -> Result<Rows, HdbError>

Fetches all rows and all data of contained LOBs

Errors

Various errors can occur.

pub async fn into_single_row(self) -> Result<Row, HdbError>

Converts the result set into a single row.

Errors

HdbError::Usage if the result set contains more than a single row, or is empty.

pub async fn into_single_value(self) -> Result<HdbValue<'static>, HdbError>

Converts the result set into a single value.

Errors

HdbError::Usage if the result set contains more than a single value, or is empty.

pub fn metadata(&self) -> Arc<ResultSetMetadata>

Access to metadata.

Examples

let rs: ResultSet;
//...
// get the precision of the second field
let prec: i16 = result_set.metadata()[1].precision();

or

let rs: ResultSet;
//...
for field_metadata in &*rs.metadata() {
    // evaluate metadata of a field
}

pub async fn total_number_of_rows(&self) -> Result<usize, HdbError>

Returns the total number of rows in the result set, including those that still need to be fetched from the database, but excluding those that have already been removed from the result set.

This method can be expensive, and it can fail, since it fetches all yet outstanding rows from the database.

Errors

Several variants of HdbError are possible.

pub async fn next_row(&mut self) -> Result<Option<Row>, HdbError>

Removes the next row and returns it, or Ok(None) if the ResultSet is empty.

Consequently, the ResultSet has one row less after the call. May need to fetch further rows from the database, which can fail.

let mut rs = connection.query(query_str).await?;
while let Some(row) = rs.next_row().await? {
    let entity: Entity = row.try_into()?;
    println!("Got entity: {:?}", entity);
}

Errors

Several variants of HdbError are possible.

pub async fn fetch_all(&self) -> Result<(), HdbError>

Fetches all not yet transported result lines from the server.

Bigger result sets are typically not transported in one roundtrip from the database; the number of roundtrips depends on the total number of rows in the result set and the configured fetch-size of the connection.

Fetching can fail, e.g. if the network connection is broken.

Errors

Several variants of HdbError are possible.

pub async fn server_usage(&self) -> ServerUsage

Provides information about the the server-side resource consumption that is related to this ResultSet object.

Trait Implementations

impl Debug for ResultSet

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

Formats the value using the given formatter.

impl Display for ResultSet

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

Formats the value using the given formatter.