uqa_core/
vector_execution.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Data returned by one physical vector invocation; storage owns production of the counts.
8
9/// Logical graph-page work. Provider pages are complete uncompressed pages returned by the storage interface, not measured SSD operations or bytes. Cache hits are observed while retaining each actual lease.
10#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
11pub struct DiskANNPageReadStats {
12    pub page_requests: u64,
13    pub cache_hits: u64,
14    pub provider_pages: u64,
15    pub provider_batches: u64,
16}
17
18/// Successful vector-bearing tensor scores and their actual cosine evaluations. Repeated scoring is repeated work, not a distinct-document census.
19#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
20pub struct DiskANNScoringStats {
21    pub documents: u64,
22    pub vectors: u64,
23}
24
25/// Actual page outcomes and scoring by candidate source. Graph and side entries share complete-tensor reranking; current uncovered changes and independent raw tensors retain their own attribution. Exact routes use only `exact`. These are logical counts at declared storage boundaries, not physical I/O measurements.
26#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
27pub struct DiskANNQueryWork {
28    pub pages: DiskANNPageReadStats,
29    pub side_entries: u64,
30    pub reranked: DiskANNScoringStats,
31    pub changed: DiskANNScoringStats,
32    pub unversioned: DiskANNScoringStats,
33    pub exact: DiskANNScoringStats,
34}
35
36/// Counts of successful logical work, independent of cache hits or provider completion order. These are not physical I/O counters.
37#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
38pub struct DiskANNTraversalStats {
39    pub approximate_expansions: u64,
40    pub completion_expansions: u64,
41    pub pq_estimates: u64,
42    pub beams: u64,
43}
44
45/// The route actually executed. Zero-k queries validate their arguments but perform no search; thresholds always use exact tensor scoring.
46#[derive(Debug, Clone, Copy, PartialEq, Eq)]
47pub enum DiskANNExecutionRoute {
48    Approximate,
49    ExactZeroNorm,
50    ExactNonFiniteNorm,
51    ExactThreshold,
52    EmptyK,
53}
54
55/// The actual primitive requested by the caller, before ranking or calibration.
56#[derive(Debug, Clone, Copy, PartialEq)]
57pub enum VectorSearchOperation {
58    KNN { k: usize },
59    Threshold { threshold: f32 },
60}
uqa_core/vector_execution.rs

uqa_core/
vector_execution.rs
