Crate rushdb_query 

Query planner and executor over the LMPG state.

Turns a SearchRequest into an access path (index_candidates), executes it against a pinned snapshot, and falls back to a full scan whenever a predicate cannot be served exactly by the maintained indexes. Every index path is required to return exactly what the forced-scan path returns; the differential tests in tests/planner_differential.rs enforce that.

Re-exports

pub use document::ParsedQuery;

pub use document::QueryDocumentError;

Modules

datetime

Query-level datetime operators over the canonical Chrono-backed type implementation in rushdb-types.

document

Native RushDB query-document parser.

Structs

AggregateRequest

A branch-grain aggregation request over distinct roots.

CollectSpec

$collect at the root binding grain (document 19): one declared step per level, batched typed-adjacency collection, optional uniqueness and local slice. Output attaches to each returned record under alias.

EvalCtx

Traversal-capable evaluation context. Records-perspective execution routes through this when the where tree contains Expr::Related.

GroupBucket

One aggregation bucket carrying its typed group tuple, per-metric maps and materialized derived outputs.

Page

One page of reconstructed records plus the pre-pagination match total.

Pagination

Offset/limit pagination applied after matching and ordering.

PlannedCandidates

The index plan’s candidate ordinals, ascending. A superset of the records matching the conditions it was planned for, or exactly them.

PointFields

Record properties read with one point read per typed definition instead of rebuilding the record (READ-1: sorting 667K matches, or checking an unindexed age < 25 on them, rebuilt every one). Covers scalar record properties only; Self::resolve answers None for a system field or a property stored as an array anywhere, and the caller rebuilds the record.

RelatedExpr

Traversal predicate mirroring the documented relationship syntax.

RelatedSpec

A root-bound traversal branch declared under related or a where alias.

SearchRequest

A records-perspective search over one committed snapshot.

TimeBucketSpec

Fixed-size calendar bucket over an epoch-millisecond field. Non-datetime or missing input collapses to the documented MISSING state key.

TraversalStep

One level of an alias traversal path (see RelatedSpec::steps).

Enums

Direction

Direction of an edge traversal.

Expr

Boolean expression tree evaluated against a reconstructed record.

FieldPred

A single-field predicate inside a where expression.

OutputExpr

Derived-output expression graph ($ref chains in document 19): arithmetic over other named outputs, evaluated after all source metrics.

QueryError

Errors returned by query planning and execution.

TimeUnit

Calendar/clock unit for a fixed-width time bucket.

Constants

MAX_AGGREGATE_BUCKETS

Maximum number of distinct buckets a single aggregation may create before it is refused with QueryError::ResourceLimit.

MAX_AVG_PRECISION

Maximum accepted $precision for $avg. f64 carries ~15 significant decimal digits; larger values would only amplify rounding noise (and 10f64.powi overflows past ~308). Parsed values are clamped to this.

MISSING_SENTINEL

Group-key sentinel emitted when a groupBy/timeBucket source field is missing (distinct from an explicit JSON null).

UNINDEXED_WALK_THRESHOLD

An unindexed predicate leaf that walks more owners than this is counted in unindexed_walks_total: the signal that a declared ordered index would pay off (DC2 keeps no automatic value postings).

Functions

aggregate

Branch-grain aggregation over a BindingRelation of distinct roots: one root contributes exactly one binding row, independent branches are filtered existentially rather than multiplied into flat rows.

aggregate_in_view

Aggregate execution over a caller-owned pinned read view. Embedded engines use this to keep every phase of a request on one snapshot and to apply the same deadline/budget context as the transport path.

aggregate_to_rows

Shape aggregate buckets into flat result rows: group-by dimensions (incl. timeBucket aliases), count/sum outputs, and derived outputs keyed by their output name.

aggregate_to_rows_in_view

Shape aggregate buckets using a caller-owned snapshot.

aggregate_to_rows_in_view_with_budget

Shape aggregate output with bounded working and retained rows.

aggregate_with_cancel

Aggregate execution with cooperative cancellation at root and bucket boundaries. Returns the completed buckets plus the total number of matched roots (the total reported by the data plane, matching a search result’s total).

aggregate_with_cancel_in_view

Execute an aggregate on the supplied view using the configured query budget.

aggregate_with_cancel_in_view_with_budget

Execute an aggregate with one caller budget across working state and groups. An explicit zero budget rejects allocations; an absent budget uses storage configuration.

effective_budget

Resolve the effective working-set budget: the caller’s remaining request budget, else the configured per-query cap.

explain_cardinality

Exact most-selective index-leaf cardinality for a predicate, for EXPLAIN . Uses the maintained derived posting cardinality when the view carries it, so EXPLAIN need not materialize candidates. Returns None when no leaf is index-eligible (a full scan).

explain_index

Name of the first declared index the predicate’s leaves can use, for EXPLAIN’s access path.

explain_range_selectivity

Selectivity fraction (estimated owners / exact owner-occurrences, clamped to [0.0, 1.0]) for the first range leaf (Gt/Gte/Lt/Lte) in where_, from the value-distribution histogram — None when the predicate has no range leaf or no usable histogram exists. This is ExplainPlan’s own estimate channel: deliberately never merged with explain_cardinality’s exact field.

explain_walk

The unindexed walk a query would start with, for EXPLAIN: the property of the most selective eligible leaf when no declared ordered index serves it, and the owners carrying that property (under labels when given), which the planner visits one point read at a time.

find_records

Records-perspective execution over one committed snapshot. Missing property = no occurrence; explicit null = live payload-free occurrence.

find_records_in_view

Execute against a caller-owned statement view, allowing response metadata and follow-up reconstruction to share the same committed version. The view must belong to lmpg.store; the caller owns authorization scope.

find_records_in_view_with_budget

Execute a search with an optional caller-owned response byte budget for the returned page. The working set (candidates, matches, ordering rows) is capped by query-memory-max instead ([working_set_budget]).

find_records_streaming

Streaming execution: identical to find_records_in_view; kept as the name the differential tests compare against the forced-scan path.

find_records_streaming_with_total

Page with a caller-supplied total (E6 cursor continuations). The total is only valid when the caller reuses the exact pinned snapshot and match set the total was computed from — the native cursor guarantees both, so continuations stop after their page instead of counting again. None computes it (ordinary search path).

find_records_with_cancel

Records-perspective execution with a cooperative cancellation probe. The probe is checked inside scan and reconstruction loops so a cancelled stream stops consuming CPU instead of merely discarding its response.

hex_decode_16

Decode exactly 16 bytes from a 32-character hex string (case-insensitive).

matches_properties

Evaluate a parse_property_predicate expression on one object. $type tests the stored JSON shape (there is no declared type to consult).

matching_ordinals

Every ordinal matching req, in match order (order_by applied).

matching_ordinals_first

The first keep ordinals matching req, in match order: the same prefix matching_ordinals returns, without resolving the rest. A search with no predicate and no order_by stops after keep matches, so its cost does not grow with the label’s size.

normalize

Normalize a property/label name to the engine’s canonical form.

parse_property_predicate

Parse a property predicate that is evaluated on one object without the graph around it (relationship properties): the full operator set, but no traversal blocks.

planned_candidates

Candidates for records of labels matching every one of conditions.

unindexed_walks_total

Unindexed leaf walks over more than UNINDEXED_WALK_THRESHOLD owners in this process (rushdb_unindexed_walks_total).

Type Aliases

QuerySnapshot

Caller-owned snapshot used for query execution and result shaping.