Skip to main content

uqa_storage_sqlite/vector_index/diskann/
retained.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Bounded canonical reads borrow native rows and preserve their original visibility and controls.
8
9mod 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
37/// A fixed native canonical source. Each visitor borrows one vector; it must not reenter this source. Failure invalidates any partial output.
38pub 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    /// Resolve the index incarnation from this source's fixed native catalog view through the SQL owner.
51    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    /// Recheck the captured native definitions and stage committed requirements on one publication command's raw record reader/batch. This does not publish a generation or complete the caller's transaction.
133    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    /// Return an origin only after verifying its complete contiguous native canonical ordinal set. An origin with zero ordinals denotes an explicit empty replacement.
148    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    /// Stream all visible ordinals with their original coordinate bits, independently of navigation, scoring or document candidate selection.
158    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}