Skip to main content

rypipe_core/engine/
table_builder.rs

1#[cfg(test)]
2use std::borrow::Cow;
3use std::sync::Arc;
4
5#[cfg(feature = "profile")]
6use std::sync::atomic::{AtomicUsize, Ordering};
7
8/// Diagnostic: counts resolve_and_put calls across all TableBuilder instances.
9#[cfg(feature = "profile")]
10pub static RESOLVE_AND_PUT_COUNT: AtomicUsize = AtomicUsize::new(0);
11/// Diagnostic: counts predicate evaluations across all TableBuilder instances.
12#[cfg(feature = "profile")]
13pub static PREDICATE_EVALUATIONS: AtomicUsize = AtomicUsize::new(0);
14/// Diagnostic: counts how many times evaluate_predicate_state returns Fail.
15#[cfg(feature = "profile")]
16pub static PREDICATE_FAILS: AtomicUsize = AtomicUsize::new(0);
17/// Diagnostic: counts how many times evaluate_predicate_state returns Undecided.
18#[cfg(feature = "profile")]
19pub static PREDICATE_UNDECIDED: AtomicUsize = AtomicUsize::new(0);
20/// Diagnostic: counts how many times is_predicate_slot returns true.
21#[cfg(feature = "profile")]
22pub static IS_PRED_TRUE: AtomicUsize = AtomicUsize::new(0);
23/// Diagnostic: counts how many times is_predicate_slot returns false.
24#[cfg(feature = "profile")]
25pub static IS_PRED_FALSE: AtomicUsize = AtomicUsize::new(0);
26
27use arrow::datatypes::{Field as ArrowField, Schema};
28use arrow::record_batch::RecordBatch;
29use rustc_hash::FxHashMap as HashMap;
30
31use smallvec::SmallVec;
32
33use crate::columnar::ColumnBuilder;
34use crate::decoder::ColumnarSink;
35use crate::engine::predicate::{PredicateState, RowBuffer};
36use crate::plan::{ExecutionPlan, FieldType, FilterPredicate};
37use crate::value::Value;
38use crate::Result;
39
40/// Generic columnar table builder.  Implements `ColumnarSink` so any decoder
41/// can feed it field/value events; at the end it produces an Arrow
42/// `RecordBatch`.
43pub struct TableBuilder {
44    pub(crate) columns: Vec<ColumnBuilder>,
45    pub(crate) field_index: HashMap<String, usize>,
46    pub(crate) column_order: Vec<String>,
47    pub(crate) row_count: usize,
48    pub(crate) estimated_rows: usize,
49    pub(crate) plan: Arc<ExecutionPlan>,
50    /// Dirty mask for the current row: bit `i` set iff column `i` received a
51    /// value in this row. `Vec<u64>` word array so >64 columns work (e.g.,
52    /// Crystal Reports exports with >64 fields). One compare `mask != full`
53    /// replaces `for col in 0..ncols` loop when every field is present (dense).
54    pub(crate) row_dirty: Vec<u64>,
55    /// Frozen schema for parallel streaming. When Some, any field not in the
56    /// schema is an unknown field and hard-errors on `finish()` (data loss
57    /// would otherwise be silent). Discovery samples 16×2 MiB for >128 MiB.
58    pub(crate) frozen: Option<std::sync::Arc<crate::schema::FrozenSchema>>,
59    pub(crate) unknown_error: Option<String>,
60    /// Heap-allocated row buffer for predicate-first deferred materialization.
61    /// `None` when `plan.filter` is `None`; unfiltered parses carry zero
62    /// overhead from predicate machinery.
63    pub(crate) row_buf: Option<Box<RowBuffer>>,
64    /// Per-ordinal layout expectation: after row 1, each ordinal maps to a
65    /// (slot_index, raw_name) pair.  The adapter can memcmp the raw bytes
66    /// in-place instead of running the full attribute scan → UTF-8 decode →
67    /// hash → lookup path.  `None` after `layout_broken` or before row 1.
68    pub(crate) ordinal_expect: Vec<Option<(u32, Vec<u8>)>>,
69    /// Current ordinal within the row (incremented per put_field call).
70    /// Used to populate `ordinal_expect` on the first row.
71    pub(crate) current_ordinal: u32,
72}
73
74impl TableBuilder {
75    pub fn new() -> Self {
76        Self {
77            columns: Vec::new(),
78            field_index: HashMap::default(),
79            column_order: Vec::new(),
80            row_count: 0,
81            estimated_rows: 0,
82            plan: Arc::new(ExecutionPlan::new()),
83            row_dirty: Vec::new(),
84            frozen: None,
85            unknown_error: None,
86            row_buf: None,
87            ordinal_expect: Vec::new(),
88            current_ordinal: 0,
89        }
90    }
91
92    pub fn with_capacity(cap: usize) -> Self {
93        Self {
94            columns: Vec::new(),
95            field_index: HashMap::default(),
96            column_order: Vec::new(),
97            row_count: 0,
98            estimated_rows: cap,
99            plan: Arc::new(ExecutionPlan::new()),
100            row_dirty: Vec::new(),
101            frozen: None,
102            unknown_error: None,
103            row_buf: None,
104            ordinal_expect: Vec::new(),
105            current_ordinal: 0,
106        }
107    }
108
109    pub fn with_plan(cap: usize, plan: Arc<ExecutionPlan>) -> Self {
110        Self {
111            columns: Vec::new(),
112            field_index: HashMap::default(),
113            column_order: Vec::new(),
114            row_count: 0,
115            estimated_rows: cap,
116            plan: Arc::clone(&plan),
117            row_dirty: Vec::new(),
118            frozen: None,
119            unknown_error: None,
120            row_buf: if plan.filter.is_some() {
121                Some(Box::new(RowBuffer {
122                    fields: SmallVec::new(),
123                    state: PredicateState::Undecided,
124                    predicate_mask: SmallVec::new(),
125                    direct: false,
126                    predicate_ordinal: None,
127                    buffer_worthwhile: true,
128                    pred_names: SmallVec::new(),
129                }))
130            } else {
131                None
132            },
133            ordinal_expect: Vec::new(),
134            current_ordinal: 0,
135        }
136    }
137
138    /// Pre-size all columns from a `FrozenSchema`.
139    ///
140    /// Called by parallel streaming workers so that every chunk's
141    /// `TableBuilder` has the full column set from construction,
142    /// regardless of which fields appear in that chunk.
143    pub fn ensure_schema(&mut self, schema: &crate::schema::FrozenSchema) -> Result<()> {
144        for (slot, name) in schema.column_names().iter().enumerate() {
145            let name_str: &str = name;
146            if self.field_index.contains_key(name_str) {
147                continue; // already present
148            }
149            let ty = schema.column_types()[slot].clone();
150            let col = ColumnBuilder::with_capacity(self.estimated_rows, &ty);
151            self.columns.push(col);
152            self.field_index
153                .insert(name_str.to_string(), self.columns.len() - 1);
154            self.column_order.push(name_str.to_string());
155        }
156        // Resize row_dirty bitmask to cover all columns.
157        let words = self.columns.len().div_ceil(64);
158        self.row_dirty.resize(words, 0);
159        // Freeze: any later field not in this schema is an unknown field and
160        // must hard-error (otherwise data loss would be silent on a default
161        // path). Sampling 16×2 MiB covers ~6% of a 533 MB file, so 1% Text21
162        // is expected ~280 hits, but 0.05% would be missed.
163        self.frozen = Some(std::sync::Arc::new(schema.clone()));
164        Ok(())
165    }
166
167    /// Lookup a column by resolved name.
168    pub(crate) fn get_column(&self, name: &str) -> Option<&ColumnBuilder> {
169        self.field_index.get(name).map(|&i| &self.columns[i])
170    }
171
172    /// Mutable lookup by resolved name.
173    pub(crate) fn get_column_mut(&mut self, name: &str) -> Option<&mut ColumnBuilder> {
174        if let Some(&i) = self.field_index.get(name) {
175            Some(&mut self.columns[i])
176        } else {
177            None
178        }
179    }
180
181    pub(crate) fn bytes_used(&self) -> usize {
182        self.columns.iter().map(|c| c.bytes_used()).sum::<usize>()
183            + self.column_order.iter().map(|s| s.len()).sum::<usize>()
184            + self.row_dirty.len() * 8
185    }
186
187    /// Split off the first `n` rows into a new `TableBuilder`.
188    ///
189    /// Leaves `n` rows in `self`'s remainder as `self - n`. Used for
190    /// 64KB streaming where a single file chunk may contain many more rows
191    /// than `rows_per_batch`.
192    pub(crate) fn split_off(&mut self, n: usize) -> Self {
193        assert!(n <= self.row_count, "split_off beyond row_count");
194        assert!(n > 0);
195        let mut other = Self {
196            columns: Vec::with_capacity(self.columns.len()),
197            field_index: self.field_index.clone(),
198            column_order: self.column_order.clone(),
199            row_count: n,
200            estimated_rows: n,
201            plan: Arc::clone(&self.plan),
202            row_dirty: vec![0; self.columns.len().div_ceil(64)],
203            frozen: self.frozen.clone(),
204            unknown_error: None,
205            row_buf: if self.plan.filter.is_some() {
206                Some(Box::new(RowBuffer {
207                    fields: SmallVec::new(),
208                    state: PredicateState::Undecided,
209                    predicate_mask: self
210                        .row_buf
211                        .as_ref()
212                        .map_or_else(SmallVec::new, |b| b.predicate_mask.clone()),
213                    direct: false,
214                    predicate_ordinal: None,
215                    buffer_worthwhile: true,
216                    pred_names: self
217                        .row_buf
218                        .as_ref()
219                        .map_or_else(SmallVec::new, |b| b.pred_names.clone()),
220                }))
221            } else {
222                None
223            },
224            ordinal_expect: Vec::new(),
225            current_ordinal: 0,
226        };
227        for (idx, col) in self.columns.iter_mut().enumerate() {
228            let drain = col.split_off(n);
229            other.columns.push(drain);
230            // Remainder stays in self.columns[idx]
231            let _ = idx;
232        }
233        self.row_count -= n;
234        // row_dirty for self should be all false (no dirty in remainder yet)
235        self.row_dirty = vec![0; self.columns.len().div_ceil(64)];
236        // row_dirty for other is also false (just finished batch)
237        other
238    }
239
240    /// Remove and return a column by name, fixing the Vec index map.
241    /// Used by `merge::extend` to move builders out of the `other` table.
242    pub(crate) fn take_column(&mut self, name: &str) -> Option<ColumnBuilder> {
243        let idx = self.field_index.remove(name)?;
244        // Keep row_dirty in sync: Vec<u64> bitmask, need to handle bit removal
245        // For simplicity, just rebuild row_dirty as all zeros after column removal
246        // (row_dirty is per-row, not per-column persistent, so clearing is fine)
247        // Rebuild to correct length
248        let new_len = self.columns.len().div_ceil(64);
249        self.row_dirty.resize(new_len, 0);
250        // Clear all bits (no dirty in remainder for take_column case)
251        self.row_dirty.fill(0);
252        let _ = idx; // suppress unused warning
253                     // After removal, columns.len() == old_len; last index = old_len - 1.
254                     // swap_remove will move the last element into idx (if not already last).
255        let last = self.columns.len() - 1;
256        let col = if idx == last {
257            self.columns.pop().unwrap()
258        } else {
259            let col = self.columns.swap_remove(idx);
260            // The element that was at `last` is now at `idx`; fix its map entry.
261            let old_last = self.columns.len(); // == last, new len after pop/swap
262                                               // Find the key that pointed to old_last and repoint it to idx.
263                                               // We must not borrow field_index mutably while iterating, so clone the key first.
264            let moved_name = self.field_index.iter().find_map(|(k, &v)| {
265                if v == old_last {
266                    Some(k.clone())
267                } else {
268                    None
269                }
270            });
271            if let Some(k) = moved_name {
272                self.field_index.insert(k, idx);
273            }
274            col
275        };
276        Some(col)
277    }
278
279    pub fn num_rows(&self) -> usize {
280        self.row_count
281    }
282
283    pub fn num_columns(&self) -> usize {
284        self.column_order.len()
285    }
286
287    pub fn column_names(&self) -> &[String] {
288        &self.column_order
289    }
290
291    /// Diagnostic: (name, bytes_used, bytes_capacity) for each column.
292    pub fn column_diagnostics(&self) -> Vec<(String, usize, usize)> {
293        self.column_order
294            .iter()
295            .map(|name| {
296                let idx = self.field_index[name];
297                let col = &self.columns[idx];
298                (name.clone(), col.bytes_used(), col.capacity_bytes())
299            })
300            .collect()
301    }
302
303    /// The estimated_rows capacity hint passed to with_plan.
304    pub fn estimated_rows(&self) -> usize {
305        self.estimated_rows
306    }
307
308    /// Finalize the builder into an Arrow `RecordBatch`.
309    ///
310    /// This is also available as the `ColumnarSink::finish` trait method.
311    pub fn finish(&mut self) -> Result<RecordBatch> {
312        ColumnarSink::finish(self)
313    }
314
315    /// Reset all data while preserving the plan and estimated rows.
316    pub fn reset(&mut self) {
317        self.columns.clear();
318        self.field_index.clear();
319        self.column_order.clear();
320        self.row_dirty.fill(0);
321        self.row_count = 0;
322        if let Some(ref mut buf) = self.row_buf {
323            buf.fields.clear();
324            buf.state = PredicateState::Undecided;
325        }
326        // Keep frozen/row_buf (per builder, not per row)
327        self.unknown_error = None;
328    }
329
330    /// Truncate every column back to `row_count`, dropping any partial-row
331    /// values from a mid-field EOF.  Idempotent.
332    pub fn normalize(&mut self) {
333        for b in &mut self.columns {
334            while b.len() > self.row_count {
335                b.pop();
336            }
337        }
338        // Discard any dirty state for the partial row.
339        self.row_dirty.fill(0);
340    }
341
342    /// If `auto_dict` is set, upgrade low-cardinality string columns using the
343    /// plan's threshold/max-size tuning (defaults: 5% ratio, max size 256).
344    pub fn auto_dict_upgrade(&mut self) {
345        if self.plan.auto_dict {
346            let max_ratio = self.plan.dict_threshold.unwrap_or(0.05);
347            let max_size = self.plan.dict_max_size.unwrap_or(256);
348            for b in &mut self.columns {
349                b.try_upgrade_to_dict(512, max_ratio, max_size);
350            }
351        }
352    }
353
354    /// Sort columns according to `schema_order`.  Columns named in
355    /// `schema_order` appear in that order; any other columns keep their
356    /// relative first-appearance order after the ordered ones.
357    pub fn sort_columns(&mut self) {
358        if self.plan.schema_order.is_empty() {
359            return;
360        }
361        let order = &self.plan.schema_order;
362        let rank = |name: &String| order.iter().position(|n| n == name).unwrap_or(usize::MAX);
363        self.column_order.sort_by_key(rank);
364    }
365
366    pub(crate) fn schema_insert_index(&self, name: &str) -> usize {
367        let order = &self.plan.schema_order;
368        if order.is_empty() {
369            return self.column_order.len();
370        }
371        let pos = order.iter().position(|n| n == name);
372        match pos {
373            Some(p) => self
374                .column_order
375                .iter()
376                .position(|existing| {
377                    order
378                        .iter()
379                        .position(|n| n == existing)
380                        .is_some_and(|ep| ep > p)
381                })
382                .unwrap_or(self.column_order.len()),
383            None => self.column_order.len(),
384        }
385    }
386
387    /// Ensure the column exists and return its Vec index.
388    /// Single hash lookup for the hot path; new columns are created and
389    /// inserted into `column_order` via `schema_insert_index`.
390    fn ensure_column_idx(&mut self, name: &str) -> usize {
391        if let Some(&idx) = self.field_index.get(name) {
392            return idx;
393        }
394        // Frozen schema: any new column not pre-sized by ensure_schema is an
395        // unknown field (sampling miss or file has column absent during
396        // discovery). Don't silently create it; hard-error on finish().
397        // We still return a dummy idx to keep the hot path inlinable, but
398        // push_field_resolved will have already early-returned after setting
399        // unknown_error, so this path is only for non-frozen builders.
400        if self.frozen.is_some() {
401            // Should have been caught in push_field_resolved; if we reach
402            // here, treat as unknown and record.
403            if let Some(frozen) = &self.frozen {
404                if self.unknown_error.is_none() {
405                    self.unknown_error = Some(format!(
406                        "unknown field {:?} not in frozen schema ({} columns, exact={}); pass schema=[...] with full column list or use full-scan discovery",
407                        name,
408                        frozen.num_columns(),
409                        frozen.is_exact()
410                    ));
411                }
412            }
413            // Return 0 as dummy to avoid panic; caller will have returned.
414            return 0;
415        }
416        let est = self.estimated_rows.max(64);
417        let col_type = self.plan.column_type(name);
418        let mut b = ColumnBuilder::with_capacity(est, &col_type);
419        // When the predicate passes mid-row, drain_buffered increments
420        // row_count before all fields are pushed. New columns created after
421        // that must backfill row_count-1 Nones (for the already-committed
422        // rows), not row_count, because the current row's value follows.
423        let backfill = if self.row_buf.as_ref().is_some_and(|b| b.direct) {
424            self.row_count.saturating_sub(1)
425        } else {
426            self.row_count
427        };
428        for _ in 0..backfill {
429            b.push(None);
430        }
431        let idx = self.columns.len();
432        self.columns.push(b);
433        self.field_index.insert(name.to_owned(), idx);
434        // Ensure row_dirty has enough words for new column
435        let needed = self.columns.len().div_ceil(64);
436        if self.row_dirty.len() < needed {
437            self.row_dirty.resize(needed, 0);
438        }
439        let order_idx = self.schema_insert_index(name);
440        self.column_order.insert(order_idx, name.to_owned());
441        idx
442    }
443
444    /// Push a field value without resolving renames/drops.
445    /// Caller must have already resolved `resolved_name` (or know it is kept).
446    #[inline]
447    fn push_field_resolved(&mut self, resolved_name: &str, value: Value<'_>) {
448        // #[inline]: small hot path, called per-field. ensure_column_idx is not
449        // inlined (too large); push_value is the real work and benefits from
450        // being in the same compilation unit as its caller.
451        // Frozen check: hard error on unknown field (data loss would be silent
452        // on a default path). Sampling 16×2 MiB covers ~6% of 533 MB, so 0.05%
453        // column would be missed.
454        if self.frozen.is_some() && !self.field_index.contains_key(resolved_name) {
455            if let Some(frozen) = &self.frozen {
456                if self.unknown_error.is_none() {
457                    self.unknown_error = Some(format!(
458                        "unknown field {:?} not in frozen schema ({} columns, exact={}); pass schema=[...] with full column list or use full-scan discovery",
459                        resolved_name,
460                        frozen.num_columns(),
461                        frozen.is_exact()
462                    ));
463                }
464            }
465            return;
466        }
467        let idx = self.ensure_column_idx(resolved_name);
468        // Track ordinal→slot mapping on first row for expect_slot fast path.
469        if self.row_count == 0 {
470            let ord = self.current_ordinal as usize;
471            if ord >= self.ordinal_expect.len() {
472                self.ordinal_expect.resize_with(ord + 1, || None);
473            }
474            self.ordinal_expect[ord] = Some((idx as u32, resolved_name.as_bytes().to_vec()));
475        }
476        self.current_ordinal += 1;
477        let word = idx / 64;
478        let bit = idx % 64;
479        self.row_dirty[word] |= 1u64 << bit;
480        let b = &mut self.columns[idx];
481        let row_count = self.row_count;
482        if b.len() > row_count {
483            b.pop();
484        }
485        b.push_value(value);
486    }
487
488    /// Push a field value, resolving renames/drops and applying last-write-wins
489    /// within the current uncommitted row.
490    #[inline]
491    fn push_field(&mut self, name: &str, value: Value<'_>) {
492        // #[inline]: fast-path (no rename/drop) is a single branch + delegate.
493        // Fast path: no rename/drop configured; zero allocation.
494        if self.plan.field_map.is_empty() && self.plan.drop_fields.is_empty() {
495            self.push_field_resolved(name, value);
496            return;
497        }
498        // Resolve name via plan's field_map (borrows &self.plan).
499        // Try the zero-allocation fast path: column already exists.
500        if let Some(idx) = Self::resolve_and_slot(&self.plan, &self.field_index, name) {
501            // Track ordinal→slot mapping on first row for expect_slot fast path.
502            if self.row_count == 0 {
503                let ord = self.current_ordinal as usize;
504                if ord >= self.ordinal_expect.len() {
505                    self.ordinal_expect.resize_with(ord + 1, || None);
506                }
507                // Store the resolved name (what plan.resolve_field would return).
508                let resolved = self.plan.resolve_field(name).unwrap_or(name);
509                self.ordinal_expect[ord] = Some((idx as u32, resolved.as_bytes().to_vec()));
510            }
511            self.current_ordinal += 1;
512            let word = idx / 64;
513            let bit = idx % 64;
514            self.row_dirty[word] |= 1u64 << bit;
515            let b = &mut self.columns[idx];
516            let row_count = self.row_count;
517            if b.len() > row_count {
518                b.pop();
519            }
520            b.push_value(value);
521        } else {
522            // Column doesn't exist yet (first row with rename) or field was
523            // dropped. Only allocate when the field is kept.
524            if let Some(resolved) = self.plan.resolve_field(name) {
525                let owned = resolved.to_owned();
526                self.push_field_resolved(&owned, value);
527            }
528        }
529    }
530
531    /// Resolve a field name through the plan's field_map and look up its slot
532    /// index. Returns `Some(slot)` only if the column already exists in
533    /// field_index. Zero allocation; borrows plan and field_index as
534    /// separate fields.
535    #[inline]
536    fn resolve_and_slot(
537        plan: &ExecutionPlan,
538        field_index: &HashMap<String, usize>,
539        name: &str,
540    ) -> Option<usize> {
541        let resolved = plan.resolve_field(name)?;
542        field_index.get(resolved).copied()
543    }
544
545    /// Advance the row counter without null-fill, filter, or dirty-mask clear.
546    /// For benchmarking only; separates per-field push cost from per-row
547    /// finalization.
548    #[doc(hidden)]
549    pub fn advance_row(&mut self) {
550        self.row_count += 1;
551    }
552
553    /// Null-fill any column missing this row, then apply the per-row filter.
554    /// If the filter rejects the row, undo it by popping values.
555    /// Uses the dirty bitmask so only missing columns are touched; fast path
556    /// when every column was set (dense data, 10 cols) skips the loop.
557    fn finish_row(&mut self) {
558        // No #[inline]: 30+ lines with loops; inlining causes code bloat.
559        let ncols = self.columns.len();
560        // Fast path: check if all bits set
561        let full_words = ncols / 64;
562        let rem_bits = ncols % 64;
563        let is_full = (0..full_words).all(|w| self.row_dirty[w] == u64::MAX)
564            && (rem_bits == 0
565                || self.row_dirty.get(full_words).copied().unwrap_or(0) == (1u64 << rem_bits) - 1);
566        if is_full {
567            self.row_dirty.fill(0);
568        } else {
569            for (i, b) in self.columns.iter_mut().enumerate() {
570                let word = i / 64;
571                let bit = i % 64;
572                let is_set = (self.row_dirty[word] >> bit) & 1 == 1;
573                if !is_set {
574                    b.push(None);
575                }
576            }
577            self.row_dirty.fill(0);
578        }
579
580        if let Some(ref filter) = self.plan.filter {
581            if !filter.check(&self.columns, &self.field_index, self.row_count, &self.plan) {
582                for b in &mut self.columns {
583                    b.pop();
584                }
585                return;
586            }
587        }
588
589        self.row_count += 1;
590    }
591
592    // Predicate-first helpers
593    /// Build the predicate bitmask from field_index. Called lazily on first
594    /// `is_predicate_slot` call when the mask is still empty.
595    fn build_predicate_mask(&mut self) {
596        let buf = match self.row_buf {
597            Some(ref mut b) => b,
598            None => return,
599        };
600        if !buf.pred_names.is_empty() {
601            return; // already built (pred_names populated)
602        }
603        // Collect predicate field names (one-time clone of the filter).
604        let mut names: SmallVec<[String; 4]> = SmallVec::new();
605        if let Some(ref f) = self.plan.filter.clone() {
606            Self::collect_predicate_field_names(f, &self.plan, &mut names);
607        }
608        // Cache the names so future calls can check without cloning.
609        buf.pred_names.clone_from(&names);
610        // Grow mask to cover all columns.
611        let ncols = self.columns.len();
612        let words = ncols.div_ceil(64);
613        buf.predicate_mask.resize(words, 0);
614        // Mark slots for predicate fields that already exist.
615        for name in &names {
616            if let Some(&slot) = self.field_index.get(name.as_str()) {
617                let word = slot / 64;
618                let bit = slot % 64;
619                if word < buf.predicate_mask.len() {
620                    buf.predicate_mask[word] |= 1u64 << bit;
621                }
622            }
623        }
624    }
625
626    /// Mark a slot as a predicate column by checking cached predicate names.
627    /// Called once per new column to handle fields created after the initial
628    /// mask build (e.g., the predicate column appears in the data after
629    /// `build_predicate_mask` already ran for earlier columns).
630    #[inline]
631    fn mark_predicate_slot(&mut self, slot: u32) {
632        if self.plan.filter.is_none() {
633            return;
634        }
635        // Phase 1: check fast path (already marked) via immutable borrow,
636        // then check if pred_names are populated.  Avoid holding &mut buf
637        // across build_predicate_mask (which needs &mut self).
638        let needs_build = self.row_buf.as_ref().is_some_and(|buf| {
639            let word = slot as usize / 64;
640            let bit = slot as usize % 64;
641            if word < buf.predicate_mask.len() && (buf.predicate_mask[word] >> bit) & 1 == 1 {
642                return false; // already marked; no-op
643            }
644            buf.pred_names.is_empty() // need to build the mask
645        });
646        if needs_build {
647            self.build_predicate_mask();
648        }
649        // Phase 2: check if this slot is now marked after build.
650        if let Some(ref buf) = self.row_buf {
651            let word = slot as usize / 64;
652            let bit = slot as usize % 64;
653            if word < buf.predicate_mask.len() && (buf.predicate_mask[word] >> bit) & 1 == 1 {
654                return; // marked during build or was already marked
655            }
656        }
657        // Phase 3: mask is built but this slot isn't in it. Check if the
658        // column name matches any cached predicate name (no filter clone).
659        if let Some(col_name) = self.column_order.get(slot as usize) {
660            let is_pred = self
661                .row_buf
662                .as_ref()
663                .is_some_and(|buf| buf.pred_names.iter().any(|n| n == col_name));
664            if is_pred {
665                let buf = self.row_buf.as_mut().unwrap();
666                let word = slot as usize / 64;
667                let bit = slot as usize % 64;
668                if word >= buf.predicate_mask.len() {
669                    buf.predicate_mask.resize(word + 1, 0);
670                }
671                buf.predicate_mask[word] |= 1u64 << bit;
672            }
673        }
674    }
675
676    fn collect_predicate_field_names(
677        pred: &FilterPredicate,
678        plan: &ExecutionPlan,
679        names: &mut SmallVec<[String; 4]>,
680    ) {
681        match pred {
682            FilterPredicate::Equal { field, .. } | FilterPredicate::NotEqual { field, .. } => {
683                let resolved = plan.resolve_field(field).unwrap_or(field);
684                names.push(resolved.to_string());
685            }
686            FilterPredicate::Compare {
687                field_a, field_b, ..
688            } => {
689                for f in [field_a, field_b] {
690                    let resolved = plan.resolve_field(f).unwrap_or(f);
691                    names.push(resolved.to_string());
692                }
693            }
694            FilterPredicate::And(a, b) | FilterPredicate::Or(a, b) => {
695                Self::collect_predicate_field_names(a, plan, names);
696                Self::collect_predicate_field_names(b, plan, names);
697            }
698            FilterPredicate::Not(inner) => Self::collect_predicate_field_names(inner, plan, names),
699        }
700    }
701
702    #[inline]
703    fn is_predicate_slot(&self, slot: u32) -> bool {
704        self.row_buf.as_ref().is_some_and(|b| {
705            let word = slot as usize / 64;
706            let bit = slot as usize % 64;
707            word < b.predicate_mask.len() && (b.predicate_mask[word] >> bit) & 1 == 1
708        })
709    }
710
711    fn get_buffered_value(&self, field: &str) -> Option<&Value<'static>> {
712        let buf = self.row_buf.as_ref()?;
713        let resolved = self.plan.resolve_field(field)?;
714        let slot = *self.field_index.get(resolved)? as u32;
715        for (s, v) in buf.fields.iter().rev() {
716            if *s == slot {
717                return Some(v);
718            }
719        }
720        None
721    }
722
723    fn get_buffered_str(&self, field: &str) -> Option<String> {
724        match self.get_buffered_value(field) {
725            Some(Value::Str(s)) => Some(s.to_string()),
726            Some(Value::Int64(i)) => Some(i.to_string()),
727            Some(Value::Float64(f)) => Some(f.to_string()),
728            Some(Value::Bool(b)) => Some(b.to_string()),
729            Some(v) => Some(format!("{:?}", v)),
730            None => None,
731        }
732    }
733
734    fn evaluate_predicate_state(&self) -> PredicateState {
735        let Some(ref pred) = self.plan.filter else {
736            return PredicateState::Pass;
737        };
738        #[cfg(feature = "profile")]
739        {
740            crate::engine::PREDICATE_EVALUATIONS.fetch_add(1, Ordering::Relaxed);
741        }
742        let result = Self::eval_predicate(pred, self);
743        #[cfg(feature = "profile")]
744        match result {
745            PredicateState::Fail => {
746                crate::engine::PREDICATE_FAILS.fetch_add(1, Ordering::Relaxed);
747            }
748            PredicateState::Undecided => {
749                crate::engine::PREDICATE_UNDECIDED.fetch_add(1, Ordering::Relaxed);
750            }
751            _ => {}
752        }
753        result
754    }
755
756    fn eval_predicate(pred: &FilterPredicate, tb: &TableBuilder) -> PredicateState {
757        match pred {
758            FilterPredicate::Equal { field, value } => match tb.get_buffered_str(field) {
759                Some(actual) => {
760                    if actual == *value {
761                        PredicateState::Pass
762                    } else {
763                        PredicateState::Fail
764                    }
765                }
766                None => PredicateState::Undecided,
767            },
768            FilterPredicate::NotEqual { field, value } => match tb.get_buffered_str(field) {
769                Some(actual) => {
770                    if actual != *value {
771                        PredicateState::Pass
772                    } else {
773                        PredicateState::Fail
774                    }
775                }
776                None => PredicateState::Undecided,
777            },
778            FilterPredicate::Compare {
779                field_a,
780                op,
781                field_b,
782            } => {
783                let normalize = |field: &str, value: &Value<'static>| {
784                    let field = tb.plan.resolve_field(field).unwrap_or(field);
785                    match tb.plan.column_type(field) {
786                        FieldType::Int64 => match value.as_str() {
787                            Some(s) => lexical::parse::<i64, _>(s.as_bytes())
788                                .ok()
789                                .map(Value::Int64),
790                            _ => Some(value.clone()),
791                        },
792                        FieldType::Float64 => match value.as_str() {
793                            Some(s) => lexical::parse::<f64, _>(s.as_bytes())
794                                .ok()
795                                .map(Value::Float64),
796                            _ => Some(value.clone()),
797                        },
798                        FieldType::Boolean => match value.as_str() {
799                            Some(s) => s.parse::<bool>().ok().map(Value::Bool),
800                            _ => Some(value.clone()),
801                        },
802                        FieldType::Date32 => match value.as_str() {
803                            Some(s) => crate::columnar::parse_date32(s).map(Value::Date32),
804                            _ => Some(value.clone()),
805                        },
806                        FieldType::Timestamp(unit) => match value.as_str() {
807                            Some(s) => {
808                                crate::columnar::parse_timestamp(s, unit).map(Value::Timestamp)
809                            }
810                            _ => Some(value.clone()),
811                        },
812                        FieldType::String | FieldType::Dictionary => Some(value.clone()),
813                    }
814                };
815                let va = tb
816                    .get_buffered_value(field_a)
817                    .and_then(|value| normalize(field_a, value));
818                let vb = tb
819                    .get_buffered_value(field_b)
820                    .and_then(|value| normalize(field_b, value));
821                match (va, vb) {
822                    (Some(ref a), Some(ref b)) => {
823                        let ord = match (a, b) {
824                            (crate::value::Value::Int64(ai), crate::value::Value::Int64(bi)) => {
825                                Some(ai.cmp(bi))
826                            }
827                            (
828                                crate::value::Value::Float64(af),
829                                crate::value::Value::Float64(bf),
830                            ) => af.partial_cmp(bf),
831                            (crate::value::Value::Int64(ai), crate::value::Value::Float64(bf)) => {
832                                (*ai as f64).partial_cmp(bf)
833                            }
834                            (crate::value::Value::Float64(af), crate::value::Value::Int64(bi)) => {
835                                af.partial_cmp(&(*bi as f64))
836                            }
837                            (crate::value::Value::Str(a), crate::value::Value::Str(b)) => {
838                                let resolved_a =
839                                    tb.plan.resolve_field(field_a).unwrap_or(field_a.as_str());
840                                let resolved_b =
841                                    tb.plan.resolve_field(field_b).unwrap_or(field_b.as_str());
842                                let type_a = tb.plan.field_types.get(resolved_a);
843                                let type_b = tb.plan.field_types.get(resolved_b);
844                                match (type_a, type_b) {
845                                    (
846                                        Some(crate::plan::FieldType::Int64),
847                                        Some(crate::plan::FieldType::Int64),
848                                    ) => {
849                                        let ai: i64 =
850                                            lexical::parse(a.as_bytes()).ok().unwrap_or(0);
851                                        let bi: i64 =
852                                            lexical::parse(b.as_bytes()).ok().unwrap_or(0);
853                                        Some(ai.cmp(&bi))
854                                    }
855                                    (
856                                        Some(crate::plan::FieldType::Float64),
857                                        Some(crate::plan::FieldType::Float64),
858                                    ) => {
859                                        let af: f64 =
860                                            lexical::parse(a.as_bytes()).ok().unwrap_or(0.0);
861                                        let bf: f64 =
862                                            lexical::parse(b.as_bytes()).ok().unwrap_or(0.0);
863                                        af.partial_cmp(&bf)
864                                    }
865                                    (
866                                        Some(crate::plan::FieldType::Int64),
867                                        Some(crate::plan::FieldType::Float64),
868                                    ) => {
869                                        let ai: f64 = lexical::parse::<i64, _>(a.as_bytes())
870                                            .ok()
871                                            .unwrap_or(0)
872                                            as f64;
873                                        let bf: f64 =
874                                            lexical::parse(b.as_bytes()).ok().unwrap_or(0.0);
875                                        ai.partial_cmp(&bf)
876                                    }
877                                    (
878                                        Some(crate::plan::FieldType::Float64),
879                                        Some(crate::plan::FieldType::Int64),
880                                    ) => {
881                                        let af: f64 =
882                                            lexical::parse(a.as_bytes()).ok().unwrap_or(0.0);
883                                        let bi: f64 = lexical::parse::<i64, _>(b.as_bytes())
884                                            .ok()
885                                            .unwrap_or(0)
886                                            as f64;
887                                        af.partial_cmp(&bi)
888                                    }
889                                    // Mixed typed/untyped or String vs non-numeric type:
890                                    // type mismatch; fail the comparison.
891                                    (Some(_), None) | (None, Some(_)) => None,
892                                    // Both untyped (String): fall back to lexicographic.
893                                    (None, None) => Some(a.cmp(b)),
894                                    // Both Timestamp: parse and compare as i64.
895                                    (
896                                        Some(crate::plan::FieldType::Timestamp(ua)),
897                                        Some(crate::plan::FieldType::Timestamp(ub)),
898                                    ) => {
899                                        let ta = crate::columnar::parse_timestamp(a.as_ref(), *ua);
900                                        let tb_val =
901                                            crate::columnar::parse_timestamp(b.as_ref(), *ub);
902                                        match (ta, tb_val) {
903                                            (Some(ai), Some(bi)) => Some(ai.cmp(&bi)),
904                                            _ => None,
905                                        }
906                                    }
907                                    // Both Date32: parse and compare as i32.
908                                    (
909                                        Some(crate::plan::FieldType::Date32),
910                                        Some(crate::plan::FieldType::Date32),
911                                    ) => {
912                                        let da = crate::columnar::parse_date32(a.as_ref());
913                                        let db = crate::columnar::parse_date32(b.as_ref());
914                                        match (da, db) {
915                                            (Some(ai), Some(bi)) => Some(ai.cmp(&bi)),
916                                            _ => None,
917                                        }
918                                    }
919                                    // Different non-numeric types (e.g. String vs Bool): fail.
920                                    _ => None,
921                                }
922                            }
923                            (crate::value::Value::Bool(a), crate::value::Value::Bool(b)) => {
924                                Some(a.cmp(b))
925                            }
926                            _ => {
927                                let av = format!("{:?}", a);
928                                let bv = format!("{:?}", b);
929                                Some(av.cmp(&bv))
930                            }
931                        };
932                        let pass = ord.is_some_and(|ord| match op {
933                            crate::plan::CompareOp::Gt => ord == std::cmp::Ordering::Greater,
934                            crate::plan::CompareOp::Lt => ord == std::cmp::Ordering::Less,
935                            crate::plan::CompareOp::Ge => ord != std::cmp::Ordering::Less,
936                            crate::plan::CompareOp::Le => ord != std::cmp::Ordering::Greater,
937                            crate::plan::CompareOp::Eq => ord == std::cmp::Ordering::Equal,
938                            crate::plan::CompareOp::Ne => ord != std::cmp::Ordering::Equal,
939                        });
940                        if pass {
941                            PredicateState::Pass
942                        } else {
943                            PredicateState::Fail
944                        }
945                    }
946                    _ => PredicateState::Undecided,
947                }
948            }
949            FilterPredicate::And(a, b) => {
950                let sa = Self::eval_predicate(a, tb);
951                let sb = Self::eval_predicate(b, tb);
952                match (sa, sb) {
953                    (PredicateState::Fail, _) | (_, PredicateState::Fail) => PredicateState::Fail,
954                    (PredicateState::Pass, PredicateState::Pass) => PredicateState::Pass,
955                    _ => PredicateState::Undecided,
956                }
957            }
958            FilterPredicate::Or(a, b) => {
959                let sa = Self::eval_predicate(a, tb);
960                let sb = Self::eval_predicate(b, tb);
961                match (sa, sb) {
962                    (PredicateState::Pass, _) | (_, PredicateState::Pass) => PredicateState::Pass,
963                    (PredicateState::Fail, PredicateState::Fail) => PredicateState::Fail,
964                    _ => PredicateState::Undecided,
965                }
966            }
967            FilterPredicate::Not(inner) => match Self::eval_predicate(inner, tb) {
968                PredicateState::Pass => PredicateState::Fail,
969                PredicateState::Fail => PredicateState::Pass,
970                PredicateState::Undecided => PredicateState::Undecided,
971            },
972        }
973    }
974
975    fn drain_buffered(&mut self, pass: bool) {
976        let buf = match self.row_buf {
977            Some(ref mut b) => b,
978            None => return,
979        };
980        if pass {
981            // Deduplicate last-write-wins by slot index (u32).
982            // O(n) reverse scan with a u64 bitmask; first hit in reverse is
983            // the last write in forward order (last-write-wins).
984            let ncols = self.columns.len();
985            let words = ncols.div_ceil(64);
986            if self.row_dirty.len() < words {
987                self.row_dirty.resize(words, 0);
988            }
989            let mut seen: u64 = 0;
990            let mut seen_extra: SmallVec<[u64; 1]> = SmallVec::new();
991            if words > 1 {
992                seen_extra.resize(words - 1, 0);
993            }
994            for &(slot, ref val) in buf.fields.iter().rev() {
995                let word = slot as usize / 64;
996                let bit = slot as usize % 64;
997                let mask = 1u64 << bit;
998                let already = if word == 0 {
999                    seen & mask != 0
1000                } else {
1001                    seen_extra.get(word - 1).is_some_and(|w| w & mask != 0)
1002                };
1003                if already {
1004                    continue;
1005                }
1006                if word == 0 {
1007                    seen |= mask;
1008                } else if let Some(w) = seen_extra.get_mut(word - 1) {
1009                    *w |= mask;
1010                }
1011                self.row_dirty[word] |= mask;
1012                let b = &mut self.columns[slot as usize];
1013                if b.len() > self.row_count {
1014                    b.pop();
1015                }
1016                b.push_value(val.clone());
1017            }
1018            // Null-fill missing columns and handle filter/dirty, then increment row_count.
1019            // Skip null-fill when called mid-row (buf.direct = true): the remaining
1020            // fields will be pushed via the direct path, and end_row's
1021            // null_fill_missing handles any columns that don't appear.
1022            if !buf.direct {
1023                let ncols = self.columns.len();
1024                let full_words = ncols / 64;
1025                let rem_bits = ncols % 64;
1026                let is_full = (0..full_words).all(|w| self.row_dirty[w] == u64::MAX)
1027                    && (rem_bits == 0
1028                        || self.row_dirty.get(full_words).copied().unwrap_or(0)
1029                            == (1u64 << rem_bits) - 1);
1030                if is_full {
1031                    self.row_dirty.fill(0);
1032                } else {
1033                    for (i, b) in self.columns.iter_mut().enumerate() {
1034                        let word = i / 64;
1035                        let bit = i % 64;
1036                        let is_set = (self.row_dirty[word] >> bit) & 1 == 1;
1037                        if !is_set {
1038                            b.push(None);
1039                        }
1040                    }
1041                    self.row_dirty.fill(0);
1042                }
1043            } else {
1044                // Mid-row: keep dirty bits set so null_fill_missing in end_row
1045                // can take the is_full fast path when all columns were pushed.
1046            }
1047            self.row_count += 1;
1048        } else {
1049            // Fail: discard buffered fields, no row increment, clear dirty
1050            buf.fields.clear();
1051            self.row_dirty.fill(0);
1052        }
1053        // Ensure fields are cleared for next row
1054        if !buf.fields.is_empty() {
1055            buf.fields.clear();
1056        }
1057        buf.state = PredicateState::Undecided;
1058    }
1059
1060    fn evaluate_against_null(&self) -> PredicateState {
1061        // At end_row, any predicate field still missing is NULL.
1062        // For Equal with missing => Fail, NotEqual with missing => Pass (as per old finish_row check where get_value returns None)
1063        // For Compare with missing => Fail.
1064        // We can reuse eval_predicate which returns Undecided for missing, then map Undecided to Pass/Fail per leaf semantics.
1065        let Some(ref pred) = self.plan.filter else {
1066            return PredicateState::Pass;
1067        };
1068        Self::eval_predicate_with_null(pred, self)
1069    }
1070
1071    fn eval_predicate_with_null(pred: &FilterPredicate, tb: &TableBuilder) -> PredicateState {
1072        match pred {
1073            FilterPredicate::Equal { field, value } => match tb.get_buffered_str(field) {
1074                Some(actual) => {
1075                    if actual == *value {
1076                        PredicateState::Pass
1077                    } else {
1078                        PredicateState::Fail
1079                    }
1080                }
1081                None => PredicateState::Fail, // missing => None != Some(value) => Fail for Equal
1082            },
1083            FilterPredicate::NotEqual { field, value } => match tb.get_buffered_str(field) {
1084                Some(actual) => {
1085                    if actual != *value {
1086                        PredicateState::Pass
1087                    } else {
1088                        PredicateState::Fail
1089                    }
1090                }
1091                None => PredicateState::Pass, // missing => None != Some(value) => Pass
1092            },
1093            FilterPredicate::Compare { .. } => {
1094                // Compare with missing => Fail (as per old check where get_typed_value returns None)
1095                match Self::eval_predicate(pred, tb) {
1096                    PredicateState::Undecided => PredicateState::Fail,
1097                    other => other,
1098                }
1099            }
1100            FilterPredicate::And(a, b) => {
1101                let sa = Self::eval_predicate_with_null(a, tb);
1102                let sb = Self::eval_predicate_with_null(b, tb);
1103                match (sa, sb) {
1104                    (PredicateState::Fail, _) | (_, PredicateState::Fail) => PredicateState::Fail,
1105                    (PredicateState::Pass, PredicateState::Pass) => PredicateState::Pass,
1106                    _ => PredicateState::Undecided, // Should not happen after null mapping, but treat as Fail?
1107                }
1108            }
1109            FilterPredicate::Or(a, b) => {
1110                let sa = Self::eval_predicate_with_null(a, tb);
1111                let sb = Self::eval_predicate_with_null(b, tb);
1112                match (sa, sb) {
1113                    (PredicateState::Pass, _) | (_, PredicateState::Pass) => PredicateState::Pass,
1114                    (PredicateState::Fail, PredicateState::Fail) => PredicateState::Fail,
1115                    _ => PredicateState::Fail,
1116                }
1117            }
1118            FilterPredicate::Not(inner) => match Self::eval_predicate_with_null(inner, tb) {
1119                PredicateState::Pass => PredicateState::Fail,
1120                PredicateState::Fail => PredicateState::Pass,
1121                PredicateState::Undecided => PredicateState::Fail, // Not Undecided -> Fail?
1122            },
1123        }
1124    }
1125
1126    /// Null-fill any column missing the current row, then clear row_dirty.
1127    /// Called when the predicate resolved to Pass mid-row (direct mode).
1128    fn null_fill_missing(&mut self) {
1129        let ncols = self.columns.len();
1130        let full_words = ncols / 64;
1131        let rem_bits = ncols % 64;
1132        let is_full = (0..full_words).all(|w| self.row_dirty[w] == u64::MAX)
1133            && (rem_bits == 0
1134                || self.row_dirty.get(full_words).copied().unwrap_or(0) == (1u64 << rem_bits) - 1);
1135        if is_full {
1136            self.row_dirty.fill(0);
1137        } else {
1138            for (i, b) in self.columns.iter_mut().enumerate() {
1139                let word = i / 64;
1140                let bit = i % 64;
1141                let is_set = (self.row_dirty[word] >> bit) & 1 == 1;
1142                if !is_set {
1143                    b.push(None);
1144                }
1145            }
1146            self.row_dirty.fill(0);
1147        }
1148        // Note: row_count was already incremented by drain_buffered(true)
1149        // when the predicate resolved to Pass mid-row. Do NOT increment here.
1150    }
1151}
1152
1153impl Default for TableBuilder {
1154    fn default() -> Self {
1155        Self::new()
1156    }
1157}
1158
1159impl ColumnarSink for TableBuilder {
1160    #[inline]
1161    fn begin_row(&mut self) {
1162        self.current_ordinal = 0;
1163        if let Some(ref mut buf) = self.row_buf {
1164            // Adaptive strategy: after at least one committed row, decide
1165            // whether buffering is worthwhile based on the predicate column's
1166            // ordinal relative to the total number of columns.  We must wait
1167            // until row_count > 0 because early-rejected rows don't create
1168            // all columns, making ncols unreliable for the ordinal comparison.
1169            if buf.predicate_ordinal.is_some() && buf.buffer_worthwhile && self.row_count > 0 {
1170                // Use the most accurate column count available. self.columns.len()
1171                // is unreliable for sparse files where not all columns exist yet.
1172                let ncols = self
1173                    .frozen
1174                    .as_ref()
1175                    .map(|f| f.num_columns() as u32)
1176                    .or_else(|| {
1177                        (!self.plan.schema_order.is_empty())
1178                            .then(|| self.plan.schema_order.len() as u32)
1179                    })
1180                    .unwrap_or(self.columns.len() as u32);
1181                if let Some(ordinal) = buf.predicate_ordinal {
1182                    if ordinal >= ncols * 4 / 5 {
1183                        buf.buffer_worthwhile = false;
1184                    }
1185                }
1186            }
1187            buf.fields.clear();
1188            buf.state = PredicateState::Undecided;
1189            buf.direct = false;
1190        }
1191    }
1192
1193    #[inline]
1194    fn put_field(&mut self, name: &str, value: Value<'_>) {
1195        if self.plan.filter.is_none() {
1196            self.push_field(name, value);
1197            return;
1198        }
1199        // Adaptive: late predicate → push directly, pop-on-reject at end_row.
1200        let buf_worthwhile = self.row_buf.as_ref().is_none_or(|b| b.buffer_worthwhile);
1201        if !buf_worthwhile {
1202            self.push_field(name, value);
1203            return;
1204        }
1205        // Buffered path: resolve name → slot, buffer (slot, value).
1206        let resolved = match self.plan.resolve_field(name) {
1207            Some(r) => r.to_owned(),
1208            None => return,
1209        };
1210        // Check frozen unknown (as in push_field_resolved)
1211        if self.frozen.is_some()
1212            && !self.field_index.contains_key(&resolved)
1213            && self.unknown_error.is_none()
1214        {
1215            if let Some(ref frozen) = self.frozen {
1216                if !frozen.column_names().iter().any(|n| n.as_ref() == resolved) {
1217                    self.unknown_error = Some(format!(
1218                            "unknown field {:?} not in frozen schema ({} columns, exact={}); pass schema=[...]",
1219                            resolved,
1220                            frozen.num_columns(),
1221                            frozen.is_exact()
1222                        ));
1223                    return;
1224                }
1225            }
1226        }
1227        let slot = self.ensure_column_idx(&resolved) as u32;
1228        self.mark_predicate_slot(slot);
1229        let val_static: Value<'static> = value.into_static();
1230        let is_pred = self.is_predicate_slot(slot);
1231        #[cfg(feature = "profile")]
1232        if is_pred {
1233            crate::engine::IS_PRED_TRUE.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
1234        } else {
1235            crate::engine::IS_PRED_FALSE.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
1236        }
1237        // Push value to buffer BEFORE evaluating predicate (value must be findable).
1238        if let Some(ref mut buf) = self.row_buf {
1239            if let Some(pos) = buf.fields.iter().position(|(s, _)| *s == slot) {
1240                buf.fields[pos].1 = val_static;
1241            } else {
1242                buf.fields.push((slot, val_static));
1243            }
1244        }
1245        if is_pred {
1246            // Record predicate ordinal for adaptive strategy (once)
1247            if let Some(ref mut buf) = self.row_buf {
1248                if buf.predicate_ordinal.is_none() {
1249                    buf.predicate_ordinal = Some(slot);
1250                }
1251            }
1252            let state = self.evaluate_predicate_state();
1253            if let Some(ref mut buf) = self.row_buf {
1254                buf.state = state;
1255            }
1256        }
1257    }
1258
1259    #[inline]
1260    fn end_row(&mut self) {
1261        if self.plan.filter.is_none() {
1262            self.finish_row();
1263            return;
1264        }
1265        // Check adaptive strategy: if buffering is not worthwhile (late
1266        // predicate), use direct push + pop-on-reject (finish_row).
1267        let buf_worthwhile = self.row_buf.as_ref().is_none_or(|b| b.buffer_worthwhile);
1268        if !buf_worthwhile {
1269            // Late predicate: values were pushed directly to columns.
1270            // finish_row null-fills missing, evaluates filter against columns,
1271            // and pops on reject; exactly the pre-buffering behavior.
1272            self.finish_row();
1273            return;
1274        }
1275        // Buffered path
1276        let (state, direct) = self
1277            .row_buf
1278            .as_ref()
1279            .map_or((PredicateState::Pass, false), |b| (b.state, b.direct));
1280        if direct {
1281            // Already flushed to columns; just null-fill missing columns.
1282            self.null_fill_missing();
1283            return;
1284        }
1285        let state = if state == PredicateState::Undecided {
1286            self.evaluate_against_null()
1287        } else {
1288            state
1289        };
1290        let pass = state == PredicateState::Pass;
1291        self.drain_buffered(pass);
1292    }
1293
1294    #[inline]
1295    fn wants(&self, name: &str) -> bool {
1296        self.resolve(name).is_some()
1297    }
1298
1299    #[inline]
1300    fn resolve<'a>(&'a self, name: &'a str) -> Option<&'a str> {
1301        self.plan.resolve_field(name)
1302    }
1303
1304    #[inline]
1305    fn put_field_resolved(&mut self, resolved_name: &str, value: Value<'_>) {
1306        if self.plan.filter.is_none() {
1307            self.push_field_resolved(resolved_name, value);
1308            return;
1309        }
1310        // Adaptive: late predicate → push directly, pop-on-reject at end_row.
1311        let buf_worthwhile = self.row_buf.as_ref().is_none_or(|b| b.buffer_worthwhile);
1312        if !buf_worthwhile {
1313            self.push_field_resolved(resolved_name, value);
1314            return;
1315        }
1316        // Buffered path for already-resolved name (no rename lookup)
1317        if self.frozen.is_some() && !self.field_index.contains_key(resolved_name) {
1318            if let Some(ref frozen) = self.frozen {
1319                if !frozen
1320                    .column_names()
1321                    .iter()
1322                    .any(|n| n.as_ref() == resolved_name)
1323                {
1324                    if self.unknown_error.is_none() {
1325                        self.unknown_error = Some(format!(
1326                            "unknown field {:?} not in frozen schema ({} columns, exact={}); pass schema=[...]",
1327                            resolved_name,
1328                            frozen.num_columns(),
1329                            frozen.is_exact()
1330                        ));
1331                    }
1332                    return;
1333                }
1334            }
1335        }
1336        let slot = self.ensure_column_idx(resolved_name) as u32;
1337        self.mark_predicate_slot(slot);
1338        let val_static: Value<'static> = value.into_static();
1339        let is_pred = self.is_predicate_slot(slot);
1340        #[cfg(feature = "profile")]
1341        if is_pred {
1342            crate::engine::IS_PRED_TRUE.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
1343        } else {
1344            crate::engine::IS_PRED_FALSE.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
1345        }
1346        if let Some(ref mut buf) = self.row_buf {
1347            if let Some(pos) = buf.fields.iter().position(|(s, _)| *s == slot) {
1348                buf.fields[pos].1 = val_static;
1349            } else {
1350                buf.fields.push((slot, val_static));
1351            }
1352        }
1353        if is_pred {
1354            // Record predicate ordinal for adaptive strategy (once)
1355            if let Some(ref mut buf) = self.row_buf {
1356                if buf.predicate_ordinal.is_none() {
1357                    buf.predicate_ordinal = Some(slot);
1358                }
1359            }
1360            let state = self.evaluate_predicate_state();
1361            if let Some(ref mut buf) = self.row_buf {
1362                buf.state = state;
1363            }
1364        }
1365    }
1366
1367    /// Push a value directly to a known slot index, bypassing all name
1368    /// resolution and hash lookups.  Used by adapters that verified the
1369    /// field identity via `expect_slot` + memcmp on raw bytes.
1370    #[inline]
1371    fn put_field_at(&mut self, slot: u32, value: Value<'_>) {
1372        let idx = slot as usize;
1373        if idx >= self.columns.len() {
1374            // Slot doesn't exist yet (sparse row). Fall back to ensure.
1375            // This shouldn't happen after row 1 with a stable layout.
1376            return;
1377        }
1378        let word = idx / 64;
1379        let bit = idx % 64;
1380        self.row_dirty[word] |= 1u64 << bit;
1381        let b = &mut self.columns[idx];
1382        let row_count = self.row_count;
1383        if b.len() > row_count {
1384            b.pop();
1385        }
1386        b.push_value(value);
1387    }
1388
1389    #[inline]
1390    fn resolve_and_put(&mut self, name: &str, value: Value<'_>) {
1391        #[cfg(feature = "profile")]
1392        RESOLVE_AND_PUT_COUNT.fetch_add(1, Ordering::Relaxed);
1393        if self.plan.filter.is_none() {
1394            if self.plan.field_map.is_empty() && self.plan.drop_fields.is_empty() {
1395                self.push_field_resolved(name, value);
1396            } else {
1397                if let Some(resolved) = self.plan.resolve_field(name) {
1398                    let owned = resolved.to_owned();
1399                    self.push_field_resolved(&owned, value);
1400                }
1401            }
1402            return;
1403        }
1404        // Adaptive: late predicate → push directly, pop-on-reject at end_row.
1405        if self.row_buf.as_ref().is_some_and(|b| !b.buffer_worthwhile) {
1406            if self.plan.field_map.is_empty() && self.plan.drop_fields.is_empty() {
1407                self.push_field_resolved(name, value);
1408            } else {
1409                if let Some(resolved) = self.plan.resolve_field(name) {
1410                    let owned = resolved.to_owned();
1411                    self.push_field_resolved(&owned, value);
1412                }
1413            }
1414            return;
1415        }
1416        // Direct mode: predicate already passed, push directly to columns.
1417        if let Some(ref buf) = self.row_buf {
1418            if buf.direct {
1419                let resolved = match self.plan.resolve_field(name) {
1420                    Some(r) => r.to_owned(),
1421                    None => return, // field is dropped
1422                };
1423                if self.frozen.is_some() && !self.field_index.contains_key(resolved.as_str()) {
1424                    if let Some(ref frozen) = self.frozen {
1425                        if !frozen
1426                            .column_names()
1427                            .iter()
1428                            .any(|n| n.as_ref() == resolved.as_str())
1429                        {
1430                            if self.unknown_error.is_none() {
1431                                self.unknown_error = Some(format!(
1432                                    "unknown field {:?} not in frozen schema ({} columns, exact={}); pass schema=[...]",
1433                                    resolved, frozen.num_columns(), frozen.is_exact()
1434                                ));
1435                            }
1436                            return;
1437                        }
1438                    }
1439                }
1440                self.push_field_resolved(&resolved, value);
1441                return;
1442            }
1443        }
1444        // Buffered path: resolve → slot, buffer (slot, value).
1445        if self.plan.field_map.is_empty() && self.plan.drop_fields.is_empty() {
1446            // No rename/drop, raw == resolved
1447            let resolved = name;
1448            if self.frozen.is_some() && !self.field_index.contains_key(resolved) {
1449                if let Some(ref frozen) = self.frozen {
1450                    if !frozen.column_names().iter().any(|n| n.as_ref() == resolved) {
1451                        if self.unknown_error.is_none() {
1452                            self.unknown_error = Some(format!(
1453                                "unknown field {:?} not in frozen schema ({} columns, exact={}); pass schema=[...]",
1454                                resolved,
1455                                frozen.num_columns(),
1456                                frozen.is_exact()
1457                            ));
1458                        }
1459                        return;
1460                    }
1461                }
1462            }
1463            let slot = self.ensure_column_idx(resolved) as u32;
1464            self.mark_predicate_slot(slot);
1465            let val_static: Value<'static> = value.into_static();
1466            let is_pred = self.is_predicate_slot(slot);
1467            #[cfg(feature = "profile")]
1468            if is_pred {
1469                crate::engine::IS_PRED_TRUE.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
1470            } else {
1471                crate::engine::IS_PRED_FALSE.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
1472            }
1473            if let Some(ref mut buf) = self.row_buf {
1474                if let Some(pos) = buf.fields.iter().position(|(s, _)| *s == slot) {
1475                    buf.fields[pos].1 = val_static;
1476                } else {
1477                    buf.fields.push((slot, val_static));
1478                }
1479            }
1480            if is_pred {
1481                // Record predicate ordinal for adaptive strategy (once)
1482                if let Some(ref mut buf) = self.row_buf {
1483                    if buf.predicate_ordinal.is_none() {
1484                        buf.predicate_ordinal = Some(slot);
1485                    }
1486                }
1487                let state = self.evaluate_predicate_state();
1488                if let Some(ref mut buf) = self.row_buf {
1489                    buf.state = state;
1490                    if state == PredicateState::Pass {
1491                        buf.direct = true;
1492                    }
1493                }
1494                if state == PredicateState::Pass {
1495                    // Predicate passed: drain buffered fields, switch to direct mode.
1496                    self.drain_buffered(true);
1497                }
1498            }
1499        } else {
1500            if let Some(resolved) = self.plan.resolve_field(name) {
1501                let owned = resolved.to_owned();
1502                if self.frozen.is_some() && !self.field_index.contains_key(&owned) {
1503                    if let Some(ref frozen) = self.frozen {
1504                        if !frozen.column_names().iter().any(|n| n.as_ref() == owned) {
1505                            if self.unknown_error.is_none() {
1506                                self.unknown_error = Some(format!(
1507                                    "unknown field {:?} not in frozen schema ({} columns, exact={}); pass schema=[...]",
1508                                    owned,
1509                                    frozen.num_columns(),
1510                                    frozen.is_exact()
1511                                ));
1512                            }
1513                            return;
1514                        }
1515                    }
1516                }
1517                let slot = self.ensure_column_idx(&owned) as u32;
1518                self.mark_predicate_slot(slot);
1519                let val_static: Value<'static> = value.into_static();
1520                let is_pred = self.is_predicate_slot(slot);
1521                #[cfg(feature = "profile")]
1522                if is_pred {
1523                    crate::engine::IS_PRED_TRUE.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
1524                } else {
1525                    crate::engine::IS_PRED_FALSE.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
1526                }
1527                if let Some(ref mut buf) = self.row_buf {
1528                    if let Some(pos) = buf.fields.iter().position(|(s, _)| *s == slot) {
1529                        buf.fields[pos].1 = val_static;
1530                    } else {
1531                        buf.fields.push((slot, val_static));
1532                    }
1533                }
1534                if is_pred {
1535                    // Record predicate ordinal for adaptive strategy (once)
1536                    if let Some(ref mut buf) = self.row_buf {
1537                        if buf.predicate_ordinal.is_none() {
1538                            buf.predicate_ordinal = Some(slot);
1539                        }
1540                    }
1541                    let state = self.evaluate_predicate_state();
1542                    if let Some(ref mut buf) = self.row_buf {
1543                        buf.state = state;
1544                    }
1545                }
1546            }
1547        }
1548    }
1549
1550    #[inline]
1551    fn row_rejected(&self) -> bool {
1552        self.plan.filter.is_some()
1553            && self
1554                .row_buf
1555                .as_ref()
1556                .is_some_and(|b| b.state == PredicateState::Fail)
1557    }
1558
1559    #[inline]
1560    fn row_satisfied(&self) -> bool {
1561        let mask = self.wanted_mask();
1562        if mask == 0 {
1563            return false;
1564        }
1565        // Check that every wanted bit is set in row_dirty.
1566        let dirty = self
1567            .row_dirty
1568            .iter()
1569            .copied()
1570            .reduce(|a, b| a | b)
1571            .unwrap_or(0);
1572        (dirty & mask) == mask
1573    }
1574
1575    #[inline]
1576    fn wanted_mask(&self) -> u64 {
1577        // Build mask from plan schema_order or field_index.
1578        if !self.plan.schema_order.is_empty() {
1579            let mut mask = 0u64;
1580            for name in &self.plan.schema_order {
1581                if let Some(&idx) = self.field_index.get(name.as_str()) {
1582                    if idx < 64 {
1583                        mask |= 1u64 << idx;
1584                    }
1585                }
1586            }
1587            mask
1588        } else {
1589            // No explicit schema_order: all columns are wanted (even if
1590            // field_map or drop_fields is active). Return 0 to disable
1591            // projection short-circuit. Only short-circuit when the user
1592            // has explicitly declared which columns they want via schema_order.
1593            0
1594        }
1595    }
1596
1597    #[inline]
1598    fn finish(&mut self) -> Result<RecordBatch> {
1599        if let Some(err) = self.unknown_error.take() {
1600            return Err(crate::Error::Merge(err));
1601        }
1602        self.normalize();
1603
1604        if self.column_order.is_empty() {
1605            let schema = Arc::new(Schema::empty());
1606            return Ok(RecordBatch::new_empty(schema));
1607        }
1608
1609        self.auto_dict_upgrade();
1610        self.sort_columns();
1611
1612        let mut fields = Vec::with_capacity(self.column_order.len());
1613        let mut arrays = Vec::with_capacity(self.column_order.len());
1614        // Iterate by index so we can borrow columns mutably for zero-copy export.
1615        for name in &self.column_order {
1616            if let Some(&idx) = self.field_index.get(name.as_str()) {
1617                let b = &mut self.columns[idx];
1618                fields.push(ArrowField::new(name.as_str(), b.arrow_datatype(), true));
1619                arrays.push(b.to_arrow_array()?);
1620            }
1621        }
1622
1623        let schema = Arc::new(Schema::new(fields));
1624        Ok(RecordBatch::try_new(schema, arrays)?)
1625    }
1626
1627    #[inline]
1628    fn expect_slot(&self, ordinal: u32) -> Option<(u32, &[u8])> {
1629        self.ordinal_expect
1630            .get(ordinal as usize)
1631            .and_then(|entry| entry.as_ref())
1632            .map(|(slot, raw)| (*slot, raw.as_slice()))
1633    }
1634
1635    #[inline]
1636    fn record_slot(&mut self, ordinal: u32, slot: u32, raw_name: &[u8]) {
1637        let idx = ordinal as usize;
1638        if idx >= self.ordinal_expect.len() {
1639            self.ordinal_expect.resize_with(idx + 1, || None);
1640        }
1641        self.ordinal_expect[idx] = Some((slot, raw_name.to_vec()));
1642    }
1643
1644    #[inline]
1645    fn layout_broken(&mut self, ordinal: u32) {
1646        if let Some(entry) = self.ordinal_expect.get_mut(ordinal as usize) {
1647            *entry = None;
1648        }
1649    }
1650
1651    #[inline]
1652    fn reset_child_ordinal(&mut self) {
1653        self.current_ordinal = 0;
1654    }
1655}
1656
1657// ---------------------------------------------------------------------------
1658// LocateOnly sink: walk rows, resolve field names, decode nothing.
1659// ---------------------------------------------------------------------------
1660
1661#[cfg(test)]
1662mod tests {
1663    use super::*;
1664    use crate::columnar::ColumnBuilder;
1665    use crate::decoder::{ColumnarSink, RecordParser, Splitter};
1666    use crate::plan::{CompareOp, ExecutionPlan, FieldType, FilterPredicate};
1667    use crate::value::Value;
1668    use crate::Result;
1669    use arrow::array::{Array, AsArray};
1670
1671    /// Simple newline-delimited parser for test data.
1672    /// Each line is a row; fields are `key=value` separated by spaces.
1673    struct LineParser;
1674
1675    impl RecordParser for LineParser {
1676        fn validate(&self, bytes: &[u8]) -> Result<()> {
1677            simdutf8::basic::from_utf8(bytes)?;
1678            Ok(())
1679        }
1680
1681        fn parse_chunk(&self, bytes: &[u8], sink: &mut dyn ColumnarSink) -> Result<()> {
1682            let text = std::str::from_utf8(bytes).map_err(|e| crate::Error::Plan(e.to_string()))?;
1683            for line in text.lines() {
1684                if line.is_empty() {
1685                    continue;
1686                }
1687                sink.begin_row();
1688                for token in line.split_whitespace() {
1689                    if let Some((k, v)) = token.split_once('=') {
1690                        sink.put_field(k, Value::Str(Cow::Borrowed(v)));
1691                    }
1692                }
1693                sink.end_row();
1694            }
1695            Ok(())
1696        }
1697    }
1698
1699    struct LineSplitter;
1700
1701    impl Splitter for LineSplitter {
1702        fn next_record_start(&self, bytes: &[u8], from: usize) -> Option<usize> {
1703            if from >= bytes.len() {
1704                return None;
1705            }
1706            // If we're at a newline, advance past it.
1707            let start = if bytes[from] == b'\n' { from + 1 } else { from };
1708            if start >= bytes.len() {
1709                return None;
1710            }
1711            memchr::memchr(b'\n', &bytes[start..]).map(|rel| start + rel + 1)
1712        }
1713
1714        fn find_split_points(&self, bytes: &[u8], max_chunks: usize) -> Vec<usize> {
1715            if max_chunks <= 1 || bytes.is_empty() {
1716                return vec![0, bytes.len()];
1717            }
1718            let mut points = vec![0usize];
1719            let mut last = 0;
1720            for (i, &b) in bytes.iter().enumerate() {
1721                if b == b'\n' {
1722                    let next = i + 1;
1723                    if next > last && points.len() < max_chunks {
1724                        points.push(next);
1725                        last = next;
1726                    }
1727                }
1728            }
1729            if *points.last().unwrap() != bytes.len() {
1730                points.push(bytes.len());
1731            }
1732            points
1733        }
1734
1735        fn estimate_bytes_per_row(&self, sample: &[u8]) -> usize {
1736            let newline_count = sample.iter().filter(|&&b| b == b'\n').count().max(1);
1737            (sample.len() / newline_count).max(1)
1738        }
1739    }
1740
1741    fn parse_bytes(bytes: &[u8], plan: ExecutionPlan) -> TableBuilder {
1742        let mut sink = TableBuilder::with_plan((bytes.len() / 16).max(4), Arc::new(plan));
1743        LineParser.parse_chunk(bytes, &mut sink).unwrap();
1744        sink
1745    }
1746
1747    #[test]
1748    fn test_extend_no_duplicates() {
1749        let e1 = parse_bytes(b"A=1 B=2\n", ExecutionPlan::new());
1750        let mut merged = TableBuilder::new();
1751        merged.extend(e1).unwrap();
1752        assert_eq!(merged.num_rows(), 1);
1753        for col in &merged.columns {
1754            assert_eq!(col.len(), merged.num_rows(), "column length mismatch");
1755        }
1756    }
1757
1758    #[test]
1759    fn test_multi_chunk_same_as_single() {
1760        let data = b"A=1\nA=2\nA=3\n";
1761        let single = parse_bytes(data, ExecutionPlan::new());
1762        assert_eq!(single.num_rows(), 3);
1763
1764        let splitter = LineSplitter;
1765        let points = splitter.find_split_points(data, 2);
1766        let mut merged = TableBuilder::new();
1767        for w in points.windows(2) {
1768            let chunk = &data[w[0]..w[1]];
1769            let engine = parse_bytes(chunk, ExecutionPlan::new());
1770            merged.extend(engine).unwrap();
1771        }
1772        assert_eq!(merged.num_rows(), single.num_rows());
1773    }
1774
1775    #[test]
1776    fn test_last_write_wins_duplicate_field() {
1777        let engine = parse_bytes(b"X=10 X=20\n", ExecutionPlan::new());
1778        assert_eq!(engine.num_rows(), 1);
1779        let col = engine.get_column("X").unwrap();
1780        assert_eq!(col.as_str_vec(), vec![Some("20".into())]);
1781    }
1782
1783    #[test]
1784    fn test_build_plan_rename() {
1785        let mut plan = ExecutionPlan::new();
1786        plan.field_map.insert("X".to_string(), "Y".to_string());
1787        let engine = parse_bytes(b"X=hello\n", plan);
1788        assert_eq!(engine.num_rows(), 1);
1789        assert!(engine.get_column("Y").is_some());
1790        assert!(engine.get_column("X").is_none());
1791        assert_eq!(
1792            engine.get_column("Y").unwrap().as_str_vec(),
1793            vec![Some("hello".into())]
1794        );
1795    }
1796
1797    #[test]
1798    fn test_build_plan_drop() {
1799        let mut plan = ExecutionPlan::new();
1800        plan.drop_fields.insert("X".to_string());
1801        let engine = parse_bytes(b"X=hello Y=world\n", plan);
1802        assert_eq!(engine.num_rows(), 1);
1803        assert!(engine.get_column("X").is_none());
1804        assert!(engine.get_column("Y").is_some());
1805    }
1806
1807    #[test]
1808    fn test_build_plan_filter_ne() {
1809        let mut plan = ExecutionPlan::new();
1810        plan.filter = Some(FilterPredicate::NotEqual {
1811            field: "X".to_string(),
1812            value: "42".to_string(),
1813        });
1814        let engine = parse_bytes(b"X=10\nX=42\nX=30\n", plan);
1815        assert_eq!(engine.num_rows(), 2);
1816        let col = engine.get_column("X").unwrap();
1817        assert_eq!(col.as_str_vec(), vec![Some("10".into()), Some("30".into())]);
1818    }
1819
1820    #[test]
1821    fn test_build_plan_filter_eq() {
1822        let mut plan = ExecutionPlan::new();
1823        plan.filter = Some(FilterPredicate::Equal {
1824            field: "X".to_string(),
1825            value: "10".to_string(),
1826        });
1827        let engine = parse_bytes(b"X=10\nX=20\nX=10\n", plan);
1828        assert_eq!(engine.num_rows(), 2);
1829        let col = engine.get_column("X").unwrap();
1830        assert_eq!(col.as_str_vec(), vec![Some("10".into()), Some("10".into())]);
1831    }
1832
1833    #[test]
1834    fn test_build_plan_filter_missing_field() {
1835        let mut plan = ExecutionPlan::new();
1836        plan.filter = Some(FilterPredicate::NotEqual {
1837            field: "X".to_string(),
1838            value: "10".to_string(),
1839        });
1840        let engine = parse_bytes(b"X=10\nY=99\n", plan);
1841        assert_eq!(engine.num_rows(), 1);
1842        let col = engine.get_column("Y").unwrap();
1843        assert_eq!(col.as_str_vec(), vec![Some("99".into())]);
1844    }
1845
1846    #[test]
1847    fn test_typed_int64_column() {
1848        let mut plan = ExecutionPlan::new();
1849        plan.field_types.insert("X".to_string(), FieldType::Int64);
1850        let engine = parse_bytes(b"X=42\nX=bad\nX=100\n", plan);
1851        assert_eq!(engine.num_rows(), 3);
1852        if let ColumnBuilder::Int64(v) = engine.get_column("X").unwrap() {
1853            assert_eq!(v.get(0), Some(42));
1854            assert_eq!(v.get(1), None);
1855            assert_eq!(v.get(2), Some(100));
1856        } else {
1857            panic!("expected Int64 builder");
1858        }
1859    }
1860
1861    #[test]
1862    fn test_typed_float64_column() {
1863        let mut plan = ExecutionPlan::new();
1864        plan.field_types.insert("X".to_string(), FieldType::Float64);
1865        let engine = parse_bytes(b"X=1.5\n", plan);
1866        if let ColumnBuilder::Float64(v) = engine.get_column("X").unwrap() {
1867            assert!((v.get(0).unwrap() - 1.5).abs() < 1e-9);
1868        } else {
1869            panic!("expected Float64 builder");
1870        }
1871    }
1872
1873    #[test]
1874    fn test_dictionary_column() {
1875        let mut plan = ExecutionPlan::new();
1876        plan.dictionary_columns.insert("P".to_string());
1877        let engine = parse_bytes(b"P=Widget\nP=Gadget\nP=Widget\n", plan);
1878        assert_eq!(engine.num_rows(), 3);
1879        if let ColumnBuilder::Dictionary { codes, dict, .. } = engine.get_column("P").unwrap() {
1880            assert_eq!(dict.len(), 2);
1881            assert_eq!(
1882                codes.iter().map(|o| o.copied()).collect::<Vec<_>>(),
1883                vec![Some(0), Some(1), Some(0)]
1884            );
1885        } else {
1886            panic!("expected Dictionary builder");
1887        }
1888    }
1889
1890    #[test]
1891    fn test_ragged_late_chunk_column_debut() {
1892        let e1 = parse_bytes(b"A=1 B=2\nA=3\n", ExecutionPlan::new());
1893        let e2 = parse_bytes(b"B=4 C=5\n", ExecutionPlan::new());
1894        let mut merged = TableBuilder::new();
1895        merged.extend(e1).unwrap();
1896        merged.extend(e2).unwrap();
1897
1898        assert_eq!(
1899            merged.get_column("A").unwrap().as_str_vec(),
1900            vec![Some("1".into()), Some("3".into()), None]
1901        );
1902        assert_eq!(
1903            merged.get_column("B").unwrap().as_str_vec(),
1904            vec![Some("2".into()), None, Some("4".into())]
1905        );
1906        assert_eq!(
1907            merged.get_column("C").unwrap().as_str_vec(),
1908            vec![None, None, Some("5".into())]
1909        );
1910    }
1911
1912    #[test]
1913    fn test_auto_dict_upgrade_only_post_merge() {
1914        let mut plan = ExecutionPlan::new();
1915        plan.auto_dict = true;
1916        let a = parse_bytes(b"P=x\nP=y\n", plan.clone());
1917        let b = parse_bytes(b"P=x\nP=y\n", plan.clone());
1918        let mut merged = TableBuilder::with_plan(64, Arc::new(plan));
1919        merged.extend(a).unwrap();
1920        merged.extend(b).unwrap();
1921        merged.auto_dict_upgrade();
1922        assert_eq!(merged.num_rows(), 4);
1923    }
1924
1925    #[test]
1926    fn test_extend_string_dictionary_promotes_not_panics() {
1927        let mut e1 = parse_bytes(b"P=x\n", ExecutionPlan::new());
1928        let mut plan = ExecutionPlan::new();
1929        plan.dictionary_columns.insert("P".to_string());
1930        let e2 = parse_bytes(b"P=x\n", plan);
1931        // Safe promotion: string + dictionary reconcile to dictionary.
1932        e1.extend(e2).expect("String/Dictionary must reconcile");
1933        assert!(matches!(
1934            e1.get_column("P").unwrap(),
1935            crate::columnar::ColumnBuilder::Dictionary { .. }
1936        ));
1937    }
1938
1939    #[test]
1940    fn test_extend_irreconcilable_variants_error_not_panic() {
1941        let mut e1 = parse_bytes(b"S=x\n", ExecutionPlan::new());
1942        let mut plan = ExecutionPlan::new();
1943        plan.field_types.insert("S".to_string(), FieldType::Int64);
1944        let e2 = parse_bytes(b"S=7\n", plan);
1945        let result = e1.extend(e2);
1946        match result {
1947            Err(crate::Error::Merge(msg)) => {
1948                assert!(msg.contains("'S'"), "error should name the column: {msg}");
1949            }
1950            other => panic!("String/Int64 mismatch must return Merge error, got {other:?}"),
1951        }
1952    }
1953
1954    #[test]
1955    fn test_compare_filter_via_arrow_compute() {
1956        use crate::arrow_export::apply_compare_filter;
1957
1958        let mut plan = ExecutionPlan::new();
1959        plan.filter = Some(FilterPredicate::Compare {
1960            field_a: "A".to_string(),
1961            op: CompareOp::Gt,
1962            field_b: "B".to_string(),
1963        });
1964        let mut engine = parse_bytes(b"A=3 B=1\nA=2 B=2\nA=5 B=4\n", plan);
1965        let batch = engine.finish().unwrap();
1966        let filtered = apply_compare_filter(
1967            batch,
1968            &FilterPredicate::Compare {
1969                field_a: "A".to_string(),
1970                op: CompareOp::Gt,
1971                field_b: "B".to_string(),
1972            },
1973        )
1974        .unwrap();
1975        assert_eq!(filtered.num_rows(), 2);
1976        let a = filtered.column_by_name("A").unwrap().as_string::<i32>();
1977        assert_eq!(a.value(0), "3");
1978        assert_eq!(a.value(1), "5");
1979    }
1980
1981    #[test]
1982    fn test_row_dirty_is_full_edge_cases() {
1983        // Directly test the is_full logic for ncols = 1,63,64,65,127,128,129
1984        // We do this via TableBuilder with varying column counts
1985        for ncols in [1, 63, 64, 65, 127, 128, 129] {
1986            let mut tb = TableBuilder::new();
1987            for i in 0..ncols {
1988                let name = format!("col{i}");
1989                tb.field_index.insert(name.clone(), i);
1990                tb.columns.push(crate::columnar::ColumnBuilder::String(
1991                    crate::columnar::StrColumn::default(),
1992                ));
1993                tb.column_order.push(name);
1994            }
1995            // row_dirty should be vec![0; (ncols+63)/64]
1996            tb.row_dirty = vec![0; ncols.div_ceil(64)];
1997            // Test is_full when all bits set
1998            for i in 0..ncols {
1999                let word = i / 64;
2000                let bit = i % 64;
2001                tb.row_dirty[word] |= 1u64 << bit;
2002            }
2003            let full_words = ncols / 64;
2004            let rem = ncols % 64;
2005            let is_full = (0..full_words).all(|w| tb.row_dirty[w] == u64::MAX)
2006                && (rem == 0
2007                    || tb.row_dirty.get(full_words).copied().unwrap_or(0) == (1u64 << rem) - 1);
2008            assert!(
2009                is_full,
2010                "ncols={ncols} should be full, row_dirty={:?}",
2011                tb.row_dirty
2012            );
2013            // Clear one bit and check not full
2014            if ncols > 0 {
2015                let word = (ncols - 1) / 64;
2016                let bit = (ncols - 1) % 64;
2017                tb.row_dirty[word] &= !(1u64 << bit);
2018                let is_full2 = (0..full_words).all(|w| tb.row_dirty[w] == u64::MAX)
2019                    && (rem == 0
2020                        || tb.row_dirty.get(full_words).copied().unwrap_or(0) == (1u64 << rem) - 1);
2021                assert!(
2022                    !is_full2,
2023                    "ncols={ncols} should not be full after clearing one bit"
2024                );
2025            }
2026        }
2027    }
2028
2029    #[test]
2030    fn test_finish_twice_does_not_panic() {
2031        // L7: zero-copy export (mem::take) leaves builders empty. Calling
2032        // finish() twice should return an empty batch, not panic.
2033        let mut tb = parse_bytes(b"A=1 B=2\nA=3 B=4\n", ExecutionPlan::new());
2034        let batch1 = tb.finish().unwrap();
2035        assert_eq!(batch1.num_rows(), 2);
2036        // Second call: columns are empty after mem::take.
2037        let batch2 = tb.finish().unwrap();
2038        assert_eq!(batch2.num_rows(), 0);
2039    }
2040
2041    #[test]
2042    fn test_c2_compound_reorder() {
2043        // L7: C2 reorder: Field2 == x AND Field1 == y must give the same
2044        // result as Field1 == y AND Field2 == x.
2045        let data = b"A=1 B=2\nA=2 B=2\nA=1 B=3\nA=2 B=3\n";
2046        let make_filter = |a: &str, va: &str, b: &str, vb: &str| -> ExecutionPlan {
2047            let mut plan = ExecutionPlan::new();
2048            plan.filter = Some(FilterPredicate::And(
2049                Box::new(FilterPredicate::Equal {
2050                    field: a.to_string(),
2051                    value: va.to_string(),
2052                }),
2053                Box::new(FilterPredicate::Equal {
2054                    field: b.to_string(),
2055                    value: vb.to_string(),
2056                }),
2057            ));
2058            plan
2059        };
2060        let r1 = parse_bytes(data, make_filter("A", "1", "B", "2"));
2061        let r2 = parse_bytes(data, make_filter("B", "2", "A", "1"));
2062        assert_eq!(
2063            r1.num_rows(),
2064            r2.num_rows(),
2065            "C2 reorder must produce identical results"
2066        );
2067        assert_eq!(r1.num_rows(), 1); // A=1 B=2
2068    }
2069
2070    #[test]
2071    fn test_c2_or_reorder() {
2072        // L7: Or reorder: same result regardless of operand order.
2073        // Row 1: A=1 B=2 → A==1 → Pass
2074        // Row 2: A=2 B=2 → A!=1, B!=3 → Fail
2075        // Row 3: A=3 B=3 → B==3 → Pass
2076        let data = b"A=1 B=2\nA=2 B=2\nA=3 B=3\n";
2077        let make_filter = |a: &str, va: &str, b: &str, vb: &str| -> ExecutionPlan {
2078            let mut plan = ExecutionPlan::new();
2079            plan.filter = Some(FilterPredicate::Or(
2080                Box::new(FilterPredicate::Equal {
2081                    field: a.to_string(),
2082                    value: va.to_string(),
2083                }),
2084                Box::new(FilterPredicate::Equal {
2085                    field: b.to_string(),
2086                    value: vb.to_string(),
2087                }),
2088            ));
2089            plan
2090        };
2091        let r1 = parse_bytes(data, make_filter("A", "1", "B", "3"));
2092        let r2 = parse_bytes(data, make_filter("B", "3", "A", "1"));
2093        assert_eq!(
2094            r1.num_rows(),
2095            r2.num_rows(),
2096            "Or reorder must produce identical results"
2097        );
2098        assert_eq!(r1.num_rows(), 2); // rows 1 and 3
2099    }
2100
2101    #[test]
2102    fn test_predicate_slot_created_after_mask_build() {
2103        // Regression: when the predicate column appears AFTER other columns
2104        // in document order, build_predicate_mask runs before the predicate
2105        // column exists in field_index, so its bit is never set. The old
2106        // early-return optimization prevented it from being added later.
2107        //
2108        // Data: A comes first, B is the predicate column (comes second).
2109        // Filter: B == "reject" → all rows should be rejected.
2110        let data = b"A=1 B=ok\nA=2 B=ok\nA=3 B=ok\n";
2111        let mut plan = ExecutionPlan::new();
2112        plan.filter = Some(FilterPredicate::Equal {
2113            field: "B".to_string(),
2114            value: "reject".to_string(),
2115        });
2116        let engine = parse_bytes(data, plan);
2117        assert_eq!(
2118            engine.num_rows(),
2119            0,
2120            "all rows should be rejected (B != reject)"
2121        );
2122
2123        // Positive case: some rows pass
2124        let data2 = b"A=1 B=ok\nA=2 B=reject\nA=3 B=ok\n";
2125        let mut plan2 = ExecutionPlan::new();
2126        plan2.filter = Some(FilterPredicate::Equal {
2127            field: "B".to_string(),
2128            value: "ok".to_string(),
2129        });
2130        let engine2 = parse_bytes(data2, plan2);
2131        assert_eq!(engine2.num_rows(), 2, "rows 1 and 3 pass (B == ok)");
2132        let col = engine2.get_column("A").unwrap();
2133        assert_eq!(col.as_str_vec(), vec![Some("1".into()), Some("3".into())]);
2134    }
2135
2136    #[test]
2137    fn test_predicate_first_via_resolve_and_put() {
2138        // Uses resolve_and_put (scanner path) instead of put_field (LineParser path)
2139        // to verify the predicate machinery works through the scanner's code path.
2140        let mut plan = ExecutionPlan::new();
2141        plan.filter = Some(FilterPredicate::Equal {
2142            field: "B".to_string(),
2143            value: "reject".to_string(),
2144        });
2145        let mut tb = TableBuilder::with_plan(16, Arc::new(plan));
2146        // Row 1: B=ok → should pass
2147        tb.begin_row();
2148        tb.resolve_and_put("A", Value::Str(Cow::Borrowed("1")));
2149        tb.resolve_and_put("B", Value::Str(Cow::Borrowed("ok")));
2150        tb.end_row();
2151        // Row 2: B=reject → should fail
2152        tb.begin_row();
2153        tb.resolve_and_put("A", Value::Str(Cow::Borrowed("2")));
2154        tb.resolve_and_put("B", Value::Str(Cow::Borrowed("reject")));
2155        tb.end_row();
2156        // Row 3: B=ok → should pass
2157        tb.begin_row();
2158        tb.resolve_and_put("A", Value::Str(Cow::Borrowed("3")));
2159        tb.resolve_and_put("B", Value::Str(Cow::Borrowed("ok")));
2160        tb.end_row();
2161        let batch = tb.finish().unwrap();
2162        assert_eq!(batch.num_rows(), 1, "only row 2 (B==reject) should pass");
2163    }
2164
2165    #[test]
2166    fn test_owned_cow_values_survive_buffered_filter() {
2167        // Regression for the use-after-free behind this change: Value::Str
2168        // used to be `&'a str`, and the buffered filtered path transmutes
2169        // `Value<'a>` to `Value<'static>` to hold values until the predicate
2170        // is decided. Adapters that unescape entities produce owned Strings;
2171        // the owned buffer was dropped at the end of the scan function and
2172        // the transmuted reference dangled, so heap reuse corrupted accepted
2173        // rows after enough rejections. With `Str(Cow<'a, str>)` the owned
2174        // buffer moves into the row buffer.
2175        let mut plan = ExecutionPlan::new();
2176        plan.filter = Some(FilterPredicate::Equal {
2177            field: "B".to_string(),
2178            value: "ok".to_string(),
2179        });
2180        let mut tb = TableBuilder::with_plan(16, Arc::new(plan));
2181        for i in 0..50 {
2182            tb.begin_row();
2183            // Owned values, as produced by entity unescaping in an adapter.
2184            let a = Cow::Owned(format!("value-{i}-unescaped"));
2185            let b = Cow::Owned(if i % 2 == 0 {
2186                "ok".to_string()
2187            } else {
2188                "no".to_string()
2189            });
2190            tb.resolve_and_put("A", Value::Str(a));
2191            tb.resolve_and_put("B", Value::Str(b));
2192            tb.end_row();
2193        }
2194        assert_eq!(tb.num_rows(), 25, "even rows pass (B == ok)");
2195        let col = tb.get_column("A").unwrap();
2196        let vals = col.as_str_vec();
2197        assert_eq!(vals.len(), 25);
2198        assert_eq!(vals[0], Some("value-0-unescaped".to_string()));
2199        assert_eq!(vals[24], Some("value-48-unescaped".to_string()));
2200    }
2201
2202    #[test]
2203    fn test_predicate_first_skip_via_resolve_and_put() {
2204        // Test the skip path: predicate on first field, all rows rejected.
2205        // This exercises the mark_predicate_slot + row_rejected + end_row path
2206        // that the scanner uses via resolve_and_put.
2207        let mut plan = ExecutionPlan::new();
2208        plan.filter = Some(FilterPredicate::Equal {
2209            field: "A".to_string(),
2210            value: "999".to_string(),
2211        });
2212        let mut tb = TableBuilder::with_plan(16, Arc::new(plan));
2213        for _i in 0..100 {
2214            tb.begin_row();
2215            tb.resolve_and_put("A", Value::Str(Cow::Borrowed("0")));
2216            tb.resolve_and_put("B", Value::Str(Cow::Borrowed("x")));
2217            tb.resolve_and_put("C", Value::Str(Cow::Borrowed("y")));
2218            tb.end_row();
2219        }
2220        let batch = tb.finish().unwrap();
2221        assert_eq!(
2222            batch.num_rows(),
2223            0,
2224            "all rows should be rejected (A=0 != 999)"
2225        );
2226    }
2227
2228    #[test]
2229    fn test_sparse_column_predicate_skip() {
2230        // Regression test for ncols gate: sparse column appears only after
2231        // row 50, predicate on early field (A). The adaptive strategy must
2232        // not disable buffering because ncols is computed from the incomplete
2233        // column set before the sparse column appears.
2234        //
2235        // Data: 100 rows. Rows 1-50 have A, B, C. Rows 51-100 also have D.
2236        // Filter: A == "reject" → all rows rejected.
2237        // The skip must fire for all rows, not just the first few.
2238        let mut plan = ExecutionPlan::new();
2239        plan.filter = Some(FilterPredicate::Equal {
2240            field: "A".to_string(),
2241            value: "reject".to_string(),
2242        });
2243        let mut tb = TableBuilder::with_plan(128, Arc::new(plan));
2244        for i in 0..100 {
2245            tb.begin_row();
2246            tb.resolve_and_put("A", Value::Str(Cow::Borrowed("ok")));
2247            tb.resolve_and_put("B", Value::Str(Cow::Borrowed("x")));
2248            tb.resolve_and_put("C", Value::Str(Cow::Borrowed("y")));
2249            if i >= 50 {
2250                tb.resolve_and_put("D", Value::Str(Cow::Borrowed("z")));
2251            }
2252            tb.end_row();
2253        }
2254        let batch = tb.finish().unwrap();
2255        assert_eq!(batch.num_rows(), 0, "all rows rejected (A=ok != reject)");
2256    }
2257
2258    #[test]
2259    fn test_sparse_column_predicate_pass() {
2260        // Like above, but predicate passes. The sparse column D should appear
2261        // only for rows 51-100; rows 1-50 should have D = null.
2262        let mut plan = ExecutionPlan::new();
2263        plan.filter = Some(FilterPredicate::Equal {
2264            field: "A".to_string(),
2265            value: "ok".to_string(),
2266        });
2267        let mut tb = TableBuilder::with_plan(128, Arc::new(plan));
2268        for _i in 0..100 {
2269            tb.begin_row();
2270            tb.resolve_and_put("A", Value::Str(Cow::Borrowed("ok")));
2271            tb.resolve_and_put("B", Value::Str(Cow::Borrowed("x")));
2272            tb.resolve_and_put("C", Value::Str(Cow::Borrowed("y")));
2273            if _i >= 50 {
2274                tb.resolve_and_put("D", Value::Str(Cow::Borrowed("z")));
2275            }
2276            tb.end_row();
2277        }
2278        let batch = tb.finish().unwrap();
2279        assert_eq!(batch.num_rows(), 100, "all rows pass (A=ok == ok)");
2280        // D column: null for first 50, "z" for last 50
2281        if let Some(col) = batch.column_by_name("D") {
2282            let arr = col.as_string::<i32>();
2283            for i in 0..50 {
2284                assert!(arr.is_null(i), "row {} should have D=null", i);
2285            }
2286            for i in 50..100 {
2287                assert!(
2288                    !arr.is_null(i),
2289                    "row {} should not be null (D len={}, total rows={})",
2290                    i,
2291                    arr.len(),
2292                    batch.num_rows()
2293                );
2294                assert_eq!(arr.value(i), "z", "rows 50+ should have D=z");
2295            }
2296        } else {
2297            panic!("D column should exist");
2298        }
2299    }
2300
2301    #[test]
2302    fn test_sparse_late_predicate_ordinal() {
2303        // Regression: predicate on column E that only appears after row 30.
2304        // ncols gate must use schema/column count that includes E, not just
2305        // the columns seen so far.
2306        let mut plan = ExecutionPlan::new();
2307        plan.filter = Some(FilterPredicate::Equal {
2308            field: "E".to_string(),
2309            value: "999".to_string(),
2310        });
2311        let mut tb = TableBuilder::with_plan(128, Arc::new(plan));
2312        // First 30 rows: only A, B
2313        for _i in 0..30 {
2314            tb.begin_row();
2315            tb.resolve_and_put("A", Value::Str(Cow::Borrowed("x")));
2316            tb.resolve_and_put("B", Value::Str(Cow::Borrowed("y")));
2317            tb.end_row();
2318        }
2319        // Rows 31-100: A, B, C, D, E
2320        for _i in 30..100 {
2321            tb.begin_row();
2322            tb.resolve_and_put("A", Value::Str(Cow::Borrowed("x")));
2323            tb.resolve_and_put("B", Value::Str(Cow::Borrowed("y")));
2324            tb.resolve_and_put("C", Value::Str(Cow::Borrowed("c")));
2325            tb.resolve_and_put("D", Value::Str(Cow::Borrowed("d")));
2326            tb.resolve_and_put("E", Value::Str(Cow::Borrowed("e")));
2327            tb.end_row();
2328        }
2329        let batch = tb.finish().unwrap();
2330        // E="e" != "999" → all rows rejected
2331        assert_eq!(batch.num_rows(), 0, "all rows rejected (E=\"e\" != 999)");
2332    }
2333
2334    #[test]
2335    fn raw_name_helpers_apply_rename_and_drop() {
2336        use crate::decoder::ColumnarSink;
2337
2338        let plan = ExecutionPlan::new()
2339            .rename("raw", "renamed")
2340            .drop("ignored");
2341        let mut tb = TableBuilder::with_plan(2, Arc::new(plan));
2342        tb.begin_row();
2343        tb.resolve_and_put_raw(b"raw", Value::Str(Cow::Borrowed("value")));
2344        tb.resolve_and_put_raw(b"ignored", Value::Str(Cow::Borrowed("not stored")));
2345        tb.put_row(&[("other", Value::Str(Cow::Borrowed("also stored")))]);
2346        tb.end_row();
2347
2348        assert_eq!(tb.column_names(), &["renamed", "other"]);
2349        assert_eq!(tb.resolve_raw(b"raw"), Some("renamed"));
2350    }
2351}