pub struct Query<'a, E, M: Memory> { /* 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>
impl<E: Entity, M: Memory> Query<'_, E, M>
Sourcepub fn start_count_distinct<K: Value>(
self,
jobs: &mut AggregateJobs<M>,
now: Timestamp,
expires: Timestamp,
) -> Result<JobHandle, Error>
pub fn start_count_distinct<K: Value>( self, jobs: &mut AggregateJobs<M>, 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.
Sourcepub fn resume_count_distinct<K: Value>(
self,
jobs: &mut AggregateJobs<M>,
handle: &JobHandle,
sequence: u64,
now: Timestamp,
) -> Result<JobStep<u64>, Error>
pub fn resume_count_distinct<K: Value>( self, jobs: &mut AggregateJobs<M>, 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.
Sourcepub fn start_group_count_distinct<K: Value, R: Value>(
self,
jobs: &mut AggregateJobs<M>,
now: Timestamp,
expires: Timestamp,
) -> Result<JobHandle, Error>
pub fn start_group_count_distinct<K: Value, R: Value>( self, jobs: &mut AggregateJobs<M>, 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.
Sourcepub fn resume_group_count_distinct<K: Value, R: Value>(
self,
jobs: &mut AggregateJobs<M>,
handle: &JobHandle,
sequence: u64,
now: Timestamp,
) -> Result<JobStep<GroupPage<GroupCount<K>>>, Error>
pub fn resume_group_count_distinct<K: Value, R: Value>( self, jobs: &mut AggregateJobs<M>, 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>
impl<E: Entity, M: Memory> Query<'_, E, M>
Sourcepub fn start_group_min<K: Value, R: Value>(
self,
jobs: &mut AggregateJobs<M>,
now: Timestamp,
expires: Timestamp,
) -> Result<JobHandle, Error>
pub fn start_group_min<K: Value, R: Value>( self, jobs: &mut AggregateJobs<M>, 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.
Sourcepub fn start_group_max<K: Value, R: Value>(
self,
jobs: &mut AggregateJobs<M>,
now: Timestamp,
expires: Timestamp,
) -> Result<JobHandle, Error>
pub fn start_group_max<K: Value, R: Value>( self, jobs: &mut AggregateJobs<M>, now: Timestamp, expires: Timestamp, ) -> Result<JobHandle, Error>
Sourcepub fn resume_group_min<K: Value, R: Value>(
self,
jobs: &mut AggregateJobs<M>,
handle: &JobHandle,
sequence: u64,
now: Timestamp,
) -> Result<JobStep<GroupPage<GroupValue<K, R>>>, Error>
pub fn resume_group_min<K: Value, R: Value>( self, jobs: &mut AggregateJobs<M>, 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.
Sourcepub fn resume_group_max<K: Value, R: Value>(
self,
jobs: &mut AggregateJobs<M>,
handle: &JobHandle,
sequence: u64,
now: Timestamp,
) -> Result<JobStep<GroupPage<GroupValue<K, R>>>, Error>
pub fn resume_group_max<K: Value, R: Value>( self, jobs: &mut AggregateJobs<M>, handle: &JobHandle, sequence: u64, now: Timestamp, ) -> Result<JobStep<GroupPage<GroupValue<K, R>>>, Error>
Sourcepub fn start_min<R: Value>(
self,
jobs: &mut AggregateJobs<M>,
now: Timestamp,
expires: Timestamp,
) -> Result<JobHandle, Error>
pub fn start_min<R: Value>( self, jobs: &mut AggregateJobs<M>, 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.
Sourcepub fn start_max<R: Value>(
self,
jobs: &mut AggregateJobs<M>,
now: Timestamp,
expires: Timestamp,
) -> Result<JobHandle, Error>
pub fn start_max<R: Value>( self, jobs: &mut AggregateJobs<M>, now: Timestamp, expires: Timestamp, ) -> Result<JobHandle, Error>
Sourcepub fn resume_min<R: Value>(
self,
jobs: &mut AggregateJobs<M>,
handle: &JobHandle,
sequence: u64,
now: Timestamp,
) -> Result<JobStep<Option<R>>, Error>
pub fn resume_min<R: Value>( self, jobs: &mut AggregateJobs<M>, 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§impl<E: Entity, M: Memory> Query<'_, E, M>
impl<E: Entity, M: Memory> Query<'_, E, M>
Sourcepub fn start_group_count<K: Value>(
self,
jobs: &mut AggregateJobs<M>,
now: Timestamp,
expires: Timestamp,
) -> Result<JobHandle, Error>
pub fn start_group_count<K: Value>( self, jobs: &mut AggregateJobs<M>, 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.
Sourcepub fn start_group_count_field<K: Value>(
self,
field: &str,
jobs: &mut AggregateJobs<M>,
now: Timestamp,
expires: Timestamp,
) -> Result<JobHandle, Error>
pub fn start_group_count_field<K: Value>( self, field: &str, jobs: &mut AggregateJobs<M>, 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.
Sourcepub fn resume_group_count<K: Value>(
self,
jobs: &mut AggregateJobs<M>,
handle: &JobHandle,
sequence: u64,
now: Timestamp,
) -> Result<JobStep<GroupPage<GroupCount<K>>>, Error>
pub fn resume_group_count<K: Value>( self, jobs: &mut AggregateJobs<M>, 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.
Sourcepub fn resume_group_count_field<K: Value>(
self,
field: &str,
jobs: &mut AggregateJobs<M>,
handle: &JobHandle,
sequence: u64,
now: Timestamp,
) -> Result<JobStep<GroupPage<GroupCount<K>>>, Error>
pub fn resume_group_count_field<K: Value>( self, field: &str, jobs: &mut AggregateJobs<M>, 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.
Sourcepub fn start_group_sum<K: Value, R: Value>(
self,
jobs: &mut AggregateJobs<M>,
now: Timestamp,
expires: Timestamp,
) -> Result<JobHandle, Error>
pub fn start_group_sum<K: Value, R: Value>( self, jobs: &mut AggregateJobs<M>, 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.
Sourcepub fn resume_group_sum<K: Value, R: Value>(
self,
jobs: &mut AggregateJobs<M>,
handle: &JobHandle,
sequence: u64,
now: Timestamp,
) -> Result<JobStep<GroupPage<GroupValue<K, R>>>, Error>
pub fn resume_group_sum<K: Value, R: Value>( self, jobs: &mut AggregateJobs<M>, 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.
Sourcepub fn start_group_avg<K: Value, R: Value>(
self,
jobs: &mut AggregateJobs<M>,
now: Timestamp,
expires: Timestamp,
) -> Result<JobHandle, Error>
pub fn start_group_avg<K: Value, R: Value>( self, jobs: &mut AggregateJobs<M>, 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.
Sourcepub fn resume_group_avg<K: Value, R: Value>(
self,
jobs: &mut AggregateJobs<M>,
handle: &JobHandle,
sequence: u64,
now: Timestamp,
) -> Result<JobStep<GroupPage<GroupValue<K, R>>>, Error>
pub fn resume_group_avg<K: Value, R: Value>( self, jobs: &mut AggregateJobs<M>, 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>
impl<E: Entity, M: Memory> Query<'_, E, M>
Sourcepub fn start_count(
self,
jobs: &mut AggregateJobs<M>,
now: Timestamp,
expires: Timestamp,
) -> Result<JobHandle, Error>
pub fn start_count( self, jobs: &mut AggregateJobs<M>, 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 the per-call work limit 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.
Sourcepub fn start_count_field(
self,
field: &str,
jobs: &mut AggregateJobs<M>,
now: Timestamp,
expires: Timestamp,
) -> Result<JobHandle, Error>
pub fn start_count_field( self, field: &str, jobs: &mut AggregateJobs<M>, 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.
Sourcepub fn resume_count(
self,
jobs: &mut AggregateJobs<M>,
handle: &JobHandle,
sequence: u64,
now: Timestamp,
) -> Result<JobStep<u64>, Error>
pub fn resume_count( self, jobs: &mut AggregateJobs<M>, 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.
Sourcepub fn resume_count_field(
self,
field: &str,
jobs: &mut AggregateJobs<M>,
handle: &JobHandle,
sequence: u64,
now: Timestamp,
) -> Result<JobStep<u64>, Error>
pub fn resume_count_field( self, field: &str, jobs: &mut AggregateJobs<M>, handle: &JobHandle, sequence: u64, now: Timestamp, ) -> Result<JobStep<u64>, Error>
Sourcepub fn start_sum<R: Value>(
self,
jobs: &mut AggregateJobs<M>,
now: Timestamp,
expires: Timestamp,
) -> Result<JobHandle, Error>
pub fn start_sum<R: Value>( self, jobs: &mut AggregateJobs<M>, 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.
Sourcepub fn resume_sum<R: Value>(
self,
jobs: &mut AggregateJobs<M>,
handle: &JobHandle,
sequence: u64,
now: Timestamp,
) -> Result<JobStep<Option<R>>, Error>
pub fn resume_sum<R: Value>( self, jobs: &mut AggregateJobs<M>, 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.
Sourcepub fn start_avg<R: Value>(
self,
jobs: &mut AggregateJobs<M>,
now: Timestamp,
expires: Timestamp,
) -> Result<JobHandle, Error>
pub fn start_avg<R: Value>( self, jobs: &mut AggregateJobs<M>, 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.
Sourcepub fn resume_avg<R: Value>(
self,
jobs: &mut AggregateJobs<M>,
handle: &JobHandle,
sequence: u64,
now: Timestamp,
) -> Result<JobStep<Option<R>>, Error>
pub fn resume_avg<R: Value>( self, jobs: &mut AggregateJobs<M>, 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>
impl<E: Entity, M: Memory> Query<'_, E, M>
Sourcepub fn sum<R: Value>(self) -> Result<Aggregate<Option<R>>, Error>
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 may preserve the exact input newtype. A primitive integer result may widen 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.
Sourcepub fn group_sum<K: Value, R: Value>(
self,
) -> Result<Aggregate<Vec<GroupValue<K, R>>>, Error>
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.
Sourcepub fn avg<R: Value>(self) -> Result<Aggregate<Option<R>>, Error>
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. A primitive Decimal selects scale 0–28;
a Decimal newtype result preserves the exact input newtype and its scale.
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.
Sourcepub fn group_avg<K: Value, R: Value>(
self,
) -> Result<Aggregate<Vec<GroupValue<K, R>>>, Error>
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>
impl<'a, E: Entity, M: Memory> Query<'a, E, M>
Sourcepub fn group_page(self, size: usize, after: Option<&'a GroupCursor>) -> Self
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.
Sourcepub fn filter_groups(
self,
comparison: Comparison,
value: impl Into<IndexValue<'a>>,
) -> Self
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 and Blob extrema also accept StartsWith, EndsWith and Contains. Only grouped terminals accept this modifier, even for empty input.
Sourcepub fn filter_groups_any(
self,
alternatives: &[(Comparison, IndexValue<'a>)],
) -> Self
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.
Sourcepub fn order_groups(self, order: GroupOrder) -> Self
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.
Sourcepub fn min<R: Value>(self) -> Result<Aggregate<Option<R>>, Error>
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 the engine output bound; 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.
Sourcepub fn group_min<K: Value, R: Value>(
self,
) -> Result<Aggregate<Vec<GroupValue<K, R>>>, Error>
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.
Sourcepub fn group_max<K: Value, R: Value>(
self,
) -> Result<Aggregate<Vec<GroupValue<K, R>>>, Error>
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.
Sourcepub fn exists(self) -> Result<Aggregate<bool>, Error>
pub fn exists(self) -> Result<Aggregate<bool>, Error>
Whether at least one row matches, without materializing an entity.
Can seek a mandatory equality prefix and evaluate remaining filters on its owner rows.
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.
Sourcepub fn count(self) -> Result<Aggregate<u64>, Error>
pub fn count(self) -> Result<Aggregate<u64>, Error>
Count all matching rows in one synchronous execution. Empty input yields zero.
Uses maintained cardinality for unfiltered input and physical index keys for
fully covered index ranges or primary-key comparison ranges. A partially covered
equality prefix narrows the owner rows checked by the remaining predicates. Use
Self::count_validated to check each visited row and selected index owner.
limit does not limit input; the scalar output occupies eight bytes.
Completion must be established within work_limit; 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.
Sourcepub fn count_validated(self) -> Result<Aggregate<u64>, Error>
pub fn count_validated(self) -> Result<Aggregate<u64>, Error>
Count by validating each visited row, including its selected index entry.
§Errors
Returns the same admission and resource errors as Self::count, and
reports corruption encountered during traversal.
Sourcepub fn count_index_entries(self) -> Result<Aggregate<u64>, Error>
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_validated 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.
Sourcepub fn count_field(self, field: &str) -> Result<Aggregate<u64>, Error>
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.
Sourcepub fn count_distinct<K: Value>(self) -> Result<Aggregate<u64>, Error>
pub fn count_distinct<K: Value>(self) -> Result<Aggregate<u64>, Error>
Count distinct projected tuples, including absent values. An indexed filter can narrow the input.
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.
Sourcepub fn group_count<K: Value>(
self,
) -> Result<Aggregate<Vec<GroupCount<K>>>, Error>
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.
The engine output allowance 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 established within 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.
Sourcepub fn group_count_field<K: Value>(
self,
field: &str,
) -> Result<Aggregate<Vec<GroupCount<K>>>, Error>
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.
Sourcepub fn group_count_distinct<K: Value, R: Value>(
self,
) -> Result<Aggregate<Vec<GroupCount<K>>>, Error>
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>
impl<'a, E: Entity, M: Memory> Query<'a, E, M>
Sourcepub fn distinct(self) -> Self
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 the best limit distinct tuples. Its order
must lead with all varying projected fields. A mandatory literal equality
fixes a field. Remove duplicates before applying limit and output bytes.
Sourcepub fn filter(
self,
field: &'a str,
comparison: Comparison,
value: impl Into<IndexValue<'a>>,
) -> Self
pub fn filter( self, field: &'a str, comparison: Comparison, value: impl Into<IndexValue<'a>>, ) -> Self
Add an AND term over a top-level field. Lists and sets support exact scalar membership with Contains.
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.
Sourcepub fn filter_fields(
self,
left: &'a str,
comparison: Comparison,
right: &'a str,
) -> Self
pub fn filter_fields( self, left: &'a str, comparison: Comparison, right: &'a str, ) -> Self
Compare two top-level fields on the same row. Lists and sets support Contains with a present scalar field of the element type. Text and Blob also support StartsWith, EndsWith and Contains with a present right-hand field. Types must match; Text and Blob bounds may differ within their respective families. Two absent values are equal. An ordered comparison requires two present values.
Sourcepub fn filter_length(
self,
field: &'a str,
comparison: Comparison,
length: u32,
) -> Self
pub fn filter_length( self, field: &'a str, comparison: Comparison, length: u32, ) -> Self
Compare UTF-8 bytes for Text, raw bytes for Blob, or the item count for a list, set or map. Accepts Eq, Ne, Lt, Le, Gt and Ge. An absent field matches Ne only; use Gt(0) for a present, nonempty value.
Sourcepub fn filter_present(self, field: &'a str) -> Self
pub fn filter_present(self, field: &'a str) -> Self
Match rows whose optional field has a value, including an empty value.
Required and unknown fields return InvalidQuery at admission.
Sourcepub fn filter_absent(self, field: &'a str) -> Self
pub fn filter_absent(self, field: &'a str) -> Self
Match rows whose optional field has no value.
Required and unknown fields return InvalidQuery at admission.
Sourcepub fn filter_between(
self,
field: &'a str,
lower: impl Into<IndexValue<'a>>,
upper: impl Into<IndexValue<'a>>,
) -> Self
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.
Sourcepub fn filter_not_between(
self,
field: &'a str,
lower: impl Into<IndexValue<'a>>,
upper: impl Into<IndexValue<'a>>,
) -> Self
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.
Sourcepub fn filter_between_fields(
self,
field: &'a str,
lower: &'a str,
upper: &'a str,
) -> Self
pub fn filter_between_fields( self, field: &'a str, lower: &'a str, upper: &'a str, ) -> Self
Match lower <= field && field <= upper using three top-level fields of the row.
Both comparisons require present values of compatible types. Equal endpoints
are inclusive. Uses the same two comparison terms and continuation as the
equivalent chained filter_fields calls.
Sourcepub fn filter_not_between_fields(
self,
field: &'a str,
lower: &'a str,
upper: &'a str,
) -> Self
pub fn filter_not_between_fields( self, field: &'a str, lower: &'a str, upper: &'a str, ) -> Self
Match field < lower || field > upper using fields of the same row.
A missing bound makes only its own comparison false. A missing tested field
never matches. Uses one OR clause and the same two comparison terms and
continuation as the equivalent filter_any_operands call.
Sourcepub fn filter_any(
self,
alternatives: &[(&'a str, Comparison, IndexValue<'a>)],
) -> Self
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.
Sourcepub fn filter_any_operands(
self,
alternatives: &[(&'a str, Comparison, QueryOperand<'a>)],
) -> Self
pub fn filter_any_operands( self, alternatives: &[(&'a str, Comparison, QueryOperand<'a>)], ) -> Self
Add one OR clause of literal, field-to-field or length comparisons.
Each alternative follows its corresponding single-filter admission rules.
All alternatives share the eight-comparison budget with the other filters.
Literal-only clauses have the same cursor and job identity as filter_any.
Sourcepub fn filter_in(self, field: &'a str, values: &[IndexValue<'a>]) -> Self
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.
Sourcepub fn filter_not_in(self, field: &'a str, values: &[IndexValue<'a>]) -> Self
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.
Sourcepub fn using_index(self, name: &'a str, values: &[IndexValue<'a>]) -> Self
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.
Sourcepub fn order_by(self, fields: &[&'a str]) -> Self
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
the best limit distinct tuples. Work exhaustion refuses; no
cursor is supported by this fallback. DISTINCT requires an identity result
or an order led by all varying projected fields. Equality terms may fix
leading index components. With using_index, require that path’s order.
Sourcepub fn order_by_each(self, fields: &[(&'a str, SortDirection)]) -> Self
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.
Sourcepub fn descending(self) -> Self
pub fn descending(self) -> Self
Reverse the complete result order, including its unique tie-breaker.
Sourcepub fn limit(self, rows: usize) -> Self
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.
Sourcepub fn work_limit(self, candidates: usize) -> Self
pub fn work_limit(self, candidates: usize) -> Self
Examine at most 1..=512 candidates, independently of the returned row limit.
Sourcepub fn after(self, cursor: &'a QueryCursor) -> Self
pub fn after(self, cursor: &'a QueryCursor) -> Self
Continue this query; page resource limits may change between calls.
Sourcepub fn fetch(self) -> Result<QueryPage<E>, Error>
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.
Sourcepub fn fetch_as<R: Value>(self) -> Result<QueryPage<R>, Error>
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.