Skip to main content

Query

Struct Query 

Source
pub struct Query<'a, E, M: Memory = DefaultMemoryImpl> { /* private fields */ }
Expand description

Fluent exact predicates over one entity. No callback executor is generated. Ordering uses primary order, an explicit index, a proven automatic path or bounded complete sorting. Work exhaustion never returns a sorted prefix.

Implementations§

Source§

impl<E: Entity, M: Memory> Query<'_, E, M>

Source

pub fn start_count_distinct<K: Value>( self, jobs: &mut AggregateJobs<impl Memory>, now: Timestamp, expires: Timestamp, ) -> Result<JobHandle, Error>

Retain an exact count of projected K tuples, including an absent tuple. Uses synchronous count_distinct admission and equality without an index. Retain at most 32 distinct keys inside the 16 KiB whole-job frame; no spill. Query/projection/algorithm bind the job; work/byte limits may vary.

§Errors

Refuses unsupported projections, group modifiers, expiry and capacity.

§Panics

Supplier mutation failures trap the enclosing message.

Source

pub fn resume_count_distinct<K: Value>( self, jobs: &mut AggregateJobs<impl Memory>, handle: &JobHandle, sequence: u64, now: Timestamp, ) -> Result<JobStep<u64>, Error>

Advance DISTINCT count under scalar jobs’ work/retry/revision/expiry rules. Duplicates across steps count once; empty input returns zero, all-absent tuples count once. Finish all input before returning a count. limit never truncates input or relaxes key-set bounds.

§Errors

Refuses mismatched queries/projections, malformed saved keys, cardinality, output or whole-frame bounds without changing the previous checkpoint.

§Panics

Supplier mutation failures trap the enclosing message.

Source

pub fn start_group_count_distinct<K: Value, R: Value>( self, jobs: &mut AggregateJobs<impl Memory>, now: Timestamp, expires: Timestamp, ) -> Result<JobHandle, Error>

Retain distinct R tuples separately in each K group, including absent tuples. Projections may overlap. Uses synchronous group_count_distinct admission. Keep at most 32 groups and 32 distinct keys per group inside one 16 KiB whole-job frame. Key/operand projections, group selection and limit bind the job. Work/output-byte limits may vary; no automatic spill.

§Errors

Refuses unsupported projections, expiry or occupied job capacity.

§Panics

Supplier mutation failures trap the enclosing message.

Source

pub fn resume_group_count_distinct<K: Value, R: Value>( self, jobs: &mut AggregateJobs<impl Memory>, handle: &JobHandle, sequence: u64, now: Timestamp, ) -> Result<JobStep<GroupPage<GroupCount<K>>>, Error>

Advance grouped DISTINCT counts with grouped jobs’ revision/retry/expiry rules. Finish all input before filtering, ordering or limiting groups. Empty input returns an empty vector; an all-absent tuple contributes one to its group. Returns a GroupPage; use group_page to page completed selected groups.

§Errors

Refuses mismatched bindings, malformed saved sets, group/key cardinality, output or frame bounds. Refusal preserves the previous checkpoint; output filters and limits cannot conceal oversized state.

§Panics

Supplier mutation failures trap the enclosing message.

Source§

impl<E: Entity, M: Memory> Query<'_, E, M>

Source

pub fn start_group_min<K: Value, R: Value>( self, jobs: &mut AggregateJobs<impl Memory>, now: Timestamp, expires: Timestamp, ) -> Result<JobHandle, Error>

Retain minima per exact key record, without scanning input. R selects one exact ordered field, as in group_min; key and operand may overlap. Retain all-absent groups with None. Keep at most 32 groups within the complete 16 KiB job frame, including keys, winners and progress. Group predicates, order and total limit bind the job. No automatic spill.

§Errors

Refuses unsupported shapes, page modifiers, expiry or occupied capacity.

§Panics

Supplier mutation failures trap the enclosing message.

Source

pub fn start_group_max<K: Value, R: Value>( self, jobs: &mut AggregateJobs<impl Memory>, now: Timestamp, expires: Timestamp, ) -> Result<JobHandle, Error>

Retain maxima per exact key record with start_group_min’s bounds. Minimum and maximum have separate job identities.

§Errors

The same query, expiry and capacity errors as start_group_min.

§Panics

Supplier mutation failures trap the enclosing message.

Source

pub fn resume_group_min<K: Value, R: Value>( self, jobs: &mut AggregateJobs<impl Memory>, handle: &JobHandle, sequence: u64, now: Timestamp, ) -> Result<JobStep<GroupPage<GroupValue<K, R>>>, Error>

