Skip to main content

uqa_execution/query/document_changes/
visible.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Merge base and command-visible identity pages without materializing the complete relation.
8
9use super::DocumentChanges;
10use uqa_core::{memory::BudgetedVec, DocId};
11use uqa_storage::{
12    document_store::read_document_ids, read_control::StorageReadControl, DocumentStore,
13    StorageBackendError, StorageBackendResult,
14};
15
16pub struct VisibleDocumentIds<'a> {
17    pub source: &'a dyn DocumentStore,
18    pub changes: &'a DocumentChanges,
19    pub control: &'a StorageReadControl,
20}
21
22enum BorrowedPage {
23    Unsupported,
24    Empty,
25    Last(DocId),
26}
27
28impl VisibleDocumentIds<'_> {
29    pub fn page(
30        &self,
31        after: Option<DocId>,
32        limit: usize,
33        control: &StorageReadControl,
34        borrowed: bool,
35    ) -> StorageBackendResult<BudgetedVec<DocId>> {
36        self.control.check()?;
37        control.check()?;
38        let mut ids = BudgetedVec::new(control.memory());
39        if limit == 0 {
40            return Ok(ids);
41        }
42        let mut base = BudgetedVec::new(control.memory());
43        let mut cursor = after;
44        while base.len() < limit {
45            control.check()?;
46            self.control.check()?;
47            let requested = (limit - base.len()).min(crate::DEFAULT_BATCH_SIZE);
48            if borrowed {
49                match self.append_borrowed_ids(cursor, requested, &mut base, control)? {
50                    BorrowedPage::Empty => break,
51                    BorrowedPage::Last(last) => {
52                        cursor = Some(last);
53                        continue;
54                    }
55                    BorrowedPage::Unsupported => {}
56                }
57            }
58            let page = read_document_ids(self.source, cursor, requested, control)?;
59            let Some(last) = page.last().copied() else {
60                break;
61            };
62            cursor = Some(last);
63            for id in page.iter().copied() {
64                control.check()?;
65                self.control.check()?;
66                if !self.changes.contains_change(id)? {
67                    base.push(id)?;
68                }
69            }
70        }
71        let mut private = BudgetedVec::new(control.memory());
72        for change in self.changes.changes_after(after) {
73            control.check()?;
74            self.control.check()?;
75            if private.len() == limit {
76                break;
77            }
78            let (id, present) = change?;
79            if present {
80                private.push(id)?;
81            }
82        }
83        let (base, _base_memory) = base.into_parts();
84        let mut base = base.into_iter().peekable();
85        let (private, _private_memory) = private.into_parts();
86        let mut private = private.into_iter().peekable();
87        while ids.len() < limit {
88            control.check()?;
89            self.control.check()?;
90            let id = match (base.peek(), private.peek()) {
91                (Some(left), Some(right)) if left < right => base.next(),
92                (_, Some(_)) => private.next(),
93                (Some(_), None) => base.next(),
94                (None, None) => break,
95            };
96            if let Some(id) = id {
97                ids.push(id)?;
98            }
99        }
100        control.check()?;
101        self.control.check()?;
102        Ok(ids)
103    }
104
105    fn append_borrowed_ids(
106        &self,
107        after: Option<DocId>,
108        limit: usize,
109        ids: &mut BudgetedVec<DocId>,
110        control: &StorageReadControl,
111    ) -> StorageBackendResult<BorrowedPage> {
112        let mut count = 0;
113        let mut last = after;
114        let mut failure = None;
115        let result = self.source.for_each_next_fields(after, limit, &[], &mut |id, _| {
116            if failure.is_some() {
117                return false;
118            }
119            let result = (|| {
120                control.check()?;
121                self.control.check()?;
122                if count == limit || last.is_some_and(|last| id <= last) {
123                    return Err(StorageBackendError::Other(
124                        "query document cursor exceeds its request or does not advance in id order".into(),
125                    ));
126                }
127                count += 1;
128                last = Some(id);
129                if !self.changes.contains_change(id)? {
130                    ids.push(id)?;
131                }
132                Ok(())
133            })();
134            if let Err(error) = result {
135                failure = Some(error);
136                return false;
137            }
138            true
139        });
140        if let Some(error) = failure {
141            return Err(error);
142        }
143        let result = result?;
144        control.check()?;
145        self.control.check()?;
146        match result {
147            Some(reported) if reported == count => Ok(if count == 0 {
148                BorrowedPage::Empty
149            } else {
150                BorrowedPage::Last(last.expect("visited identity"))
151            }),
152            None if count == 0 => Ok(BorrowedPage::Unsupported),
153            _ => Err(StorageBackendError::Other(
154                "query document cursor reports a count inconsistent with its callbacks".into(),
155            )),
156        }
157    }
158}