Skip to main content

uqa_execution/maintenance/diskann/
rebuild.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Rebuild admission retains the exact census source and its original temporary allowance.
8
9use uqa_storage::{
10    diskann_index::{
11        build::DiskANNTemporaryBudget,
12        format::DiskANNGeneration,
13        maintenance::{
14            DiskANNChangeStatistics, DiskANNMaintenanceSource, DiskANNStatisticsCursor,
15            DiskANNStatisticsRequest,
16        },
17        DiskANNIndexOptions,
18    },
19    read_control::StorageReadControl,
20    StorageBackendError, StorageBackendResult,
21};
22
23/// Soft triggers for one index's current uncovered documents or logical raw vector bytes. Neither limit is a write quota or a physical-retention limit.
24#[derive(Clone, Copy, Debug, PartialEq, Eq)]
25pub struct DiskANNRebuildPolicy {
26    documents: u64,
27    vector_bytes: u64,
28}
29
30impl Default for DiskANNRebuildPolicy {
31    fn default() -> Self {
32        Self {
33            documents: 1024,
34            vector_bytes: 64 << 20,
35        }
36    }
37}
38
39impl DiskANNRebuildPolicy {
40    pub fn new(documents: u64, vector_bytes: u64) -> StorageBackendResult<Self> {
41        if documents == 0 || vector_bytes == 0 {
42            return Err(StorageBackendError::Other(
43                "DiskANN rebuild thresholds must be positive".into(),
44            ));
45        }
46        Ok(Self {
47            documents,
48            vector_bytes,
49        })
50    }
51
52    pub fn documents(self) -> u64 {
53        self.documents
54    }
55    pub fn vector_bytes(self) -> u64 {
56        self.vector_bytes
57    }
58
59    pub(super) fn admits(self, changes: DiskANNChangeStatistics) -> bool {
60        changes.documents >= self.documents || changes.vector_bytes >= self.vector_bytes
61    }
62}
63
64/// Exact counts for the most recently completed index capture; later commits may already have changed its live corpus.
65#[derive(Clone, Copy, Debug, PartialEq, Eq)]
66pub struct DiskANNMaintenanceCensus {
67    pub generation: DiskANNGeneration,
68    pub changes: DiskANNChangeStatistics,
69}
70
71#[derive(Clone)]
72pub(super) struct Configuration {
73    pub policy: DiskANNRebuildPolicy,
74    pub temporary: DiskANNTemporaryBudget,
75}
76
77pub(super) struct Capture {
78    pub source: Box<dyn DiskANNMaintenanceSource>,
79    pub options: DiskANNIndexOptions,
80    pub configuration: Configuration,
81    pub ready: bool,
82    after: Option<DiskANNStatisticsCursor>,
83    generation: Option<DiskANNGeneration>,
84    total: DiskANNChangeStatistics,
85}
86
87impl Capture {
88    pub fn new(
89        source: Box<dyn DiskANNMaintenanceSource>,
90        options: DiskANNIndexOptions,
91        configuration: Configuration,
92    ) -> Self {
93        Self {
94            source,
95            options,
96            configuration,
97            ready: false,
98            after: None,
99            generation: None,
100            total: DiskANNChangeStatistics::default(),
101        }
102    }
103
104    pub fn step(
105        &mut self,
106        control: &StorageReadControl,
107    ) -> StorageBackendResult<Option<DiskANNMaintenanceCensus>> {
108        let page = self.source.statistics(
109            DiskANNStatisticsRequest {
110                after: self.after,
111                max_records: 64,
112            },
113            control,
114        )?;
115        if page.examined > 64
116            || (page.next.is_some() && (page.examined == 0 || page.next == self.after))
117            || self
118                .generation
119                .is_some_and(|generation| generation != page.generation)
120        {
121            return Err(StorageBackendError::Other(
122                "invalid DiskANN maintenance census page".into(),
123            ));
124        }
125        control.check()?;
126        self.total = self.total.checked_add(page.outstanding)?;
127        self.generation = Some(page.generation);
128        self.after = page.next;
129        Ok(page.next.is_none().then_some(DiskANNMaintenanceCensus {
130            generation: page.generation,
131            changes: self.total,
132        }))
133    }
134}