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