1mod cache;
10mod coordinator;
11pub(crate) use coordinator::{shared_statistics, StatisticsCoordinator};
12pub(crate) mod value_size;
13mod worker;
14pub(crate) use cache::StatisticsSnapshots;
15
16use std::collections::BTreeMap;
17use std::sync::atomic::{AtomicUsize, Ordering};
18use std::sync::{mpsc, Arc};
19use std::time::{SystemTime, UNIX_EPOCH};
20
21use parking_lot::Mutex;
22use uqa_storage::StorageBackendResult;
23
24use crate::{Engine, TableState};
25
26pub(crate) use uqa_storage::statistics_maintenance::StatisticsMaintenance as MaintenanceState;
27
28type SampledDataGenerations = Arc<[(String, Option<u64>)]>;
29
30#[derive(Clone, Default)]
31pub(crate) struct StatisticsChange {
32 object_id: [u8; 16],
33 count: u64,
34 reset: bool,
35 through: Option<u64>,
37 sampled_generations: Option<SampledDataGenerations>,
39}
40
41pub(crate) type StatisticsChanges = BTreeMap<String, StatisticsChange>;
42
43#[derive(Clone, Default)]
45pub(crate) struct StatisticsSettlement {
46 recorded: Vec<String>,
48 kept: StatisticsChanges,
50}
51
52impl StatisticsSettlement {
53 pub(crate) fn recorded(&self) -> bool {
55 !self.recorded.is_empty()
56 }
57}
58
59#[derive(Clone, Debug, Default)]
62pub struct AutomaticStatisticsStatus {
63 pub running: bool,
64 pub completed: u64,
65 pub last_error: Option<String>,
66}
67
68#[derive(Default)]
69pub(crate) struct AutomaticStatistics {
70 clients: AtomicUsize,
71 control: Mutex<Option<StatisticsWorker>>,
72 status: Mutex<AutomaticStatisticsStatus>,
73}
74
75struct StatisticsWorker {
76 sender: mpsc::SyncSender<()>,
77 cancellation: uqa_core::CancellationToken,
78 thread: std::thread::JoinHandle<()>,
79}
80
81pub(crate) fn now_ms() -> u64 {
82 SystemTime::now()
83 .duration_since(UNIX_EPOCH)
84 .map_or(0, |duration| {
85 u64::try_from(duration.as_millis()).unwrap_or(u64::MAX)
86 })
87}
88
89impl Engine {
90 pub fn automatic_statistics_status(&self) -> AutomaticStatisticsStatus {
91 self.statistics.automatic_statistics.status.lock().clone()
92 }
93
94 pub fn automatic_diskann_maintenance_status(&self) -> crate::DiskANNMaintenanceStatus {
95 self.statistics.diskann.lock().clone()
96 }
97
98 pub fn diskann_rebuild_policy(&self) -> crate::DiskANNRebuildPolicy {
100 *self.statistics.diskann_policy.lock()
101 }
102
103 pub fn set_diskann_rebuild_policy(&self, policy: crate::DiskANNRebuildPolicy) {
105 *self.statistics.diskann_policy.lock() = policy;
106 self.start_automatic_statistics();
107 }
108
109 pub(crate) fn record_statistics_change(
110 &self,
111 name: &str,
112 table: &TableState,
113 count: u64,
114 ) -> StorageBackendResult<()> {
115 if self.storage.catalog.is_none()
116 || table.persistence == uqa_sql::ast::RelationPersistence::Temporary
117 {
118 let previous_rows = table
119 .column_stats
120 .read()
121 .values()
122 .next()
123 .map(|stats| stats.row_count);
124 return table.statistics_maintenance.lock().record_changes(
125 table.object_id(),
126 count,
127 previous_rows,
128 now_ms(),
129 );
130 }
131 let mut stack = self.session.transactions.lock();
132 if let Some(frame) = stack.last_mut() {
133 let change = frame.statistics_changes.entry(name.to_owned()).or_default();
134 if change.object_id != table.object_id() {
135 *change = StatisticsChange {
136 object_id: table.object_id(),
137 count: 0,
138 reset: false,
139 through: None,
140 sampled_generations: None,
141 };
142 }
143 change.count = change.count.saturating_add(count);
144 return Ok(());
145 }
146 drop(stack);
147 let changes = BTreeMap::from([(
148 name.to_owned(),
149 StatisticsChange {
150 object_id: table.object_id(),
151 count,
152 reset: false,
153 through: None,
154 sampled_generations: None,
155 },
156 )]);
157 let settlement = self.persist_statistics_changes(&changes)?;
158 self.settle_statistics_changes(settlement);
159 self.start_automatic_statistics();
160 Ok(())
161 }
162
163 pub(crate) fn persist_statistics_changes(
165 &self,
166 changes: &StatisticsChanges,
167 ) -> StorageBackendResult<StatisticsSettlement> {
168 let mut settlement = StatisticsSettlement::default();
169 let Some(catalog) = self.storage.catalog.as_deref() else {
170 return Ok(settlement);
171 };
172 let keeps = self.epochs.storage_cache_revisions.lock().is_some()
174 && self
175 .storage
176 .backend
177 .as_ref()
178 .is_some_and(|backend| backend.transaction_model().is_versioned());
179 let kept = self.session.kept_statistics.lock().clone();
180 let now = now_ms();
181 let revisions = if changes
182 .values()
183 .any(|change| change.sampled_generations.is_some())
184 {
185 catalog.cache_revisions()?
186 } else {
187 None
188 };
189 let tables = self.storage.tables.read();
190 for (name, change) in changes {
191 if change.count == 0 && change.sampled_generations.is_none() {
192 continue;
193 }
194 let Some(table) = tables.iter().find_map(|(relation, table)| {
197 (relation.qualified_name() == *name && table.object_id() == change.object_id)
198 .then_some(table)
199 }) else {
200 continue;
201 };
202 let mut state = MaintenanceState::load_for(catalog, name, change.object_id)?;
203 if let Some(sampled) = &change.sampled_generations {
204 let stale_sample = revisions.as_ref().is_none_or(|current| {
205 sampled.iter().any(|(member, generation)| {
206 current.table_data.get(member).copied() != *generation
207 })
208 });
209 if stale_sample && !state.dirty() {
210 state.record_changes(change.object_id, 1, None, now)?;
211 state.save(catalog, name)?;
212 table.column_stats_dirty.store(true, Ordering::Release);
213 settlement.recorded.push(name.clone());
214 }
215 if change.count == 0 {
216 continue;
217 }
218 }
219 let earlier = kept
221 .get(name)
222 .filter(|earlier| {
223 earlier.object_id == change.object_id && !state.covers(earlier.through)
224 })
225 .map_or(0, |earlier| earlier.count);
226 let count = earlier.saturating_add(change.count);
227 if keeps && state.defers(count, now) {
228 settlement.kept.insert(
229 name.clone(),
230 StatisticsChange {
231 object_id: change.object_id,
232 count,
233 reset: false,
234 through: None,
235 sampled_generations: None,
236 },
237 );
238 continue;
239 }
240 state.record_changes(
241 change.object_id,
242 count,
243 table
244 .column_stats
245 .read()
246 .values()
247 .next()
248 .map(|stats| stats.row_count),
249 now,
250 )?;
251 state.save(catalog, name)?;
252 settlement.recorded.push(name.clone());
253 }
254 Ok(settlement)
255 }
256
257 pub(crate) fn settle_statistics_changes(&self, settlement: StatisticsSettlement) {
259 let through = (!settlement.kept.is_empty())
261 .then(|| {
262 let backend = self.storage.backend.as_ref()?;
263 if backend.in_transaction() {
264 return None;
265 }
266 backend.change_version().ok()?
267 })
268 .flatten();
269 let mut kept = self.session.kept_statistics.lock();
270 for name in settlement.recorded {
271 kept.remove(&name);
272 }
273 kept.extend(settlement.kept.into_iter().map(|(name, mut change)| {
274 change.through = through;
275 (name, change)
276 }));
277 }
278
279 pub(crate) fn statistics_sample_sequence(&self) -> Option<u64> {
281 let backend = self.storage.backend.as_ref()?;
282 if !backend.transaction_model().is_versioned()
283 || self.current_transaction_uses_fixed_snapshot()
284 {
285 return None;
286 }
287 backend.change_version().ok().flatten()
288 }
289
290 pub(crate) fn merge_statistics_changes(
291 into: &mut StatisticsChanges,
292 changes: StatisticsChanges,
293 ) {
294 for (name, change) in changes {
295 let previous = into.entry(name).or_default();
296 if previous.object_id == change.object_id && !change.reset {
297 previous.count = previous.count.saturating_add(change.count);
298 if change.sampled_generations.is_some() {
299 previous.sampled_generations = change.sampled_generations;
300 }
301 } else {
302 *previous = change;
303 }
304 }
305 }
306
307 pub(crate) fn retain_statistics_sample(
309 &self,
310 name: &str,
311 object_id: [u8; 16],
312 generations: Option<Vec<(String, Option<u64>)>>,
313 ) {
314 let Some(generations) = generations else {
315 return;
316 };
317 let mut stack = self.session.transactions.lock();
318 let frame = stack
319 .last_mut()
320 .expect("statistics publication owns a transaction");
321 let change = frame.statistics_changes.entry(name.to_owned()).or_default();
322 if change.object_id != object_id {
323 *change = StatisticsChange {
324 object_id,
325 ..StatisticsChange::default()
326 };
327 }
328 change.sampled_generations = Some(generations.into());
329 }
330
331 pub(crate) fn clear_pending_statistics_changes(&self, name: &str, object_id: [u8; 16]) {
332 if let Some(frame) = self.session.transactions.lock().last_mut() {
333 frame.statistics_changes.insert(
335 name.to_owned(),
336 StatisticsChange {
337 object_id,
338 count: 0,
339 reset: true,
340 through: None,
341 sampled_generations: None,
342 },
343 );
344 }
345 }
346
347 pub(crate) fn start_automatic_statistics(&self) {
348 let Some(provider) = self.storage.provider.as_ref() else {
349 return;
350 };
351 if self.session.statistics_worker.load(Ordering::Acquire) {
352 return;
353 }
354 let automatic = &self.statistics.automatic_statistics;
355 if !self.session.statistics_client.swap(true, Ordering::AcqRel) {
356 automatic.clients.fetch_add(1, Ordering::AcqRel);
357 }
358 let mut control = automatic.control.lock();
359 if let Some(worker) = control.as_ref() {
360 if !worker.thread.is_finished() {
363 return;
364 }
365 *control = None;
366 }
367 let (requests, receiver) = mpsc::sync_channel(1);
368 let provider = Arc::downgrade(provider);
369 let manager = Arc::downgrade(&self.row_locks);
370 let statistics = Arc::downgrade(&self.statistics);
371 let cancellation = uqa_core::CancellationToken::new();
372 let worker_cancellation = cancellation.clone();
373 match std::thread::Builder::new()
374 .name("uqa-maintenance".into())
375 .spawn(move || {
376 worker::run(
377 &provider,
378 &manager,
379 &statistics,
380 &receiver,
381 &worker_cancellation,
382 );
383 }) {
384 Ok(thread) => {
385 *control = Some(StatisticsWorker {
386 sender: requests,
387 cancellation,
388 thread,
389 });
390 }
391 Err(error) => {
392 automatic.status.lock().last_error = Some(error.to_string());
393 }
394 }
395 }
396
397 pub(crate) fn release_automatic_statistics_client(&self) {
398 if self.session.statistics_client.swap(false, Ordering::AcqRel) {
399 let automatic = &self.statistics.automatic_statistics;
400 if automatic.clients.fetch_sub(1, Ordering::AcqRel) != 1 {
401 return;
402 }
403 let worker = {
404 let mut control = automatic.control.lock();
405 if automatic.clients.load(Ordering::Acquire) != 0 {
406 return;
407 }
408 control.take()
409 };
410 if let Some(worker) = worker {
411 worker.cancellation.cancel();
412 let _ = worker.sender.try_send(());
413 if worker.thread.join().is_err() {
417 automatic.status.lock().last_error =
418 Some("automatic statistics worker panicked".into());
419 }
420 }
421 }
422 }
423}