Skip to main content

uqa_storage_sqlite/vector_index/diskann/
live.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Native live writes guard catalog records on the evaluated canonical boundary.
8
9mod runtime;
10
11use super::{invalid, RetainedSQLiteDiskANNCanonical, SQLiteDiskANNCanonical};
12use std::sync::Arc;
13use uqa_core::{memory::MemoryReservation, DocId};
14use uqa_storage::{
15    diskann_index::{
16        catalog::{DiskANNIndexResolver, DiskANNIndexScope},
17        format::DiskANNVectorVersion,
18        pages::DiskANNReadLimits,
19        RetainedDiskANNIndex,
20    },
21    key_value::publication::selected_generation,
22    read_control::StorageReadControl,
23    vector_index::DiskANNIndexParams,
24    RelationIdentity, StorageBackendResult,
25};
26
27/// A native session-bound handle to an already published index. Complete tensor mutations join the caller's transaction, while query snapshots retain their original catalog, canonical and physical views. Catalog lifecycle owners perform structural creation, rebuilding and removal.
28pub struct SQLiteDiskANNHandle {
29    canonical: SQLiteDiskANNCanonical,
30    index: RelationIdentity,
31    resolver: Arc<dyn DiskANNIndexResolver + Send + Sync>,
32    scope: DiskANNIndexScope,
33    parameters: DiskANNIndexParams,
34    limits: DiskANNReadLimits,
35    control: StorageReadControl,
36    _memory: MemoryReservation,
37}
38
39impl SQLiteDiskANNCanonical {
40    /// Bind through the actual native catalog and published head. No generation is implicitly created, adopted or replaced.
41    pub fn bind(
42        self,
43        index: RelationIdentity,
44        resolver: Arc<dyn DiskANNIndexResolver + Send + Sync>,
45        limits: DiskANNReadLimits,
46        control: &StorageReadControl,
47    ) -> StorageBackendResult<SQLiteDiskANNHandle> {
48        control.check()?;
49        let bytes = [
50            size_of::<SQLiteDiskANNHandle>(),
51            self.index.table.capacity(),
52            self.index.field.capacity(),
53            index.schema.capacity(),
54            index.name.capacity(),
55        ]
56        .into_iter()
57        .try_fold(0_usize, usize::checked_add)
58        .ok_or(uqa_core::memory::MemoryError::SizeOverflow)?;
59        let memory = control.memory().reserve(bytes)?;
60        self.initialize_populations(&index, &*resolver, control)?;
61        let source = self.retain_for_index(&index, control)?;
62        let scope = source.index_scope(&*resolver, control)?;
63        let parameters = source
64            .index_parameters()
65            .ok_or_else(|| invalid("live native index has no bound parameters"))?;
66        source
67            .selected_source(&*resolver, control)?
68            .ok_or_else(|| invalid("live native index has no published generation"))?;
69        control.check()?;
70        Ok(SQLiteDiskANNHandle {
71            canonical: self,
72            index,
73            resolver,
74            scope,
75            parameters,
76            limits,
77            control: control.clone(),
78            _memory: memory,
79        })
80    }
81}
82
83impl SQLiteDiskANNHandle {
84    /// Replace all ordinals and their origin/change record atomically. Empty tensors remove vector membership. The actual native catalog records become commit requirements in this same evaluated mutation.
85    pub fn replace(
86        &self,
87        document: DocId,
88        vectors: &[Vec<f32>],
89    ) -> StorageBackendResult<DiskANNVectorVersion> {
90        self.control.check()?;
91        self.canonical
92            .replace_guarded(document, vectors, &self.control, |snapshot, batch| {
93                let canonical = &self.canonical.index;
94                let binding = crate::catalog::DiskANNCatalogBinding::capture(
95                    snapshot,
96                    &canonical.table,
97                    &canonical.field,
98                    canonical.dimensions,
99                    &self.index,
100                    &self.control,
101                )?;
102                let current =
103                    binding.scope(snapshot, &*self.resolver, &self.control, &self.control)?;
104                self.validate(&current, binding.parameters)?;
105                let read = snapshot.record_read();
106                let physical = crate::diskann::map_read(&read, snapshot.database)?;
107                if selected_generation(&current, &physical, &self.control)?.is_none() {
108                    return Err(invalid("live native index has no published generation"));
109                }
110                binding.require_current(&read, batch, &self.control)
111            })
112    }
113
114    /// Prepare a fresh query snapshot; repeated and nested reads of the returned index share resident data and keep the original generation through subsequent writes, undo and session closure.
115    pub fn snapshot(
116        &self,
117    ) -> StorageBackendResult<RetainedDiskANNIndex<RetainedSQLiteDiskANNCanonical>> {
118        self.retain_current()?
119            .into_vector_index(&*self.resolver, self.limits, &self.control)?
120            .ok_or_else(|| invalid("live native index has no published generation"))
121    }
122
123    fn retain_current(&self) -> StorageBackendResult<RetainedSQLiteDiskANNCanonical> {
124        self.control.check()?;
125        let source = self
126            .canonical
127            .retain_for_index(&self.index, &self.control)?;
128        let current = source.index_scope(&*self.resolver, &self.control)?;
129        self.validate(
130            &current,
131            source
132                .index_parameters()
133                .ok_or_else(|| invalid("live native index has no bound parameters"))?,
134        )?;
135        Ok(source)
136    }
137
138    fn validate(
139        &self,
140        current: &DiskANNIndexScope,
141        parameters: DiskANNIndexParams,
142    ) -> StorageBackendResult<()> {
143        self.scope.require_same_index(current, &self.control)?;
144        if self.parameters != parameters {
145            return Err(invalid("live native index parameters changed"));
146        }
147        self.control.check()
148    }
149}