uqa-storage 0.5.3

Document store, inverted index, IVF/HNSW vectors, B-tree, R*Tree, catalog
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100

//
// Unified Query Algebra
//
// Copyright (c) 2023-2026 Cognica, Inc.
//

//! Provider-independent canonical origin envelope; raw coordinates remain in their existing canonical layout.

use super::DiskANNVectorVersion;
use crate::mvcc::{DatabaseId, StorageTransactionId, VersionError};
use crate::StorageBackendResult;

const MAGIC: &[u8; 8] = b"UQAVORG1";
pub const CANONICAL_ORIGIN_BYTES: usize = 56;
const BYTES: usize = CANONICAL_ORIGIN_BYTES;

/// Original publishing mutation and complete canonical tensor shape, independent of the provider layout.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct DiskANNCanonicalOrigin {
    version: DiskANNVectorVersion,
    dimensions: u32,
    count: u64,
}

impl DiskANNCanonicalOrigin {
    pub fn new(
        version: DiskANNVectorVersion,
        dimensions: u32,
        count: u64,
    ) -> StorageBackendResult<Self> {
        validate(dimensions, count)?;
        Ok(Self {
            version,
            dimensions,
            count,
        })
    }

    pub fn version(self) -> DiskANNVectorVersion {
        self.version
    }
    pub fn count(self) -> u64 {
        self.count
    }
    pub fn dimensions(self) -> u32 {
        self.dimensions
    }

    pub fn encode(self) -> [u8; BYTES] {
        let mut bytes = [0; BYTES];
        bytes[..8].copy_from_slice(MAGIC);
        bytes[8..24].copy_from_slice(&self.version.writer().database().as_bytes());
        bytes[24..32].copy_from_slice(&self.version.writer().allocation().to_le_bytes());
        bytes[32..40].copy_from_slice(&self.version.revision().to_le_bytes());
        bytes[40..44].copy_from_slice(&self.dimensions.to_le_bytes());
        bytes[48..56].copy_from_slice(&self.count.to_le_bytes());
        bytes
    }

    pub fn decode(bytes: &[u8], dimensions: u32) -> StorageBackendResult<Self> {
        if bytes.len() != BYTES || &bytes[..8] != MAGIC || bytes[44..48] != [0; 4] {
            return Err(invalid("invalid canonical origin envelope"));
        }
        let read = |offset: usize| -> [u8; 8] {
            bytes[offset..offset + 8]
                .try_into()
                .expect("validated width")
        };
        if bytes[40..44] != dimensions.to_le_bytes() {
            return Err(invalid("canonical origin dimension mismatch"));
        }
        let database = DatabaseId::from_bytes(bytes[8..24].try_into().expect("validated width"));
        let writer = StorageTransactionId::new(database, u64::from_le_bytes(read(24)))
            .map_err(VersionError::into_storage_error)?;
        let version = DiskANNVectorVersion::new(writer, u64::from_le_bytes(read(32)))?;
        let count = u64::from_le_bytes(read(48));
        validate(dimensions, count)?;
        Ok(Self {
            version,
            dimensions,
            count,
        })
    }
}

fn validate(dimensions: u32, count: u64) -> StorageBackendResult<()> {
    if dimensions == 0 || count > (1_u64 << 32) {
        return Err(invalid(
            "invalid canonical tensor dimensions or ordinal count",
        ));
    }
    Ok(())
}

fn invalid(message: &'static str) -> crate::StorageBackendError {
    VersionError::InvalidEncoding(message).into_storage_error()
}

#[cfg(test)]
mod tests;