Skip to main content

uqa_execution/query/
document_projection.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Project stored fields and transaction metadata through a SQL row type.
8
9use std::collections::BTreeMap;
10use uqa_core::{DocId, Value};
11use uqa_sql::semantics::XMIN_COLUMN;
12use uqa_sql::{ast::ColumnDef, SQLError};
13use uqa_storage::{document_store::Document, DocumentMetadata, DocumentStore, StoredDocument};
14
15mod captured;
16pub use captured::FilterProjection;
17
18/// Read only requested fields and tuple metadata. Complete rows are needed only when a requested virtual generated expression must be evaluated.
19pub fn read_document_projection(
20    source: &dyn DocumentStore,
21    ids: &[DocId],
22    fields: &[&str],
23    definitions: &[ColumnDef],
24) -> Result<BTreeMap<DocId, Vec<Value>>, SQLError> {
25    let requested = fields
26        .iter()
27        .map(|field| (*field).to_string())
28        .collect::<Vec<_>>();
29    if super::generated::projection_contains_virtual_generated_column(definitions, &requested) {
30        let documents = source.get_stored_many(ids).map_err(|error| {
31            crate::storage_errors::storage_error("read generated document projection", &error)
32        })?;
33        return documents
34            .into_iter()
35            .map(|(id, mut document)| {
36                super::generated::materialize_projected_virtual_generated_columns(
37                    definitions,
38                    document.fields_mut(),
39                    &requested,
40                )?;
41                let values = fields
42                    .iter()
43                    .map(|field| project_stored_document_column(&document, field, definitions))
44                    .collect();
45                Ok((id, values))
46            })
47            .collect();
48    }
49    let mut rows = source.get_fields_multi(ids, fields).map_err(|error| {
50        crate::storage_errors::storage_error("read document projection", &error)
51    })?;
52    if !projections_use_tuple_xmin(&requested, definitions) {
53        return Ok(rows);
54    }
55    for (id, values) in &mut rows {
56        if values.len() != fields.len() {
57            return Err(SQLError::Internal(format!(
58                "document {id} returned {} fields for a {}-field projection",
59                values.len(),
60                fields.len(),
61            )));
62        }
63        let explicit = if definitions.is_empty() {
64            source.get_field(*id, XMIN_COLUMN).map_err(|error| {
65                crate::storage_errors::storage_error("read dynamic xmin field", &error)
66            })?
67        } else {
68            None
69        };
70        let xmin = if let Some(value) = explicit {
71            value
72        } else {
73            source
74                .get_metadata(*id)
75                .map_err(|error| {
76                    crate::storage_errors::storage_error("read projected tuple metadata", &error)
77                })?
78                .and_then(DocumentMetadata::tuple_xmin)
79                .map_or(Value::Null, |xmin| Value::Int(i64::from(xmin)))
80        };
81        for (field, value) in fields.iter().zip(values) {
82            if *field == XMIN_COLUMN {
83                *value = xmin.clone();
84            }
85        }
86    }
87    Ok(rows)
88}
89
90pub fn projection_uses_tuple_xmin(column: &str, definitions: &[uqa_sql::ast::ColumnDef]) -> bool {
91    column == XMIN_COLUMN
92        && !definitions
93            .iter()
94            .any(|definition| definition.name == XMIN_COLUMN)
95}
96
97pub fn projections_use_tuple_xmin(
98    columns: &[String],
99    definitions: &[uqa_sql::ast::ColumnDef],
100) -> bool {
101    columns
102        .iter()
103        .any(|column| projection_uses_tuple_xmin(column, definitions))
104}
105
106pub fn project_document_column(
107    document: &Document,
108    metadata: DocumentMetadata,
109    column: &str,
110    definitions: &[uqa_sql::ast::ColumnDef],
111) -> Value {
112    if !projection_uses_tuple_xmin(column, definitions) {
113        return document.get(column).cloned().unwrap_or(Value::Null);
114    }
115    if definitions.is_empty() {
116        if let Some(value) = document.get(column) {
117            return value.clone();
118        }
119    }
120    metadata
121        .tuple_xmin()
122        .map_or(Value::Null, |xmin| Value::Int(i64::from(xmin)))
123}
124
125pub fn project_stored_document_column(
126    document: &StoredDocument,
127    column: &str,
128    definitions: &[uqa_sql::ast::ColumnDef],
129) -> Value {
130    project_document_column(document.fields(), document.metadata(), column, definitions)
131}