Skip to main content

uqa_storage/vector_index/memory_snapshot/
canonical.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Canonical memory reads borrow the fixed root and copy only one requested vector.
8
9use super::{MemoryVectorIndex, StorageBackendResult, StorageReadControl};
10use crate::vector_index::{copy_vector, VectorRead};
11use sha2::{Digest, Sha256};
12use std::ops::Bound::{Excluded, Unbounded};
13use uqa_core::{memory::BudgetedVec, DocId};
14
15impl MemoryVectorIndex {
16    pub(super) fn fingerprint(
17        &self,
18        control: &StorageReadControl,
19    ) -> StorageBackendResult<[u8; 32]> {
20        control.check()?;
21        if let Some(fingerprint) = self.state.fingerprint.get() {
22            return Ok(*fingerprint);
23        }
24        let mut digest = Sha256::new();
25        digest.update(b"uqa-retained-vector-values-v1\0");
26        digest.update(self.dimensions.to_le_bytes());
27        for (&document, vectors) in &self.state.vectors {
28            for (ordinal, vector) in vectors.iter().enumerate() {
29                control.check()?;
30                let ordinal = u32::try_from(ordinal).map_err(|_| {
31                    crate::StorageBackendError::Other(
32                        "vector ordinal exceeds u32 index format".into(),
33                    )
34                })?;
35                digest.update(document.to_le_bytes());
36                digest.update(ordinal.to_le_bytes());
37                digest.update((vector.len() as u64).to_le_bytes());
38                for chunk in vector.chunks(1024) {
39                    control.check()?;
40                    for value in chunk {
41                        digest.update(value.to_bits().to_le_bytes());
42                    }
43                }
44            }
45        }
46        control.check()?;
47        let fingerprint = digest.finalize().into();
48        let _ = self.state.fingerprint.set(fingerprint);
49        Ok(fingerprint)
50    }
51}
52
53impl VectorRead for MemoryVectorIndex {
54    fn check_control(&self, control: &StorageReadControl) -> StorageBackendResult<()> {
55        control.check()
56    }
57    fn dimensions(&self) -> u32 {
58        self.dimensions
59    }
60    fn corpus_fingerprint(
61        &self,
62        control: &StorageReadControl,
63    ) -> StorageBackendResult<Option<[u8; 32]>> {
64        self.fingerprint(control).map(Some)
65    }
66    fn next_document_after(
67        &self,
68        after: Option<DocId>,
69        control: &StorageReadControl,
70    ) -> StorageBackendResult<Option<DocId>> {
71        control.check()?;
72        Ok(self
73            .state
74            .vectors
75            .first_from(after.as_ref().map_or(Unbounded, Excluded))
76            .map(|(&document, _)| document))
77    }
78    fn document_vector_count(
79        &self,
80        document: DocId,
81        control: &StorageReadControl,
82    ) -> StorageBackendResult<u64> {
83        control.check()?;
84        Ok(self
85            .state
86            .vectors
87            .get(&document)
88            .map_or(0, |vectors| vectors.len() as u64))
89    }
90    fn read_vector(
91        &self,
92        document: DocId,
93        ordinal: u32,
94        control: &StorageReadControl,
95    ) -> StorageBackendResult<Option<BudgetedVec<f32>>> {
96        control.check()?;
97        self.state
98            .vectors
99            .get(&document)
100            .and_then(|vectors| vectors.get(ordinal as usize))
101            .map(|vector| copy_vector(vector, control))
102            .transpose()
103    }
104}