Advance grouped minima with the retained revision, retry and expiry contract. Finish all input before group filtering, ordering and limiting. Absent keys form a group; all-absent operands yield None. Use group_page for completed result pagination, retaining its continuation when mapping rows.

§Errors

Refuses mismatched queries/operations, corrupt winners, group/frame bounds and oversized output without changing saved progress. Selection cannot hide state exhaustion. No prefix winner is returned as an exact result.

§Panics

Supplier mutation failures trap the enclosing message.

Source

pub fn resume_group_max<K: Value, R: Value>( self, jobs: &mut AggregateJobs<impl Memory>, handle: &JobHandle, sequence: u64, now: Timestamp, ) -> Result<JobStep<GroupPage<GroupValue<K, R>>>, Error>

Advance grouped maxima with resume_group_min’s exactness and bounds. Equal operands retain their first encountered value.

§Errors

The same query, checkpoint, resource and output errors as resume_group_min.

§Panics

Supplier mutation failures trap the enclosing message.

Source

pub fn start_min<R: Value>( self, jobs: &mut AggregateJobs<impl Memory>, now: Timestamp, expires: Timestamp, ) -> Result<JobHandle, Error>

Retain a minimum over one exact single-field result record, without scanning. Uses min’s ordered types and absence semantics and start_count’s expiry, revision and capacity bounds. Persist only the winning record, within the complete 16 KiB job frame; no partial result or automatic spill.

§Errors

Refuses unsupported projections/query shapes, expiry or occupied capacity.

§Panics

Supplier mutation failures trap the enclosing message.

Source

pub fn start_max<R: Value>( self, jobs: &mut AggregateJobs<impl Memory>, now: Timestamp, expires: Timestamp, ) -> Result<JobHandle, Error>

Retain a maximum with start_min’s types and bounds. Minimum and maximum have distinct job identities, even when they select the same field.

§Errors

The same admission, expiry and capacity errors as start_min.

§Panics

Supplier mutation failures trap the enclosing message.

Source

pub fn resume_min<R: Value>( self, jobs: &mut AggregateJobs<impl Memory>, handle: &JobHandle, sequence: u64, now: Timestamp, ) -> Result<JobStep<Option<R>>, Error>

Advance a retained minimum with resume_count’s bounded work, retry, revision and expiry contract. Ignore absent operands; empty/all-absent input completes with None. Return the winning record only after exhaustion. Equal values retain the first encountered value. A completed result stays fixed after source writes, until expiry or cancellation.

§Errors

Refuses changed queries/operations, malformed winner bytes, work/state bounds or oversized completed output. Refusal preserves the checkpoint. A comparison key exceeding 4096 bytes refuses even for a losing candidate.

§Panics

Supplier mutation failures trap the enclosing message.

Source

pub fn resume_max<R: Value>( self, jobs: &mut AggregateJobs<impl Memory>, handle: &JobHandle, sequence: u64, now: Timestamp, ) -> Result<JobStep<Option<R>>, Error>

Advance a retained maximum with resume_min’s exactness and bounds.

§Errors

The same query, resource and checkpoint errors as resume_min.

§Panics

Supplier mutation failures trap the enclosing message.

Source§

impl<E: Entity, M: Memory> Query<'_, E, M>

Source

pub fn start_group_count<K: Value>( self, jobs: &mut AggregateJobs<impl Memory>, now: Timestamp, expires: Timestamp, ) -> Result<JobHandle, Error>

Retain grouped row counts without scanning input. K is the same exact key record as synchronous group_count. Group predicates, order and output row limit bind the job; work/output-byte allowances may change on resume. Keep at most 32 groups and the complete job frame within 16 KiB, including progress and encoded key records. No spill or partial output.

§Errors

Refuses group/query admission, invalid expiry or occupied job capacity.

§Panics

Supplier mutation failures trap the enclosing message.

Source

pub fn start_group_count_field<K: Value>( self, field: &str, jobs: &mut AggregateJobs<impl Memory>, now: Timestamp, expires: Timestamp, ) -> Result<JobHandle, Error>

Retain present-field counts per exact key record. Any top-level stored field is accepted; empty values count. Groups containing only absent values remain with count zero. Uses start_group_count’s bounds and selection binding.

§Errors

Refuses unknown fields and ordinary grouped-count admission failures.

§Panics

Supplier mutation failures trap the enclosing message.

Source

pub fn resume_group_count<K: Value>( self, jobs: &mut AggregateJobs<impl Memory>, handle: &JobHandle, sequence: u64, now: Timestamp, ) -> Result<JobStep<GroupPage<GroupCount<K>>>, Error>

