Skip to main content

uqa_execution/query/
diagnostics.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Invocation scopes and bounded records for actual native execution.
8
9use parking_lot::Mutex;
10use std::sync::Arc;
11use uqa_core::{
12    io_usage::{IOContext, IOObservation, IOOptions, IOUsage},
13    memory::{Budgeted, BudgetedString, BudgetedVec, MemoryError, MemoryReservation},
14    vector_execution::VectorSearchOperation,
15    VectorGeneration,
16};
17use uqa_operators::vector::diagnostics::VectorSearchObserver;
18use uqa_sql::{
19    result::vector::{ExplainVectorSearch, ExplainVectorSearches},
20    SQLError,
21};
22use uqa_storage::{
23    read_control::StorageReadControl, vector_index::VectorQueryResult, StorageBackendError,
24    StorageBackendResult,
25};
26
27pub(crate) mod executions;
28pub(crate) mod io;
29mod scope;
30pub use scope::{CapturedScope, InvocationRequest, QueryDiagnostics, RequestScope};
31
32pub type CapturedDiagnostics = Arc<Budgeted<InvocationDiagnostics>>;
33
34/// Existing vector observers use the same invocation owner.
35pub type VectorDiagnostics = InvocationDiagnostics;
36
37struct Records {
38    searches: ExplainVectorSearches,
39    failed: Option<Failure>,
40    closed: bool,
41    executions: Option<executions::Executions>,
42}
43
44#[derive(Clone, Copy)]
45enum Failure {
46    Memory,
47    Cancelled,
48    Closed,
49    ExecutionMemory,
50    Measurement,
51}
52
53impl Failure {
54    fn error(self) -> SQLError {
55        match self {
56            Self::Cancelled => uqa_core::QueryCancelled::USER_REQUEST.into(),
57            Self::Memory => SQLError::Routine {
58                sqlstate: "53200".into(),
59                message: "EXPLAIN could not retain complete vector execution diagnostics".into(),
60            },
61            Self::Closed => SQLError::Internal("vector diagnostics scope is closed".into()),
62            Self::ExecutionMemory => SQLError::Routine {
63                sqlstate: "53200".into(),
64                message: "EXPLAIN could not retain complete native execution diagnostics".into(),
65            },
66            Self::Measurement => SQLError::Internal(
67                "EXPLAIN native execution measurements could not be completed".into(),
68            ),
69        }
70    }
71}
72
73/// A captured invocation is shared by parallel work; it never samples a mutable current scope.
74pub struct InvocationDiagnostics {
75    control: StorageReadControl,
76    parent: Option<CapturedDiagnostics>,
77    io: Option<IOObservation>,
78    records: Mutex<Records>,
79}
80
81impl InvocationDiagnostics {
82    fn new(
83        control: StorageReadControl,
84        parent: Option<CapturedDiagnostics>,
85        timing: Option<bool>,
86        io_options: IOOptions,
87        io_timing: Arc<std::sync::atomic::AtomicBool>,
88    ) -> StorageBackendResult<CapturedDiagnostics> {
89        control.check()?;
90        let parent_io =
91            IOContext::for_observation(parent.as_ref().and_then(|parent| parent.io.as_ref()));
92        let io = if io_options.buffers || io_options.wal || parent_io.observation().is_some() {
93            Some(IOObservation::new(
94                control.memory(),
95                io_options,
96                io_timing,
97                parent_io.observation().cloned(),
98            )?)
99        } else {
100            None
101        };
102        let records = Mutex::new(Records {
103            searches: BudgetedVec::new(control.memory()),
104            failed: None,
105            closed: false,
106            executions: timing.map(|timing| executions::Executions::new(&control, timing)),
107        });
108        let memory = control.memory().empty_reservation();
109        Ok(Budgeted::new(
110            Self {
111                control,
112                parent,
113                io,
114                records,
115            },
116            memory,
117        )
118        .into_shared()?)
119    }
120
121    fn is_active(&self) -> bool {
122        !self.records.lock().closed
123    }
124
125    pub fn control(&self) -> &StorageReadControl {
126        &self.control
127    }
128
129    /// Bind only contexts that are about to execute inside this invocation.
130    pub fn observer(
131        collector: &CapturedDiagnostics,
132        relation: &str,
133    ) -> StorageBackendResult<Arc<dyn VectorSearchObserver>> {
134        let mut name = BudgetedString::new(collector.control.memory());
135        name.push_str(relation)?;
136        let value = BoundObserver {
137            collector: Arc::clone(collector),
138            relation: name,
139            _memory: collector
140                .control
141                .memory()
142                .reserve(std::mem::size_of::<BoundObserver>())?,
143        };
144        Ok(Arc::new(value))
145    }
146
147    pub fn record(
148        &self,
149        relation: &str,
150        field: &str,
151        operation: VectorSearchOperation,
152        result: &VectorQueryResult,
153    ) -> StorageBackendResult<()> {
154        let Some(stats) = result.diskann else {
155            return Ok(());
156        };
157        let recorded = (|| {
158            self.control.check()?;
159            let mut relation_name = BudgetedString::new(self.control.memory());
160            relation_name.push_str(relation)?;
161            let mut field_name = BudgetedString::new(self.control.memory());
162            field_name.push_str(field)?;
163            let generation = stats.generation;
164            let record = ExplainVectorSearch {
165                relation: relation_name,
166                field: field_name,
167                operation,
168                returned_documents: u64::try_from(result.postings.len())
169                    .map_err(|_| MemoryError::SizeOverflow)?,
170                generation: VectorGeneration {
171                    database: generation.database(),
172                    table: generation.table(),
173                    index: generation.index(),
174                    generation: generation.generation(),
175                },
176                route: stats.route,
177                traversal: stats.traversal,
178                work: stats.work,
179            };
180            let record =
181                Budgeted::new(record, self.control.memory().empty_reservation()).into_shared()?;
182            let mut current = Some(self);
183            while let Some(collector) = current {
184                collector.control.check()?;
185                let mut records = collector.records.lock();
186                if records.closed {
187                    return Err(StorageBackendError::Other(
188                        "vector diagnostics scope is closed".into(),
189                    ));
190                }
191                records.searches.push(Arc::clone(&record))?;
192                current = collector.parent.as_ref().map(|parent| &***parent);
193            }
194            Ok(())
195        })();
196        if let Err(error) = &recorded {
197            let failure = match error {
198                StorageBackendError::Cancelled(_) => Failure::Cancelled,
199                StorageBackendError::Memory(_) => Failure::Memory,
200                _ => Failure::Closed,
201            };
202            let mut current = Some(self);
203            while let Some(collector) = current {
204                let mut records = collector.records.lock();
205                if records.closed {
206                    break;
207                }
208                records.failed.get_or_insert(failure);
209                current = collector.parent.as_ref().map(|parent| &***parent);
210            }
211        }
212        recorded
213    }
214
215    fn finish(&self) -> Result<CapturedExecution, SQLError> {
216        let records = self.close();
217        self.control.cancellation().check()?;
218        if let Some(failure) = records.failed {
219            return Err(failure.error());
220        }
221        let nodes = records.executions.as_ref().map_or_else(
222            || Ok(BudgetedVec::new(self.control.memory())),
223            |nodes| nodes.snapshot(&self.control),
224        )?;
225        Ok(CapturedExecution {
226            io_timing: self.io.as_ref().is_some_and(IOObservation::timing_enabled),
227            io: self
228                .io
229                .as_ref()
230                .map_or(Ok(IOUsage::default()), IOObservation::finish)
231                .map_err(|_| Failure::Measurement.error())?,
232            vector_searches: records.searches,
233            nodes,
234        })
235    }
236
237    /// Closing transfers all retained records out of the collector. Worker captures keep only a closed owner, on success, error and unwind alike.
238    fn close(&self) -> Records {
239        let records = std::mem::replace(
240            &mut *self.records.lock(),
241            Records {
242                searches: BudgetedVec::new(self.control.memory()),
243                failed: None,
244                closed: true,
245                executions: None,
246            },
247        );
248        if let Some(io) = &self.io {
249            let _ = io.finish();
250        }
251        records
252    }
253}
254
255struct BoundObserver {
256    collector: CapturedDiagnostics,
257    relation: BudgetedString,
258    _memory: MemoryReservation,
259}
260
261impl VectorSearchObserver for BoundObserver {
262    fn control(&self) -> &StorageReadControl {
263        self.collector.control()
264    }
265    fn record(
266        &self,
267        field: &str,
268        operation: VectorSearchOperation,
269        result: &VectorQueryResult,
270    ) -> StorageBackendResult<()> {
271        self.collector
272            .record(&self.relation, field, operation, result)
273    }
274}
275
276pub struct CapturedExecution {
277    pub io: IOUsage,
278    pub io_timing: bool,
279    pub vector_searches: ExplainVectorSearches,
280    pub nodes: BudgetedVec<uqa_sql::result::explain::ExplainNodeExecution>,
281}
282
283/// The guard restores its caller's binding on success, SQL error and unwind.
284pub struct DiagnosticsScope {
285    _binding: CapturedScope,
286    collector: CapturedDiagnostics,
287}
288
289impl DiagnosticsScope {
290    pub fn finish_execution(self) -> Result<CapturedExecution, SQLError> {
291        self.collector.finish()
292    }
293
294    pub fn finish(self) -> Result<ExplainVectorSearches, SQLError> {
295        Ok(self.collector.finish()?.vector_searches)
296    }
297}
298
299impl Drop for DiagnosticsScope {
300    fn drop(&mut self) {
301        drop(self.collector.close());
302    }
303}
304
305#[cfg(test)]
306mod io_tests;
307#[cfg(test)]
308mod tests;