Metadata и Statistics

Иерархия метаданных

Parquet хранит метаданные в Thrift-сериализованной структуре в конце файла. Эта структура — трёхуровневая иерархия: FileMetaData → RowGroupMetaData → ColumnChunkMetaData. Ридер читает только футер, чтобы понять: какие колонки в файле, сколько row groups, где лежит каждый chunk, и какие статистики доступны.

Statistics: min/max/null_count

Каждый ColumnChunkMetaData содержит структуру Statistics с агрегированными значениями по всему chunk:

• min_value / max_value — минимальное и максимальное значение в chunk
• null_count — количество null-значений
• distinct_count — количество уникальных значений (опционально, часто отсутствует)
• is_min_value_exact / is_max_value_exact — флаги точности (для усечённых строк)

Это позволяет row group pruning: если запрос WHERE user_id > 150000, а статистики Row Group 0 показывают max_value = 100000, вся группа пропускается без чтения данных.

ColumnIndex и OffsetIndex

Chunk-level статистики — грубый инструмент. Если row group содержит 1 000 000 строк на 20 страниц, мы можем пропустить ненужные страницы, а не только row groups. Для этого Parquet определяет два индекса:

ColumnIndex хранит min/max/null_count для каждой страницы column chunk. Читается из footer, не требует доступа к самим страницам.

OffsetIndex хранит offset и compressed_page_size для каждой страницы. Позволяет вычислить, какие байты файла нужно прочитать для конкретной страницы.

Комбинация работает так:

1. Ридер читает ColumnIndex из footer → определяет, какие страницы содержат нужные значения
2. Ридер читает OffsetIndex → определяет byte ranges для нужных страниц
3. Выполняет точечные чтения только нужных байтов (Range Reads на S3/GCS)

Это превращает Parquet из «скипаем целые row groups» в «скипаем отдельные страницы» — на порядок точнее.

Bloom-фильтры

Statistics хорошо работают для range-предикатов (>, <, BETWEEN), но для point lookups (WHERE city = 'Berlin') min/max бесполезны, если chunk содержит значения от ‘Amsterdam’ до ‘Zurich’ — диапазон слишком широкий.

Bloom-фильтр — вероятностная структура данных, которая отвечает на вопрос «содержит ли chunk это значение?» с гарантиями:

• Нет → точно нет (false negative невозможен)
• Да → возможно (false positive возможен, но контролируем)

Parquet использует Split Block Bloom Filter (SBBF) — эффективный вариант, оптимизированный под кэш-линии CPU. Фильтр хранится отдельно от данных и читается по offset из footer metadata.

Настройки в PyArrow:

import pyarrow.parquet as pq

pq.write_table(
 table,
 'users.parquet',
 write_statistics=True,
 # Bloom-фильтр для колонки city с FPP 1%
 column_config={
 'city': pq.ColumnConfig(
 bloom_filter_enabled=True,
 bloom_filter_fpp=0.01
 )
 }
)

Порядок чтения метаданных

Когда движок (Spark, DuckDB, Trino) открывает Parquet-файл, происходит многоступенчатый процесс фильтрации — каждый шаг сужает объём данных, которые нужно реально прочитать:

1. Читаем footer (последние N байт файла)
 └── FileMetaData → знаем схему и список row groups

2. Projection pushdown → отбрасываем ненужные колонки
 └── SELECT user_id, score → skip column chunk "username"

3. Row Group pruning по Statistics
 └── WHERE user_id > 150000 → skip Row Group 0 (max=100000)

4. Page-level pruning по ColumnIndex + OffsetIndex
 └── skip Page 0 в Row Group 1 (max=150000)

5. Bloom-фильтр для point lookups
 └── WHERE city = 'Berlin' → skip chunks без 'Berlin'

6. Читаем только нужные байты → декодируем → возвращаем результат

Эволюция метаданных: Page Index и Parquet 2.11+ logical types

Структуры метаданных Parquet эволюционировали постепенно. Понимание timeline помогает читать чужой код и спецификации:

GEOMETRY и GEOGRAPHY logical types (Parquet 2.11+)

Parquet 2.11 (март 2025) ратифицировал нативную поддержку геопространственных типов. До этого геоданные хранились через расширения GeoParquet (1.x — Well-Known Binary в обычном BYTE_ARRAY колонке + sidecar метаданные). Теперь типы — first-class:

• GEOMETRY — features в WKB-формате (Well-Known Binary) с линейной/планарной интерполяцией рёбер. Аннотирует BYTE_ARRAY.
• GEOGRAPHY — features в WKB-формате с нелинейной (геодезической) интерполяцией — рёбра идут по большим кругам сферы/эллипсоида. Тоже BYTE_ARRAY.

Для GEOMETRY и GEOGRAPHY обычные min/max не вычисляются — они бессмысленны для WKB-байтов. Если такие статистики записаны не-compliant писателем, ридер обязан их игнорировать.

Statistics V2: bounding box и distinct count

Parquet 2.11+ добавляет в ColumnChunkMetaData опциональное поле geospatial statistics — bounding box на уровне row group:

GeospatialStatistics {
 bbox: BoundingBox { xmin, xmax, ymin, ymax, zmin?, zmax?, mmin?, mmax? }
 geospatial_types: [POINT, LINESTRING, POLYGON, ...] // какие WKB-типы встречаются
}

Это даёт spatial pruning:

-- Запрос: точки внутри Берлина
SELECT * FROM events
WHERE ST_Within(location, ST_GeomFromText('POLYGON((13.0 52.3, 13.8 52.3, 13.8 52.7, 13.0 52.7, 13.0 52.3))'));

-- Pruning: bbox row group [10.0..11.5, 50.0..51.5] не пересекается с Берлином → skip

Помимо геостатистик, Statistics V2 также формализует distinct count histogram для не-геометрических типов — раньше distinct_count был просто числом и часто отсутствовал. Histogram-based статистики позволяют cost-based optimizer’ам точнее оценивать селективность.

Ключевые выводы

1. FileMetaData хранится в footer файла и содержит полную иерархию: схема → row groups → column chunks → statistics
2. Statistics (min/max/null_count) — chunk-level, позволяют пропускать целые row groups
3. ColumnIndex + OffsetIndex = Page Index (с Parquet 2.5, 2018) — page-level pruning
4. Bloom-фильтры — для point lookups, вероятностное «точно нет / возможно есть» (повсеместная поддержка с PyArrow 11+ / parquet-mr 1.13+ ~2023–2024)
5. Parquet 2.11 (март 2025) добавил VARIANT, GEOMETRY, GEOGRAPHY logical types и Statistics V2 (bbox, distinct count histogram)
6. Многоступенчатая фильтрация: projection → row group pruning → page pruning → bloom filter → spatial pruning → чтение