Advance grouped counts with scalar jobs’ revision/retry/work/expiry contract. Empty input completes as an empty vector; absent keys form their own group. Finalize all input before filtering, ordering and selecting completed groups. Use group_page to page completed output; otherwise all selected groups must fit.

§Errors

Refuses mismatched queries/keys/selection, cardinality or the 16 KiB job frame. Group/output bounds apply before saving; a refusal preserves prior progress. limit never limits input or relaxes retained-state bounds.

§Panics

Supplier mutation failures trap the enclosing message.

Source

pub fn resume_group_count_field<K: Value>( self, field: &str, jobs: &mut AggregateJobs<impl Memory>, handle: &JobHandle, sequence: u64, now: Timestamp, ) -> Result<JobStep<GroupPage<GroupCount<K>>>, Error>

Advance grouped present-field counts with resume_group_count’s lifecycle. Finish all input before selection; zero-count groups are retained. The field binds the job, including required fields whose count equals the row count.

§Errors

Refuses changed fields, row-count jobs and ordinary grouped-count failures.

§Panics

Supplier mutation failures trap the enclosing message.

Source

pub fn start_group_sum<K: Value, R: Value>( self, jobs: &mut AggregateJobs<impl Memory>, now: Timestamp, expires: Timestamp, ) -> Result<JobHandle, Error>

Retain grouped integer/Decimal sums with group_sum‘s exact result types. Uses grouped counts’ 32-group/16 KiB frame, revision and expiry bounds. Key/result types, operation and completed-group selection bind the job.

§Errors

Refuses invalid query/result shapes, expiry or exhausted job capacity.

§Panics

Supplier mutation failures trap the enclosing message.

Source

pub fn resume_group_sum<K: Value, R: Value>( self, jobs: &mut AggregateJobs<impl Memory>, handle: &JobHandle, sequence: u64, now: Timestamp, ) -> Result<JobStep<GroupPage<GroupValue<K, R>>>, Error>

Advance grouped sums; all-absent groups have None, present zero is a value. Finish every group before filtering/order/limit. Overflow in an excluded group still refuses. Output and frame refusals preserve the saved checkpoint. Returns a GroupPage; use group_page to page the completed selected groups.

§Errors

Grouped-count resume failures and group_sum arithmetic/result errors apply.

§Panics

Supplier mutation failures trap the enclosing message.

Source

pub fn start_group_avg<K: Value, R: Value>( self, jobs: &mut AggregateJobs<impl Memory>, now: Timestamp, expires: Timestamp, ) -> Result<JobHandle, Error>

Retain grouped averages, saving exact totals and each group’s present count. Round once at completion to R’s Decimal scale, nearest with ties to even. Bounds and query binding match start_group_sum; no precision fallback.

§Errors

Refuses invalid average shapes, expiry or exhausted job capacity.

§Panics

Supplier mutation failures trap the enclosing message.

Source

pub fn resume_group_avg<K: Value, R: Value>( self, jobs: &mut AggregateJobs<impl Memory>, handle: &JobHandle, sequence: u64, now: Timestamp, ) -> Result<JobStep<GroupPage<GroupValue<K, R>>>, Error>

Advance grouped averages with resume_group_sum’s complete-input contract. Selection compares completed rounded values. Absent operands do not enter the denominator; all-absent groups remain None. Never average chunk means.

§Errors

Grouped-count resume failures and group_avg arithmetic/result errors apply.

§Panics

Supplier mutation failures trap the enclosing message.

Source§

impl<E: Entity, M: Memory> Query<'_, E, M>

Source

pub fn start_count<J: Memory>( self, jobs: &mut AggregateJobs<J>, now: Timestamp, expires: Timestamp, ) -> Result<JobHandle, Error>

Retain an exact count job without scanning input. Expiry must be after the host-captured now and at most one hour later. No write freeze is acquired. Reconstruct this fluent query on every advance; predicates/access path bind the job, while work/output limits may change. Limit never truncates input.

§Errors

Ordinary count admission, invalid expiry, or all 16 retained slots occupied.

§Panics

Supplier mutation failures trap the enclosing message.

Source

pub fn start_count_field( self, field: &str, jobs: &mut AggregateJobs<impl Memory>, now: Timestamp, expires: Timestamp, ) -> Result<JobHandle, Error>

Retain the count of present values in a named top-level field, of any stored type. Empty values count; absent values do not. The field binds the job, even for a required field. Uses start_count’s limits and expiry contract.

§Errors

Refuses unknown fields and ordinary count-job admission failures.

§Panics

Supplier mutation failures trap the enclosing message.

Source

