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::vector_index::HNSWIndexParams;
16use uqa_storage::ReadOnlySnapshot;
17
18mod consistency;
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}
40
41#[derive(Clone)]
42pub(super) struct CachedGraph {
43    pub(super) revision: u64,
44    pub(super) identity: GraphIdentity,
45    pub(super) graph: ReadOnlySnapshot<HNSWIndex>,
46}
47
48#[derive(Clone)]
49pub(super) enum GraphIdentity {
50    Physical(crate::connection::SnapshotIdentity),
51    Native(native::GraphIdentity),
52}
53
54impl SQLiteHNSWIndex {
55    pub fn new(
56        conn: ManagedConnection,
57        table: impl Into<String>,
58        field: impl Into<String>,
59        dimensions: u32,
60    ) -> Self {
61        Self::with_params(conn, table, field, dimensions, HNSWIndexParams::default())
62    }
63
64    pub fn with_params(
65        conn: ManagedConnection,
66        table: impl Into<String>,
67        field: impl Into<String>,
68        dimensions: u32,
69        params: HNSWIndexParams,
70    ) -> Self {
71        Self {
72            persistent: SQLiteVectorIndex::new(conn, table, field, dimensions),
73            params,
74            graph: Arc::new(RwLock::new(None)),
75            require_persisted_graph: false,
76        }
77    }
78
79    pub fn open_existing(
80        conn: ManagedConnection,
81        table: impl Into<String>,
82        field: impl Into<String>,
83        dimensions: u32,
84        params: HNSWIndexParams,
85    ) -> Self {
86        let mut index = Self::with_params(conn, table, field, dimensions, params);
87        index.require_persisted_graph = true;
88        index
89    }
90
91    pub fn drop_metadata(conn: &ManagedConnection, table: &str, field: &str) -> SQLiteResult<()> {
92        writing::drop_metadata(conn, table, field)
93    }
94}