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 supports_batched_consumption(&self) -> bool {
89        self.sources
90            .iter()
91            .all(crate::RowSource::supports_batched_consumption)
92    }
93
94    fn physical_schema(&self) -> Option<&crate::RowSchema> {
95        Some(&self.physical_schema)
96    }
97
98    fn estimated_cardinality(&self) -> Option<u64> {
99        Some(self.estimated_cardinality)
100    }
101
102    fn next_row(&mut self) -> crate::ExecResult<Option<ResultRow>> {
103        Ok(self.next_batch(1)?.pop())
104    }
105
106    fn next_batch(&mut self, max_rows: usize) -> crate::ExecResult<Vec<ResultRow>> {
107        let rows = self.next_physical_batch(max_rows)?;
108        Ok(rows
109            .iter()
110            .map(|row| self.physical_schema.view(row).to_result_row())
111            .collect())
112    }
113
114    fn next_physical_batch(
115        &mut self,
116        max_rows: usize,
117    ) -> crate::ExecResult<Vec<crate::PhysicalRow>> {
118        if max_rows == 0 {
119            return Ok(Vec::new());
120        }
121        loop {
122            let Some(source) = self.sources.front_mut() else {
123                return Ok(Vec::new());
124            };
125            let batch = source.next_physical_rows_batch(max_rows)?;
126            if batch.is_empty() {
127                self.sources.pop_front();
128            } else {
129                return Ok(batch);
130            }
131        }
132    }
133}
134
135pub struct LocalTableScanConfig {
136    pub cancellation: uqa_core::CancellationToken,
137    pub serializable: Option<crate::serializable::SerializableRelationRead>,
138    pub table_name: String,
139    pub table: Arc<dyn super::table_read::TableRead>,
140    pub column_definitions: Arc<Vec<uqa_sql::ast::ColumnDef>>,
141    pub columns: Vec<String>,
142    pub schema: Vec<String>,
143    pub physical_schema: crate::RowSchema,
144    pub metadata: RelationMetadataProjection,
145    pub table_oid: Option<Value>,
146    pub predicate: Option<crate::ProjectedPredicate>,
147    pub estimated_cardinality: u64,
148    pub lock_origin: Option<SharedLockOrigin>,
149    pub recheck_pins: Option<Arc<Vec<crate::row_locks::recheck::RecheckDoc>>>,
150    /// The only identities the scan's filter admits, in ascending order.
151    pub candidates: Option<super::SelectedIds>,
152    pub command_changes: Option<super::document_changes::DocumentChanges>,
153}
154
155impl LocalTableRowSource {
156    pub fn new(config: LocalTableScanConfig) -> Self {
157        Self {
158            scan_batch_bytes: 64 * 1024 * 1024,
159            batch_layout: crate::spill::EncodedBatchLayout::default(),
160            shared_page_rows: 1,
161            cancellation: config.cancellation,
162            serializable: crate::serializable::SerializableScan::new(config.serializable),
163            table_name: config.table_name,
164            table: config.table,
165            column_definitions: config.column_definitions,
166            columns: config.columns,
167            schema: config.schema,
168            physical_schema: config.physical_schema,
169            metadata: config.metadata,
170            table_oid: config.table_oid,
171            predicate: config.predicate,
172            estimated_cardinality: config.estimated_cardinality,
173            lock_origin: config.lock_origin,
174            recheck_pins: config.recheck_pins,
175            candidates: config.candidates,
176            command_changes: config.command_changes,
177            after: None,
178            recheck_cursor: 0,
179            candidate_cursor: None,
180            command_change_after: None,
181            command_change_page: std::collections::VecDeque::new(),
182            command_changes_exhausted: false,
183            command_base_after: None,
184            command_base_ids: std::collections::VecDeque::new(),
185            command_base_exhausted: false,
186        }
187    }
188
189    /// Bound an ordered shared or borrowed projection batch without combining independently bounded child batches. The current row may exceed the allowance.
190    pub fn with_scan_batch_bytes(mut self, bytes: usize) -> Self {
191        self.scan_batch_bytes = bytes;
192        self
193    }
194}
195
196pub use row_source::table_lock_origin;