pub fn resume_count<J: Memory>( self, jobs: &mut AggregateJobs<J>, handle: &JobHandle, sequence: u64, now: Timestamp, ) -> Result<JobStep<u64>, Error>

Advance count within work_limit (1..=512) and 64 KiB of source row/key bytes. Each job admits at most one million examined candidates. A budget boundary returns Running; it never changes the mathematical input set. Supply zero first, then the last returned sequence. An older sequence only reads saved progress; a future sequence refuses. Source changes invalidate running jobs, including on retries; completed results keep their boundary.

§Errors

Refuses a foreign query/handle, future sequence, backward host time, resource bounds or corruption without changing progress. No automatic restart.

§Panics

Supplier mutation failures trap the enclosing message.

Source

pub fn resume_count_field( self, field: &str, jobs: &mut AggregateJobs<impl Memory>, handle: &JobHandle, sequence: u64, now: Timestamp, ) -> Result<JobStep<u64>, Error>

Advance the present-field count with resume_count’s bounds, revision, retry and expiry rules. Empty/all-absent input completes with zero.

§Errors

Refuses changed fields, row-count jobs and ordinary count resume failures.

§Panics

Supplier mutation failures trap the enclosing message.

Source

pub fn start_sum<R: Value>( self, jobs: &mut AggregateJobs<impl Memory>, now: Timestamp, expires: Timestamp, ) -> Result<JobHandle, Error>

Retain an integer/Decimal sum job with synchronous sum’s exact result shape. Same expiry, capacity and query-binding contract as Self::start_count.

§Errors

Refuses unsupported sum shapes, query admission, expiry or occupied capacity.

§Panics

Supplier mutation failures trap the enclosing message.

Source

pub fn resume_sum<R: Value>( self, jobs: &mut AggregateJobs<impl Memory>, handle: &JobHandle, sequence: u64, now: Timestamp, ) -> Result<JobStep<Option<R>>, Error>

Advance exact sum under count’s work/retry/invalidation contract. Check the declared result width only after all input completes, allowing signed prefixes to cancel across messages. Empty/all-absent input completes as None.

§Errors

Count’s refusals plus arithmetic overflow or completed-result byte limits. A refused finalization preserves the previous checkpoint.

§Panics

Supplier mutation failures trap the enclosing message.

Source

pub fn start_avg<R: Value>( self, jobs: &mut AggregateJobs<impl Memory>, now: Timestamp, expires: Timestamp, ) -> Result<JobHandle, Error>

Retain an exact integer/Decimal average. R declares one Decimal field with the source name and optionality, and its desired result scale (0–28). Shares count/sum’s expiry, capacity and revision contract. Average versus sum and the result scale are bound to the job; they cannot change on resume.

§Errors

Refuses unsupported average shapes, query admission, expiry or occupied capacity.

§Panics

Supplier mutation failures trap the enclosing message.

Source

pub fn resume_avg<R: Value>( self, jobs: &mut AggregateJobs<impl Memory>, handle: &JobHandle, sequence: u64, now: Timestamp, ) -> Result<JobStep<Option<R>>, Error>

Advance average under count’s bounded work/retry/invalidation contract. Retain the exact total and present count across steps; divide and round once at completion to the declared Decimal scale, nearest with ties to even. Empty/all-absent input completes as None. Never average rounded page means.

§Errors

Count’s refusals plus arithmetic overflow or completed-result byte limits. A refused finalization preserves the prior exact checkpoint; no scale fallback.

§Panics

Supplier mutation failures trap the enclosing message.

Source§

impl<E: Entity, M: Memory> Query<'_, E, M>

Source

pub fn sum<R: Value>(self) -> Result<Aggregate<Option<R>>, Error>

Sum one integer or Decimal field into a single-field result record with the same field name and optionality. Scalar newtype inputs use their declared primitive. The result field uses a primitive whose integer width may match or widen the source within the same signed/unsigned family. Unsigned results may widen to U256. Decimal results preserve the source’s declared scale; coefficients accumulate exactly in I256 and must fit i128 at completion. No rescaling or rounding. Empty/all-absent input returns None; present zero returns a record. Signed accumulation uses I256, so cancelling prefixes do not cause narrow overflow. Unsigned accumulation uses checked U256. The final total must fit the declared result width. No decimal/float conversion or rounding occurs.

§Errors

Refuses unsupported/narrower/cross-signedness result shapes, cursors, DISTINCT, input ordering and group modifiers. Work exhaustion returns Limit without a prefix total; numeric overflow returns ArithmeticOverflow. Output bytes count the completed result record, with RowTooLarge on overflow of that budget.

§Panics

Supplier corruption traps without repair.

Source

