Struct Query 

pub struct Query<'db, T: Document> { /* private fields */ }

The M8 query builder.

Obtain via Db::query. Compose with Query::filter, Query::limit, and Query::index_range; terminate with Query::fetch.

Query borrows &'db Db so multiple builders can coexist; the borrow ends when .fetch() returns. The actual scan runs inside a fresh read_transaction opened by .fetch() — the builder itself holds no locks.

Implementations

impl<'db, T> Query<'db, T>

where T: Send + 'static + Document,

pub fn filter<F>(self, predicate: F) -> Self

where F: Fn(&T) -> bool + 'static,

Append a filter predicate. Filters compose with AND — every predicate must return true for a doc to be emitted.

'static is required so the closure can outlive the temporary builder; capture by value if you need to borrow a stack-local value.

pub fn limit(self, n: usize) -> Self

Cap the result set at n documents. Order is the source order (primary Id for full-scan; index-key bytes for an index range).

pub fn index_range<R>(self, name: &str, range: R) -> Result<Self>

where R: RangeBounds<Dynamic>,

Switch the query source from full-scan to the named index’s range. Bounds are Dynamic values; the builder encodes them through obj_core::index::encode_field at call time so the actual range arithmetic sees byte-ordered keys.

Order is by the index key bytes, not by primary Id. The scan is bounded to the slice of the index B-tree the range covers — no full-collection walk.

Examples

Range query on an indexed u64 field:

use obj::Db;
use obj_core::codec::Dynamic;
use serde::{Deserialize, Serialize};

#[derive(Debug, Serialize, Deserialize, obj::Document)]
#[obj(collection = "orders_index_range_doc")]
struct Order {
    #[obj(index)]
    placed_at: u64,
}

let dir = tempfile::tempdir()?;
let db = Db::open(dir.path().join("range.obj"))?;
for i in 0..100u64 {
    let _ = db.insert(Order { placed_at: i * 1_000 })?;
}
let last_week = Dynamic::U64(30_000);
let now = Dynamic::U64(60_000);
let recent: Vec<Order> = db
    .query::<Order>()
    .index_range("placed_at", last_week..now)?
    .fetch()?;
assert_eq!(recent.len(), 30);

Errors

• obj_core::Error::Codec if a Dynamic::String bound carries an embedded NUL byte (the order-preserving encoder rejects those — see obj_core::index::encode_field).

pub fn sort_by<F>(self, key: F) -> Self

where F: Fn(&T) -> Dynamic + 'static,

Sort the result by key’s output in ascending key order.

