ic_db/store/query/aggregate/jobs/extrema.rs
1//! Retained extrema over the synchronous comparator and shared job lifecycle.
2use super::{AggregateJobs, JobHandle, JobStep, binding, start};
3use crate::{Entity, Error, GroupPage, GroupValue, Query, Timestamp, Value};
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<impl Memory>,
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<impl Memory>,
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<impl Memory>,
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<impl Memory>,
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<impl Memory>,
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<impl Memory>,
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<impl Memory>,
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<impl Memory>,
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<impl Memory>,
153 now: Timestamp,
154 expires: Timestamp,
155 maximum: bool,
156 ) -> Result<JobHandle, Error> {
157 let (plan, reducer) = self.extremum_plan::<R>(maximum)?;
158 start(
159 jobs,
160 binding(&plan, &reducer)?,
161 self.db.revision_by_id(E::ID)?,
162 now,
163 expires,
164 Vec::new(),
165 )
166 }
167}