pub fn group_sum<K: Value, R: Value>( self, ) -> Result<Aggregate<Vec<GroupValue<K, R>>>, Error>

Sum one integer or Decimal operand per exact grouping record, retaining absent keys and all-absent groups. R selects the same explicit result widening as sum. Group predicates use R’s result type; e.g. Nat128 totals require u128 operands. Complete every group before filtering, ordering and output limits.

§Errors

Scalar sum shape/range errors and grouped query work/state/output bounds apply. Overflow in any group refuses the whole query, even if that group would be filtered out or fall beyond the output limit. Finalization is bounded to 32 groups and charged to the retained-state byte cap.

§Panics

Supplier corruption traps without repair.

Source

pub fn avg<R: Value>(self) -> Result<Aggregate<Option<R>>, Error>

Average an integer or Decimal field (including a scalar newtype) into a single-field Decimal record. Preserve the field name and optionality; the result declares scale 0–28. Ignore absent operands, returning None for empty/all-absent input. Divide the exact total by the present count once, rounding to nearest with ties to even at the result scale. No floating-point conversion or scale fallback.

§Errors

Refuses nonnumeric inputs, non-Decimal results, changed optionality, cursors, DISTINCT, input ordering and group modifiers. Work exhaustion returns Limit; an unrepresentable rounded coefficient returns ArithmeticOverflow. Output-byte bounds match Self::sum. No partial average is returned.

§Panics

Supplier corruption traps without repair.

Source

pub fn group_avg<K: Value, R: Value>( self, ) -> Result<Aggregate<Vec<GroupValue<K, R>>>, Error>

Average per group using Self::avg’s Decimal scale and rounding contract. Finalize all groups before filtering, ordering and output limits; these operations compare the rounded Decimal results. Retain all-absent groups.

§Errors

Scalar average admission/range errors and grouped work/state/output bounds apply. Overflow in an excluded group still refuses the whole query.

§Panics

Supplier corruption traps without repair.

Source§

impl<'a, E: Entity, M: Memory> Query<'a, E, M>

Source

