Struct LazyMaterializedBatch 

pub struct LazyMaterializedBatch { /* private fields */ }

A lazy materialized batch that defers row materialization

This is the key abstraction for late materialization. It holds:

• Source data (either row-based or columnar)
• A selection vector indicating which rows are active

Rows are only materialized when explicitly requested, typically at the output boundary of query execution.

Performance Benefits

1. Memory: Only stores indices (4 bytes each) instead of full rows
2. Cache: Selection vectors are cache-friendly during iteration
3. Composition: Multiple operations can share source data via Arc
4. Lazy Evaluation: Skips materialization for filtered rows

Example

// Create a lazy batch from source data
let source = SourceData::Rows(Arc::new(rows));
let lazy_batch = LazyMaterializedBatch::new(source);

// Apply filter (just updates selection, no materialization)
let filtered = lazy_batch.filter(&filter_bitmap);

// Only materialize at output
let result_rows = filtered.materialize_selected(&[0, 2, 3])?; // Only these columns

Implementations

impl LazyMaterializedBatch

pub fn new(source: SourceData) -> Self

Create a new lazy batch from source data (selects all rows)

pub fn with_selection(source: SourceData, selection: SelectionVector) -> Self

Create a new lazy batch with a specific selection

pub fn from_rows(rows: Vec<Row>) -> Self

Create from row-based data

pub fn from_columnar(batch: ColumnarBatch) -> Self

Create from columnar data

pub fn with_column_names(self, names: Vec<String>) -> Self

Set column names

pub fn source(&self) -> &SourceData

Get the source data

pub fn selection(&self) -> &SelectionVector

Get the selection vector

pub fn column_names(&self) -> Option<&[String]>

Get column names if available

pub fn len(&self) -> usize

Number of selected (active) rows

pub fn is_empty(&self) -> bool

Check if no rows are selected

pub fn column_count(&self) -> usize

Number of columns in the source

pub fn source_row_count(&self) -> usize

Total rows in source (before selection)

pub fn filter(&self, bitmap: &[bool]) -> Self

Apply a filter bitmap, returning a new lazy batch with refined selection

This is a lazy operation - it updates the selection vector without materializing any row data.

pub fn filter_with<F>(&self, predicate: F) -> Self

where F: Fn(usize) -> bool,

Apply a filter to the current selection

The predicate receives the source row index and should return true to keep the row.

pub fn intersect_selection(&self, other: &SelectionVector) -> Self

Intersect selection with another selection vector

pub fn union_selection(&self, other: &SelectionVector) -> Self

Union selection with another selection vector

pub fn materialize(&self) -> Result<Vec<Row>, ExecutorError>

Materialize all selected rows

This is typically called at the output boundary when results need to be returned to the caller.

pub fn materialize_columns( &self, column_indices: &[usize], ) -> Result<Vec<Row>, ExecutorError>

Materialize only specific columns for selected rows

This is the most efficient output path - only materializes columns that appear in the final SELECT projection.

pub fn materialize_column( &self, column_idx: usize, ) -> Result<Vec<SqlValue>, ExecutorError>

Materialize a single column for selected rows

Useful for extracting join keys or aggregation inputs.

pub fn get_selected_value( &self, selection_idx: usize, column_idx: usize, ) -> Result<SqlValue, ExecutorError>

Get a single value from selected row

pub fn iter_indices(&self) -> impl Iterator<Item = u32> + '_

Iterate over selected row indices

pub fn remap_selection(&self, child_selection: &SelectionVector) -> Self

Create a child batch with remapped selection

Used when chaining operations: if we filter a filtered result, we need to maintain the chain of selections.

pub fn column_array(&self, column_idx: usize) -> Option<&ColumnArray>

Get the raw column array if source is columnar

Returns None if source is row-based.

pub fn is_columnar(&self) -> bool

Check if the source is columnar

pub fn to_columnar(&self) -> Result<LazyMaterializedBatch, ExecutorError>

Convert to columnar format if not already

This is useful when downstream operations benefit from columnar access.

pub fn selectivity(&self) -> f64

Selectivity ratio

Trait Implementations

impl Clone for LazyMaterializedBatch

fn clone(&self) -> LazyMaterializedBatch

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for LazyMaterializedBatch

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.