key returns an obj_core::codec::Dynamic for each document; the builder runs each value through obj_core::index::encode_field (M7 #55) so the comparator is a byte comparison whose ordering matches the value’s natural Ord. This reuses the same order-preserving encoder the index layer uses, so a .sort_by(|o| o.placed_at.into()) produces the same ordering an index_range("placed_at", ...) scan would visit.

Last-call-wins: a second .sort_by (or .sort_by_bytes) overwrites the first; the two extractors share the same internal slot because they are mutually exclusive.

The sort runs BEFORE Query::limit truncation, so .sort_by(...).limit(N) returns the N smallest by the extractor’s key — the “top-N sorted” workload design.md shows for the Orders example.

Errors at fetch time

sort_by itself is infallible — it stores the closure. The encoder runs during Query::fetch; a Dynamic whose encode_field representation cannot be computed (e.g. a Dynamic::String carrying an embedded 0x00 byte that the order-preserving encoder rejects) surfaces as Error::SortKeyEncode — power-of-ten Rule 7 (no silent errors). Callers who want to bypass encode_field entirely should use Query::sort_by_bytes.

Sort-buffer bound

The pre-sort buffer is capped at Query::sort_buffer_limit (default MAX_SORT_BUFFER = 100 000). A scan that produces more candidates surfaces Error::SortBufferExceeded; the user should narrow the source via .filter / .index_range / .limit, or raise the cap with .sort_buffer_limit(N).

pub fn sort_by_bytes<F>(self, key: F) -> Self

where F: Fn(&T) -> Vec<u8> + 'static,

Sort the result by key’s raw byte output in ascending order.

Companion to Query::sort_by that lets callers supply the already-encoded sort bytes. The byte-order = sort-order invariant is the caller’s responsibility: two documents whose key bytes compare Less MUST also be in the desired sort order, otherwise the produced ordering is unspecified.

Bypassing obj_core::index::encode_field means Error::SortKeyEncode cannot fire — sort_by_bytes is the right shape for callers who already have an order-preserving byte form (e.g. a precomputed i64::to_be_bytes of a signed counter that they have already biased to the unsigned range).

Last-call-wins: sort_by_bytes overwrites a prior Query::sort_by (and vice versa).

Sort-buffer bound

Same bound as Query::sort_by — see that method’s docs.

pub fn sort_buffer_limit(self, n: usize) -> Self

Override the per-query sort-buffer ceiling. Only consulted when Query::sort_by is set. Defaults to MAX_SORT_BUFFER (100 000).

A scan that overshoots the cap surfaces Error::SortBufferExceeded; narrow the candidate set with Query::filter / Query::index_range / Query::limit, or raise the cap with this method.

Examples

use obj::Db;
use obj_core::codec::Dynamic;
use serde::{Deserialize, Serialize};

#[derive(Debug, Serialize, Deserialize, obj::Document)]
#[obj(collection = "ticks_sort_buffer_doc")]
struct Tick { value: u64 }

let dir = tempfile::tempdir()?;
let db = Db::open(dir.path().join("sort.obj"))?;
for v in 0..10u64 {
    let _ = db.insert(Tick { value: v })?;
}
let top: Vec<Tick> = db
    .query::<Tick>()
    .sort_by(|t| Dynamic::U64(t.value))
    .sort_buffer_limit(1_000) // narrower than the default
    .limit(3)
    .fetch()?;
assert_eq!(top.len(), 3);

pub fn fetch(self) -> Result<Vec<T>>

Execute the query and materialise the matching documents.

Opens a fresh read_transaction, drives the configured source iterator, applies every filter in declaration order, and truncates to limit (if set). Returns the documents in source order.

Errors

• As Db::read_transaction.
• Any error from the underlying crate::Collection scan.

pub fn count(&self) -> Result<u64>

Count the documents this query would return, ignoring Query::sort_by (sort does not change the count) but honouring Query::limit (returns min(total, limit)).

Takes &self rather than consuming the builder so callers can chain a follow-up .fetch() on the same predicate set.

Fast path (no filter set)

When no filter is set, count walks the source B-tree without decoding any document. The exact shape of the walk depends on the source’s index kind so the answer matches what fetch would return:

• Full scan — walks the primary B-tree counting entries (Collection::count_all). One entry per doc; the count is exact.
• Standard / Unique / Composite index_range — walks the named index’s B-tree counting entries (Collection::count_index_range). One entry per doc; the count is exact.
• Each index_range — walks the named index’s B-tree tracking distinct trailing-id suffixes via Collection::count_distinct_ids_in_range (M8 follow-up #72). A single doc may emit multiple entries under different element keys; the entry count would overshoot. The distinct set is bounded by crate::MAX_DISTINCT_IDS (100 000); exceeding it surfaces obj_core::Error::DistinctCountExceeded.

Slow path (filter set)

When at least one filter is set, the predicate has to see a decoded T, so the slow path pays the per-doc decode cost (same as fetch). Sort, if set, is ignored — the total count is the same.

Examples

Count without materialising documents:

use obj::Db;
use serde::{Deserialize, Serialize};

#[derive(Debug, Serialize, Deserialize, obj::Document)]
#[obj(collection = "counts_doc")]
struct Order { customer_id: u64 }

let dir = tempfile::tempdir()?;
let db = Db::open(dir.path().join("count.obj"))?;
for i in 0..30u64 {
    let _ = db.insert(Order { customer_id: i % 3 })?;
}
let n: u64 = db.query::<Order>()
    .filter(|o| o.customer_id == 1)
    .count()?;
assert_eq!(n, 10);

Errors

• As Db::read_transaction.
• Any error from the underlying crate::Collection scan.
• obj_core::Error::DistinctCountExceeded on the Each fast path.