Skip to main content

uqa_execution/batch/
physical_row.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Allocation-light physical row fragments and projections.
8
9use super::{
10    concat_lock_origins, Arc, ResultRow, RowLockOrigin, RowSchema, SmallVec, Value,
11    INLINE_ROW_FRAGMENTS, NULL_SLOT, NULL_VALUE,
12};
13
14#[derive(Debug, Clone, PartialEq)]
15pub(super) struct RowFragment {
16    pub(super) values: Arc<Vec<Value>>,
17    /// Fragment-local output slot -> stored value slot. `None` is the common
18    /// contiguous case. A projection lets an in-memory scan share its stored
19    /// row even when column pruning selects or reorders fields.
20    pub(super) projection: Option<Arc<[usize]>>,
21}
22
23impl RowFragment {
24    fn contiguous(values: Arc<Vec<Value>>) -> Self {
25        Self {
26            values,
27            projection: None,
28        }
29    }
30
31    fn projected(values: Arc<Vec<Value>>, projection: Arc<[usize]>) -> Self {
32        debug_assert!(projection
33            .iter()
34            .all(|slot| *slot == NULL_SLOT || *slot < values.len()));
35        let identity = projection.len() == values.len()
36            && projection
37                .iter()
38                .enumerate()
39                .all(|(index, slot)| index == *slot);
40        if identity {
41            Self::contiguous(values)
42        } else {
43            Self {
44                values,
45                projection: Some(projection),
46            }
47        }
48    }
49
50    pub(super) fn len(&self) -> usize {
51        #[cfg(test)]
52        FRAGMENT_WIDTH_READS.with(|reads| reads.set(reads.get() + 1));
53        self.projection
54            .as_ref()
55            .map_or(self.values.len(), |projection| projection.len())
56    }
57
58    pub(super) fn get(&self, slot: usize) -> Option<&Value> {
59        match self.projection.as_ref() {
60            Some(projection) => match projection.get(slot).copied()? {
61                NULL_SLOT => Some(&NULL_VALUE),
62                stored => self.values.get(stored),
63            },
64            None => self.values.get(slot),
65        }
66    }
67
68    fn stored_slot(&self, slot: usize) -> Option<usize> {
69        match self.projection.as_ref() {
70            Some(projection) => projection.get(slot).copied(),
71            None => (slot < self.values.len()).then_some(slot),
72        }
73    }
74
75    fn into_prefix(mut self, width: usize) -> Self {
76        debug_assert!(width <= self.len());
77        if width == self.len() {
78            return self;
79        }
80        if let Some(projection) = self.projection.as_ref() {
81            self.projection = Some(Arc::from(&projection[..width]));
82            return self;
83        }
84        if let Some(values) = Arc::get_mut(&mut self.values) {
85            values.truncate(width);
86        } else {
87            self.projection = Some((0..width).collect::<Arc<[usize]>>());
88        }
89        self
90    }
91}
92
93pub(super) type RowFragments = SmallVec<[RowFragment; INLINE_ROW_FRAGMENTS]>;
94
95/// A physical row owns no column names. Each fragment is created by a scan or
96/// projection and shared thereafter; joining rows copies only `Arc` handles.
97#[derive(Debug, Clone, Default, PartialEq)]
98pub struct PhysicalRow {
99    pub(super) fragments: RowFragments,
100    pub(super) lock_origins: Option<Arc<Vec<RowLockOrigin>>>,
101}
102
103/// One output position in a mixed physical projection.
104#[derive(Debug, Clone, PartialEq)]
105pub enum RowProjectionValue {
106    /// Reuse one flattened slot from the input row.
107    InputSlot(usize),
108    /// Append a newly computed value.
109    Owned(Value),
110}
111
112impl PhysicalRow {
113    #[cfg(test)]
114    pub(crate) fn count_fragment_width_reads<T>(visit: impl FnOnce() -> T) -> (T, usize) {
115        FRAGMENT_WIDTH_READS.with(|reads| reads.set(0));
116        let output = visit();
117        (output, FRAGMENT_WIDTH_READS.with(std::cell::Cell::get))
118    }
119
120    pub fn from_values(values: Vec<Value>) -> Self {
121        let mut fragments = RowFragments::new();
122        if !values.is_empty() {
123            fragments.push(RowFragment::contiguous(Arc::new(values)));
124        }
125        Self {
126            fragments,
127            lock_origins: None,
128        }
129    }
130
131    /// Build a row by sharing a stored positional value vector and applying a
132    /// fragment-local slot projection. Neither the values nor contained
133    /// strings are cloned.
134    pub fn from_shared_values(values: Arc<Vec<Value>>, projection: Arc<[usize]>) -> Self {
135        let mut fragments = RowFragments::new();
136        if !projection.is_empty() {
137            fragments.push(RowFragment::projected(values, projection));
138        }
139        Self {
140            fragments,
141            lock_origins: None,
142        }
143    }
144
145    pub fn from_result_row(schema: &RowSchema, mut row: ResultRow) -> Self {
146        let values = schema
147            .columns()
148            .iter()
149            .map(|column| row.remove(column).unwrap_or(Value::Null))
150            .collect();
151        Self::from_values(values)
152    }
153
154    pub fn nulls(width: usize) -> Self {
155        Self::from_values(vec![Value::Null; width])
156    }
157
158    pub fn append_values(mut self, values: Vec<Value>) -> Self {
159        if !values.is_empty() {
160            self.fragments
161                .push(RowFragment::contiguous(Arc::new(values)));
162        }
163        self
164    }
165
166    pub fn concat(left: &Self, right: &Self) -> Self {
167        let mut fragments =
168            RowFragments::with_capacity(left.fragments.len() + right.fragments.len());
169        fragments.extend(left.fragments.iter().cloned());
170        fragments.extend(right.fragments.iter().cloned());
171        let lock_origins =
172            concat_lock_origins(left.lock_origins.as_ref(), right.lock_origins.as_ref());
173        Self {
174            fragments,
175            lock_origins,
176        }
177    }
178
179    pub fn concat_left_owned(mut left: Self, right: &Self) -> Self {
180        left.fragments.extend(right.fragments.iter().cloned());
181        left.lock_origins =
182            concat_lock_origins(left.lock_origins.as_ref(), right.lock_origins.as_ref());
183        left
184    }
185
186    pub fn concat_right_owned(left: &Self, mut right: Self) -> Self {
187        let mut fragments =
188            RowFragments::with_capacity(left.fragments.len() + right.fragments.len());
189        fragments.extend(left.fragments.iter().cloned());
190        fragments.append(&mut right.fragments);
191        let lock_origins =
192            concat_lock_origins(left.lock_origins.as_ref(), right.lock_origins.as_ref());
193        Self {
194            fragments,
195            lock_origins,
196        }
197    }
198
199    pub(crate) fn value(&self, mut slot: usize) -> Option<&Value> {
200        for fragment in &self.fragments {
201            if slot < fragment.len() {
202                return fragment.get(slot);
203            }
204            slot -= fragment.len();
205        }
206        None
207    }
208
209    /// Visit physical slots once in order, including absent values in malformed projections so the caller can preserve its slot diagnostic.
210    pub(crate) fn values(&self) -> impl Iterator<Item = Option<&Value>> {
211        self.fragments
212            .iter()
213            .flat_map(|fragment| (0..fragment.len()).map(move |slot| fragment.get(slot)))
214    }
215
216    /// Re-express selected flattened slots as a compact positional row while
217    /// sharing the underlying value vectors. Consecutive slots backed by the
218    /// same source fragment share one projection fragment; no `Value` (and in
219    /// particular no string payload) is cloned.
220    pub(crate) fn project_slots(&self, slots: &[usize]) -> Self {
221        let mut output = RowFragments::new();
222        let null_values = Arc::new(Vec::new());
223        let null_source = self.fragments.len();
224        let mut current_source = None;
225        let mut current_values: Option<Arc<Vec<Value>>> = None;
226        let mut current_projection = Vec::new();
227
228        let flush = |output: &mut RowFragments,
229                     values: &mut Option<Arc<Vec<Value>>>,
230                     projection: &mut Vec<usize>| {
231            if let Some(values) = values.take() {
232                output.push(RowFragment::projected(
233                    values,
234                    Arc::from(std::mem::take(projection)),
235                ));
236            }
237        };
238
239        for requested in slots {
240            let mut remaining = *requested;
241            let resolved = if remaining == NULL_SLOT {
242                None
243            } else {
244                let mut found = None;
245                for (fragment_index, fragment) in self.fragments.iter().enumerate() {
246                    if remaining < fragment.len() {
247                        found = fragment
248                            .stored_slot(remaining)
249                            .filter(|slot| *slot != NULL_SLOT)
250                            .map(|stored| (fragment_index, Arc::clone(&fragment.values), stored));
251                        break;
252                    }
253                    remaining -= fragment.len();
254                }
255                found
256            };
257            let (source, values, stored) =
258                resolved.unwrap_or_else(|| (null_source, Arc::clone(&null_values), NULL_SLOT));
259            if current_source != Some(source) {
260                flush(&mut output, &mut current_values, &mut current_projection);
261                current_source = Some(source);
262                current_values = Some(values);
263            }
264            current_projection.push(stored);
265        }
266        flush(&mut output, &mut current_values, &mut current_projection);
267        Self {
268            fragments: output,
269            lock_origins: self.lock_origins.clone(),
270        }
271    }
272
273    /// Build an output row from shared input slots and newly computed values while preserving their requested order and sharing row metadata.
274    pub fn project_with_values(
275        &self,
276        values: impl IntoIterator<Item = RowProjectionValue>,
277    ) -> Self {
278        fn flush_slots(source: &PhysicalRow, output: &mut RowFragments, slots: &mut Vec<usize>) {
279            if slots.is_empty() {
280                return;
281            }
282            let mut projected = source.project_slots(slots);
283            output.append(&mut projected.fragments);
284            slots.clear();
285        }
286
287        fn flush_owned(output: &mut RowFragments, owned: &mut Vec<Value>) {
288            if owned.is_empty() {
289                return;
290            }
291            output.push(RowFragment::contiguous(Arc::new(std::mem::take(owned))));
292        }
293
294        let mut fragments = RowFragments::new();
295        let mut slots = Vec::new();
296        let mut owned = Vec::new();
297        for value in values {
298            match value {
299                RowProjectionValue::InputSlot(slot) => {
300                    flush_owned(&mut fragments, &mut owned);
301                    slots.push(slot);
302                }
303                RowProjectionValue::Owned(value) => {
304                    flush_slots(self, &mut fragments, &mut slots);
305                    owned.push(value);
306                }
307            }
308        }
309        flush_slots(self, &mut fragments, &mut slots);
310        flush_owned(&mut fragments, &mut owned);
311        Self {
312            fragments,
313            lock_origins: self.lock_origins.clone(),
314        }
315    }
316
317    pub fn fragment_count(&self) -> usize {
318        self.fragments.len()
319    }
320
321    pub(crate) fn into_prefix(self, width: usize) -> Self {
322        let mut remaining = width;
323        let mut fragments = RowFragments::new();
324        for fragment in self.fragments {
325            if remaining == 0 {
326                break;
327            }
328            let fragment_width = fragment.len();
329            if fragment_width <= remaining {
330                fragments.push(fragment);
331                remaining -= fragment_width;
332            } else {
333                fragments.push(fragment.into_prefix(remaining));
334                remaining = 0;
335            }
336        }
337        debug_assert_eq!(remaining, 0, "physical row prefix exceeds row width");
338        Self {
339            fragments,
340            lock_origins: self.lock_origins,
341        }
342    }
343}
344
345#[cfg(test)]
346thread_local! {
347    static FRAGMENT_WIDTH_READS: std::cell::Cell<usize> = const { std::cell::Cell::new(0) };
348}