Struct ejdb::PreparedQuery

pub struct PreparedQuery<'coll, 'db: 'coll, 'out, Q, H> { /* fields omitted */ }

Represents a query which is ready to be executed.

This structure is created out of query::Query object and provides methods to perform queries in various ways. It is tied with a lifetime parameter to the collection this query is executed on and therefore cannot outlive it.

PreparedQuery is created using Collection::query() method.

Methods

impl<'coll, 'db, 'out, Q, H> PreparedQuery<'coll, 'db, 'out, Q, H> where
    Q: Borrow<Query>,
    H: Borrow<QueryHints>, 

pub fn log_output<'o>(
    self,
    target: &'o mut (dyn Write + 'o)
) -> PreparedQuery<'coll, 'db, 'o, Q, H>

Sets the provided writer as a logging target for this query.

This method can be used to analyze how the query is executed. It is needed mostly for debug purposes.

Unfortunately, due to EJDB API design, the data will be written to the provided target only after the query is executed entirely (and if it is executed at all).

Example

use ejdb::query::{Q, QH};
use std::io::Write;

let db = Database::open("/path/to/db").unwrap();
let coll = db.collection("some_collection").unwrap();

let mut log_data = Vec::new();
let query = coll.query(Q.field("name").eq("Foo"), QH.empty())
    .log_output(&mut log_data);
// the query now will log to `log_data` vector when executed

pub fn count(self) -> Result<u32>

Executes the query, returning the number of affected records.

This method is equivalent to find().map(|r| r.len()) but more efficient because it does not load the actual data from the database.

Note that due to EJDB API structure this method is exactly equivalent to PreparedQuery::update(), but it has its own name for semantic purposes.

Failures

Returns an error if the query document can't be serialized to EJDB representation, if writing to the output log has failed or if any of the underlying EJDB operations can't be completed successfully.

Example

use ejdb::query::{Q, QH};

let db = Database::open("/path/to/db").unwrap();
let coll = db.collection("some_collection").unwrap();
let query = coll.query(Q.field("name").eq("Foo"), QH.empty());
let n = query.count().unwrap();
// n is the number of records with "name" field equal to "Foo"

pub fn update(self) -> Result<u32>

Executes the query which does not return results, returning the number of affected records.

No data is loaded from the database when this method is executed, so it is primarily needed for updating queries.

Note that due to EJDB API structure this method is exactly equivalent to PreparedQuery::count(), but it has its own name for semantic purposes.

Failures

Returns an error if the query document can't be serialized to EJDB representation, if writing to the output log has failed or if any of the underlying EJDB operations can't be completed successfully.

Example

use ejdb::query::{Q, QH};

let db = Database::open("/path/to/db").unwrap();
let coll = db.collection("some_collection").unwrap();
let n = coll.query(Q.field("name").eq("Foo").set("count", 42), QH.empty())
    .update().unwrap();
// n is the number of records affected by the update

pub fn find_one(self) -> Result<Option<Document>>

Executes the query, returning the first matched element if it is available.

This method executes the prepared query, returning only one element matching the query. This is more efficient than PreparedQuery::find() method because only one object is actually loaded from the database.

Failures

Returns an error if the query document can't be serialized to EJDB representation, if the returned document can't be deserialized from EJDB representation, if writing to the output log has failed or if any of the underlying EJDB operations can't be completed successfully.

Example

use ejdb::query::{Q, QH};

let db = Database::open("/path/to/db").unwrap();
let coll = db.collection("some_collection").unwrap();
match coll.query(Q.field("name").eq("Foo"), QH.empty()).find_one().unwrap() {
    Some(doc) => { /* `doc` is the first record with "name" field equal to "Foo" */ }
    None => { /* no document with "name" equal to "Foo" has been found */ }
}

pub fn find(self) -> Result<QueryResult>

Executes the query, returning an iterator of all documents matching the query.

This method executes the prepared query and returns an iterator of all records which match it. This is the main method to use if you need to access multiple elements from the database.

Failures

Returns an error if the query document can't be serialized to EJDB representation, if writing to the output log has failed or if any of the underlying EJDB operations can't be completed successfully. Each document from the query is deserialized from EJDB representation separately when the iterator is traversed.

Example

use ejdb::query::{Q, QH};

let db = Database::open("/path/to/db").unwrap();
let coll = db.collection("some_collection").unwrap();
let result = coll.query(Q.field("name").eq("Foo"), QH.empty()).find().unwrap();
let items: Result<Vec<_>, _> = result.collect();  // collect all found records into a vector