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 vector execution.
8
9use parking_lot::Mutex;
10use std::sync::Arc;
11use uqa_core::{
12    memory::{Budgeted, BudgetedString, BudgetedVec, MemoryError, MemoryReservation},
13    vector_execution::VectorSearchOperation,
14    VectorGeneration,
15};
16use uqa_operators::vector::diagnostics::VectorSearchObserver;
17use uqa_sql::{
18    result::vector::{ExplainVectorSearch, ExplainVectorSearches},
19    SQLError,
20};
21use uqa_storage::{
22    read_control::StorageReadControl, vector_index::VectorQueryResult, StorageBackendError,
23    StorageBackendResult,
24};
25
26mod scope;
27pub use scope::{CapturedScope, InvocationRequest, QueryDiagnostics, RequestScope};
28
29pub type CapturedDiagnostics = Arc<Budgeted<VectorDiagnostics>>;
30
31struct Records {
32    searches: ExplainVectorSearches,
33    failed: Option<Failure>,
34    closed: bool,
35}
36
37#[derive(Clone, Copy)]
38enum Failure {
39    Memory,
40    Cancelled,
41    Closed,
42}
43
44impl Failure {
45    fn error(self) -> SQLError {
46        match self {
47            Self::Cancelled => uqa_core::QueryCancelled::USER_REQUEST.into(),
48            Self::Memory => SQLError::Routine {
49                sqlstate: "53200".into(),
50                message: "EXPLAIN could not retain complete vector execution diagnostics".into(),
51            },
52            Self::Closed => SQLError::Internal("vector diagnostics scope is closed".into()),
53        }
54    }
55}
56
57/// A captured invocation is shared by parallel work; it never samples a mutable current scope.
58pub struct VectorDiagnostics {
59    control: StorageReadControl,
60    parent: Option<CapturedDiagnostics>,
61    records: Mutex<Records>,
62}
63
64impl VectorDiagnostics {
65    fn new(
66        control: StorageReadControl,
67        parent: Option<CapturedDiagnostics>,
68    ) -> StorageBackendResult<CapturedDiagnostics> {
69        control.check()?;
70        let records = Mutex::new(Records {
71            searches: BudgetedVec::new(control.memory()),
72            failed: None,
73            closed: false,
74        });
75        let memory = control.memory().empty_reservation();
76        Ok(Budgeted::new(
77            Self {
78                control,
79                parent,
80                records,
81            },
82            memory,
83        )
84        .into_shared()?)
85    }
86
87    fn is_active(&self) -> bool {
88        !self.records.lock().closed
89    }
90
91    pub fn control(&self) -> &StorageReadControl {
92        &self.control
93    }
94
95    /// Bind only contexts that are about to execute inside this invocation.
96    pub fn observer(
97        collector: &CapturedDiagnostics,
98        relation: &str,
99    ) -> StorageBackendResult<Arc<dyn VectorSearchObserver>> {
100        let mut name = BudgetedString::new(collector.control.memory());
101        name.push_str(relation)?;
102        let value = BoundObserver {
103            collector: Arc::clone(collector),
104            relation: name,
105            _memory: collector
106                .control
107                .memory()
108                .reserve(std::mem::size_of::<BoundObserver>())?,
109        };
110        Ok(Arc::new(value))
111    }
112
113    pub fn record(
114        &self,
115        relation: &str,
116        field: &str,
117        operation: VectorSearchOperation,
118        result: &VectorQueryResult,
119    ) -> StorageBackendResult<()> {
120        let Some(stats) = result.diskann else {
121            return Ok(());
122        };
123        let recorded = (|| {
124            self.control.check()?;
125            let mut relation_name = BudgetedString::new(self.control.memory());
126            relation_name.push_str(relation)?;
127            let mut field_name = BudgetedString::new(self.control.memory());
128            field_name.push_str(field)?;
129            let generation = stats.generation;
130            let record = ExplainVectorSearch {
131                relation: relation_name,
132                field: field_name,
133                operation,
134                returned_documents: u64::try_from(result.postings.len())
135                    .map_err(|_| MemoryError::SizeOverflow)?,
136                generation: VectorGeneration {
137                    database: generation.database(),
138                    table: generation.table(),
139                    index: generation.index(),
140                    generation: generation.generation(),
141                },
142                route: stats.route,
143                traversal: stats.traversal,
144                work: stats.work,
145            };
146            let record =
147                Budgeted::new(record, self.control.memory().empty_reservation()).into_shared()?;
148            let mut current = Some(self);
149            while let Some(collector) = current {
150                collector.control.check()?;
151                let mut records = collector.records.lock();
152                if records.closed {
153                    return Err(StorageBackendError::Other(
154                        "vector diagnostics scope is closed".into(),
155                    ));
156                }
157                records.searches.push(Arc::clone(&record))?;
158                current = collector.parent.as_ref().map(|parent| &***parent);
159            }
160            Ok(())
161        })();
162        if let Err(error) = &recorded {
163            let failure = match error {
164                StorageBackendError::Cancelled(_) => Failure::Cancelled,
165                StorageBackendError::Memory(_) => Failure::Memory,
166                _ => Failure::Closed,
167            };
168            let mut current = Some(self);
169            while let Some(collector) = current {
170                collector.records.lock().failed.get_or_insert(failure);
171                current = collector.parent.as_ref().map(|parent| &***parent);
172            }
173        }
174        recorded
175    }
176
177    fn finish(&self) -> Result<ExplainVectorSearches, SQLError> {
178        self.control.cancellation().check()?;
179        let mut records = self.records.lock();
180        records.closed = true;
181        if let Some(failure) = records.failed {
182            return Err(failure.error());
183        }
184        Ok(std::mem::replace(
185            &mut records.searches,
186            BudgetedVec::new(self.control.memory()),
187        ))
188    }
189}
190
191struct BoundObserver {
192    collector: CapturedDiagnostics,
193    relation: BudgetedString,
194    _memory: MemoryReservation,
195}
196
197impl VectorSearchObserver for BoundObserver {
198    fn control(&self) -> &StorageReadControl {
199        self.collector.control()
200    }
201    fn record(
202        &self,
203        field: &str,
204        operation: VectorSearchOperation,
205        result: &VectorQueryResult,
206    ) -> StorageBackendResult<()> {
207        self.collector
208            .record(&self.relation, field, operation, result)
209    }
210}
211
212/// The guard restores its caller's binding on success, SQL error and unwind.
213pub struct DiagnosticsScope {
214    _binding: CapturedScope,
215    collector: CapturedDiagnostics,
216}
217
218impl DiagnosticsScope {
219    pub fn finish(self) -> Result<ExplainVectorSearches, SQLError> {
220        self.collector.finish()
221    }
222}
223
224impl Drop for DiagnosticsScope {
225    fn drop(&mut self) {
226        self.collector.records.lock().closed = true;
227    }
228}
229
230#[cfg(test)]
231mod tests;