uqa_execution/query/
diagnostics.rs1use 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
57pub 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 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
212pub 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;