Skip to main content

uqa_execution/query/local_table/
row_source.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6//! Physical row production for persisted, generated, pinned, and command-overlay table rows.
7
8use super::{Arc, LocalTableRowSource, ResultRow, SQLError, SharedLockOrigin, Value};
9use crate::catalog::{CatalogReadView, RelationNameResolution};
10use crate::RowSchemaExecution;
11use uqa_sql::semantics::doc_id_value;
12
13pub fn table_lock_origin(
14    catalog: &CatalogReadView,
15    resolution: &RelationNameResolution,
16    table: &str,
17    qualifier: &str,
18    enabled: bool,
19) -> Result<Option<SharedLockOrigin>, SQLError> {
20    if !enabled {
21        return Ok(None);
22    }
23    let storage_name = catalog
24        .table_name_resolved(resolution, table)?
25        .unwrap_or_else(|| table.to_string());
26    Ok(Some((
27        Arc::<str>::from(qualifier),
28        Arc::<str>::from(storage_name),
29    )))
30}
31
32impl LocalTableRowSource {
33    #[expect(
34        clippy::too_many_lines,
35        reason = "preserves source schema and row identity"
36    )]
37    pub(super) fn next_physical_rows_batch(
38        &mut self,
39        max_rows: usize,
40    ) -> crate::ExecResult<Vec<crate::PhysicalRow>> {
41        self.cancellation.check().map_err(SQLError::from)?;
42        if max_rows == 0 {
43            return Ok(Vec::new());
44        }
45        if self.recheck_pins.is_some() {
46            return self.next_pinned_physical_rows_batch(max_rows);
47        }
48        if self.candidates.is_some() {
49            return self.next_candidate_physical_rows_batch(max_rows);
50        }
51        self.serializable.observe_relation()?;
52        if self.command_changes.is_some() {
53            return self.next_command_physical_rows_batch(max_rows);
54        }
55        if crate::query::generated::projection_contains_virtual_generated_column(
56            &self.column_definitions,
57            &self.columns,
58        ) || crate::query::document_projection::projections_use_tuple_xmin(
59            &self.columns,
60            &self.column_definitions,
61        ) {
62            return self.next_stored_physical_rows_batch(max_rows);
63        }
64        if let Some(rows) = self.next_borrowed_physical_rows_batch(max_rows)? {
65            return Ok(rows);
66        }
67        let store = self.table.read_documents();
68        let fields = self.columns.iter().map(String::as_str).collect::<Vec<_>>();
69        let mut rows = Vec::with_capacity(max_rows);
70        loop {
71            self.cancellation.check().map_err(SQLError::from)?;
72            // A source must not return an empty batch before end-of-stream: TableScan treats it as EOF. Keep advancing storage pages when a pushed predicate rejects an entire page, and fill the requested output batch when selectivity permits it.
73            let remaining = max_rows - rows.len();
74            if remaining == 0 {
75                break;
76            }
77            let doc_ids = store.next_doc_ids(self.after, remaining).map_err(|error| {
78                SQLError::Internal(format!(
79                    "scan document ids for `{}`: {error}",
80                    self.table_name
81                ))
82            })?;
83            let Some(last) = doc_ids.last().copied() else {
84                break;
85            };
86            self.after = Some(last);
87
88            let shared_rows = store
89                .get_shared_fields(&doc_ids, &fields)
90                .map_err(|error| {
91                    SQLError::Internal(format!(
92                        "read shared projected fields from `{}`: {error}",
93                        self.table_name
94                    ))
95                })?;
96            if let Some(shared_rows) = shared_rows {
97                if shared_rows.len() != doc_ids.len() {
98                    return Err(SQLError::Internal(format!(
99                        "table `{}` returned {} shared rows for {} document ids",
100                        self.table_name,
101                        shared_rows.len(),
102                        doc_ids.len()
103                    ))
104                    .into());
105                }
106                let null = Value::Null;
107                for (doc_id, shared) in doc_ids.iter().copied().zip(shared_rows) {
108                    let keep = if let Some(shared) = shared.as_ref() {
109                        shared.with_projected(|projected| {
110                            self.predicate
111                                .as_ref()
112                                .map_or(Ok(true), |predicate| predicate.keep(projected))
113                        })?
114                    } else {
115                        let projected = vec![&null; fields.len()];
116                        self.predicate
117                            .as_ref()
118                            .map_or(Ok(true), |predicate| predicate.keep(&projected))?
119                    };
120                    if !keep {
121                        continue;
122                    }
123                    rows.push(self.with_lock_identity(
124                        match shared {
125                            Some(shared) => {
126                                let (values, projection) = shared.into_parts();
127                                crate::PhysicalRow::from_shared_values(values, projection)
128                            }
129                            None => crate::PhysicalRow::nulls(fields.len()),
130                        },
131                        doc_id,
132                    )?);
133                }
134            } else {
135                let mut visited = 0usize;
136                let mut predicate_error = None;
137                store
138                    .for_each_fields_multi_ref(&doc_ids, &fields, &mut |doc_id, values| {
139                        visited += 1;
140                        if let Some(predicate) = self.predicate.as_ref() {
141                            match predicate.keep(values) {
142                                Ok(true) => {}
143                                Ok(false) => return true,
144                                Err(error) => {
145                                    predicate_error = Some(error);
146                                    return false;
147                                }
148                            }
149                        }
150                        match self.with_lock_identity(
151                            crate::PhysicalRow::from_values(
152                                values.iter().map(|value| (*value).clone()).collect(),
153                            ),
154                            doc_id,
155                        ) {
156                            Ok(row) => rows.push(row),
157                            Err(error) => {
158                                predicate_error = Some(error);
159                                return false;
160                            }
161                        }
162                        true
163                    })
164                    .map_err(|error| {
165                        SQLError::Internal(format!(
166                            "read projected fields from `{}`: {error}",
167                            self.table_name
168                        ))
169                    })?;
170                if let Some(error) = predicate_error {
171                    return Err(error.into());
172                }
173                if visited != doc_ids.len() {
174                    return Err(SQLError::Internal(format!(
175                        "table `{}` visited {visited} of {} projected cursor rows",
176                        self.table_name,
177                        doc_ids.len()
178                    ))
179                    .into());
180                }
181            }
182        }
183        Ok(rows)
184    }
185
186    /// Emit exactly the candidate tuples pinned for a tuple-local row-lock recheck: the latest committed image for a changed tuple, or the statement-snapshot image for an unchanged join partner. Pushed predicates re-apply to the substituted values, matching `PostgreSQL`'s `EvalPlanQual` scan behavior for marked relations.
187    fn next_pinned_physical_rows_batch(
188        &mut self,
189        max_rows: usize,
190    ) -> crate::ExecResult<Vec<crate::PhysicalRow>> {
191        let Some(pins) = self.recheck_pins.as_ref() else {
192            return Err(
193                SQLError::Internal("row-lock recheck scan has no pinned tuples".into()).into(),
194            );
195        };
196        let pins = Arc::clone(pins);
197        let store = self.table.read_documents();
198        let mut rows = Vec::with_capacity(max_rows.min(pins.len()));
199        while rows.len() < max_rows && self.recheck_cursor < pins.len() {
200            self.cancellation.check().map_err(SQLError::from)?;
201            let pin = &pins[self.recheck_cursor];
202            self.serializable.observe_row(pin.doc_id)?;
203            self.recheck_cursor += 1;
204            let mut document = if let Some(document) = pin.document.as_ref() {
205                (**document).clone()
206            } else {
207                let Some(document) = store.get_stored(pin.doc_id).map_err(|error| {
208                    SQLError::Internal(format!(
209                        "read pinned recheck row from `{}`: {error}",
210                        self.table_name
211                    ))
212                })?
213                else {
214                    continue;
215                };
216                document
217            };
218            crate::query::generated::materialize_projected_virtual_generated_columns(
219                &self.column_definitions,
220                document.fields_mut(),
221                &self.columns,
222            )?;
223            let values = self
224                .columns
225                .iter()
226                .map(|column| {
227                    crate::query::document_projection::project_stored_document_column(
228                        &document,
229                        column,
230                        &self.column_definitions,
231                    )
232                })
233                .collect::<Vec<_>>();
234            let value_refs = values.iter().collect::<Vec<_>>();
235            if let Some(predicate) = self.predicate.as_ref() {
236                if !predicate.keep(&value_refs)? {
237                    continue;
238                }
239            }
240            rows.push(
241                self.with_lock_identity(crate::PhysicalRow::from_values(values), pin.doc_id)?,
242            );
243        }
244        Ok(rows)
245    }
246
247    fn next_stored_physical_rows_batch(
248        &mut self,
249        max_rows: usize,
250    ) -> crate::ExecResult<Vec<crate::PhysicalRow>> {
251        let store = self.table.read_documents();
252        let mut rows = Vec::with_capacity(max_rows);
253        while rows.len() < max_rows {
254            self.cancellation.check().map_err(SQLError::from)?;
255            let remaining = max_rows - rows.len();
256            let doc_ids = store.next_doc_ids(self.after, remaining).map_err(|error| {
257                SQLError::Internal(format!(
258                    "scan generated rows from `{}`: {error}",
259                    self.table_name
260                ))
261            })?;
262            let Some(last) = doc_ids.last().copied() else {
263                break;
264            };
265            self.after = Some(last);
266            let mut documents = store.get_stored_many(&doc_ids).map_err(|error| {
267                SQLError::Internal(format!(
268                    "read rows with metadata from `{}`: {error}",
269                    self.table_name
270                ))
271            })?;
272            for doc_id in doc_ids {
273                let mut document = documents.remove(&doc_id).ok_or_else(|| {
274                    SQLError::Internal(format!(
275                        "table `{}` listed document {doc_id} but did not return it",
276                        self.table_name
277                    ))
278                })?;
279                crate::query::generated::materialize_projected_virtual_generated_columns(
280                    &self.column_definitions,
281                    document.fields_mut(),
282                    &self.columns,
283                )?;
284                let values = self
285                    .columns
286                    .iter()
287                    .map(|column| {
288                        crate::query::document_projection::project_stored_document_column(
289                            &document,
290                            column,
291                            &self.column_definitions,
292                        )
293                    })
294                    .collect::<Vec<_>>();
295                let value_refs = values.iter().collect::<Vec<_>>();
296                if let Some(predicate) = self.predicate.as_ref() {
297                    if !predicate.keep(&value_refs)? {
298                        continue;
299                    }
300                }
301                rows.push(
302                    self.with_lock_identity(crate::PhysicalRow::from_values(values), doc_id)?,
303                );
304            }
305        }
306        Ok(rows)
307    }
308
309    pub(super) fn with_lock_identity(
310        &self,
311        mut row: crate::PhysicalRow,
312        doc_id: uqa_core::DocId,
313    ) -> Result<crate::PhysicalRow, SQLError> {
314        if let Some(table_oid) = self.table_oid.as_ref() {
315            row = row.append_values(vec![table_oid.clone()]);
316        }
317        let mut metadata = Vec::with_capacity(2);
318        if self.metadata.includes_doc_id() {
319            metadata.push(doc_id_value(doc_id)?);
320        }
321        if self.metadata.includes_score() {
322            metadata.push(Value::Float(0.0));
323        }
324        if !metadata.is_empty() {
325            row = row.append_values(metadata);
326        }
327        let Some((qualifier, storage_name)) = self.lock_origin.as_ref() else {
328            return Ok(row);
329        };
330        Ok(row.with_lock_origin(crate::RowLockOrigin::from_shared(
331            std::sync::Arc::clone(qualifier),
332            std::sync::Arc::clone(storage_name),
333            doc_id,
334        )))
335    }
336}
337
338impl crate::RowSource for LocalTableRowSource {
339    fn schema(&self) -> &[String] {
340        &self.schema
341    }
342
343    fn physical_schema(&self) -> Option<&crate::RowSchema> {
344        Some(&self.physical_schema)
345    }
346
347    fn estimated_cardinality(&self) -> Option<u64> {
348        Some(self.estimated_cardinality)
349    }
350
351    fn next_row(&mut self) -> crate::ExecResult<Option<ResultRow>> {
352        Ok(self.next_batch(1)?.pop())
353    }
354
355    fn next_batch(&mut self, max_rows: usize) -> crate::ExecResult<Vec<ResultRow>> {
356        let rows = self.next_physical_rows_batch(max_rows)?;
357        Ok(rows
358            .iter()
359            .map(|row| self.physical_schema.view(row).to_result_row())
360            .collect())
361    }
362
363    fn next_physical_batch(
364        &mut self,
365        max_rows: usize,
366    ) -> crate::ExecResult<Vec<crate::PhysicalRow>> {
367        self.next_physical_rows_batch(max_rows)
368    }
369}