Skip to main content

uqa_storage_sqlite/vector_index/diskann/
maintenance.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Native maintenance retains one canonical capture for change accounting, pruning discovery and a consuming rebuild.
8
9use super::{invalid, RetainedSQLiteDiskANNCanonical, SQLiteDiskANNCanonical};
10use std::sync::Arc;
11use uqa_core::memory::MemoryReservation;
12use uqa_storage::{
13    diskann_index::{
14        build::DiskANNTemporaryBudget,
15        catalog::DiskANNIndexResolver,
16        changes::{DiskANNJournalPruner, DiskANNPruneRequest, DiskANNPruneResult},
17        maintenance::{DiskANNMaintenanceSource, DiskANNStatisticsPage, DiskANNStatisticsRequest},
18        DiskANNIndexOptions,
19    },
20    key_value::KeyValueDiskANNPruner,
21    read_control::StorageReadControl,
22    RelationIdentity, StorageBackendResult,
23};
24
25struct MaintenanceSource {
26    canonical: SQLiteDiskANNCanonical,
27    source: RetainedSQLiteDiskANNCanonical,
28    coverage: KeyValueDiskANNPruner,
29    resolver: Arc<dyn DiskANNIndexResolver + Send + Sync>,
30    control: StorageReadControl,
31    _memory: MemoryReservation,
32}
33
34impl SQLiteDiskANNCanonical {
35    pub fn journal_pruner(
36        self,
37        index: &RelationIdentity,
38        resolver: Arc<dyn DiskANNIndexResolver + Send + Sync>,
39        max_record_bytes: usize,
40        control: &StorageReadControl,
41    ) -> StorageBackendResult<Box<dyn DiskANNJournalPruner>> {
42        Ok(self.maintenance_source(index, resolver, max_record_bytes, control)?)
43    }
44
45    pub fn maintenance_source(
46        self,
47        index: &RelationIdentity,
48        resolver: Arc<dyn DiskANNIndexResolver + Send + Sync>,
49        max_record_bytes: usize,
50        control: &StorageReadControl,
51    ) -> StorageBackendResult<Box<dyn DiskANNMaintenanceSource>> {
52        control.check()?;
53        if self.index.conn.in_transaction() {
54            return Err(invalid("journal discovery requires an inactive session"));
55        }
56        let bytes = size_of::<MaintenanceSource>()
57            .checked_add(self.index.table.capacity())
58            .and_then(|bytes| bytes.checked_add(self.index.field.capacity()))
59            .ok_or(uqa_core::memory::MemoryError::SizeOverflow)?;
60        let memory = control.memory().reserve(bytes)?;
61        let source = self.retain_for_index(index, control)?;
62        let physical = source
63            .selected_source(&*resolver, control)?
64            .ok_or_else(|| invalid("journal discovery has no published generation"))?;
65        let coverage = KeyValueDiskANNPruner::open(physical, max_record_bytes, control)?;
66        Ok(Box::new(MaintenanceSource {
67            canonical: self,
68            source,
69            coverage,
70            resolver,
71            control: control.clone(),
72            _memory: memory,
73        }))
74    }
75}
76
77impl DiskANNJournalPruner for MaintenanceSource {
78    fn prune(
79        &self,
80        request: DiskANNPruneRequest,
81        control: &StorageReadControl,
82    ) -> StorageBackendResult<DiskANNPruneResult> {
83        control.check()?;
84        let connection = &self.canonical.index.conn;
85        if !connection.in_transaction() {
86            return Err(invalid("journal page requires the caller's transaction"));
87        }
88        connection
89            .with_native_write(|current, batch| {
90                Ok(self.source.prune_captured_changes(
91                    &*self.resolver,
92                    &self.coverage,
93                    (current, batch),
94                    request,
95                    control,
96                )?)
97            })?
98            .ok_or_else(|| invalid("journal page requires a bound native session"))
99    }
100}
101
102impl DiskANNMaintenanceSource for MaintenanceSource {
103    fn statistics(
104        &self,
105        request: DiskANNStatisticsRequest,
106        control: &StorageReadControl,
107    ) -> StorageBackendResult<DiskANNStatisticsPage> {
108        self.check_invocation(control)?;
109        self.source
110            .measure_changes(&self.coverage, request, control)
111    }
112
113    fn rebuild(
114        self: Box<Self>,
115        options: DiskANNIndexOptions,
116        temporary: &DiskANNTemporaryBudget,
117        control: &StorageReadControl,
118    ) -> StorageBackendResult<()> {
119        self.check_invocation(control)?;
120        let Self {
121            canonical,
122            source,
123            coverage,
124            resolver,
125            control: _,
126            _memory,
127        } = *self;
128        drop(coverage);
129        canonical.rebuild_source(source, &*resolver, options, temporary, control)
130    }
131}
132
133impl MaintenanceSource {
134    fn check_invocation(&self, control: &StorageReadControl) -> StorageBackendResult<()> {
135        self.control.check()?;
136        control.check()?;
137        if !self.control.memory().shares_allowance(control.memory())
138            || !self
139                .control
140                .cancellation()
141                .shares_signal(control.cancellation())
142        {
143            return Err(invalid(
144                "maintenance requires its original allowance and cancellation",
145            ));
146        }
147        Ok(())
148    }
149}