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