1mod changes;
10mod populations;
11mod pruning;
12mod publication;
13mod selection;
14
15use super::invalid;
16use crate::mvcc::native::{
17 decode_record, NativeRecordFamily as Family, NativeRecordIdentity as Identity,
18 NativeRecordOwner, NativeSnapshot,
19};
20use crate::vector_index::{encode_doc_id, native::records::Address, SQLiteVectorIndex};
21use rusqlite::types::ValueRef;
22use std::sync::Arc;
23use uqa_core::{
24 memory::{BudgetedVec, MemoryReservation},
25 DocId,
26};
27use uqa_storage::{
28 diskann_index::{
29 format::{DiskANNCanonicalOrigin, DiskANNVectorVersion, CANONICAL_ORIGIN_BYTES},
30 DiskANNCanonicalRead, DiskANNCanonicalVectorVisitor,
31 },
32 mvcc::VersionError,
33 read_control::StorageReadControl,
34 StorageBackendResult,
35};
36
37pub struct RetainedSQLiteDiskANNCanonical {
39 snapshot: Arc<NativeSnapshot>,
40 owner: Option<NativeRecordOwner>,
41 table: BudgetedVec<u8>,
42 field: BudgetedVec<u8>,
43 dimensions: u32,
44 control: StorageReadControl,
45 binding: Option<crate::catalog::DiskANNCatalogBinding>,
46 _memory: MemoryReservation,
47}
48
49impl RetainedSQLiteDiskANNCanonical {
50 pub fn index_scope(
52 &self,
53 resolver: &dyn uqa_storage::diskann_index::catalog::DiskANNIndexResolver,
54 control: &StorageReadControl,
55 ) -> StorageBackendResult<uqa_storage::diskann_index::catalog::DiskANNIndexScope> {
56 self.check(control)?;
57 let scope = self
58 .binding
59 .as_ref()
60 .ok_or_else(|| invalid("native canonical source has no index binding"))?
61 .scope(&self.snapshot, resolver, &self.control, control)?;
62 self.check(control)?;
63 Ok(scope)
64 }
65
66 pub(super) fn capture(
67 index: &SQLiteVectorIndex,
68 control: &StorageReadControl,
69 ) -> StorageBackendResult<Self> {
70 Self::capture_selected(index, None, control)
71 }
72
73 pub(super) fn capture_for_index(
74 index: &SQLiteVectorIndex,
75 catalog_index: &uqa_storage::RelationIdentity,
76 control: &StorageReadControl,
77 ) -> StorageBackendResult<Self> {
78 Self::capture_selected(index, Some(catalog_index), control)
79 }
80
81 fn capture_selected(
82 index: &SQLiteVectorIndex,
83 catalog_index: Option<&uqa_storage::RelationIdentity>,
84 control: &StorageReadControl,
85 ) -> StorageBackendResult<Self> {
86 control.check()?;
87 let memory = control
88 .memory()
89 .reserve(std::mem::size_of::<Self>() + std::mem::size_of::<NativeSnapshot>())?;
90 let snapshot = index
91 .conn
92 .native_snapshot()?
93 .ok_or_else(|| invalid("native canonical source requires a bound session"))?;
94 let binding = catalog_index
95 .map(|catalog_index| {
96 crate::catalog::DiskANNCatalogBinding::capture(
97 &snapshot,
98 &index.table,
99 &index.field,
100 index.dimensions,
101 catalog_index,
102 control,
103 )
104 })
105 .transpose()?;
106 let owner = if let Some(binding) = &binding {
107 Some(binding.owner)
108 } else {
109 snapshot.table_owner_controlled(&index.table, control)?
110 };
111 let mut table = BudgetedVec::new(control.memory());
112 table.extend_from_slice(index.table.as_bytes())?;
113 let mut field = BudgetedVec::new(control.memory());
114 field.extend_from_slice(index.field.as_bytes())?;
115 control.check()?;
116 Ok(Self {
117 snapshot,
118 owner,
119 table,
120 field,
121 dimensions: index.dimensions,
122 control: control.clone(),
123 binding,
124 _memory: memory,
125 })
126 }
127
128 pub fn index_parameters(&self) -> Option<uqa_storage::vector_index::DiskANNIndexParams> {
129 self.binding.as_ref().map(|binding| binding.parameters)
130 }
131
132 pub fn require_current_index(
134 &self,
135 read: &dyn uqa_storage::key_value::KeyValueRead,
136 batch: &mut dyn uqa_storage::KeyValueBatch,
137 control: &StorageReadControl,
138 ) -> StorageBackendResult<()> {
139 self.check(control)?;
140 self.binding
141 .as_ref()
142 .ok_or_else(|| invalid("native canonical source has no index binding"))?
143 .require_current(read, batch, control)?;
144 self.check(control)
145 }
146
147 pub fn origin(
149 &self,
150 document: DocId,
151 control: &StorageReadControl,
152 ) -> StorageBackendResult<Option<DiskANNVectorVersion>> {
153 self.record(document, control)
154 .map(|record| record.map(DiskANNCanonicalOrigin::version))
155 }
156
157 pub fn visit_document(
159 &self,
160 document: DocId,
161 control: &StorageReadControl,
162 visit: &mut DiskANNCanonicalVectorVisitor<'_>,
163 ) -> StorageBackendResult<Option<DiskANNVectorVersion>> {
164 let Some(record) = self.record(document, control)? else {
165 return Ok(None);
166 };
167 if record.count() == 0 {
168 return Ok(Some(record.version()));
169 }
170 let document = encode_doc_id(document)?;
171 let dimensions = usize::try_from(self.dimensions)
172 .map_err(|_| invalid("canonical dimensions exceed platform size"))?;
173 let bytes = dimensions
174 .checked_mul(4)
175 .ok_or(uqa_core::memory::MemoryError::SizeOverflow)?;
176 let mut vector = BudgetedVec::new(control.memory());
177 vector.reserve(dimensions)?;
178 for ordinal in 0..record.count() {
179 self.read_payload(document, Some(ordinal), bytes, control, &mut |value| {
180 let value = value.ok_or_else(|| invalid("missing native canonical ordinal"))?;
181 if value.len() != bytes {
182 return Err(invalid("native canonical vector width mismatch"));
183 }
184 vector.clear();
185 for (coordinate, chunk) in value.chunks_exact(4).enumerate() {
186 if coordinate.is_multiple_of(1024) {
187 self.check(control)?;
188 }
189 vector.push(f32::from_le_bytes(chunk.try_into().expect("fixed width")))?;
190 }
191 uqa_storage::vector_index::validate_vector_values_controlled(
192 self.dimensions,
193 &vector,
194 Some(control),
195 )?;
196 visit(ordinal as u32, record.version(), &vector)
197 })?;
198 }
199 self.check(control)?;
200 Ok(Some(record.version()))
201 }
202
203 fn record(
204 &self,
205 document: DocId,
206 control: &StorageReadControl,
207 ) -> StorageBackendResult<Option<DiskANNCanonicalOrigin>> {
208 self.record_on(&self.snapshot, document, control)
209 }
210
211 fn record_on(
212 &self,
213 snapshot: &NativeSnapshot,
214 document: DocId,
215 control: &StorageReadControl,
216 ) -> StorageBackendResult<Option<DiskANNCanonicalOrigin>> {
217 self.check(control)?;
218 let document = encode_doc_id(document)?;
219 let Some(owner) = self.owner else {
220 return Ok(None);
221 };
222 let mut record = None;
223 self.read_payload_on(
224 snapshot,
225 document,
226 None,
227 CANONICAL_ORIGIN_BYTES,
228 control,
229 &mut |bytes| {
230 record = bytes
231 .map(|bytes| DiskANNCanonicalOrigin::decode(bytes, self.dimensions))
232 .transpose()?;
233 Ok(())
234 },
235 )?;
236 let identity =
237 Identity::new(Family::Vectors, owner).map_err(VersionError::into_storage_error)?;
238 let prefix = identity
239 .encode_prefix(
240 &[ValueRef::Text(&self.field), ValueRef::Integer(document)],
241 control,
242 )
243 .map_err(VersionError::into_storage_error)?;
244 let expected = record.map_or(0, DiskANNCanonicalOrigin::count);
245 let mut count = 0;
246 snapshot
247 .view
248 .visit_keys(&prefix, None, usize::MAX, control, &mut |key, metadata| {
249 self.check(control).map_err(VersionError::Storage)?;
250 if metadata.live {
251 let address = Address::decode(key, control)?;
252 if count >= expected
253 || address.identity != identity
254 || *address.field != *self.field
255 || address.numbers[..2] != [document, count as i64]
256 {
257 return Err(VersionError::InvalidEncoding(
258 "native canonical origin or ordinal coverage mismatch",
259 ));
260 }
261 count += 1;
262 }
263 Ok(true)
264 })
265 .map_err(VersionError::into_storage_error)?;
266 if count != expected {
267 return Err(invalid("native canonical replacement count mismatch"));
268 }
269 self.check(control)?;
270 Ok(record)
271 }
272
273 fn read_payload(
274 &self,
275 document: i64,
276 ordinal: Option<u64>,
277 max_bytes: usize,
278 control: &StorageReadControl,
279 visit: &mut dyn FnMut(Option<&[u8]>) -> StorageBackendResult<()>,
280 ) -> StorageBackendResult<()> {
281 self.read_payload_on(&self.snapshot, document, ordinal, max_bytes, control, visit)
282 }
283
284 fn read_payload_on(
285 &self,
286 snapshot: &NativeSnapshot,
287 document: i64,
288 ordinal: Option<u64>,
289 max_bytes: usize,
290 control: &StorageReadControl,
291 visit: &mut dyn FnMut(Option<&[u8]>) -> StorageBackendResult<()>,
292 ) -> StorageBackendResult<()> {
293 self.check(control)?;
294 let Some(owner) = self.owner else {
295 return visit(None);
296 };
297 let family = if ordinal.is_some() {
298 Family::Vectors
299 } else {
300 Family::VectorOrigins
301 };
302 let components = [
303 ValueRef::Text(&self.field),
304 ValueRef::Integer(document),
305 ValueRef::Integer(ordinal.unwrap_or(0) as i64),
306 ];
307 let identity = Identity::new(family, owner).map_err(VersionError::into_storage_error)?;
308 let key = identity
309 .encode_key(
310 &components[..if ordinal.is_some() { 3 } else { 2 }],
311 control,
312 )
313 .map_err(VersionError::into_storage_error)?;
314 let limit = crate::mvcc::native::vector_row_limit(
315 self.table.len(),
316 self.field.len(),
317 max_bytes,
318 ordinal.is_some(),
319 )
320 .map_err(VersionError::into_storage_error)?;
321 snapshot
322 .view
323 .visit_value_bounded(&key, limit, control, &mut |record| {
324 self.check(control).map_err(VersionError::Storage)?;
325 let Some(bytes) = record.and_then(|record| record.value) else {
326 return visit(None).map_err(VersionError::Storage);
327 };
328 let (actual, row) = decode_record(&key, bytes, control)?;
329 if actual != identity || row[0] != ValueRef::Text(&self.table) {
330 return Err(VersionError::InvalidEncoding(
331 "native canonical row scope mismatch",
332 ));
333 }
334 let payload = row[if ordinal.is_some() { 4 } else { 3 }]
335 .as_blob()
336 .map_err(|_| {
337 VersionError::InvalidEncoding("invalid native canonical payload")
338 })?;
339 control.check_value_size(payload.len(), max_bytes)?;
340 visit(Some(payload)).map_err(VersionError::Storage)
341 })
342 .map_err(VersionError::into_storage_error)?;
343 self.check(control)
344 }
345
346 fn check(&self, control: &StorageReadControl) -> StorageBackendResult<()> {
347 self.snapshot.control.check()?;
348 self.control.check()?;
349 control.check()
350 }
351
352 fn next_key_document(
353 &self,
354 family: Family,
355 after: Option<i64>,
356 control: &StorageReadControl,
357 ) -> StorageBackendResult<Option<DocId>> {
358 let Some(owner) = self.owner else {
359 return Ok(None);
360 };
361 let identity = Identity::new(family, owner).map_err(VersionError::into_storage_error)?;
362 let prefix = identity
363 .encode_prefix(&[ValueRef::Text(&self.field)], control)
364 .map_err(VersionError::into_storage_error)?;
365 let after_key = after
366 .map(|document| {
367 let components = [
368 ValueRef::Text(&self.field),
369 ValueRef::Integer(document),
370 ValueRef::Integer(i64::MAX),
371 ];
372 identity.encode_key(
373 &components[..if family == Family::Vectors { 3 } else { 2 }],
374 control,
375 )
376 })
377 .transpose()
378 .map_err(VersionError::into_storage_error)?;
379 let mut selected = None;
380 self.snapshot
381 .view
382 .visit_keys(
383 &prefix,
384 after_key.as_deref(),
385 usize::MAX,
386 control,
387 &mut |key, metadata| {
388 self.check(control).map_err(VersionError::Storage)?;
389 if !metadata.live {
390 return Ok(true);
391 }
392 let address = Address::decode(key, control)?;
393 let document = address.numbers[0];
394 if address.identity != identity
395 || *address.field != *self.field
396 || document < 0
397 || after.is_some_and(|after| document <= after)
398 || (family == Family::Vectors && u32::try_from(address.numbers[1]).is_err())
399 {
400 return Err(VersionError::InvalidEncoding(
401 "invalid native canonical corpus identity",
402 ));
403 }
404 selected = Some(document as DocId);
405 Ok(false)
406 },
407 )
408 .map_err(VersionError::into_storage_error)?;
409 Ok(selected)
410 }
411}
412
413impl DiskANNCanonicalRead for RetainedSQLiteDiskANNCanonical {
414 fn population_counts(
415 &self,
416 generation: uqa_storage::diskann_index::format::DiskANNGeneration,
417 control: &StorageReadControl,
418 ) -> StorageBackendResult<Option<uqa_storage::diskann_index::DiskANNCanonicalCounts>> {
419 self.read_population(generation, control)
420 }
421
422 fn corpus_fingerprint(
423 &self,
424 control: &StorageReadControl,
425 ) -> StorageBackendResult<Option<[u8; 32]>> {
426 self.check(control)?;
427 self.owner
428 .map(|owner| {
429 self.snapshot
430 .vector_field_fingerprint(owner, &self.field, control)
431 })
432 .transpose()
433 }
434 fn read_vector(
435 &self,
436 document: DocId,
437 ordinal: u32,
438 control: &StorageReadControl,
439 ) -> StorageBackendResult<Option<BudgetedVec<f32>>> {
440 self.check(control)?;
441 let bytes = usize::try_from(self.dimensions)
442 .map_err(|_| uqa_core::memory::MemoryError::SizeOverflow)?
443 .checked_mul(4)
444 .ok_or(uqa_core::memory::MemoryError::SizeOverflow)?;
445 let mut result = None;
446 self.read_payload(
447 encode_doc_id(document)?,
448 Some(u64::from(ordinal)),
449 bytes,
450 control,
451 &mut |value| {
452 result = value
453 .map(|value| {
454 uqa_storage::vector_index::decode_vector_bytes(
455 value,
456 self.dimensions,
457 control,
458 )
459 })
460 .transpose()?;
461 Ok(())
462 },
463 )?;
464 self.check(control)?;
465 Ok(result)
466 }
467 fn check_control(&self, control: &StorageReadControl) -> StorageBackendResult<()> {
468 self.check(control)
469 }
470
471 fn dimensions(&self) -> u32 {
472 self.dimensions
473 }
474
475 fn next_document_after(
476 &self,
477 after: Option<DocId>,
478 control: &StorageReadControl,
479 ) -> StorageBackendResult<Option<DocId>> {
480 self.check(control)?;
481 if after.is_some_and(|document| document >= i64::MAX as DocId) {
482 return Ok(None);
483 }
484 let after = after.map(|document| document as i64);
485 let origin = self.next_key_document(Family::VectorOrigins, after, control)?;
486 let vector = self.next_key_document(Family::Vectors, after, control)?;
487 self.check(control)?;
488 Ok(origin.into_iter().chain(vector).min())
489 }
490
491 fn origin(
492 &self,
493 document: DocId,
494 control: &StorageReadControl,
495 ) -> StorageBackendResult<Option<DiskANNVectorVersion>> {
496 self.origin(document, control)
497 }
498
499 fn visit_document(
500 &self,
501 document: DocId,
502 control: &StorageReadControl,
503 visit: &mut DiskANNCanonicalVectorVisitor<'_>,
504 ) -> StorageBackendResult<Option<DiskANNVectorVersion>> {
505 self.visit_document(document, control, visit)
506 }
507}