Skip to main content

ic_db/store/query/aggregate/jobs/
extrema.rs

1//! Retained extrema over the synchronous comparator and shared job lifecycle.
2use super::{Accumulator, AggregateJobs, JobHandle, JobStep, binding, start};
3use crate::{Entity, Error, GroupPage, GroupValue, Timestamp, Value, store::Query};
4use ic_storage::Memory;
5
6impl<E: Entity, M: Memory> Query<'_, E, M> {
7    /// Retain minima per exact key record, without scanning input. R selects one
8    /// exact ordered field, as in `group_min`; key and operand may overlap.
9    /// Retain all-absent groups with None. Keep at most 32 groups within the
10    /// complete 16 KiB job frame, including keys, winners and progress.
11    /// Group predicates, order and total limit bind the job. No automatic spill.
12    /// # Errors
13    /// Refuses unsupported shapes, page modifiers, expiry or occupied capacity.
14    /// # Panics
15    /// Supplier mutation failures trap the enclosing message.
16    pub fn start_group_min<K: Value, R: Value>(
17        self,
18        jobs: &mut AggregateJobs<M>,
19        now: Timestamp,
20        expires: Timestamp,
21    ) -> Result<JobHandle, Error> {
22        let admitted = self.group_extremum_plan::<K, R>(false)?;
23        self.start_group_value(jobs, now, expires, admitted)
24    }
25
26    /// Retain maxima per exact key record with `start_group_min`'s bounds.
27    /// Minimum and maximum have separate job identities.
28    /// # Errors
29    /// The same query, expiry and capacity errors as `start_group_min`.
30    /// # Panics
31    /// Supplier mutation failures trap the enclosing message.
32    pub fn start_group_max<K: Value, R: Value>(
33        self,
34        jobs: &mut AggregateJobs<M>,
35        now: Timestamp,
36        expires: Timestamp,
37    ) -> Result<JobHandle, Error> {
38        let admitted = self.group_extremum_plan::<K, R>(true)?;
39        self.start_group_value(jobs, now, expires, admitted)
40    }
41
42    /// Advance grouped minima with the retained revision, retry and expiry contract.
43    /// Finish all input before group filtering, ordering and limiting. Absent keys
44    /// form a group; all-absent operands yield None. Use `group_page` for completed
45    /// result pagination, retaining its continuation when mapping rows.
46    /// # Errors
47    /// Refuses mismatched queries/operations, corrupt winners, group/frame bounds
48    /// and oversized output without changing saved progress. Selection cannot
49    /// hide state exhaustion. No prefix winner is returned as an exact result.
50    /// # Panics
51    /// Supplier mutation failures trap the enclosing message.
52    pub fn resume_group_min<K: Value, R: Value>(
53        self,
54        jobs: &mut AggregateJobs<M>,
55        handle: &JobHandle,
56        sequence: u64,
57        now: Timestamp,
58    ) -> Result<JobStep<GroupPage<GroupValue<K, R>>>, Error> {
59        let admitted = self.group_extremum_plan::<K, R>(false)?;
60        self.resume_group_value(jobs, handle, sequence, now, admitted)
61    }
62
63    /// Advance grouped maxima with `resume_group_min`'s exactness and bounds.
64    /// Equal operands retain their first encountered value.
65    /// # Errors
66    /// The same query, checkpoint, resource and output errors as `resume_group_min`.
67    /// # Panics
68    /// Supplier mutation failures trap the enclosing message.
69    pub fn resume_group_max<K: Value, R: Value>(
70        self,
71        jobs: &mut AggregateJobs<M>,
72        handle: &JobHandle,
73        sequence: u64,
74        now: Timestamp,
75    ) -> Result<JobStep<GroupPage<GroupValue<K, R>>>, Error> {
76        let admitted = self.group_extremum_plan::<K, R>(true)?;
77        self.resume_group_value(jobs, handle, sequence, now, admitted)
78    }
79
80    /// Retain a minimum over one exact single-field result record, without scanning.
81    /// Uses `min`'s ordered types and absence semantics and `start_count`'s expiry,
82    /// revision and capacity bounds. Persist only the winning record, within the
83    /// complete 16 KiB job frame; no partial result or automatic spill.
84    /// # Errors
85    /// Refuses unsupported projections/query shapes, expiry or occupied capacity.
86    /// # Panics
87    /// Supplier mutation failures trap the enclosing message.
88    pub fn start_min<R: Value>(
89        self,
90        jobs: &mut AggregateJobs<M>,
91        now: Timestamp,
92        expires: Timestamp,
93    ) -> Result<JobHandle, Error> {
94        self.start_extremum::<R>(jobs, now, expires, false)
95    }
96
97    /// Retain a maximum with `start_min`'s types and bounds. Minimum and maximum
98    /// have distinct job identities, even when they select the same field.
99    /// # Errors
100    /// The same admission, expiry and capacity errors as `start_min`.
101    /// # Panics
102    /// Supplier mutation failures trap the enclosing message.
103    pub fn start_max<R: Value>(
104        self,
105        jobs: &mut AggregateJobs<M>,
106        now: Timestamp,
107        expires: Timestamp,
108    ) -> Result<JobHandle, Error> {
109        self.start_extremum::<R>(jobs, now, expires, true)
110    }
111
112    /// Advance a retained minimum with `resume_count`'s bounded work, retry,
113    /// revision and expiry contract. Ignore absent operands; empty/all-absent
114    /// input completes with None. Return the winning record only after exhaustion.
115    /// Equal values retain the first encountered value. A completed result stays
116    /// fixed after source writes, until expiry or cancellation.
117    /// # Errors
118    /// Refuses changed queries/operations, malformed winner bytes, work/state
119    /// bounds or oversized completed output. Refusal preserves the checkpoint.
120    /// A comparison key exceeding 4096 bytes refuses even for a losing candidate.
121    /// # Panics
122    /// Supplier mutation failures trap the enclosing message.
123    pub fn resume_min<R: Value>(
124        self,
125        jobs: &mut AggregateJobs<M>,
126        handle: &JobHandle,
127        sequence: u64,
128        now: Timestamp,
129    ) -> Result<JobStep<Option<R>>, Error> {
130        let (plan, reducer) = self.extremum_plan::<R>(false)?;
131        self.resume_value(jobs, handle, sequence, now, (plan, reducer))
132    }
133
134    /// Advance a retained maximum with `resume_min`'s exactness and bounds.
135    /// # Errors
136    /// The same query, resource and checkpoint errors as `resume_min`.
137    /// # Panics
138    /// Supplier mutation failures trap the enclosing message.
139    pub fn resume_max<R: Value>(
140        self,
141        jobs: &mut AggregateJobs<M>,
142        handle: &JobHandle,
143        sequence: u64,
144        now: Timestamp,
145    ) -> Result<JobStep<Option<R>>, Error> {
146        let (plan, reducer) = self.extremum_plan::<R>(true)?;
147        self.resume_value(jobs, handle, sequence, now, (plan, reducer))
148    }
149
150    fn start_extremum<R: Value>(
151        self,
152        jobs: &mut AggregateJobs<M>,
153        now: Timestamp,
154        expires: Timestamp,
155        maximum: bool,
156    ) -> Result<JobHandle, Error> {
157        let (plan, mut reducer) = self.extremum_plan::<R>(maximum)?;
158        start(
159            jobs,
160            binding(&plan, &reducer)?,
161            self.db.revision_by_id(E::SCHEMA.id)?,
162            now,
163            expires,
164            &Accumulator::Scalar(&mut reducer),
165        )
166    }
167}