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 changes = self.changes.changes_after(after);
43        let mut private = changes.next().transpose()?;
44        let mut base = BudgetedVec::new(control.memory());
45        let mut position = 0;
46        let mut cursor = after;
47        let mut exhausted = false;
48        while ids.len() < limit {
49            control.check()?;
50            self.control.check()?;
51            if position == base.len() && !exhausted {
52                base = BudgetedVec::new(control.memory());
53                position = 0;
54                let requested = (limit - ids.len()).min(crate::DEFAULT_BATCH_SIZE);
55                let page = if borrowed {
56                    self.append_borrowed_ids(cursor, requested, &mut base, control)?
57                } else {
58                    BorrowedPage::Unsupported
59                };
60                match page {
61                    BorrowedPage::Empty => exhausted = true,
62                    BorrowedPage::Last(last) => cursor = Some(last),
63                    BorrowedPage::Unsupported => {
64                        base = read_document_ids(self.source, cursor, requested, control)?;
65                        if let Some(last) = base.last().copied() {
66                            cursor = Some(last);
67                        } else {
68                            exhausted = true;
69                        }
70                    }
71                }
72            }
73            control.check()?;
74            self.control.check()?;
75            let stored = base.get(position).copied();
76            match (stored, private) {
77                (Some(id), Some((changed, _))) if id < changed => {
78                    ids.push(id)?;
79                    position += 1;
80                }
81                (_, Some((id, present))) => {
82                    position += usize::from(stored == Some(id));
83                    if present {
84                        ids.push(id)?;
85                        if ids.len() == limit {
86                            break;
87                        }
88                    }
89                    private = changes.next().transpose()?;
90                }
91                (Some(id), None) => {
92                    ids.push(id)?;
93                    position += 1;
94                }
95                (None, None) => break,
96            }
97        }
98        control.check()?;
99        self.control.check()?;
100        Ok(ids)
101    }
102
103    fn append_borrowed_ids(
104        &self,
105        after: Option<DocId>,
106        limit: usize,
107        ids: &mut BudgetedVec<DocId>,
108        control: &StorageReadControl,
109    ) -> StorageBackendResult<BorrowedPage> {
110        let mut count = 0;
111        let mut last = after;
112        let mut failure = None;
113        let result = self.source.for_each_next_fields(after, limit, &[], &mut |id, _| {
114            if failure.is_some() {
115                return false;
116            }
117            let result = (|| {
118                control.check()?;
119                self.control.check()?;
120                if count == limit || last.is_some_and(|last| id <= last) {
121                    return Err(StorageBackendError::Other(
122                        "query document cursor exceeds its request or does not advance in id order".into(),
123                    ));
124                }
125                count += 1;
126                last = Some(id);
127                ids.push(id)?;
128                Ok(())
129            })();
130            if let Err(error) = result {
131                failure = Some(error);
132                return false;
133            }
134            true
135        });
136        if let Some(error) = failure {
137            return Err(error);
138        }
139        let result = result?;
140        control.check()?;
141        self.control.check()?;
142        match result {
143            Some(reported) if reported == count => Ok(if count == 0 {
144                BorrowedPage::Empty
145            } else {
146                BorrowedPage::Last(last.expect("visited identity"))
147            }),
148            None if count == 0 => Ok(BorrowedPage::Unsupported),
149            _ => Err(StorageBackendError::Other(
150                "query document cursor reports a count inconsistent with its callbacks".into(),
151            )),
152        }
153    }
154}