pub fn group_page(self, size: usize, after: Option<&'a GroupCursor>) -> Self

Page completed retained groups, returning at most 1..=32 rows per response. limit still caps the complete selected result and binds the job. Page size and byte allowance may change. Supply None for the first page; continuation is valid only for a completed job. Only grouped resume terminals accept this.

Source

pub fn filter_groups( self, comparison: Comparison, value: impl Into<IndexValue<'a>>, ) -> Self

Add an AND predicate on the completed aggregate value, before group ordering and output limits. At most eight terms. Counts require Nat64 operands; extrema require the source type; sums require the declared result type. Absent values support Eq/Ne only. Text extrema also accept StartsWith, EndsWith and Contains; Blob extrema accept StartsWith and EndsWith. Only grouped terminals accept this modifier, even for empty input.

Source

pub fn filter_groups_any( self, alternatives: &[(Comparison, IndexValue<'a>)], ) -> Self

Add an OR clause on completed aggregate values, ANDed with other group filters. The clause must be nonempty; all group filters together permit eight comparisons. Every operand is admitted before reading any rows. Uses filter_groups’ exact type and absence rules. All groups must finish and validate before selection, ordering and output limits. Clause boundaries bind retained jobs; a singleton clause is equivalent to filter_groups.

Source

pub fn order_groups(self, order: GroupOrder) -> Self

Order completed groups before applying output limits. Only grouped terminals accept this modifier. The last call selects the order.

Source

pub fn min<R: Value>(self) -> Result<Aggregate<Option<R>>, Error>

Minimum present value of an exact single-field record projection. Supports ordered scalars/unit enums without requiring an index. The result preserves the declared type and optionality; empty/all-absent input returns None. limit never truncates input. Only the winning record’s bytes count toward byte_limit; an absent result occupies zero payload bytes.

§Errors

Refuses multi-field projections, unsupported types, cursors, DISTINCT and explicit ordering. Work exhaustion or a comparison key beyond 4096 bytes returns Limit; an oversized winning result returns RowTooLarge. Ordinary projection/query errors apply. Completion must precede work_limit.

§Panics

Supplier corruption traps without repair.

Source

pub fn max<R: Value>(self) -> Result<Aggregate<Option<R>>, Error>

Maximum present value, with the same types, bounds and empty-input behavior as Self::min. Equal operands retain the first encountered value.

§Errors

The same projection, resource and query errors as Self::min.

§Panics

Supplier corruption traps without repair.

Source

pub fn group_min<K: Value, R: Value>( self, ) -> Result<Aggregate<Vec<GroupValue<K, R>>>, Error>

Minimum present operand per group. K is an exact grouping record; R is an exact single-field operand record. They may overlap. All-absent groups retain None; empty input yields no groups. No index is required. Groups default to ascending canonical field-name tuple order; filter_groups and order_groups select completed results. limit selects completed groups, never input rows. Output bytes are the key record plus the present winning record; transport option framing is excluded. At most 32 groups and 128 KiB of retained keys, records and reducer payloads are admitted. Every comparison key is bounded to 4096 bytes. Winner growth is charged, and replacement releases the previous winner’s charge.

§Errors

The projection, work and shape refusals of Self::min apply. Group or retained-state exhaustion returns Limit. An oversized output group returns RowTooLarge; combined output exhaustion returns Limit.

§Panics

Supplier corruption traps without repair.

Source

pub fn group_max<K: Value, R: Value>( self, ) -> Result<Aggregate<Vec<GroupValue<K, R>>>, Error>

Maximum present operand per group, with the contract of Self::group_min.

§Errors

The same projection, work, state, shape and output refusals as grouped minimum.

§Panics

Supplier corruption traps without repair.

Source

pub fn exists(self) -> Result<Aggregate<bool>, Error>

Whether at least one row matches, without materializing an entity. Stops after validating the first matching row; later rows are not inspected. Returns false only after observing the end of the selected input. limit does not truncate input. The boolean result occupies one byte.

§Errors

Refuses cursors, DISTINCT, explicit ordering and group modifiers, as for count. Exhausting work_limit without a match returns Limit, never false; an exact-boundary no-match scan can conservatively refuse. Ordinary admission and examined-row integrity errors still apply.

§Panics

Supplier corruption traps without repair, as for ordinary query execution.

Source

pub fn count(self) -> Result<Aggregate<u64>, Error>

Count all matching rows in one synchronous execution. Empty input yields zero. limit does not limit input; the scalar output occupies eight bytes. Completion must be observed before work_limit is reached; an exact-boundary scan can conservatively refuse. Use start_count/resume_count for retained work.

§Errors

Refuses cursors, DISTINCT, explicit ordering and the ordinary query failures. Work exhaustion returns Limit, never a partial count. Too few output bytes returns RowTooLarge.

§Panics

Supplier corruption traps without repair, as for ordinary query execution.

Source

pub fn count_index_entries(self) -> Result<Aggregate<u64>, Error>

Count physical entries in the range selected by using_index and its leading operands. This reads neither index values nor owner rows. A dangling index entry counts as one. Use Self::count to validate rows. Like other scalar counts, the row limit does not truncate the input.

§Errors

Requires an explicit index. Row predicates, ordering, cursors, grouping and DISTINCT refuse. Reaching the work limit before observing completion returns Limit; fewer than eight output bytes returns RowTooLarge.

§Panics

Malformed supplier storage can trap during traversal.

Source

pub fn count_field(self, field: &str) -> Result<Aggregate<u64>, Error>

Count present values of a top-level field, including non-scalar fields. Empty input and all-absent input yield zero; present empty values count. Limits, refusals and corruption traps are the same as Self::count.

§Errors

Unknown fields refuse even for empty input. Ordinary count errors apply.

§Panics

Supplier corruption traps without repair.

Source

pub fn count_distinct<K: Value>(self) -> Result<Aggregate<u64>, Error>

Count distinct projected tuples, including absent values, without an index. Retain at most 32 distinct comparison keys, each at most 4096 bytes, within the shared 128-KiB state bound. No projected records are retained. limit never truncates this count. The scalar result occupies eight bytes.

§Errors

Ordinary count/projection errors and distinct-state exhaustion refuse.

§Panics

Supplier corruption traps without repair.

Source

pub fn group_count<K: Value>( self, ) -> Result<Aggregate<Vec<GroupCount<K>>>, Error>

Count matching rows grouped by an exact named-record projection. Keys support ordered scalars/unit enums, including optional absence; no index is required. Results default to ascending tuple order in canonical field-name order. filter_groups and order_groups select completed results before output limits. limit selects the first completed groups (1..=32), never input rows. byte_limit bounds key-record bytes plus eight count bytes per group. Empty input yields no groups. At most 32 groups and 128 KiB of key/output state may be retained, independently of the requested output limit; each comparison key is capped at 4096 bytes, independently of index-key limits.

§Errors

Refuses unsupported key types, cursors, DISTINCT and explicit ordering. Work, group or retained-state exhaustion returns Limit, never partial groups. Completion must be observed before work_limit; a boundary scan can refuse. Ordinary projection/query integrity and byte-limit errors also apply.

§Panics

Supplier corruption traps without repair, as for ordinary query execution.

Source

pub fn group_count_field<K: Value>( self, field: &str, ) -> Result<Aggregate<Vec<GroupCount<K>>>, Error>

Count present operand values within each projected group. Groups whose operands are all absent remain in the output with count zero. The operand may be any top-level stored field and need not belong to the group key. Bounds and ordering are the same as Self::group_count.

§Errors

Unknown operands and ordinary grouped-count errors refuse.

§Panics

Supplier corruption traps without repair.

Source

pub fn group_count_distinct<K: Value, R: Value>( self, ) -> Result<Aggregate<Vec<GroupCount<K>>>, Error>

Count distinct projected R tuples within each projected K group. Absence is a tuple component, as for Self::count_distinct; an all-absent group has one distinct tuple, not zero. Projections may overlap. No index is required. Complete input before group filtering/order and output limits. Retain at most 32 groups and 32 distinct tuples per group, with one shared 128-KiB state allowance and a 4096-byte cap per comparison key.

§Errors

Refuses unsupported projections, cursors, DISTINCT and explicit input order. Work, cardinality or byte exhaustion returns Limit, never partial counts. Ordinary grouped-count output and integrity errors apply.

§Panics

Supplier corruption traps without repair.

Source§

impl<'a, E: Entity, M: Memory> Query<'a, E, M>

Source

pub fn distinct(self) -> Self

Remove duplicate output records. Proven leading index tuples use live pages; identity projections need no duplicate tracking. Other projections scan to completion in one call, retaining at most 32 tuples within 128 KiB. That fallback preserves first-match traversal order, refuses cursors and returns Limit if work, result count or combined bytes cannot fit; it never returns a partial result. An individually oversized row returns RowTooLarge. Comparison keys are bounded to 4096 bytes. Non-identity sorted DISTINCT retains at most 32 distinct tuples. Its order must cover exactly the projected fields (unless the result is inherently unique); remove duplicates before applying limit and output bytes.

Source

pub fn filter( self, field: &'a str, comparison: Comparison, value: impl Into<IndexValue<'a>>, ) -> Self

Add an AND term over an exact top-level ordered scalar/unit-enum field. Eq/Ne with IndexValue::Absent also accept any optional stored field, including blobs and containers. Empty values are present, not absent. All operands are admitted before storage reads, including contradictory terms. On a primary traversal, mandatory Eq/Lt/Le/Gt/Ge primary-key comparisons narrow the scanned range. On an index path, those comparisons can narrow its first field after the admitted fixed prefix. Only examined rows undergo integrity checks; oversized derived bounds remain residual filters. Indexed StartsWith can seek that field’s exact encoded Text/Blob prefix too.

Source

pub fn filter_between( self, field: &'a str, lower: impl Into<IndexValue<'a>>, upper: impl Into<IndexValue<'a>>, ) -> Self

Match a present field inside an inclusive range, ANDed with other filters. Equivalent to filter(field, Comparison::Ge, lower) followed by filter(field, Comparison::Le, upper), including cursor/job identity. Both exact operands are admitted and consume two of the eight comparisons. Absent operands refuse; absent fields never match. Reversed bounds produce no matches, without skipping admission of either operand or other filters.

Source

pub fn filter_not_between( self, field: &'a str, lower: impl Into<IndexValue<'a>>, upper: impl Into<IndexValue<'a>>, ) -> Self

Match a present field strictly outside an inclusive range. Equivalent to one filter_any clause containing Lt lower then Gt upper, including cursor/job identity. Both exact operands consume filter terms. Absent operands refuse and absent fields never match; this is not a general negation of filter_between. Equal bounds exclude that value; reversed bounds match every present value, once. Uses the existing single traversal and work budget, without seeking separate ranges for the two alternatives.

Source

pub fn filter_any( self, alternatives: &[(&'a str, Comparison, IndexValue<'a>)], ) -> Self

Add an OR clause of exact top-level comparisons, ANDed with other filters. Each clause must contain at least one comparison; all filters together may contain at most eight. Empty/oversized clauses refuse with Error::Limit at execution. Every operand is admitted, even if another alternative matches. Uses one ordered traversal, without union scans or duplicate rows. Alternatives do not establish fixed index prefixes; a one-term clause behaves like filter.

Source

pub fn filter_in(self, field: &'a str, values: &[IndexValue<'a>]) -> Self

Match a field against any supplied exact value, ANDed with other filters. Equivalent to filter_any with equality comparisons in the supplied order. Absence matches only an explicit IndexValue::Absent member on an optional field. Repeated members never repeat rows, but each counts toward the shared eight-comparison limit. Empty or oversized lists refuse with Error::Limit. Every member is admitted before reading; there is no coercion, sorting or deduplication of operands. Reordering members changes cursor/job identity.

Source

pub fn filter_not_in(self, field: &'a str, values: &[IndexValue<'a>]) -> Self

Exclude every supplied exact value, ANDed with other filters. Equivalent to consecutive filter(field, Comparison::Ne, value) calls in the supplied order. Absent fields match unless absence is explicitly excluded. Empty lists refuse; all members, including duplicates, count toward the shared eight-comparison budget. Every operand is admitted. The equivalent inequality chain shares cursor/job identity; reordering the list changes that identity. No coercion or deduplication is performed.

Source

pub fn using_index(self, name: &'a str, values: &[IndexValue<'a>]) -> Self

Select index order and exact leading components (at most four). All rows matching this prefix are considered. Sparse indexes require every optional indexed component to be proven present by the prefix or filters. Every alternative in a proving OR clause must reject absence.

Source

pub fn order_by(self, fields: &[&'a str]) -> Self

Order by 1..=4 distinct top-level ordered fields, then the primary key. An explicitly listed primary key must be last. All fields share one direction, reversed by descending. Prefer a complete ordered path. Otherwise scan to completion while retaining the best limit rows within 128 KiB of key/output buffers, then sort them. Non-identity DISTINCT retains at most 32 distinct tuples before output selection. Work exhaustion refuses; no cursor is supported by this fallback. DISTINCT requires an identity result or an order covering exactly the projected fields. Equality terms may fix leading index components. With using_index, require that path’s order.

Source

pub fn order_by_each(self, fields: &[(&'a str, SortDirection)]) -> Self

Replace the order with 1..=4 fields and their individual directions. An explicit primary key must be last; otherwise append it ascending. descending() reverses every direction, including that tie-breaker. The same path proof and complete-sort bounds as order_by apply.

Source

pub fn descending(self) -> Self

Reverse the complete result order, including its unique tie-breaker.

Source

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

Return at most 1..=32 matching rows in this page. Complete-collection DISTINCT refuses if the full result exceeds this cap. Complete sorting applies this cap after examining the entire input; it never relaxes the separate 32-matching-row retention bound. For grouped aggregates, cap the complete selected result instead; use group_page to set a retained grouped response’s page size separately.

Source

pub fn work_limit(self, candidates: usize) -> Self

Examine at most 1..=512 candidates, independently of the returned row limit.

Source

pub fn byte_limit(self, bytes: usize) -> Self

Allow 1..=131072 encoded result-row bytes. Transport framing is host-owned.

Source

pub fn after(self, cursor: &'a QueryCursor) -> Self

Continue this query; page resource limits may change between calls.

Source

pub fn fetch(self) -> Result<QueryPage<E>, Error>

Admit and execute one page, then decode only its matching output rows.

§Errors

Refuses unsupported shapes, inexact operands, limits, invalid cursors and corruption. A selected output row larger than the whole byte allowance returns RowTooLarge.

§Panics

Supplier corruption traps without repair, as for direct record reads.

Source

pub fn fetch_as<R: Value>(self) -> Result<QueryPage<R>, Error>

Project matching top-level fields into an existing #[record] type. Names, optionality and complete value definitions must match exactly. The record is an output shape, not a new stored entity or schema entry. Byte limits count projected bytes; all source fields still undergo validation.

§Errors

Refuses non-record/empty or incompatible output shapes, and the same failures as fetch. A continuation must use the same selected field shape.

§Panics

Supplier corruption traps without repair, as for direct record reads.

Auto Trait Implementations§

§

impl<'a, E, M = Rc<RefCell<Vec<u8>>>> !RefUnwindSafe for Query<'a, E, M>

§

impl<'a, E, M = Rc<RefCell<Vec<u8>>>> !Send for Query<'a, E, M>

§

impl<'a, E, M = Rc<RefCell<Vec<u8>>>> !Sync for Query<'a, E, M>

§

impl<'a, E, M = Rc<RefCell<Vec<u8>>>> !UnwindSafe for Query<'a, E, M>

§

impl<'a, E, M> Forget for Query<'a, E, M>

§

impl<'a, E, M> Freeze for Query<'a, E, M>
where &'a Database<M>: Freeze, PhantomData<E>: Freeze,

§

impl<'a, E, M> Move for Query<'a, E, M>

§

impl<'a, E, M> Unpin for Query<'a, E, M>
where &'a Database<M>: Unpin, PhantomData<E>: Unpin,

§

impl<'a, E, M> UnsafeUnpin for Query<'a, E, M>

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> Same for T

Source§

type Output = T

Should always be Self
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.