Skip to main content

uqa_execution/
columnar_batch.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Positional, column-oriented batches for public result transfer.
8
9#[cfg(test)]
10use crate::RowSchemaExecution;
11use std::collections::BTreeMap;
12
13use uqa_core::Value;
14use uqa_sql::ResultRow;
15
16use crate::{Batch, RowSchema};
17
18#[cfg(test)]
19mod ownership_tests;
20mod positions;
21pub(crate) use positions::{result_column_positions, result_column_positions_with_control};
22
23/// A column vector preserves its position in the declared output schema.
24///
25/// Duplicate labels remain distinct because conversion from a physical batch
26/// reads each logical position directly. The named-row compatibility
27/// constructor cannot recover values that were already collapsed by a map.
28#[derive(Debug, Clone, PartialEq)]
29pub struct ColumnVector {
30    pub name: String,
31    pub values: Vec<Value>,
32}
33
34/// Column-oriented transfer batch. Physical operators may remain row-oriented
35/// internally; API consumers can process one bounded batch without retaining
36/// the complete result set or rebuilding columns themselves.
37#[derive(Debug, Clone, PartialEq)]
38pub struct ColumnarBatch {
39    columns: Vec<ColumnVector>,
40    row_count: usize,
41}
42
43impl ColumnarBatch {
44    /// Convert a positional physical batch without crossing the legacy
45    /// map-backed row boundary. Repeated output labels are matched to repeated
46    /// logical schema positions in order, so differently-valued duplicate
47    /// columns remain distinct for wire and cursor consumers.
48    pub fn from_batch(schema: &[String], mut batch: Batch) -> Self {
49        let row_count = batch.rows.len();
50        let positions = result_column_positions(&batch.schema, schema);
51        let materializer = crate::batch::SelectedRowMaterializer::new(&batch.schema, &positions);
52        let mut columns = schema
53            .iter()
54            .map(|name| ColumnVector {
55                name: name.clone(),
56                values: Vec::with_capacity(row_count),
57            })
58            .collect::<Vec<_>>();
59        for (index, row) in batch.rows.iter_mut().enumerate() {
60            if materializer.copy_shared_row(row, |output, value| {
61                columns[output].values.push(value);
62            }) {
63                continue;
64            }
65            for column in &mut columns {
66                column.values.push(Value::Null);
67            }
68            materializer.materialize(std::mem::take(row), |output, value| {
69                columns[output].values[index] = value;
70            });
71        }
72        Self { columns, row_count }
73    }
74
75    #[cfg(test)]
76    fn from_borrowed_batch(schema: &[String], batch: &Batch) -> Self {
77        let row_count = batch.rows.len();
78        let positions = result_column_positions(&batch.schema, schema);
79        let mut columns = schema
80            .iter()
81            .map(|name| ColumnVector {
82                name: name.clone(),
83                values: Vec::with_capacity(row_count),
84            })
85            .collect::<Vec<_>>();
86        for row in &batch.rows {
87            let view = batch.schema.view(row);
88            for (column, position) in columns.iter_mut().zip(&positions) {
89                column.values.push(
90                    position
91                        .and_then(|position| view.value_at(position))
92                        .cloned()
93                        .unwrap_or(Value::Null),
94                );
95            }
96        }
97        Self { columns, row_count }
98    }
99
100    /// Move map-backed rows into positional columns. A missing projected value
101    /// has SQL `NULL` semantics.
102    pub fn from_rows(schema: &[String], rows: Vec<ResultRow>) -> Self {
103        let row_count = rows.len();
104        let occurrences = schema.iter().fold(BTreeMap::new(), |mut counts, name| {
105            *counts.entry(name.as_str()).or_insert(0_usize) += 1;
106            counts
107        });
108        let mut columns = schema
109            .iter()
110            .map(|name| ColumnVector {
111                name: name.clone(),
112                values: Vec::with_capacity(row_count),
113            })
114            .collect::<Vec<_>>();
115        if occurrences.values().all(|count| *count == 1) {
116            for mut row in rows {
117                for column in &mut columns {
118                    column
119                        .values
120                        .push(row.remove(&column.name).unwrap_or(Value::Null));
121                }
122            }
123            return Self { columns, row_count };
124        }
125        for mut row in rows {
126            let mut remaining = occurrences.clone();
127            for column in &mut columns {
128                let remaining_for_name = remaining
129                    .get_mut(column.name.as_str())
130                    .expect("column occurrence was counted");
131                *remaining_for_name -= 1;
132                let value = if *remaining_for_name == 0 {
133                    row.remove(&column.name)
134                } else {
135                    row.get(&column.name).cloned()
136                };
137                column.values.push(value.unwrap_or(Value::Null));
138            }
139        }
140        Self { columns, row_count }
141    }
142
143    pub fn schema(&self) -> RowSchema {
144        RowSchema::new(
145            self.columns
146                .iter()
147                .map(|column| column.name.clone())
148                .collect(),
149        )
150    }
151
152    pub fn columns(&self) -> &[ColumnVector] {
153        &self.columns
154    }
155
156    pub fn len(&self) -> usize {
157        self.row_count
158    }
159
160    pub fn is_empty(&self) -> bool {
161        self.row_count == 0
162    }
163
164    /// Convert the column vectors to row-major positional values without
165    /// passing through a name-keyed map.
166    pub fn into_positional_rows(self) -> Vec<Vec<Value>> {
167        let mut rows = (0..self.row_count)
168            .map(|_| Vec::with_capacity(self.columns.len()))
169            .collect::<Vec<_>>();
170        for column in self.columns {
171            for (row, value) in rows.iter_mut().zip(column.values) {
172                row.push(value);
173            }
174        }
175        rows
176    }
177
178    /// Convert back to the legacy named-row representation. Duplicate output
179    /// labels necessarily collapse because [`ResultRow`] is a map.
180    pub fn into_rows(self) -> Vec<ResultRow> {
181        let mut rows = (0..self.row_count)
182            .map(|_| BTreeMap::new())
183            .collect::<Vec<ResultRow>>();
184        for column in self.columns {
185            for (row, value) in rows.iter_mut().zip(column.values) {
186                row.insert(column.name.clone(), value);
187            }
188        }
189        rows
190    }
191}
192
193#[cfg(test)]
194mod tests {
195    use super::*;
196
197    #[test]
198    fn conversion_is_positional_and_fills_missing_values_with_null() {
199        let mut first = ResultRow::new();
200        first.insert("a".into(), Value::Int(1));
201        first.insert("b".into(), Value::Str("x".into()));
202        let mut second = ResultRow::new();
203        second.insert("a".into(), Value::Int(2));
204
205        let batch = ColumnarBatch::from_rows(&["b".into(), "a".into()], vec![first, second]);
206        assert_eq!(batch.len(), 2);
207        assert_eq!(
208            batch.columns()[0].values,
209            vec![Value::Str("x".into()), Value::Null]
210        );
211        assert_eq!(
212            batch.columns()[1].values,
213            vec![Value::Int(1), Value::Int(2)]
214        );
215    }
216
217    #[test]
218    fn duplicate_schema_labels_remain_visible_as_separate_slots() {
219        let mut row = ResultRow::new();
220        row.insert("value".into(), Value::Int(7));
221        let batch = ColumnarBatch::from_rows(&["value".into(), "value".into()], vec![row]);
222        assert_eq!(batch.columns().len(), 2);
223        assert_eq!(batch.columns()[0].values, batch.columns()[1].values);
224    }
225
226    #[test]
227    fn physical_batch_preserves_different_duplicate_values() {
228        let schema = RowSchema::new(vec!["value".into(), "value".into()]);
229        let batch = Batch::from_physical_rows(
230            schema,
231            vec![crate::PhysicalRow::from_values(vec![
232                Value::Int(1),
233                Value::Int(2),
234            ])],
235        );
236        let batch = ColumnarBatch::from_batch(&["value".into(), "value".into()], batch);
237        assert_eq!(batch.columns()[0].values, [Value::Int(1)]);
238        assert_eq!(batch.columns()[1].values, [Value::Int(2)]);
239    }
240
241    #[test]
242    fn positional_rows_preserve_duplicate_values() {
243        let schema = RowSchema::new(vec!["value".into(), "value".into()]);
244        let batch = Batch::from_physical_rows(
245            schema,
246            vec![crate::PhysicalRow::from_values(vec![
247                Value::Int(1),
248                Value::Int(2),
249            ])],
250        );
251        assert_eq!(
252            ColumnarBatch::from_batch(&["value".into(), "value".into()], batch)
253                .into_positional_rows(),
254            [vec![Value::Int(1), Value::Int(2)]]
255        );
256    }
257}