Skip to main content

uqa_execution/query/
local_table.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Physical scans over persisted rows, generated fields, recheck pins, and command overlays.
8
9use crate::RowSchemaExecution;
10use std::sync::Arc;
11use uqa_core::Value;
12use uqa_sql::{plan::source_projection::RelationMetadataProjection, ResultRow, SQLError};
13
14mod borrowed;
15mod command_scan;
16mod row_source;
17
18pub type SharedLockOrigin = (Arc<str>, Arc<str>);
19
20pub struct LocalTableRowSource {
21    scan_batch_bytes: usize,
22    batch_layout: crate::spill::EncodedBatchLayout,
23    shared_page_rows: usize,
24    cancellation: uqa_core::CancellationToken,
25    serializable: crate::serializable::SerializableScan,
26    table_name: String,
27    table: Arc<dyn super::table_read::TableRead>,
28    column_definitions: Arc<Vec<uqa_sql::ast::ColumnDef>>,
29    columns: Vec<String>,
30    schema: Vec<String>,
31    physical_schema: crate::RowSchema,
32    metadata: RelationMetadataProjection,
33    table_oid: Option<Value>,
34    predicate: Option<crate::ProjectedPredicate>,
35    estimated_cardinality: u64,
36    after: Option<uqa_core::DocId>,
37    lock_origin: Option<SharedLockOrigin>,
38    recheck_pins: Option<Arc<Vec<crate::row_locks::recheck::RecheckDoc>>>,
39    recheck_cursor: usize,
40    /// The only identities the scan's filter admits, in ascending order, and the position of the next of them.
41    candidates: Option<super::SelectedIds>,
42    candidate_cursor: Option<super::SelectedIdCursor>,
43    command_changes: Option<super::document_changes::DocumentChanges>,
44    command_change_after: Option<uqa_core::DocId>,
45    /// The next changes of the command scan after `command_change_after`, read a page at a time.
46    command_change_page: std::collections::VecDeque<(uqa_core::DocId, bool)>,
47    command_changes_exhausted: bool,
48    command_base_after: Option<uqa_core::DocId>,
49    command_base_ids: std::collections::VecDeque<uqa_core::DocId>,
50    command_base_exhausted: bool,
51}
52
53/// One logical inheritance scan over independently stored physical tables.
54/// Each child source retains its own lock origin and command overlay while the
55/// SQL-visible row type remains the selected ancestor's row type.
56pub struct HierarchyRowSource {
57    sources: std::collections::VecDeque<LocalTableRowSource>,
58    schema: Vec<String>,
59    physical_schema: crate::RowSchema,
60    estimated_cardinality: u64,
61}
62
63impl HierarchyRowSource {
64    pub fn new(sources: Vec<LocalTableRowSource>) -> Result<Self, SQLError> {
65        let first = sources.first().ok_or_else(|| {
66            SQLError::Internal("inheritance scan was built without a physical table".into())
67        })?;
68        let schema = first.schema.clone();
69        let physical_schema = first.physical_schema.clone();
70        let estimated_cardinality = sources
71            .iter()
72            .map(|source| source.estimated_cardinality)
73            .sum();
74        Ok(Self {
75            sources: sources.into(),
76            schema,
77            physical_schema,
78            estimated_cardinality,
79        })
80    }
81}
82
83impl crate::RowSource for HierarchyRowSource {
84    fn schema(&self) -> &[String] {
85        &self.schema
86    }
87
88    fn physical_schema(&self) -> Option<&crate::RowSchema> {
89        Some(&self.physical_schema)
90    }
91
92    fn estimated_cardinality(&self) -> Option<u64> {
93        Some(self.estimated_cardinality)
94    }
95
96    fn next_row(&mut self) -> crate::ExecResult<Option<ResultRow>> {
97        Ok(self.next_batch(1)?.pop())
98    }
99
100    fn next_batch(&mut self, max_rows: usize) -> crate::ExecResult<Vec<ResultRow>> {
101        let rows = self.next_physical_batch(max_rows)?;
102        Ok(rows
103            .iter()
104            .map(|row| self.physical_schema.view(row).to_result_row())
105            .collect())
106    }
107
108    fn next_physical_batch(
109        &mut self,
110        max_rows: usize,
111    ) -> crate::ExecResult<Vec<crate::PhysicalRow>> {
112        if max_rows == 0 {
113            return Ok(Vec::new());
114        }
115        loop {
116            let Some(source) = self.sources.front_mut() else {
117                return Ok(Vec::new());
118            };
119            let batch = source.next_physical_rows_batch(max_rows)?;
120            if batch.is_empty() {
121                self.sources.pop_front();
122            } else {
123                return Ok(batch);
124            }
125        }
126    }
127}
128
129pub struct LocalTableScanConfig {
130    pub cancellation: uqa_core::CancellationToken,
131    pub serializable: Option<crate::serializable::SerializableRelationRead>,
132    pub table_name: String,
133    pub table: Arc<dyn super::table_read::TableRead>,
134    pub column_definitions: Arc<Vec<uqa_sql::ast::ColumnDef>>,
135    pub columns: Vec<String>,
136    pub schema: Vec<String>,
137    pub physical_schema: crate::RowSchema,
138    pub metadata: RelationMetadataProjection,
139    pub table_oid: Option<Value>,
140    pub predicate: Option<crate::ProjectedPredicate>,
141    pub estimated_cardinality: u64,
142    pub lock_origin: Option<SharedLockOrigin>,
143    pub recheck_pins: Option<Arc<Vec<crate::row_locks::recheck::RecheckDoc>>>,
144    /// The only identities the scan's filter admits, in ascending order.
145    pub candidates: Option<super::SelectedIds>,
146    pub command_changes: Option<super::document_changes::DocumentChanges>,
147}
148
149impl LocalTableRowSource {
150    pub fn new(config: LocalTableScanConfig) -> Self {
151        Self {
152            scan_batch_bytes: 64 * 1024 * 1024,
153            batch_layout: crate::spill::EncodedBatchLayout::default(),
154            shared_page_rows: 1,
155            cancellation: config.cancellation,
156            serializable: crate::serializable::SerializableScan::new(config.serializable),
157            table_name: config.table_name,
158            table: config.table,
159            column_definitions: config.column_definitions,
160            columns: config.columns,
161            schema: config.schema,
162            physical_schema: config.physical_schema,
163            metadata: config.metadata,
164            table_oid: config.table_oid,
165            predicate: config.predicate,
166            estimated_cardinality: config.estimated_cardinality,
167            lock_origin: config.lock_origin,
168            recheck_pins: config.recheck_pins,
169            candidates: config.candidates,
170            command_changes: config.command_changes,
171            after: None,
172            recheck_cursor: 0,
173            candidate_cursor: None,
174            command_change_after: None,
175            command_change_page: std::collections::VecDeque::new(),
176            command_changes_exhausted: false,
177            command_base_after: None,
178            command_base_ids: std::collections::VecDeque::new(),
179            command_base_exhausted: false,
180        }
181    }
182
183    /// Bound an ordered shared or borrowed projection batch without combining independently bounded child batches. The current row may exceed the allowance.
184    pub fn with_scan_batch_bytes(mut self, bytes: usize) -> Self {
185        self.scan_batch_bytes = bytes;
186        self
187    }
188}
189
190pub use row_source::table_lock_origin;