Skip to main content

uqa_execution/
projected_row.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Borrowed positional rows produced directly by projected storage reads.
8
9use uqa_core::Value;
10use uqa_sql::expr::RowLookup;
11
12use crate::RowSchema;
13
14/// Source of one logical value in a [`ProjectedRow`].
15#[derive(Debug, Clone, Copy, PartialEq, Eq)]
16pub enum ProjectedValueSlot {
17    /// Borrowed value at this position in the storage projection.
18    Field(usize),
19    /// Query-local value at this position in the extra-value slice.
20    Extra(usize),
21    /// A logical column that is absent from the projected source.
22    Missing,
23}
24
25impl ProjectedValueSlot {
26    /// Compile logical output columns against borrowed storage fields and query-local extras.
27    #[must_use]
28    pub fn compile(columns: &[String], fields: &[String], extras: &[&str]) -> Vec<Self> {
29        columns
30            .iter()
31            .map(|column| {
32                fields
33                    .iter()
34                    .position(|field| field == column)
35                    .map(Self::Field)
36                    .or_else(|| {
37                        extras
38                            .iter()
39                            .position(|extra| *extra == column)
40                            .map(Self::Extra)
41                    })
42                    .unwrap_or(Self::Missing)
43            })
44            .collect()
45    }
46}
47
48/// Concrete borrowed row passed from a projected source into an aggregate executor.
49///
50/// Keeping this representation in the execution contract lets aggregate hot paths use positional values without a trait-object call for every group key and aggregate input. Extra values cover source metadata such as document identifiers and scores without materializing a named row.
51pub struct ProjectedRow<'schema, 'row> {
52    schema: &'schema RowSchema,
53    slots: &'schema [ProjectedValueSlot],
54    fields: &'row [&'row Value],
55    extras: &'row [Option<Value>],
56}
57
58impl<'schema, 'row> ProjectedRow<'schema, 'row> {
59    #[must_use]
60    pub fn new(
61        schema: &'schema RowSchema,
62        slots: &'schema [ProjectedValueSlot],
63        fields: &'row [&'row Value],
64        extras: &'row [Option<Value>],
65    ) -> Self {
66        debug_assert_eq!(schema.len(), slots.len());
67        Self {
68            schema,
69            slots,
70            fields,
71            extras,
72        }
73    }
74
75    #[inline]
76    #[must_use]
77    pub(crate) fn row_schema(&self) -> &RowSchema {
78        self.schema
79    }
80
81    #[inline]
82    #[must_use]
83    pub fn positional_column(&self, index: usize) -> Option<&Value> {
84        match self.slots.get(index)? {
85            ProjectedValueSlot::Field(index) => self.fields.get(*index).copied(),
86            ProjectedValueSlot::Extra(index) => self.extras.get(*index).and_then(Option::as_ref),
87            ProjectedValueSlot::Missing => None,
88        }
89    }
90
91    /// Materialize only at an operator boundary that requires owned physical values.
92    #[must_use]
93    pub fn into_values(self) -> Vec<Value> {
94        (0..self.slots.len())
95            .map(|index| {
96                self.positional_column(index)
97                    .cloned()
98                    .unwrap_or(Value::Null)
99            })
100            .collect()
101    }
102}
103
104impl RowLookup for ProjectedRow<'_, '_> {
105    fn column(&self, name: &str) -> Option<&Value> {
106        self.schema
107            .unqualified_position(name)
108            .and_then(|index| self.positional_column(index))
109    }
110
111    fn column_is_ambiguous(&self, name: &str) -> bool {
112        self.schema.column_is_ambiguous(name)
113    }
114
115    fn qualified_column(&self, qualifier: &str, column: &str) -> Option<&Value> {
116        self.schema
117            .qualified_position(qualifier, column)
118            .and_then(|index| self.positional_column(index))
119    }
120
121    fn qualified_column_is_ambiguous(&self, qualifier: &str, column: &str) -> bool {
122        self.schema.qualified_column_is_ambiguous(qualifier, column)
123    }
124
125    #[inline]
126    fn positional_column(&self, index: usize) -> Option<&Value> {
127        Self::positional_column(self, index)
128    }
129
130    fn score_source(&self, qualifier: Option<&str>) -> Option<&Value> {
131        let physical = self.schema.score_source_slot(qualifier)?;
132        let logical = (0..self.schema.len())
133            .find(|logical| self.schema.physical_slot(*logical) == Some(physical))?;
134        self.positional_column(logical)
135    }
136
137    fn score_source_is_ambiguous(&self, qualifier: Option<&str>) -> bool {
138        self.schema.score_source_is_ambiguous(qualifier)
139    }
140
141    fn visit_columns(&self, visitor: &mut dyn FnMut(&str, &Value)) {
142        for (index, column) in self.schema.columns().iter().enumerate() {
143            visitor(
144                column,
145                self.positional_column(index).unwrap_or(&Value::Null),
146            );
147        }
148    }
149}
150
151#[cfg(test)]
152mod tests {
153    use super::*;
154
155    #[test]
156    fn projected_row_resolves_fields_extras_and_missing_slots() {
157        let columns = vec!["name".into(), "score".into(), "missing".into()];
158        let fields = vec!["name".into()];
159        let slots = ProjectedValueSlot::compile(&columns, &fields, &["score"]);
160        let schema = RowSchema::new(columns);
161        let name = Value::Str("Ada".into());
162        let values = [&name];
163        let extras = [Some(Value::Float(0.75))];
164        let row = ProjectedRow::new(&schema, &slots, &values, &extras);
165
166        assert_eq!(row.positional_column(0), Some(&name));
167        assert_eq!(row.positional_column(1), Some(&Value::Float(0.75)));
168        assert_eq!(row.positional_column(2), None);
169        assert_eq!(row.column("name"), Some(&name));
170    }
171
172    #[test]
173    fn projected_row_preserves_structured_qualification() {
174        let columns = vec!["id".into(), "id".into()];
175        let schema = RowSchema::with_identities(
176            columns.clone(),
177            vec![
178                crate::ColumnIdentity::qualified("left.dot", "id.dot"),
179                crate::ColumnIdentity::qualified("right", "id.dot"),
180            ],
181            vec![None, None],
182        );
183        let slots = vec![ProjectedValueSlot::Field(0), ProjectedValueSlot::Field(1)];
184        let left = Value::Int(1);
185        let right = Value::Int(2);
186        let values = [&left, &right];
187        let row = ProjectedRow::new(&schema, &slots, &values, &[]);
188
189        assert!(row.column_is_ambiguous("id.dot"));
190        assert_eq!(
191            row.qualified_column("left.dot", "id.dot"),
192            Some(&Value::Int(1))
193        );
194        assert_eq!(row.qualified_column("left", "dot.id.dot"), None);
195    }
196}