Struct RowSelection 

pub struct RowSelection {
    inner: RowSelectionInner,
}

RowSelection represents selecting a subset of rows when scanning a parquet file.

This is applied prior to reading column data, and can therefore be used to skip IO to fetch data into memory

A typical use-case would be using the PageIndex to filter out rows that don’t satisfy a predicate

Depending on the pattern of rows to be selected, RowSelection has either a bitmap or an RLE (RowSelector) based implementation.

Example

use parquet::arrow::arrow_reader::{RowSelection, RowSelector};

let selectors = vec![
    RowSelector::skip(5),
    RowSelector::select(5),
    RowSelector::select(5),
    RowSelector::skip(5),
];

// Creating a selection will combine adjacent selectors
let selection: RowSelection = selectors.into();

let expected = vec![
    RowSelector::skip(5),
    RowSelector::select(10),
    RowSelector::skip(5),
];

let actual: Vec<RowSelector> = selection.into();
assert_eq!(actual, expected);

// you can also create a selection from consecutive ranges
let ranges = vec![5..10, 10..15];
let selection =
  RowSelection::from_consecutive_ranges(ranges.into_iter(), 20);
let actual: Vec<RowSelector> = selection.into();
assert_eq!(actual, expected);

// or directly from a packed bitmap, when the upstream producer already
// has one. The bitmap is kept as-is rather than run-length-encoded.
use arrow_buffer::BooleanBuffer;
let mask = BooleanBuffer::from(vec![true, false, true, true]);
let selection = RowSelection::from_boolean_buffer(mask);
assert_eq!(selection.row_count(), 3);

An RLE (RowSelector) backed RowSelection maintains the following invariants (they do not apply to the bitmap backed implementation):

• It contains no RowSelector of 0 rows
• Consecutive RowSelectors alternate skipping or selecting rows

Fields

inner: RowSelectionInner

Implementations

impl RowSelection

fn from_selectors(selectors: Vec<RowSelector>) -> Self

Not pub: unlike From<Vec<RowSelector>>, this performs no validation/normalization of the selectors (e.g. combining adjacent selectors), so callers must uphold the invariants themselves.

pub fn from_boolean_buffer(mask: BooleanBuffer) -> Self

Create a RowSelection from a packed [BooleanBuffer].

Each set bit selects a row, each unset bit skips one. Unlike Self::from_filters, the bitmap is kept as-is rather than eagerly run-length-encoded. Self::iter materializes and caches the RLE form on first use; use MaskRunIter to stream the RLE form directly from the bitmap.

fn from_mask_selection(mask: MaskSelection) -> Self

pub fn as_mask(&self) -> Option<&BooleanBuffer>

Returns the underlying mask if this selection is mask-backed.

Public so that engines composing selections (e.g. DataFusion’s ParquetAccessPlan::into_overall_row_selection) can concatenate mask-backed selections without materialising the RLE form.

pub(crate) fn into_inner(self) -> RowSelectionInner

Consume the selection and return its internal storage.

pub(crate) fn auto_selection_strategy( &self, threshold: usize, ) -> RowSelectionStrategy

Choose the automatic materialisation strategy without converting between selector and mask backing.

fn into_selectors_vec(self) -> Vec<RowSelector>

pub fn from_filters(filters: &[BooleanArray]) -> Self

Creates a RowSelection from a slice of [BooleanArray]

Panic

Panics if any of the [BooleanArray] contain nulls

pub fn from_consecutive_ranges<I: Iterator<Item = Range<usize>>>( ranges: I, total_rows: usize, ) -> Self

Creates a RowSelection from an iterator of consecutive ranges to keep

pub fn scan_ranges(&self, page_locations: &[PageLocation]) -> Vec<Range<u64>>

Given an offset index, return the byte ranges for all data pages selected by self

This is useful for determining what byte ranges to fetch from underlying storage

Note: this method does not make any effort to combine consecutive ranges, nor coalesce ranges that are close together. This is instead delegated to the IO subsystem to optimise, e.g. ObjectStore::get_ranges

