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 resolution_schema(&self) -> Option<&RowSchema> {
131        Some(self.schema)
132    }
133
134    fn key_space(&self) -> uqa_sql::expr::RowKeySpace {
135        uqa_sql::expr::RowKeySpace::LogicalPosition
136    }
137
138    fn column_key(&self, name: &str) -> Option<usize> {
139        self.schema.unqualified_position(name)
140    }
141
142    fn qualified_column_key(&self, qualifier: &str, column: &str) -> Option<usize> {
143        self.schema.qualified_position(qualifier, column)
144    }
145
146    #[inline]
147    fn keyed_value(&self, key: usize) -> Option<&Value> {
148        Self::positional_column(self, key)
149    }
150
151    fn score_source(&self, qualifier: Option<&str>) -> Option<&Value> {
152        let physical = self.schema.score_source_slot(qualifier)?;
153        let logical = (0..self.schema.len())
154            .find(|logical| self.schema.physical_slot(*logical) == Some(physical))?;
155        self.positional_column(logical)
156    }
157
158    fn score_source_is_ambiguous(&self, qualifier: Option<&str>) -> bool {
159        self.schema.score_source_is_ambiguous(qualifier)
160    }
161
162    fn visit_columns(&self, visitor: &mut dyn FnMut(&str, &Value)) {
163        for (index, column) in self.schema.columns().iter().enumerate() {
164            visitor(
165                column,
166                self.positional_column(index).unwrap_or(&Value::Null),
167            );
168        }
169    }
170}
171
172#[cfg(test)]
173mod tests {
174    use super::*;
175
176    #[test]
177    fn projected_row_resolves_fields_extras_and_missing_slots() {
178        let columns = vec!["name".into(), "score".into(), "missing".into()];
179        let fields = vec!["name".into()];
180        let slots = ProjectedValueSlot::compile(&columns, &fields, &["score"]);
181        let schema = RowSchema::new(columns);
182        let name = Value::Str("Ada".into());
183        let values = [&name];
184        let extras = [Some(Value::Float(0.75))];
185        let row = ProjectedRow::new(&schema, &slots, &values, &extras);
186
187        assert_eq!(row.positional_column(0), Some(&name));
188        assert_eq!(row.positional_column(1), Some(&Value::Float(0.75)));
189        assert_eq!(row.positional_column(2), None);
190        assert_eq!(row.column("name"), Some(&name));
191    }
192
193    #[test]
194    fn projected_row_preserves_structured_qualification() {
195        let columns = vec!["id".into(), "id".into()];
196        let schema = RowSchema::with_identities(
197            columns.clone(),
198            vec![
199                crate::ColumnIdentity::qualified("left.dot", "id.dot"),
200                crate::ColumnIdentity::qualified("right", "id.dot"),
201            ],
202            vec![None, None],
203        );
204        let slots = vec![ProjectedValueSlot::Field(0), ProjectedValueSlot::Field(1)];
205        let left = Value::Int(1);
206        let right = Value::Int(2);
207        let values = [&left, &right];
208        let row = ProjectedRow::new(&schema, &slots, &values, &[]);
209
210        assert!(row.column_is_ambiguous("id.dot"));
211        assert_eq!(
212            row.qualified_column("left.dot", "id.dot"),
213            Some(&Value::Int(1))
214        );
215        assert_eq!(row.qualified_column("left", "dot.id.dot"), None);
216    }
217}