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