Skip to main content

uqa_storage_sqlite/vector_index/hnsw/
mod.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! SQLite-backed HNSW index with a session-local immutable graph generation.
8
9use std::sync::Arc;
10
11use parking_lot::RwLock;
12
13use super::{ManagedConnection, SQLiteResult, SQLiteVectorIndex};
14use uqa_storage::hnsw_index::HNSWIndex;
15use uqa_storage::read_control::StorageReadControl;
16use uqa_storage::vector_index::HNSWIndexParams;
17use uqa_storage::ReadOnlySnapshot;
18
19mod encoding;
20mod lifecycle;
21mod loading;
22mod mutation;
23mod native;
24mod persistence;
25mod search;
26mod writing;
27
28pub(crate) use native::NativeHNSWRecords;
29
30#[cfg(test)]
31mod tests;
32
33#[derive(Clone)]
34pub struct SQLiteHNSWIndex {
35    pub(super) persistent: SQLiteVectorIndex,
36    pub(super) params: HNSWIndexParams,
37    pub(super) graph: Arc<RwLock<Option<CachedGraph>>>,
38    pub(super) require_persisted_graph: bool,
39    pub(super) physical_control: StorageReadControl,
40}
41
42#[derive(Clone)]
43pub(super) struct CachedGraph {
44    pub(super) revision: u64,
45    pub(super) identity: GraphIdentity,
46    pub(super) graph: ReadOnlySnapshot<HNSWIndex>,
47}
48
49#[derive(Clone)]
50pub(super) enum GraphIdentity {
51    Physical(crate::connection::SnapshotIdentity),
52    Native(native::GraphIdentity),
53}
54
55impl SQLiteHNSWIndex {
56    pub fn new(
57        conn: ManagedConnection,
58        table: impl Into<String>,
59        field: impl Into<String>,
60        dimensions: u32,
61    ) -> Self {
62        Self::with_params(conn, table, field, dimensions, HNSWIndexParams::default())
63    }
64
65    pub fn with_params(
66        conn: ManagedConnection,
67        table: impl Into<String>,
68        field: impl Into<String>,
69        dimensions: u32,
70        params: HNSWIndexParams,
71    ) -> Self {
72        Self {
73            persistent: SQLiteVectorIndex::new(conn, table, field, dimensions),
74            params,
75            graph: Arc::new(RwLock::new(None)),
76            require_persisted_graph: false,
77            physical_control: StorageReadControl::with_limit(
78                uqa_storage::mvcc::VersionedSessionOptions::default().retained_bytes,
79            ),
80        }
81    }
82
83    pub fn open_existing(
84        conn: ManagedConnection,
85        table: impl Into<String>,
86        field: impl Into<String>,
87        dimensions: u32,
88        params: HNSWIndexParams,
89    ) -> Self {
90        let mut index = Self::with_params(conn, table, field, dimensions, params);
91        index.require_persisted_graph = true;
92        index
93    }
94
95    pub fn drop_metadata(conn: &ManagedConnection, table: &str, field: &str) -> SQLiteResult<()> {
96        writing::drop_metadata(conn, table, field)
97    }
98}