Skip to main content

uqa_storage_sqlite/vector_index/ivf/
lifecycle.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Construction and public vector-index contract for `SQLite` IVF.
8
9use std::sync::Arc;
10
11use uqa_core::{DocId, PostingList};
12
13use super::writing::drop_metadata;
14use super::SQLiteIVFIndex;
15use crate::vector_index::SQLiteVectorIndex;
16use crate::{ManagedConnection, Result as SQLiteResult};
17use uqa_storage::vector_index::{IVFIndexParams, VectorIndex};
18use uqa_storage::StorageBackendResult;
19
20impl SQLiteIVFIndex {
21    pub fn new(
22        conn: ManagedConnection,
23        table: impl Into<String>,
24        field: impl Into<String>,
25        dimensions: u32,
26    ) -> Self {
27        Self::from_params(conn, table, field, dimensions, IVFIndexParams::default())
28    }
29
30    pub fn with_params(
31        conn: ManagedConnection,
32        table: impl Into<String>,
33        field: impl Into<String>,
34        dimensions: u32,
35        nlist: usize,
36        nprobe: usize,
37        train_threshold: usize,
38    ) -> Self {
39        Self::from_params(
40            conn,
41            table,
42            field,
43            dimensions,
44            IVFIndexParams {
45                nlist: nlist.max(1),
46                nprobe: nprobe.max(1),
47                train_threshold: train_threshold.max(1),
48            },
49        )
50    }
51
52    fn from_params(
53        conn: ManagedConnection,
54        table: impl Into<String>,
55        field: impl Into<String>,
56        dimensions: u32,
57        params: IVFIndexParams,
58    ) -> Self {
59        Self {
60            persistent: SQLiteVectorIndex::new(conn, table, field, dimensions),
61            params,
62            native_state: Arc::default(),
63        }
64    }
65
66    pub fn open_existing(
67        conn: ManagedConnection,
68        table: impl Into<String>,
69        field: impl Into<String>,
70        dimensions: u32,
71        nlist: usize,
72        nprobe: usize,
73        train_threshold: usize,
74    ) -> Self {
75        Self::with_params(
76            conn,
77            table,
78            field,
79            dimensions,
80            nlist,
81            nprobe,
82            train_threshold,
83        )
84    }
85
86    pub fn drop_metadata(conn: &ManagedConnection, table: &str, field: &str) -> SQLiteResult<()> {
87        drop_metadata(conn, table, field)
88    }
89}
90
91impl VectorIndex for SQLiteIVFIndex {
92    fn contains_document(&self, doc_id: DocId) -> StorageBackendResult<bool> {
93        self.persistent.contains_document(doc_id)
94    }
95
96    fn dimensions(&self) -> u32 {
97        self.persistent.dimensions
98    }
99
100    fn index_kind(&self) -> &'static str {
101        "sqlite-ivf"
102    }
103
104    fn add(&mut self, doc_id: DocId, vector: Vec<f32>) -> StorageBackendResult<()> {
105        self.replace_document(doc_id, vec![vector])
106    }
107
108    fn add_many(&mut self, doc_id: DocId, vectors: Vec<Vec<f32>>) -> StorageBackendResult<()> {
109        self.replace_document(doc_id, vectors)
110    }
111
112    fn delete(&mut self, doc_id: DocId) -> StorageBackendResult<()> {
113        self.delete_document(doc_id)
114    }
115
116    fn clear(&mut self) -> StorageBackendResult<()> {
117        self.clear_index()
118    }
119
120    fn search_knn(&self, query: &[f32], k: usize) -> StorageBackendResult<PostingList> {
121        self.search_top_k(query, k)
122    }
123
124    fn search_threshold(&self, query: &[f32], threshold: f32) -> StorageBackendResult<PostingList> {
125        self.persistent.search_threshold(query, threshold)
126    }
127
128    fn count(&self) -> StorageBackendResult<usize> {
129        self.persistent.count()
130    }
131
132    fn initialize(&mut self) -> StorageBackendResult<()> {
133        self.initialize_metadata()
134    }
135
136    fn snapshot(&self) -> StorageBackendResult<Arc<dyn VectorIndex>> {
137        Ok(Arc::new(Self {
138            persistent: self.persistent.retained_snapshot()?,
139            params: self.params,
140            native_state: Arc::default(),
141        }))
142    }
143    fn vector_read_snapshot(
144        &self,
145        control: &uqa_storage::read_control::StorageReadControl,
146    ) -> StorageBackendResult<Option<uqa_storage::vector_index::VectorReadSnapshot>> {
147        self.persistent.vector_read_snapshot(control)
148    }
149}