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    table_lock_origin_with_control(
21        catalog,
22        resolution,
23        table,
24        qualifier,
25        enabled,
26        &uqa_core::memory::ProductionControl::uncontrolled(),
27    )
28}
29
30pub(crate) fn table_lock_origin_with_control(
31    catalog: &CatalogReadView,
32    resolution: &RelationNameResolution,
33    table: &str,
34    qualifier: &str,
35    enabled: bool,
36    control: &uqa_core::memory::ProductionControl<'_>,
37) -> Result<Option<SharedLockOrigin>, SQLError> {
38    control.check()?;
39    if !enabled {
40        return Ok(None);
41    }
42    let storage_name = match catalog.table_name_resolved_with_control(resolution, table, control)? {
43        Some(name) => name,
44        None => control.copy_text(table)?,
45    };
46    Ok(Some((
47        crate::RowLockName::copy_with_control(qualifier, control)?,
48        crate::RowLockName::from_produced(storage_name, control)?,
49    )))
50}
51
52impl LocalTableRowSource {
53    #[expect(
54        clippy::too_many_lines,
55        reason = "preserves source schema and row identity"
56    )]
57    pub(super) fn next_physical_rows_batch(
58        &mut self,
59        max_rows: usize,
60    ) -> crate::ExecResult<Vec<crate::PhysicalRow>> {
61        self.cancellation.check().map_err(SQLError::from)?;
62        if max_rows == 0 {
63            return Ok(Vec::new());
64        }
65        if self.recheck_pins.is_some() {
66            return self.next_pinned_physical_rows_batch(max_rows);
67        }
68        if self.candidates.is_some() {
69            return self.next_candidate_physical_rows_batch(max_rows);
70        }
71        self.serializable.observe_relation()?;
72        if self.command_changes.is_some() {
73            return self.next_command_physical_rows_batch(max_rows);
74        }
75        if crate::query::generated::projection_contains_virtual_generated_column(
76            &self.column_definitions,
77            &self.columns,
78        ) || crate::query::document_projection::projections_use_tuple_xmin(
79            &self.columns,
80            &self.column_definitions,
81        ) {
82            return self.next_stored_physical_rows_batch(max_rows);
83        }
84        if let Some(rows) = self.next_borrowed_physical_rows_batch(max_rows)? {
85            return Ok(rows);
86        }
87        let store = self.table.read_documents();
88        let fields = self.columns.iter().map(String::as_str).collect::<Vec<_>>();
89        let mut rows = Vec::with_capacity(max_rows);
90        loop {
91            self.cancellation.check().map_err(SQLError::from)?;
92            // 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.
93            let remaining = max_rows - rows.len();
94            if remaining == 0 {
95                break;
96            }
97            let doc_ids = store.next_doc_ids(self.after, remaining).map_err(|error| {
98                SQLError::Internal(format!(
99                    "scan document ids for `{}`: {error}",
100                    self.table_name
101                ))
102            })?;
103            let Some(last) = doc_ids.last().copied() else {
104                break;
105            };
106            self.after = Some(last);
107
108            let shared_rows = store
109                .get_shared_fields(&doc_ids, &fields)
110                .map_err(|error| {
111                    SQLError::Internal(format!(
112                        "read shared projected fields from `{}`: {error}",
113                        self.table_name
114                    ))
115                })?;
116            if let Some(shared_rows) = shared_rows {
117                if shared_rows.len() != doc_ids.len() {
118                    return Err(SQLError::Internal(format!(
119                        "table `{}` returned {} shared rows for {} document ids",
120                        self.table_name,
121                        shared_rows.len(),
122                        doc_ids.len()
123                    ))
124                    .into());
125                }
126                let null = Value::Null;
127                for (doc_id, shared) in doc_ids.iter().copied().zip(shared_rows) {
128                    let keep = if let Some(shared) = shared.as_ref() {
129                        shared.with_projected(|projected| {
130                            self.predicate
131                                .as_ref()
132                                .map_or(Ok(true), |predicate| predicate.keep(projected))
133                        })?
134                    } else {
135                        let projected = vec![&null; fields.len()];
136                        self.predicate
137                            .as_ref()
138                            .map_or(Ok(true), |predicate| predicate.keep(&projected))?
139                    };
140                    if !keep {
141                        continue;
142                    }
143                    rows.push(self.with_lock_identity(
144                        match shared {
145                            Some(shared) => {
146                                let (values, projection) = shared.into_parts();
147                                crate::PhysicalRow::from_shared_values(values, projection)
148                            }
149                            None => crate::PhysicalRow::nulls(fields.len()),
150                        },
151                        doc_id,
152                    )?);
153                }
154            } else {
155                let mut visited = 0usize;
156                let mut predicate_error = None;
157                store
158                    .for_each_fields_multi_ref(&doc_ids, &fields, &mut |doc_id, values| {
159                        visited += 1;
160                        if let Some(predicate) = self.predicate.as_ref() {
161                            match predicate.keep(values) {
162                                Ok(true) => {}
163                                Ok(false) => return true,
164                                Err(error) => {
165                                    predicate_error = Some(error);
166                                    return false;
167                                }
168                            }
169                        }
170                        match self.with_lock_identity(
171                            crate::PhysicalRow::from_values(
172                                values.iter().map(|value| (*value).clone()).collect(),
173                            ),
174                            doc_id,
175                        ) {
176                            Ok(row) => rows.push(row),
177                            Err(error) => {
178                                predicate_error = Some(error);
179                                return false;
180                            }
181                        }
182                        true
183                    })
184                    .map_err(|error| {
185                        SQLError::Internal(format!(
186                            "read projected fields from `{}`: {error}",
187                            self.table_name
188                        ))
189                    })?;
190                if let Some(error) = predicate_error {
191                    return Err(error.into());
192                }
193                if visited != doc_ids.len() {
194                    return Err(SQLError::Internal(format!(
195                        "table `{}` visited {visited} of {} projected cursor rows",
196                        self.table_name,
197                        doc_ids.len()
198                    ))
199                    .into());
200                }
201            }
202        }
203        Ok(rows)
204    }
205
206    /// 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.
207    fn next_pinned_physical_rows_batch(
208        &mut self,
209        max_rows: usize,
210    ) -> crate::ExecResult<Vec<crate::PhysicalRow>> {
211        let Some(pins) = self.recheck_pins.as_ref() else {
212            return Err(
213                SQLError::Internal("row-lock recheck scan has no pinned tuples".into()).into(),
214            );
215        };
216        let pins = Arc::clone(pins);
217        let store = self.table.read_documents();
218        let mut rows = Vec::with_capacity(max_rows.min(pins.len()));
219        while rows.len() < max_rows && self.recheck_cursor < pins.len() {
220            self.cancellation.check().map_err(SQLError::from)?;
221            let pin = &pins[self.recheck_cursor];
222            self.serializable.observe_row(pin.doc_id)?;
223            self.recheck_cursor += 1;
224            let mut document = if let Some(document) = pin.document.as_ref() {
225                (**document).clone()
226            } else {
227                let Some(document) = store.get_stored(pin.doc_id).map_err(|error| {
228                    SQLError::Internal(format!(
229                        "read pinned recheck row from `{}`: {error}",
230                        self.table_name
231                    ))
232                })?
233                else {
234                    continue;
235                };
236                document
237            };
238            crate::query::generated::materialize_projected_virtual_generated_columns(
239                &self.column_definitions,
240                document.fields_mut(),
241                &self.columns,
242            )?;
243            let values = self
244                .columns
245                .iter()
246                .map(|column| {
247                    crate::query::document_projection::project_stored_document_column(
248                        &document,
249                        column,
250                        &self.column_definitions,
251                    )
252                })
253                .collect::<Vec<_>>();
254            let value_refs = values.iter().collect::<Vec<_>>();
255            if let Some(predicate) = self.predicate.as_ref() {
256                if !predicate.keep(&value_refs)? {
257                    continue;
258                }
259            }
260            rows.push(
261                self.with_lock_identity(crate::PhysicalRow::from_values(values), pin.doc_id)?,
262            );
263        }
264        Ok(rows)
265    }
266
267    fn next_stored_physical_rows_batch(
268        &mut self,
269        max_rows: usize,
270    ) -> crate::ExecResult<Vec<crate::PhysicalRow>> {
271        let store = self.table.read_documents();
272        let mut rows = Vec::with_capacity(max_rows);
273        while rows.len() < max_rows {
274            self.cancellation.check().map_err(SQLError::from)?;
275            let remaining = max_rows - rows.len();
276            let doc_ids = store.next_doc_ids(self.after, remaining).map_err(|error| {
277                SQLError::Internal(format!(
278                    "scan generated rows from `{}`: {error}",
279                    self.table_name
280                ))
281            })?;
282            let Some(last) = doc_ids.last().copied() else {
283                break;
284            };
285            self.after = Some(last);
286            let mut documents = store.get_stored_many(&doc_ids).map_err(|error| {
287                SQLError::Internal(format!(
288                    "read rows with metadata from `{}`: {error}",
289                    self.table_name
290                ))
291            })?;
292            for doc_id in doc_ids {
293                let mut document = documents.remove(&doc_id).ok_or_else(|| {
294                    SQLError::Internal(format!(
295                        "table `{}` listed document {doc_id} but did not return it",
296                        self.table_name
297                    ))
298                })?;
299                crate::query::generated::materialize_projected_virtual_generated_columns(
300                    &self.column_definitions,
301                    document.fields_mut(),
302                    &self.columns,
303                )?;
304                let values = self
305                    .columns
306                    .iter()
307                    .map(|column| {
308                        crate::query::document_projection::project_stored_document_column(
309                            &document,
310                            column,
311                            &self.column_definitions,
312                        )
313                    })
314                    .collect::<Vec<_>>();
315                let value_refs = values.iter().collect::<Vec<_>>();
316                if let Some(predicate) = self.predicate.as_ref() {
317                    if !predicate.keep(&value_refs)? {
318                        continue;
319                    }
320                }
321                rows.push(
322                    self.with_lock_identity(crate::PhysicalRow::from_values(values), doc_id)?,
323                );
324            }
325        }
326        Ok(rows)
327    }
328
329    pub(super) fn with_lock_identity(
330        &self,
331        mut row: crate::PhysicalRow,
332        doc_id: uqa_core::DocId,
333    ) -> Result<crate::PhysicalRow, SQLError> {
334        if let Some(table_oid) = self.table_oid.as_ref() {
335            row = row.append_values(vec![table_oid.clone()]);
336        }
337        let mut metadata = Vec::with_capacity(2);
338        if self.metadata.includes_doc_id() {
339            metadata.push(doc_id_value(doc_id)?);
340        }
341        if self.metadata.includes_score() {
342            metadata.push(Value::Float(0.0));
343        }
344        if !metadata.is_empty() {
345            row = row.append_values(metadata);
346        }
347        let Some((qualifier, storage_name)) = self.lock_origin.as_ref() else {
348            return Ok(row);
349        };
350        Ok(row.with_lock_origin(crate::RowLockOrigin::from_shared(
351            qualifier.clone(),
352            storage_name.clone(),
353            doc_id,
354        )))
355    }
356}
357
358impl crate::RowSource for LocalTableRowSource {
359    fn schema(&self) -> &[String] {
360        &self.schema
361    }
362
363    fn supports_batched_consumption(&self) -> bool {
364        // Ordinary stored-column scans evaluate predicates in row order. Generated fields and command/candidate partition projection retain singleton scheduling until their cross-stage error order is established.
365        self.command_changes.is_none()
366            && self.candidates.is_none()
367            && !crate::query::generated::projection_contains_virtual_generated_column(
368                &self.column_definitions,
369                &self.columns,
370            )
371    }
372
373    fn physical_schema(&self) -> Option<&crate::RowSchema> {
374        Some(&self.physical_schema)
375    }
376
377    fn estimated_cardinality(&self) -> Option<u64> {
378        Some(self.estimated_cardinality)
379    }
380
381    fn next_row(&mut self) -> crate::ExecResult<Option<ResultRow>> {
382        Ok(self.next_batch(1)?.pop())
383    }
384
385    fn next_batch(&mut self, max_rows: usize) -> crate::ExecResult<Vec<ResultRow>> {
386        let rows = self.next_physical_rows_batch(max_rows)?;
387        Ok(rows
388            .iter()
389            .map(|row| self.physical_schema.view(row).to_result_row())
390            .collect())
391    }
392
393    fn next_physical_batch(
394        &mut self,
395        max_rows: usize,
396    ) -> crate::ExecResult<Vec<crate::PhysicalRow>> {
397        self.next_physical_rows_batch(max_rows)
398    }
399}