Skip to main content

uqa_engine/
statistics.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Durable automatic-statistics scheduling, independent of query planning.
8
9mod 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    /// For changes a session keeps: a commit sequence at or after the last commit that made them, or `None` when its provider numbers no commits. An analysis that sampled at or after it has seen them.
36    through: Option<u64>,
37    /// Data generations a staged sample observed. The committing writer rechecks them after earlier publications, including writes whose counters stayed private.
38    sampled_generations: Option<SampledDataGenerations>,
39}
40
41pub(crate) type StatisticsChanges = BTreeMap<String, StatisticsChange>;
42
43/// What a commit did with the statistics changes of its transaction. The session takes it over once the commit has succeeded: a failed or undone commit leaves what the session kept as it was.
44#[derive(Clone, Default)]
45pub(crate) struct StatisticsSettlement {
46    /// Tables whose maintenance record the transaction wrote, with every change the session had kept of them.
47    recorded: Vec<String>,
48    /// Changes the session keeps to itself, including the ones it kept before.
49    kept: StatisticsChanges,
50}
51
52impl StatisticsSettlement {
53    /// Whether the transaction wrote a maintenance record, which the automatic statistics worker should see.
54    pub(crate) fn recorded(&self) -> bool {
55        !self.recorded.is_empty()
56    }
57}
58
59/// Process-local health of the database's automatic statistics worker.
60/// A failed refresh retains its durable pending state and is retried.
61#[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    /// Database-shared, process-local rebuild thresholds for future maintenance admissions.
99    pub fn diskann_rebuild_policy(&self) -> crate::DiskANNRebuildPolicy {
100        *self.statistics.diskann_policy.lock()
101    }
102
103    /// Revisit pending changes under this policy at the next maintenance poll. Current builds retain their admitted policy and resource limits; this setting is not persisted.
104    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    /// Write the maintenance records the changes of a committing transaction call for. A session keeps the changes that decide nothing ([`MaintenanceState::defers`]) to itself and records them with a later commit, where an analysis learns of every committed write from the table's data generation instead of from this record.
164    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        // A session keeps changes only where an analysis can do without the record: cache generations tell it of every committed write to what it sampled, and numbered commits tell the session which of its changes the analysis saw.
173        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            // DROP/recreate and rename cannot attach the old relation's
195            // pending maintenance to a different durable object.
196            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            // What the session kept counts unless an analysis has sampled the commits that made it.
220            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    /// Take over what a successful commit did with its statistics changes. The caller has left the transaction that committed them.
258    pub(crate) fn settle_statistics_changes(&self, settlement: StatisticsSettlement) {
259        // Read after the commit, so that it lies at or after every commit of the kept changes. A session that is still inside a transaction would read that transaction's earlier view.
260        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    /// The commit sequence an analysis that samples now reads at, for the record it writes. `None` where commits are not numbered, and in a transaction that reads its data at an earlier fixed snapshot than its storage view.
280    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    /// Keep a sample's observation in the same transaction/savepoint state as its staged statistics. Final commit rechecks it under writer preparation, rather than relying on the earlier publication decision.
308    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            // A child analysis covers its parent's pending changes only if the child commits. Preserve the parent entry across a child rollback.
334            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            // Session admission only retains the worker. Sending a liveness
361            // probe wakes its wait without advancing the maintenance deadline.
362            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                // Release every maintenance connection before the final
414                // client's drop returns. redb requires this for immediate
415                // reopen; SQLite requires it for final WAL checkpointing.
416                if worker.thread.join().is_err() {
417                    automatic.status.lock().last_error =
418                        Some("automatic statistics worker panicked".into());
419                }
420            }
421        }
422    }
423}