pub(crate) fn row_ranges_for_selected_pages( &self, page_locations: &[PageLocation], total_rows: usize, ) -> Vec<Range<usize>>

Returns the complete row ranges of the pages selected by Self::scan_ranges.

pub fn split_off(&mut self, row_count: usize) -> Self

Splits off the first row_count from this RowSelection

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

returns a RowSelection representing rows that are selected in both input RowSelections.

This is equivalent to the logical AND / conjunction of the two selections.

Example

If N means the row is not selected, and Y means it is selected:

self:     NNNNNNNNNNNNYYYYYYYYYYYYYYYYYYYYYYNNNYYYYY
other:                YYYYYNNNNYYYYYYYYYYYYY   YYNNN

returned: NNNNNNNNNNNNYYYYYNNNNYYYYYYYYYYYYYNNNYYNNN

Panics

Panics if other does not have a length equal to the number of rows selected by this RowSelection

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

Compute the intersection of two RowSelection For example: self: NNYYYYNNYYNYN other: NYNNNNNNY

returned: NNNNNNNNYYNYN

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

Compute the union of two RowSelection For example: self: NNYYYYNNYYNYN other: NYNNNNNNN

returned: NYYYYYNNYYNYN

pub fn selects_any(&self) -> bool

Returns true if this RowSelection selects any rows

pub(crate) fn trim(self) -> Self

Trims this RowSelection removing any trailing skips

pub(crate) fn offset(self, offset: usize) -> Self

Applies an offset to this RowSelection, skipping the first offset selected rows

pub(crate) fn limit(self, limit: usize) -> Self

Limit this RowSelection to only select limit rows

pub fn iter(&self) -> RowSelectionIter<'_>

Returns a borrowed iterator yielding the RowSelectors for this selection.

Mask-backed selections materialize a Vec<RowSelector> cache on first call (one allocation, O(set_slices) work) so the iterator can hand out &RowSelector; the cache is not copied on clone. For single-pass walks over mask-backed selections, prefer streaming directly via Self::as_mask + MaskRunIter::new — that path is allocation-free and avoids populating the cache.

pub fn row_count(&self) -> usize

Returns the number of selected rows

pub fn skipped_row_count(&self) -> usize

Returns the number of de-selected rows

pub(crate) fn expand_to_batch_boundaries( &self, batch_size: usize, total_rows: usize, ) -> Self

Expands the selection to align with batch boundaries. This is needed when using cached array readers to ensure that the cached data covers full batches.

Trait Implementations

impl Clone for RowSelection

fn clone(&self) -> RowSelection

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for RowSelection

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

Formats the value using the given formatter.

impl Default for RowSelection

fn default() -> RowSelection

Returns the “default value” for a type.

impl Eq for RowSelection

impl From<BooleanBuffer> for RowSelection

fn from(mask: BooleanBuffer) -> Self

Converts to this type from the input type.

impl From<RowSelection> for Vec<RowSelector>

fn from(r: RowSelection) -> Self

Converts to this type from the input type.

impl From<RowSelection> for VecDeque<RowSelector>

fn from(r: RowSelection) -> Self

Converts to this type from the input type.

impl From<Vec<RowSelector>> for RowSelection

fn from(selectors: Vec<RowSelector>) -> Self

Converts to this type from the input type.

impl FromIterator<RowSelection> for RowSelection

fn from_iter<T: IntoIterator<Item = RowSelection>>(iter: T) -> Self

Concatenate multiple RowSelections in iterator order.

When every input is mask-backed the result stays mask-backed (BooleanBuffers are appended); otherwise falls back to flattening through the per-RowSelector form.

impl FromIterator<RowSelector> for RowSelection

fn from_iter<T: IntoIterator<Item = RowSelector>>(iter: T) -> Self

Creates a value from an iterator.

impl PartialEq for RowSelection

fn eq(&self, other: &Self) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.