diff --git a/parquet/src/arrow/async_reader/mod.rs b/parquet/src/arrow/async_reader/mod.rs index 7d5a07f36985..7bee2de2d816 100644 --- a/parquet/src/arrow/async_reader/mod.rs +++ b/parquet/src/arrow/async_reader/mod.rs @@ -1008,7 +1008,7 @@ mod tests { use crate::basic::Encoding; use crate::file::metadata::PageIndexPolicy; use crate::file::metadata::ParquetMetaDataReader; - use crate::file::metadata::page_index::PageIndex; + use crate::file::metadata::page_index::{Grid, PageIndex}; use crate::file::properties::WriterProperties; use arrow::compute::kernels::cmp::eq; use arrow::error::Result as ArrowResult; @@ -1970,7 +1970,7 @@ mod tests { .await .unwrap(); - let page_index = PageIndex::new(None, Some(vec![])); + let page_index = PageIndex::new(None, Some(Grid::from_vec(vec![]).unwrap())); metadata.set_page_index(Some(Arc::new(page_index))); let options = ArrowReaderOptions::new().with_page_index_policy(PageIndexPolicy::Required); let arrow_reader_metadata = ArrowReaderMetadata::try_new(metadata.into(), options).unwrap(); diff --git a/parquet/src/file/metadata/mod.rs b/parquet/src/file/metadata/mod.rs index f5ee3b20a24c..dfe85e2df47f 100644 --- a/parquet/src/file/metadata/mod.rs +++ b/parquet/src/file/metadata/mod.rs @@ -2122,9 +2122,9 @@ mod tests { // Size with page index (includes Arc overhead plus PageIndex heap size) #[cfg(not(feature = "encryption"))] - let bigger_expected_size = 3280; + let bigger_expected_size = 3328; #[cfg(feature = "encryption")] - let bigger_expected_size = 3448; + let bigger_expected_size = 3496; // more set fields means more memory usage assert!(bigger_expected_size > base_expected_size); diff --git a/parquet/src/file/metadata/page_index.rs b/parquet/src/file/metadata/page_index.rs index 78c3dc2792bb..cf5c519c401a 100644 --- a/parquet/src/file/metadata/page_index.rs +++ b/parquet/src/file/metadata/page_index.rs @@ -17,6 +17,8 @@ //! Page Index structures for efficient page-level skipping +use crate::errors::{ParquetError, Result}; +use crate::file::metadata::ColumnChunkMask; use crate::file::metadata::memory::HeapSize; use crate::file::page_index::{ column_index::ColumnIndexMetaData, @@ -363,12 +365,228 @@ impl RowGroupPageIndex { } } +/// A memory-efficient sparse set representation storing sorted deduplicated indexes +/// +/// Stores which positions are set in a sparse vector. For example: +/// `[None, None, Some(...), Some(...), None, Some(...)]` becomes `[2, 3, 5]` +/// +/// Position checking uses binary search. +/// Stores indexes as `u32` because Parquet/Thrift collections cannot contain more than +/// `i32::MAX` entries. +#[derive(Debug, Clone, PartialEq)] +pub(crate) struct Keep { + /// Sorted, deduplicated indexes of set positions + /// None means all positions in the span are set + kept: Option>, + /// Total span of positions (0..span) + span: u32, +} + +impl Keep { + // shortened version for a full keep set + pub(crate) fn new_full(span: usize) -> Result { + Ok(Self { + kept: None, + span: Self::try_span(span)?, + }) + } + + /// Creates a keep set from an already sorted and deduplicated mask axis. + /// + /// The mask allocation is shared when all of its indexes are in range. + fn from_mask(kept: Option>, span: usize) -> Result { + let span = Self::try_span(span)?; + let Some(kept) = kept else { + return Ok(Self { kept: None, span }); + }; + + let in_range = kept.partition_point(|&idx| idx < span); + let kept = if in_range == span as usize { + None + } else if in_range == kept.len() { + Some(kept) + } else { + Some(Arc::from(&kept[..in_range])) + }; + Ok(Self { kept, span }) + } + + fn try_span(span: usize) -> Result { + u32::try_from(span).map_err(|_| { + ParquetError::General(format!("page index dimension exceeds u32::MAX: {span}")) + }) + } + + /// Retrieve a position if set + fn position(&self, idx: usize) -> Option { + let needle = u32::try_from(idx).ok()?; + match self.kept.as_ref() { + None => (needle < self.span).then_some(idx), + Some(k) => k.binary_search(&needle).ok(), + } + } + + /// Returns the number of set positions + fn len(&self) -> usize { + match &self.kept { + None => self.span as usize, + Some(indexes) => indexes.len(), + } + } + + /// Returns the logical index at the specified storage position. + fn index(&self, position: usize) -> usize { + match &self.kept { + None => position, + Some(indexes) => indexes[position] as usize, + } + } +} + +impl HeapSize for Arc<[u32]> { + fn heap_size(&self) -> usize { + // The heap block contains the strong and weak counts followed by the slice, + // padded to the alignment of usize. The fat pointer itself is stored inline. + (2 * std::mem::size_of::() + std::mem::size_of_val(self.as_ref())) + .next_multiple_of(std::mem::align_of::()) + } +} + +impl HeapSize for Keep { + fn heap_size(&self) -> usize { + self.kept.heap_size() + } +} + +/// A memory-efficient 2D sparse grid using Keep structures for rows and columns +/// +/// Maps (row_group_idx, column_idx) to values efficiently for sparse access patterns. +/// This is particularly useful when only a few columns are accessed from wide schemas. +#[derive(Debug, Clone)] +pub(crate) struct Grid { + /// Row group indexes that have storage; a cell can still be `None` + rows: Keep, + /// Column indexes that have storage; a cell can still be `None` + cols: Keep, + /// Flattened cells stored in row-major order + /// cells[row_offset * cols.len() + col_offset] = value at (row, col) + /// where row_offset = position of row in rows.kept + /// and col_offset = position of col in cols.kept + cells: Vec>, +} + +impl PartialEq for Grid { + fn eq(&self, other: &Self) -> bool { + if self.rows == other.rows && self.cols == other.cols { + return self.cells == other.cells; + } + + let num_rows = self.rows.span.max(other.rows.span) as usize; + let num_columns = self.cols.span.max(other.cols.span) as usize; + (0..num_rows).all(|row| { + (0..num_columns).all(|column| self.get(row, column) == other.get(row, column)) + }) + } +} + +impl Grid { + /// Creates a new empty Grid with the specified dimensions + fn new(rows: Keep, cols: Keep) -> Self { + let size = rows.len() * cols.len(); + let mut cells = Vec::with_capacity(size); + cells.resize_with(size, || None); + Self { rows, cols, cells } + } + + pub(crate) fn from_vec(index: Vec>>) -> Result { + let num_row_groups = index.len(); + let num_columns = index.first().map_or(0, Vec::len); + let mut cells = Vec::with_capacity(num_row_groups * num_columns); + for (row_group_idx, row_group) in index.into_iter().enumerate() { + if row_group.len() != num_columns { + return Err(ParquetError::General(format!( + "ragged page index: row group {row_group_idx} has {} columns, expected {num_columns}", + row_group.len() + ))); + } + cells.extend(row_group); + } + + Ok(Self { + rows: Keep::new_full(num_row_groups)?, + cols: Keep::new_full(num_columns)?, + cells, + }) + } + + /// Gets a value at the specified row and column + pub(crate) fn get(&self, row: usize, col: usize) -> Option<&T> { + // Find the offset of this row in the kept rows + let row_offset = self.rows.position(row)?; + let col_offset = self.cols.position(col)?; + + let index = row_offset * self.cols.len() + col_offset; + self.cells.get(index)?.as_ref() + } + + /// Sets a value at the specified row and column. + /// + /// Returns `false`, and drops `value`, if the grid has no storage for the position. + pub(crate) fn insert(&mut self, row: usize, col: usize, value: T) -> bool { + let (Some(row_offset), Some(col_offset)) = + (self.rows.position(row), self.cols.position(col)) + else { + return false; + }; + + self.cells[row_offset * self.cols.len() + col_offset] = Some(value); + true + } + + /// Moves values into a new grid, preserving those whose logical coordinates + /// are selected by the new grid. + fn reshape(self, mut reshaped: Self) -> Self { + let old_num_cols = self.cols.len(); + + for (cell_idx, value) in self.cells.into_iter().enumerate() { + let Some(value) = value else { + continue; + }; + + let row_offset = cell_idx / old_num_cols; + let col_offset = cell_idx % old_num_cols; + let row = self.rows.index(row_offset); + let col = self.cols.index(col_offset); + // A smaller shape or sparse mask may intentionally omit this coordinate. + let _ = reshaped.insert(row, col, value); + } + + reshaped + } + + /// Returns true if the grid has no values + pub(crate) fn is_empty(&self) -> bool { + self.cells.iter().all(|cell| cell.is_none()) + } +} + +impl HeapSize for Grid { + fn heap_size(&self) -> usize { + self.rows.heap_size() + self.cols.heap_size() + self.cells.heap_size() + } +} + /// Struct to encapsulate the Parquet [Page Index] /// -/// This struct provides a dense representation of the Page Index. It is -/// used internally by this crate when assembling and writing the Page -/// Index. It is also the default implementation of the [`PageIndexProvider`] -/// contained in the [`ParquetMetaData`]. +/// This struct provides a sparse representation of the Page Index: it has storage only for +/// the column chunks selected when it was built (all chunks by default). It is used internally +/// by this crate when assembling and writing the Page Index. It is also the default +/// implementation of the [`PageIndexProvider`] contained in the [`ParquetMetaData`]. +/// +/// Use [`PageIndexBuilder::new`] to create dense storage for both index types, or +/// [`PageIndexBuilder::try_new_with_masks`] to select storage independently for column and +/// offset indexes. An existing index can be reshaped while retaining selected entries with +/// [`PageIndex::try_into_builder_with_shape`]. /// /// # Example: Constructing a synthetic `PageIndex` /// @@ -435,20 +653,80 @@ impl RowGroupPageIndex { /// assert!(metadata.page_index().unwrap().is_complete()); /// ``` /// +/// # Example: Expanding a cached sparse `PageIndex` +/// +/// A query engine may cache only the page indexes needed by an initial query. If a later +/// query projects another column, the cached index can be reshaped to add storage for that +/// column without discarding the existing entries. +/// +/// ``` +/// # use parquet::errors::Result; +/// # use parquet::file::metadata::{ColumnChunkMask, OffsetIndexBuilder}; +/// # use parquet::file::metadata::page_index::{PageIndexBuilder, PageIndexProvider}; +/// # use parquet::file::page_index::offset_index::OffsetIndexMetaData; +/// +/// # fn main() -> Result<()> { +/// fn offset_index(offset: i64) -> OffsetIndexMetaData { +/// // create an `OffsetIndexMetaData` with the given offset +/// # let mut builder = OffsetIndexBuilder::new(); +/// # builder.append_row_count(10); +/// # builder.append_offset_and_size(offset, 100); +/// # builder.build() +/// } +/// +/// // The file has two row groups and five columns. The first query needs offset +/// // indexes for columns 0 and 2 in row group 0 only. +/// // The column index is not used so it is left unallocated. +/// let initial_projection = ColumnChunkMask::row_groups_and_columns([0], [0, 2]); +/// let mut builder = PageIndexBuilder::try_new_with_masks( +/// 2, +/// 5, +/// None, +/// Some(&initial_projection), +/// )?; +/// builder.put_offset_index(offset_index(100), 0, 0); +/// builder.put_offset_index(offset_index(200), 0, 2); +/// let cached = builder.build(); +/// +/// assert!(cached.offset_index(0, 0).is_some()); +/// assert!(cached.offset_index(0, 1).is_none()); +/// assert!(cached.offset_index(0, 2).is_some()); +/// assert!(cached.offset_index(1, 0).is_none()); +/// +/// // A later query also projects column 4. Reshape the offset-index grid to +/// // include it; entries for columns 0 and 2 are retained. +/// let expanded_projection = ColumnChunkMask::row_groups_and_columns([0], [0, 2, 4]); +/// let mut builder = cached.try_into_builder_with_shape( +/// 2, +/// 5, +/// None, +/// Some(&expanded_projection), +/// )?; +/// builder.put_offset_index(offset_index(400), 0, 4); +/// let expanded = builder.build(); +/// +/// assert!(expanded.offset_index(0, 0).is_some()); +/// assert!(expanded.offset_index(0, 2).is_some()); +/// assert!(expanded.offset_index(0, 4).is_some()); +/// assert!(expanded.offset_index(0, 1).is_none()); +/// # Ok(()) +/// # } +/// ``` +/// /// [Page Index]: https://parquet.apache.org/docs/file-format/pageindex/ /// [`ColumnIndex`]: crate::file::page_index::column_index::ColumnIndexMetaData /// [`OffsetIndex`]: crate::file::page_index::offset_index::OffsetIndexMetaData /// [`ParquetMetaData`]: crate::file::metadata::ParquetMetaData #[derive(Debug, Clone, PartialEq)] pub struct PageIndex { - column_indexes: Option>>>, - offset_indexes: Option>>>, + column_indexes: Option>, + offset_indexes: Option>, } impl PageIndex { pub(crate) fn new( - column_indexes: Option>>>, - offset_indexes: Option>>>, + column_indexes: Option>, + offset_indexes: Option>, ) -> Self { Self { column_indexes, @@ -456,10 +734,42 @@ impl PageIndex { } } - /// Convert this `PageIndex` into a [`PageIndexBuilder`] + /// Convert this `PageIndex` into a [`PageIndexBuilder`]. + /// + /// The builder retains the storage shape of this index. Consequently, its `put_*` + /// methods ignore positions outside that shape. The `allocate_*` methods can replace it + /// with dense storage, but discard existing entries for that index type. Use + /// [`Self::try_into_builder_with_shape`] to change the shape while preserving entries. pub fn into_builder(self) -> PageIndexBuilder { self.into() } + + /// Convert this `PageIndex` into a [`PageIndexBuilder`] with the requested shape. + /// + /// Existing entries selected by the new masks are preserved. Passing `Some` with a + /// [`ColumnChunkMask::all`] mask creates dense storage for that index type, passing + /// `Some` with another mask creates sparse storage, and passing `None` removes storage + /// for that index type. + /// + /// # Errors + /// + /// Returns an error if either dimension exceeds `u32::MAX`. + pub fn try_into_builder_with_shape( + self, + num_row_groups: usize, + num_columns: usize, + column_index_mask: Option<&ColumnChunkMask>, + offset_index_mask: Option<&ColumnChunkMask>, + ) -> Result { + let mut builder = self.into_builder(); + builder.try_reshape( + num_row_groups, + num_columns, + column_index_mask, + offset_index_mask, + )?; + Ok(builder) + } } impl PageIndexProvider for PageIndex { @@ -476,8 +786,7 @@ impl PageIndexProvider for PageIndex { row_group_idx: usize, column_idx: usize, ) -> Option<&ColumnIndexMetaData> { - let rg = self.column_indexes.as_ref()?.get(row_group_idx)?; - rg.get(column_idx)?.as_ref() + self.column_indexes.as_ref()?.get(row_group_idx, column_idx) } fn offset_index( @@ -485,8 +794,7 @@ impl PageIndexProvider for PageIndex { row_group_idx: usize, column_idx: usize, ) -> Option<&OffsetIndexMetaData> { - let rg = self.offset_indexes.as_ref()?.get(row_group_idx)?; - rg.get(column_idx)?.as_ref() + self.offset_indexes.as_ref()?.get(row_group_idx, column_idx) } fn as_any(&self) -> &dyn std::any::Any { @@ -496,6 +804,9 @@ impl PageIndexProvider for PageIndex { impl HeapSize for PageIndex { fn heap_size(&self) -> usize { + // Column and offset grids created from the same ColumnChunkMask may share their + // Keep allocations. HeapSize accounts for each Arc independently, so those shared + // allocations may be counted more than once. self.column_indexes.heap_size() + self.offset_indexes.heap_size() } } @@ -508,28 +819,52 @@ impl HeapSize for PageIndex { /// - Automatic conversion of empty structures to `None` to save memory #[derive(Default)] pub struct PageIndexBuilder { - column_indexes: Option>>>, - offset_indexes: Option>>>, + column_indexes: Option>, + offset_indexes: Option>, } impl PageIndexBuilder { - /// Creates an empty index structure with space for the specified number of row groups and columns + fn storage_for_selection( + num_row_groups: usize, + num_columns: usize, + mask: Option<&ColumnChunkMask>, + ) -> Result>> { + let Some(mask) = mask else { + return Ok(None); + }; + + let rows = Keep::from_mask(mask.selected_row_groups_shared(), num_row_groups)?; + let cols = Keep::from_mask(mask.selected_columns_shared(), num_columns)?; + Ok(Some(Grid::new(rows, cols))) + } + + /// Creates a new builder with storage selected independently for each index type. /// - /// Returns `Some` containing a nested vector structure where all entries are initialized to `None`. - /// The outer vector has one entry per row group, and each inner vector has one entry per column. + /// Passing `Some` with a [`ColumnChunkMask::all`] mask creates dense storage for that + /// index type, passing `Some` with another mask creates sparse storage, and passing + /// `None` leaves that index type unallocated. /// - /// # Type Parameters - /// * `T` - The type of index this is to be, either `ColumnIndexMetaData` or `OffsetIndexMetaData` - fn empty_index(num_row_groups: usize, num_columns: usize) -> Option>>> { - Some( - (0..num_row_groups) - .map(|_| { - let mut idx = Vec::with_capacity(num_columns); - idx.resize_with(num_columns, || None); - idx - }) - .collect(), - ) + /// # Errors + /// + /// Returns an error if either dimension exceeds `u32::MAX`. + pub fn try_new_with_masks( + num_row_groups: usize, + num_columns: usize, + column_index_mask: Option<&ColumnChunkMask>, + offset_index_mask: Option<&ColumnChunkMask>, + ) -> Result { + Ok(Self { + column_indexes: Self::storage_for_selection( + num_row_groups, + num_columns, + column_index_mask, + )?, + offset_indexes: Self::storage_for_selection( + num_row_groups, + num_columns, + offset_index_mask, + )?, + }) } /// Creates a new [`PageIndexBuilder`] with space allocated for both column and offset indexes @@ -537,10 +872,18 @@ impl PageIndexBuilder { /// This allocates empty index structures for the specified number of row groups and columns. /// All index entries are initialized to `None` and can be populated using /// [`put_column_index`](Self::put_column_index) and [`put_offset_index`](Self::put_offset_index). + /// + /// # Panics + /// + /// Panics if either dimension exceeds `u32::MAX`. pub fn new(num_row_groups: usize, num_columns: usize) -> Self { + let keep_cols = + Keep::new_full(num_columns).expect("page index column count exceeds u32::MAX"); + let keep_rows = + Keep::new_full(num_row_groups).expect("page index row group count exceeds u32::MAX"); Self { - column_indexes: Self::empty_index(num_row_groups, num_columns), - offset_indexes: Self::empty_index(num_row_groups, num_columns), + column_indexes: Some(Grid::new(keep_rows.clone(), keep_cols.clone())), + offset_indexes: Some(Grid::new(keep_rows, keep_cols)), } } @@ -555,6 +898,39 @@ impl PageIndexBuilder { } } + /// Changes the shape of the index storage while preserving selected entries. + /// + /// Existing entries selected by the new masks are preserved. Passing `Some` with a + /// [`ColumnChunkMask::all`] mask creates dense storage for that index type, passing + /// `Some` with another mask creates sparse storage, and passing `None` removes storage + /// for that index type. A mask may also allocate a previously absent index type. + /// + /// # Errors + /// + /// Returns an error if either dimension exceeds `u32::MAX`. + pub fn try_reshape( + &mut self, + num_row_groups: usize, + num_columns: usize, + column_index_mask: Option<&ColumnChunkMask>, + offset_index_mask: Option<&ColumnChunkMask>, + ) -> Result<()> { + let column_indexes = + Self::storage_for_selection(num_row_groups, num_columns, column_index_mask)?; + let offset_indexes = + Self::storage_for_selection(num_row_groups, num_columns, offset_index_mask)?; + + self.column_indexes = match (self.column_indexes.take(), column_indexes) { + (Some(old), Some(new)) => Some(old.reshape(new)), + (_, new) => new, + }; + self.offset_indexes = match (self.offset_indexes.take(), offset_indexes) { + (Some(old), Some(new)) => Some(old.reshape(new)), + (_, new) => new, + }; + Ok(()) + } + /// Allocates space for column indexes /// /// This allocates an empty index structure for the specified number of row groups and columns. @@ -563,8 +939,17 @@ impl PageIndexBuilder { /// /// This can be used to add column index storage to a builder that lacks one /// (either a `Default` builder, or one created from a [`PageIndex`] without column indexes). + /// This replaces any existing column index storage and discards its entries. + /// + /// # Panics + /// + /// Panics if either dimension exceeds `u32::MAX`. pub fn allocate_column_indexes(&mut self, num_row_groups: usize, num_columns: usize) { - self.column_indexes = Self::empty_index(num_row_groups, num_columns); + let keep_cols = + Keep::new_full(num_columns).expect("page index column count exceeds u32::MAX"); + let keep_rows = + Keep::new_full(num_row_groups).expect("page index row group count exceeds u32::MAX"); + self.column_indexes = Some(Grid::new(keep_rows, keep_cols)); } /// Allocates space for offset indexes @@ -575,8 +960,17 @@ impl PageIndexBuilder { /// /// This can be used to add offset index storage to a builder that lacks one /// (either a `Default` builder, or one created from a [`PageIndex`] without offset indexes). + /// This replaces any existing offset index storage and discards its entries. + /// + /// # Panics + /// + /// Panics if either dimension exceeds `u32::MAX`. pub fn allocate_offset_indexes(&mut self, num_row_groups: usize, num_columns: usize) { - self.offset_indexes = Self::empty_index(num_row_groups, num_columns); + let keep_cols = + Keep::new_full(num_columns).expect("page index column count exceeds u32::MAX"); + let keep_rows = + Keep::new_full(num_row_groups).expect("page index row group count exceeds u32::MAX"); + self.offset_indexes = Some(Grid::new(keep_rows, keep_cols)); } /// Sets the column index for a specific row group and column @@ -589,12 +983,22 @@ impl PageIndexBuilder { row_group_idx: usize, column_idx: usize, ) { - if let Some(ref mut indexes) = self.column_indexes - && let Some(row_group) = indexes.get_mut(row_group_idx) - && let Some(column_slot) = row_group.get_mut(column_idx) - { - *column_slot = Some(column_index); - } + let _ = self.try_put_column_index(column_index, row_group_idx, column_idx); + } + + /// Attempts to set the column index for a specific row group and column. + /// + /// Returns `false`, and drops `column_index`, if column indexes were not allocated + /// (see [`Self::allocate_column_indexes`]) or the grid has no storage for the position. + pub fn try_put_column_index( + &mut self, + column_index: ColumnIndexMetaData, + row_group_idx: usize, + column_idx: usize, + ) -> bool { + self.column_indexes + .as_mut() + .is_some_and(|indexes| indexes.insert(row_group_idx, column_idx, column_index)) } /// Sets the offset index for a specific row group and column @@ -607,21 +1011,29 @@ impl PageIndexBuilder { row_group_idx: usize, column_idx: usize, ) { - if let Some(ref mut indexes) = self.offset_indexes - && let Some(row_group) = indexes.get_mut(row_group_idx) - && let Some(column_slot) = row_group.get_mut(column_idx) - { - *column_slot = Some(offset_index); - } + let _ = self.try_put_offset_index(offset_index, row_group_idx, column_idx); + } + + /// Attempts to set the offset index for a specific row group and column. + /// + /// Returns `false`, and drops `offset_index`, if offset indexes were not allocated + /// (see [`Self::allocate_offset_indexes`]) or the grid has no storage for the position. + pub fn try_put_offset_index( + &mut self, + offset_index: OffsetIndexMetaData, + row_group_idx: usize, + column_idx: usize, + ) -> bool { + self.offset_indexes + .as_mut() + .is_some_and(|indexes| indexes.insert(row_group_idx, column_idx, offset_index)) } /// Checks if an index structure is entirely empty (all entries are None) - fn is_empty_index(index: Option<&Vec>>>) -> bool { + fn is_empty_index(index: Option<&Grid>) -> bool { match index { None => true, - Some(row_groups) => row_groups - .iter() - .all(|columns| columns.iter().all(|entry| entry.is_none())), + Some(index) => index.is_empty(), } } @@ -654,3 +1066,281 @@ impl From for PageIndexBuilder { Self::new_from(page_index) } } + +#[cfg(test)] +mod tests { + use super::{Grid, Keep, PageIndex, PageIndexBuilder}; + use crate::{ + basic::BoundaryOrder, + file::metadata::ColumnChunkMask, + file::page_index::column_index::{ColumnIndexMetaData, PrimitiveColumnIndex}, + }; + use std::sync::Arc; + + fn colidx_for_test() -> ColumnIndexMetaData { + let ci = PrimitiveColumnIndex::::try_new( + vec![false; 3], + BoundaryOrder::ASCENDING, + Some(vec![0; 3]), + Some(vec![0; 3]), + None, + None, + vec![&[0, 0, 0, 0]; 3], + vec![&[1, 0, 0, 0]; 3], + ) + .unwrap(); + ColumnIndexMetaData::INT32(ci) + } + + #[test] + fn test_sparse_get_put() { + let ci = colidx_for_test(); + + let keep_rows = Keep::from_mask(Some(Arc::from([0, 3, 7])), 10).unwrap(); + let keep_cols = Keep::from_mask(Some(Arc::from([5, 10, 99])), 100).unwrap(); + let mut storage = Grid::new(keep_rows, keep_cols); + + // Test insertion and retrieval + assert!(storage.insert(0, 5, ci.clone())); + assert!(storage.insert(3, 10, ci.clone())); + assert!(storage.insert(7, 99, ci.clone())); + assert!(!storage.insert(1, 5, ci.clone())); + + // Test successful retrievals + assert!(storage.get(0, 5).is_some()); + assert!(storage.get(3, 10).is_some()); + assert!(storage.get(7, 99).is_some()); + + // Test missing entries + assert!(storage.get(0, 0).is_none()); + assert!(storage.get(1, 5).is_none()); + assert!(storage.get(0, 10).is_none()); + + // Test out of bounds + assert!(storage.get(20, 5).is_none()); + assert!(storage.get(0, 200).is_none()); + } + + #[test] + fn test_empty_keep_selects_nothing() { + let keep = Keep::from_mask(Some(Arc::from([])), 10).unwrap(); + assert_eq!(keep.len(), 0); + assert_eq!(keep.position(0), None); + assert_eq!(keep.position(9), None); + assert_eq!(keep.position(10), None); + } + + #[test] + fn test_keep_shares_mask_storage() { + let mask = ColumnChunkMask::columns([1, 3]); + let selected = mask.selected_columns_shared().unwrap(); + let keep = Keep::from_mask(Some(Arc::clone(&selected)), 5).unwrap(); + + assert!(Arc::ptr_eq(keep.kept.as_ref().unwrap(), &selected)); + assert_eq!(keep.position(1), Some(0)); + assert_eq!(keep.position(3), Some(1)); + } + + #[test] + fn test_keep_from_mask_discards_out_of_range_indexes() { + let mask = ColumnChunkMask::columns([1, 3, 10]); + let keep = Keep::from_mask(mask.selected_columns_shared(), 5).unwrap(); + + assert_eq!(keep.kept.as_deref(), Some([1, 3].as_slice())); + assert_eq!(keep.position(10), None); + } + + #[test] + fn test_keep_normalizes_full_selection() { + let mask = ColumnChunkMask::columns([2, 0, 1, 2]); + let keep = Keep::from_mask(mask.selected_columns_shared(), 3).unwrap(); + + assert!(keep.kept.is_none()); + assert_eq!(keep.len(), 3); + assert_eq!(keep.position(0), Some(0)); + assert_eq!(keep.position(2), Some(2)); + assert_eq!(keep.position(3), None); + } + + #[cfg(target_pointer_width = "64")] + #[test] + fn test_oversized_dimensions_return_error() { + let span = u32::MAX as usize + 1; + assert!(Keep::from_mask(Some(Arc::from([])), span).is_err()); + assert!(Keep::new_full(span).is_err()); + assert!(std::panic::catch_unwind(|| PageIndexBuilder::new(0, span)).is_err()); + assert!( + std::panic::catch_unwind(|| { + PageIndexBuilder::default().allocate_column_indexes(0, span) + }) + .is_err() + ); + assert!( + std::panic::catch_unwind(|| { + PageIndexBuilder::default().allocate_offset_indexes(0, span) + }) + .is_err() + ); + assert!( + PageIndexBuilder::default() + .try_reshape(0, span, Some(&ColumnChunkMask::all()), None) + .is_err() + ); + } + + #[test] + fn test_builder_try_put_reports_missing_storage() { + let ci = colidx_for_test(); + let mut grid = Grid::new( + Keep::from_mask(Some(Arc::from([0])), 1).unwrap(), + Keep::from_mask(Some(Arc::from([0])), 2).unwrap(), + ); + assert!(grid.insert(0, 0, ci.clone())); + + let mut builder = PageIndex::new(Some(grid), None).into_builder(); + assert!(builder.try_put_column_index(ci.clone(), 0, 0)); + assert!(!builder.try_put_column_index(ci, 0, 1)); + } + + #[test] + fn test_builder_sparse_storage_shape() { + let mask = ColumnChunkMask::columns([0, 2]); + let builder = PageIndexBuilder::try_new_with_masks(4, 5, Some(&mask), None).unwrap(); + + let column_indexes = builder.column_indexes.unwrap(); + assert_eq!(column_indexes.rows.len(), 4); + assert_eq!(column_indexes.cols.len(), 2); + assert_eq!(column_indexes.cells.len(), 8); + assert!(builder.offset_indexes.is_none()); + } + + #[test] + fn test_builder_allocate_indexes_creates_dense_empty_storage() { + let ci = colidx_for_test(); + let mut builder = PageIndexBuilder::default(); + + builder.allocate_column_indexes(2, 3); + assert!(builder.try_put_column_index(ci, 1, 2)); + builder.allocate_column_indexes(2, 3); + let column_indexes = builder.column_indexes.as_ref().unwrap(); + assert_eq!(column_indexes.rows.len(), 2); + assert_eq!(column_indexes.cols.len(), 3); + assert_eq!(column_indexes.cells.len(), 6); + assert!(column_indexes.is_empty()); + + builder.allocate_offset_indexes(2, 3); + let offset_indexes = builder.offset_indexes.as_ref().unwrap(); + assert_eq!(offset_indexes.rows.len(), 2); + assert_eq!(offset_indexes.cols.len(), 3); + assert_eq!(offset_indexes.cells.len(), 6); + assert!(offset_indexes.is_empty()); + } + + #[test] + fn test_builder_reshape_preserves_entries_with_dense_and_sparse_storage() { + let ci = colidx_for_test(); + let mut grid = Grid::new( + Keep::from_mask(Some(Arc::from([0, 2])), 3).unwrap(), + Keep::from_mask(Some(Arc::from([1])), 3).unwrap(), + ); + assert!(grid.insert(0, 1, ci.clone())); + assert!(grid.insert(2, 1, ci.clone())); + + let page_index = PageIndex::new(Some(grid), None); + let all = ColumnChunkMask::all(); + let mut builder = page_index + .try_into_builder_with_shape(4, 4, Some(&all), None) + .unwrap(); + + let column_indexes = builder.column_indexes.as_ref().unwrap(); + assert!(column_indexes.rows.kept.is_none()); + assert!(column_indexes.cols.kept.is_none()); + assert_eq!(column_indexes.cells.len(), 16); + assert_eq!(column_indexes.get(0, 1), Some(&ci)); + assert_eq!(column_indexes.get(2, 1), Some(&ci)); + assert!(builder.offset_indexes.is_none()); + + // A position omitted from the original sparse grid is now available. + builder.put_column_index(ci.clone(), 3, 3); + assert_eq!( + builder.column_indexes.as_ref().unwrap().get(3, 3), + Some(&ci) + ); + + // Sparse reshaping retains selected entries, drops unselected entries, and can + // allocate storage for an index type that was previously absent. + let column_mask = ColumnChunkMask::row_groups_and_columns([0, 3], [1, 3]); + let offset_mask = ColumnChunkMask::row_groups_and_columns([1], [2]); + builder + .try_reshape(4, 4, Some(&column_mask), Some(&offset_mask)) + .unwrap(); + let column_indexes = builder.column_indexes.as_ref().unwrap(); + assert_eq!(column_indexes.cells.len(), 4); + assert_eq!(column_indexes.get(0, 1), Some(&ci)); + assert!(column_indexes.get(2, 1).is_none()); + assert_eq!(column_indexes.get(3, 3), Some(&ci)); + let offset_indexes = builder.offset_indexes.as_ref().unwrap(); + assert_eq!(offset_indexes.cells.len(), 1); + assert!(offset_indexes.get(1, 2).is_none()); + + // Changing dimensions preserves only entries that remain in bounds. + builder.try_reshape(2, 2, Some(&all), None).unwrap(); + let column_indexes = builder.column_indexes.as_ref().unwrap(); + assert_eq!(column_indexes.cells.len(), 4); + assert_eq!(column_indexes.get(0, 1), Some(&ci)); + assert!(column_indexes.get(3, 3).is_none()); + + // Passing None removes storage for that index type. + builder.try_reshape(4, 4, None, Some(&all)).unwrap(); + assert!(builder.column_indexes.is_none()); + assert_eq!(builder.offset_indexes.as_ref().unwrap().cells.len(), 16); + } + + #[test] + fn test_grid_is_empty() { + let ci = colidx_for_test(); + + let keep_rows = Keep::from_mask(Some(Arc::from([0, 3, 7])), 10).unwrap(); + let keep_cols = Keep::from_mask(Some(Arc::from([5, 10, 99])), 100).unwrap(); + let mut storage = Grid::new(keep_rows, keep_cols); + assert!(storage.is_empty()); + + assert!(storage.insert(0, 5, ci.clone())); + assert!(!storage.is_empty()); + } + + #[test] + fn test_grid_equality_ignores_storage_shape() { + let ci = colidx_for_test(); + let mut dense = Grid::new(Keep::new_full(2).unwrap(), Keep::new_full(3).unwrap()); + assert!(dense.insert(0, 0, ci.clone())); + + let mut sparse = Grid::new( + Keep::from_mask(Some(Arc::from([0])), 2).unwrap(), + Keep::from_mask(Some(Arc::from([0])), 3).unwrap(), + ); + assert!(sparse.insert(0, 0, ci.clone())); + assert_eq!(dense, sparse); + + assert!(dense.insert(1, 2, ci)); + assert_ne!(dense, sparse); + } + + #[test] + fn test_grid_from_vec() { + let grid = Grid::from_vec(vec![vec![Some(1), None], vec![None, Some(2)]]).unwrap(); + assert_eq!(grid.get(0, 0), Some(&1)); + assert_eq!(grid.get(0, 1), None); + assert_eq!(grid.get(1, 0), None); + assert_eq!(grid.get(1, 1), Some(&2)); + } + + #[test] + fn test_grid_from_vec_rejects_ragged_rows() { + let error = Grid::from_vec(vec![vec![None::], vec![None, Some(1)]]).unwrap_err(); + assert_eq!( + error.to_string(), + "Parquet error: ragged page index: row group 1 has 2 columns, expected 1" + ); + } +} diff --git a/parquet/src/file/metadata/parser.rs b/parquet/src/file/metadata/parser.rs index 22f0564a9c4f..b613742d52b3 100644 --- a/parquet/src/file/metadata/parser.rs +++ b/parquet/src/file/metadata/parser.rs @@ -260,10 +260,13 @@ pub(crate) fn parse_page_index( ) -> Result<()> { let num_row_groups = metadata.num_row_groups(); let num_columns = metadata.file_metadata().schema_descr().num_columns(); - let mut builder = PageIndexBuilder::default(); - + let mut builder = PageIndexBuilder::try_new_with_masks( + num_row_groups, + num_columns, + (column_index_policy != PageIndexPolicy::Skip).then_some(column_index_mask), + (offset_index_policy != PageIndexPolicy::Skip).then_some(offset_index_mask), + )?; if column_index_policy != PageIndexPolicy::Skip { - builder.allocate_column_indexes(num_row_groups, num_columns); parse_column_index( metadata, column_index_policy, @@ -274,7 +277,6 @@ pub(crate) fn parse_page_index( )?; } if offset_index_policy != PageIndexPolicy::Skip { - builder.allocate_offset_indexes(num_row_groups, num_columns); parse_offset_index( metadata, offset_index_policy, diff --git a/parquet/src/file/metadata/reader.rs b/parquet/src/file/metadata/reader.rs index 78710600bfe5..b22b447346bd 100644 --- a/parquet/src/file/metadata/reader.rs +++ b/parquet/src/file/metadata/reader.rs @@ -237,6 +237,14 @@ impl ColumnChunkMask { self.row_groups.is_none() && self.columns.is_none() } + pub(crate) fn selected_row_groups_shared(&self) -> Option> { + self.row_groups.clone() + } + + pub(crate) fn selected_columns_shared(&self) -> Option> { + self.columns.clone() + } + /// Returns `true` when either configured axis is empty (and thus would select no column chunks). /// /// This does not consider the dimensions of a particular Parquet file, so may return `false` diff --git a/parquet/src/file/writer.rs b/parquet/src/file/writer.rs index 7030cb28c671..5900d8f04e7b 100644 --- a/parquet/src/file/writer.rs +++ b/parquet/src/file/writer.rs @@ -18,7 +18,7 @@ //! [`SerializedFileWriter`]: Low level Parquet writer API use crate::bloom_filter::Sbbf; -use crate::file::metadata::page_index::PageIndex; +use crate::file::metadata::page_index::{Grid, PageIndex}; use crate::file::metadata::thrift::PageHeader; use crate::file::page_index::column_index::ColumnIndexMetaData; use crate::file::page_index::offset_index::OffsetIndexMetaData; @@ -387,13 +387,13 @@ impl SerializedFileWriter { { None } else { - Some(column_indexes) + Some(Grid::from_vec(column_indexes)?) }; // offset index will always be created unless explicitly disabled let offset_indexes = if self.props.offset_index_disabled() { None } else { - Some(offset_indexes) + Some(Grid::from_vec(offset_indexes)?) }; if column_indexes.is_some() || offset_indexes.is_some() { let page_index = PageIndex::new(column_indexes, offset_indexes); diff --git a/parquet/tests/arrow_reader/page_index.rs b/parquet/tests/arrow_reader/page_index.rs index e1a830028647..4b32990545a7 100644 --- a/parquet/tests/arrow_reader/page_index.rs +++ b/parquet/tests/arrow_reader/page_index.rs @@ -382,9 +382,9 @@ fn test_page_index_sizes() { let metadata = reader.finish().unwrap(); assert!(metadata.page_index().is_some()); #[cfg(not(feature = "encryption"))] - assert_eq!(metadata.memory_size(), 13897); + assert_eq!(metadata.memory_size(), 13849); #[cfg(feature = "encryption")] - assert_eq!(metadata.memory_size(), 14321); + assert_eq!(metadata.memory_size(), 14273); // populate column 0 for column index and all columns for offset index let mut reader = ParquetMetaDataReader::new() @@ -397,9 +397,9 @@ fn test_page_index_sizes() { let metadata = reader.finish().unwrap(); assert!(metadata.page_index().is_some()); #[cfg(not(feature = "encryption"))] - assert_eq!(metadata.memory_size(), 12776); + assert_eq!(metadata.memory_size(), 10664); #[cfg(feature = "encryption")] - assert_eq!(metadata.memory_size(), 13200); + assert_eq!(metadata.memory_size(), 11088); // populate column 0 for column index and columns 0 & 2 for the offset index let mut reader = ParquetMetaDataReader::new() @@ -412,9 +412,9 @@ fn test_page_index_sizes() { let metadata = reader.finish().unwrap(); assert!(metadata.page_index().is_some()); #[cfg(not(feature = "encryption"))] - assert_eq!(metadata.memory_size(), 12056); + assert_eq!(metadata.memory_size(), 9680); #[cfg(feature = "encryption")] - assert_eq!(metadata.memory_size(), 12480); + assert_eq!(metadata.memory_size(), 10104); // populate only row group 1, column index gets column 0, offset index gets // columns 0 and 2. @@ -428,7 +428,7 @@ fn test_page_index_sizes() { let metadata = reader.finish().unwrap(); assert!(metadata.page_index().is_some()); #[cfg(not(feature = "encryption"))] - assert_eq!(metadata.memory_size(), 11326); + assert_eq!(metadata.memory_size(), 8342); #[cfg(feature = "encryption")] - assert_eq!(metadata.memory_size(), 11750); + assert_eq!(metadata.memory_size(), 8766); }