@loaders.gl/parquet 5.0.0-alpha.2 → 5.0.0-alpha.4

package/src/parquet-source-loader.ts

@@ -2,13 +2,42 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-import {hydrateArrowTable} from '@loaders.gl/arrow';
+import {dehydrateArrowTable, hydrateArrowTable, IndexedArrowTable} from '@loaders.gl/arrow';
 import type {CoreAPI, ReadableFile, SourceLoader} from '@loaders.gl/loader-utils';
-import {BlobFile, DataSource, isBrowser} from '@loaders.gl/loader-utils';
+import {
+  BlobFile,
+  DataSource,
+  createScanQueryMetadata,
+  emitScanExecutionTelemetry,
+  explainTableQuery,
+  isBrowser,
+  makeTableScanBatch,
+  validateTableQueryLimit
+} from '@loaders.gl/loader-utils';
+import type {
+  ScanColumnRole,
+  ScanExecutionTelemetry,
+  ScanQueryMetadata,
+  ScanQueryMetadataOptions,
+  TableScanSource
+} from '@loaders.gl/loader-utils';
 import type {ArrayType, ArrowTable, Schema} from '@loaders.gl/schema';
 import {convertTable} from '@loaders.gl/schema-utils';
+import {getGeoMetadata} from '@loaders.gl/gis';
 
 import {getSchemaFromParquetReader} from './lib/parsers/get-parquet-schema';
+import {
+  canGeoParquetRowGroupMatch,
+  combineParquetPredicates,
+  createGeoParquetBoundingBoxPredicate
+} from './lib/geo/geoparquet-covering';
+import {
+  decodeParquetSplitBlockBloomFilter,
+  encodeParquetBloomFilterValue,
+  hashParquetBloomFilterValue,
+  checkParquetSplitBlockBloomFilter
+} from './lib/parquet-bloom-filter';
+import {getParquetBloomFilterProbes} from './lib/parquet-bloom-filter-planner';
 import {
   canParquetRowGroupMatch,
   copyParquetPredicate,
@@ -31,28 +60,43 @@ import {
   type ParquetSourceWorkerOptions,
   type ParquetSourceWorkerResult
 } from './lib/parquet-source-worker-types';
+import {sliceParquetBatch} from './lib/slice-parquet-batch';
 import {ParquetRangeFile} from './lib/sources/parquet-range-file';
+import {toPrimitive} from './parquetjs/schema/types';
+import type {ParquetType} from './parquetjs/schema/declare';
 import {
+  PARQUET_TABLE_QUERY_CAPABILITIES,
   PARQUET_SOURCE_CAPABILITIES,
   type ParquetSourceCapabilities
 } from './parquet-source-capabilities';
 import {ParquetSourceLoader as ParquetSourceLoaderMetadata} from './parquet-source-loader-types';
+import type {
+  ParquetEncodedPageBatch,
+  ParquetEncodedPageReadOptions,
+  ParquetDeferredPageFilter
+} from './parquet-encoded-page-types';
 import type {
   ParquetBatch,
   ParquetColumnChunkMetadata,
   ParquetColumnChunkStatistics,
+  ParquetColumnChunkSizeStatistics,
+  ParquetGeospatialStatistics,
   ParquetMetadataRequestOptions,
   ParquetObjectVersion,
+  ParquetPageScanPlan,
   ParquetPredicate,
   ParquetRowGroupMetadata,
+  ParquetSortingColumn,
   ParquetSourceBatch,
   ParquetSourceLoaderOptions,
   ParquetSourceMetadata,
   ParquetSourceReadOptions,
+  ParquetSourceExplain,
   ParquetTelemetry,
   ParquetTelemetryEvent
 } from './parquet-source-types';
 export {
+  PARQUET_TABLE_QUERY_CAPABILITIES,
   PARQUET_SOURCE_CAPABILITIES,
   type ParquetSourceCapabilities
 } from './parquet-source-capabilities';
@@ -62,6 +106,8 @@ import {
   Encoding,
   type ColumnChunk,
   type FileMetaData,
+  type GeospatialStatistics as ParquetThriftGeospatialStatistics,
+  type RowGroup,
   type Statistics as ParquetThriftStatistics
 } from './parquetjs/parquet-thrift/index';
 import {ParquetReader} from './parquetjs/parser/parquet-reader';
@@ -80,14 +126,28 @@ import {
 } from './parquetjs/utils/binary-utils';
 import {fieldIndexOf} from './parquetjs/utils/read-utils';
 
+export type {
+  ParquetEncodedColumnChunk,
+  ParquetEncodedPage,
+  ParquetEncodedPageBatch,
+  ParquetEncodedPageReadOptions,
+  ParquetEncodedPageSection,
+  ParquetDeferredPageFilter,
+  ParquetPageCompressionState
+} from './parquet-encoded-page-types';
 export type {
   ParquetBatch,
   ParquetBatchMetadata,
   ParquetBatchProvenance,
+  ParquetBoundingBox,
   ParquetColumnChunkMetadata,
   ParquetColumnChunkStatistics,
+  ParquetColumnChunkSizeStatistics,
+  ParquetGeospatialBoundingBox,
+  ParquetGeospatialStatistics,
   ParquetMetadataRequestOptions,
   ParquetObjectVersion,
+  ParquetPageScanPlan,
   ParquetComparisonPredicate,
   ParquetInPredicate,
   ParquetLogicalPredicate,
@@ -99,10 +159,12 @@ export type {
   ParquetRangeRequestOptions,
   ParquetReadOptions,
   ParquetRowGroupMetadata,
+  ParquetSortingColumn,
   ParquetSourceBatch,
   ParquetSourceLoaderOptions,
   ParquetSourceMetadata,
   ParquetSourceReadOptions,
+  ParquetSourceExplain,
   ParquetTelemetry,
   ParquetTelemetryEvent
 } from './parquet-source-types';
@@ -149,6 +211,27 @@ type SettledParquetRowGroupRead =
       result?: never;
     };
 
+type ParquetPhysicalRowGroupPlan = {
+  /** Predicate including any GeoParquet covering predicate derived from a bounding box. */
+  predicate?: ParquetPredicate;
+  /** Row groups retained by all physical pruning stages. */
+  rowGroupIndices: number[];
+  /** Candidate row groups explicitly requested by the caller. */
+  requested: number;
+  /** Row groups rejected by the caller metadata callback. */
+  prunedByCallback: number;
+  /** Row groups rejected by native geospatial statistics. */
+  prunedBySpatial: number;
+  /** Row groups rejected by column or covering statistics. */
+  prunedByStatistics: number;
+  /** Row groups rejected by split-block Bloom filters. */
+  prunedByBloomFilter: number;
+  /** Bloom-filter payloads read while planning. */
+  bloomFiltersRead: number;
+  /** Bloom-filter bytes read while planning. */
+  bloomFilterBytesRead: number;
+};
+
 const {
   preload: _preloadParquetSourceLoader,
   createDataSource: _createMetadataDataSource,
@@ -169,7 +252,12 @@ export const ParquetSourceLoaderWithParser = {
 export {ParquetSourceLoaderWithParser as ParquetSourceLoader};
 
 /** Reusable Parquet source that caches footer/schema state and selectively reads byte ranges. */
-export class ParquetSource extends DataSource<string | Blob, ParquetSourceLoaderOptions> {
+export class ParquetSource
+  extends DataSource<string | Blob, ParquetSourceLoaderOptions>
+  implements TableScanSource<ParquetSourceBatch, ParquetPredicate>
+{
+  /** Common projection, predicate, limit, streaming, and cancellation capabilities. */
+  readonly tableQueryCapabilities = PARQUET_TABLE_QUERY_CAPABILITIES;
   /** Immutable feature support for the current range-backed source implementation. */
   readonly capabilities: ParquetSourceCapabilities = PARQUET_SOURCE_CAPABILITIES;
   /** Shared initialization for this source instance. */
@@ -212,6 +300,179 @@ export class ParquetSource extends DataSource<string | Blob, ParquetSourceLoader
     };
   }
 
+  /** Discovers schema, capabilities, and footer statistics without decoding Parquet data pages. */
+  async getQueryMetadata(options: ScanQueryMetadataOptions = {}): Promise<ScanQueryMetadata> {
+    const [schema, metadata] = await Promise.all([
+      this.getSchema({signal: options.signal}),
+      this.getMetadata({signal: options.signal})
+    ]);
+    return createScanQueryMetadata({
+      sourceType: 'parquet',
+      queryType: 'table',
+      execution: {status: 'supported', method: 'read'},
+      name: metadata.name,
+      schema,
+      capabilities: {table: this.tableQueryCapabilities},
+      columnRoles: getParquetColumnRoles(schema.fields.map(field => field.name)),
+      statistics: {rowCount: metadata.rowCount, byteLength: metadata.fileByteLength}
+    });
+  }
+
+  /** Plans a portable query using Parquet metadata without decoding data pages. */
+  async getScanPlan(options: ParquetSourceReadOptions = {}): Promise<ParquetSourceExplain> {
+    const readOptions = this.getReadOptions(options);
+    const initialization = await this.getInitialization(readOptions.signal);
+    const sourceColumnNames = initialization.schema.fields.map(field => field.name);
+    const signal = readOptions.signal ?? new AbortController().signal;
+    const physicalPlan = await this.planRowGroups(initialization, readOptions, signal);
+    const pagePlans = await this.planPages(initialization, readOptions, physicalPlan, signal);
+    const explanation = explainTableQuery(
+      sourceColumnNames,
+      {
+        columns: readOptions.columns,
+        predicate: physicalPlan.predicate,
+        limit: readOptions.limit
+      },
+      PARQUET_TABLE_QUERY_CAPABILITIES
+    );
+    return Object.freeze({
+      ...explanation,
+      source: 'parquet' as const,
+      rowGroups: Object.freeze({
+        indices: Object.freeze([...physicalPlan.rowGroupIndices]),
+        requested: physicalPlan.requested,
+        selected: physicalPlan.rowGroupIndices.length,
+        prunedByCallback: physicalPlan.prunedByCallback,
+        prunedBySpatial: physicalPlan.prunedBySpatial,
+        prunedByStatistics: physicalPlan.prunedByStatistics,
+        prunedByBloomFilter: physicalPlan.prunedByBloomFilter
+      }),
+      bloomFilters: Object.freeze({
+        read: physicalPlan.bloomFiltersRead,
+        bytesRead: physicalPlan.bloomFilterBytesRead
+      }),
+      pages: Object.freeze({
+        rowGroupsPlanned: new Set(pagePlans.map(plan => plan.rowGroupIndex)).size,
+        indexesRead: pagePlans.reduce((sum, plan) => sum + plan.indexesRead, 0),
+        total: pagePlans.reduce((sum, plan) => sum + plan.totalPages, 0),
+        selected: pagePlans.reduce((sum, plan) => sum + plan.selectedPages, 0),
+        rowsPruned: pagePlans.reduce((sum, plan) => sum + plan.rowsPruned, 0),
+        plans: Object.freeze(pagePlans)
+      })
+    });
+  }
+
+  /** Explains the common logical query and Parquet-specific physical scan plan. */
+  async explain(options: ParquetSourceReadOptions = {}): Promise<ParquetSourceExplain> {
+    return await this.getScanPlan(options);
+  }
+
+  /** Executes a previously computed physical plan while preserving its row-group decisions. */
+  async *executeScanPlan(
+    plan: ParquetSourceExplain,
+    options: ParquetSourceReadOptions = {}
+  ): AsyncIterable<ParquetSourceBatch> {
+    if (plan.source !== 'parquet') {
+      throw new Error('ParquetSource can only execute Parquet scan plans');
+    }
+    const predicateStep = plan.plan.find(step => step.kind === 'filter');
+    const limitStep = plan.plan.find(step => step.kind === 'limit');
+    yield* this.read({
+      ...options,
+      columns: options.columns ?? plan.outputColumns,
+      predicate:
+        options.predicate ??
+        (predicateStep?.kind === 'filter' ? predicateStep.predicate : undefined),
+      limit: options.limit ?? (limitStep?.kind === 'limit' ? limitStep.limit : undefined),
+      rowGroups: plan.rowGroups.indices
+    });
+  }
+
+  /** Common scan-architecture alias for selective Parquet reads. */
+  scan(options: ParquetSourceReadOptions = {}): AsyncIterable<ParquetSourceBatch> {
+    return this.read(options);
+  }
+
+  /**
+   * Reads candidate encoded pages without decoding values or constructing Arrow arrays.
+   *
+   * Footer statistics and Bloom filters prune complete row groups. Any exact predicate or spatial
+   * filter is returned as residual work, and its hidden columns are included in the page batch.
+   */
+  async *readPages(
+    options: ParquetEncodedPageReadOptions = {}
+  ): AsyncIterable<ParquetEncodedPageBatch> {
+    const readOptions = this.getReadOptions({
+      rowGroups: options.rowGroups,
+      columns: options.columns,
+      rowGroupFilter: options.rowGroupFilter,
+      predicate: options.predicate,
+      bbox: options.bbox,
+      geometryColumn: options.geometryColumn,
+      signal: options.signal
+    });
+    const readContext = createReadAbortContext(readOptions.signal);
+    this.activeReadControllers.add(readContext.abortController);
+    try {
+      const initialization = await this.getInitialization(readContext.abortController.signal);
+      await this.getCompressionInitialization();
+      throwIfAborted(readContext.abortController.signal);
+      const physicalPlan = await this.planRowGroups(
+        initialization,
+        readOptions,
+        readContext.abortController.signal
+      );
+      const projectedColumns = normalizeColumns(readOptions.columns, initialization.schema);
+      const predicateColumns = physicalPlan.predicate
+        ? getParquetPredicateColumns(physicalPlan.predicate)
+        : [];
+      const geoMetadata = readOptions.bbox
+        ? getGeoMetadata(initialization.schema.metadata)
+        : undefined;
+      const geometryColumn = readOptions.bbox
+        ? readOptions.geometryColumn || geoMetadata?.primary_column
+        : undefined;
+      const filterColumns = [
+        ...new Set([...predicateColumns, ...(geometryColumn ? [geometryColumn] : [])])
+      ];
+      const decodedColumns =
+        projectedColumns.length === 0 ? [] : [...new Set([...projectedColumns, ...filterColumns])];
+      const columnList = decodedColumns.map(column => [column]);
+      const preserveCompression = new Set(options.preserveCompression ?? []);
+      const residualFilter: ParquetDeferredPageFilter | undefined =
+        readOptions.predicate || readOptions.bbox
+          ? Object.freeze({
+              predicate: readOptions.predicate,
+              bbox: readOptions.bbox,
+              geometryColumn
+            })
+          : undefined;
+      for (const rowGroupIndex of physicalPlan.rowGroupIndices) {
+        throwIfAborted(readContext.abortController.signal);
+        const columns = await initialization.reader.readRowGroupEncodedPages(
+          initialization.parquetSchema,
+          initialization.fileMetadata.row_groups[rowGroupIndex],
+          columnList,
+          preserveCompression,
+          readContext.abortController.signal,
+          rowGroupIndex
+        );
+        yield Object.freeze({
+          shape: 'parquet-encoded-pages' as const,
+          rowGroup: initialization.metadata.rowGroups[rowGroupIndex],
+          projectedColumns: Object.freeze([...projectedColumns]),
+          filterColumns: Object.freeze(filterColumns),
+          columns,
+          residualFilter
+        });
+      }
+    } finally {
+      readContext.abortController.abort();
+      readContext.removeSignalListener();
+      this.activeReadControllers.delete(readContext.abortController);
+    }
+  }
+
   /** Returns a copy of cumulative transport, decode, conversion, and pruning telemetry. */
   getTelemetry(): ParquetTelemetry {
     return Object.freeze({...this.telemetry});
@@ -219,10 +480,26 @@ export class ParquetSource extends DataSource<string | Blob, ParquetSourceLoader
 
   /** Selectively fetches row groups and columns as ordered Arrow batches with source provenance. */
   async *read(options: ParquetSourceReadOptions = {}): AsyncIterable<ParquetSourceBatch> {
+    const startedAt = Date.now();
+    const telemetryBefore = this.getTelemetry();
     const readOptions = this.getReadOptions(options);
+    if (readOptions.limit === 0) {
+      emitScanExecutionTelemetry(
+        options.onTelemetry,
+        createParquetScanExecutionTelemetry(
+          telemetryBefore,
+          this.getTelemetry(),
+          startedAt,
+          'early-terminated',
+          'limit'
+        )
+      );
+      return;
+    }
     const readContext = createReadAbortContext(readOptions.signal);
     const inFlightReads = new Set<Promise<SettledParquetRowGroupRead>>();
     let completed = false;
+    let limitReached = false;
     let readError: unknown;
     this.activeReadControllers.add(readContext.abortController);
 
@@ -231,33 +508,21 @@ export class ParquetSource extends DataSource<string | Blob, ParquetSourceLoader
       await this.getCompressionInitialization();
       throwIfAborted(readContext.abortController.signal);
 
-      const candidateRowGroupIndices = normalizeRowGroupIndices(
-        readOptions.rowGroups,
-        initialization.fileMetadata.row_groups.length
+      const physicalPlan = await this.planRowGroups(
+        initialization,
+        readOptions,
+        readContext.abortController.signal
       );
-      const callbackFilteredRowGroupIndices = readOptions.rowGroupFilter
-        ? candidateRowGroupIndices.filter(rowGroupIndex =>
-            readOptions.rowGroupFilter!(initialization.metadata.rowGroups[rowGroupIndex])
-          )
-        : candidateRowGroupIndices;
-      const predicate = readOptions.predicate;
-      const availableColumns = new Set(initialization.schema.fields.map(field => field.name));
-      if (predicate) {
-        validateParquetPredicate(predicate, availableColumns);
-      }
-      const rowGroupIndices = predicate
-        ? callbackFilteredRowGroupIndices.filter(rowGroupIndex =>
-            canParquetRowGroupMatch(predicate, initialization.metadata.rowGroups[rowGroupIndex])
-          )
-        : callbackFilteredRowGroupIndices;
-      const rowGroupsPrunedByStatistics =
-        callbackFilteredRowGroupIndices.length - rowGroupIndices.length;
+      const {predicate, rowGroupIndices} = physicalPlan;
       this.recordTelemetry(
         'row-group-prune',
         {
-          rowGroupsRequested: candidateRowGroupIndices.length,
-          rowGroupsPruned: candidateRowGroupIndices.length - rowGroupIndices.length,
-          rowGroupsPrunedByStatistics
+          rowGroupsRequested: physicalPlan.requested,
+          rowGroupsPruned: physicalPlan.requested - rowGroupIndices.length,
+          rowGroupsPrunedByStatistics: physicalPlan.prunedByStatistics,
+          rowGroupsPrunedByBloomFilter: physicalPlan.prunedByBloomFilter,
+          bloomFiltersRead: physicalPlan.bloomFiltersRead,
+          bloomFilterBytesRead: physicalPlan.bloomFilterBytesRead
         },
         {}
       );
@@ -271,9 +536,12 @@ export class ParquetSource extends DataSource<string | Blob, ParquetSourceLoader
       const projectedSchema = projectSchema(initialization.schema, columns);
       const projectedColumnNames = columns.length ? new Set(columns) : undefined;
       const workerOptions = this.getWorkerOptions(concurrency, readContext.abortController.signal);
-      const decodeOnWorker = canDecodeParquetSourceOnWorker(workerOptions);
+      const decodeOnWorker =
+        canDecodeParquetSourceOnWorker(workerOptions) &&
+        (!initialization.reader.encrypted || Boolean(this.options.parquet?.keyRetriever));
       const scheduledReads = new Map<number, Promise<SettledParquetRowGroupRead>>();
       let nextPositionToSchedule = 0;
+      let remainingRows = readOptions.limit ?? Number.POSITIVE_INFINITY;
 
       const scheduleReads = (): void => {
         while (
@@ -329,21 +597,30 @@ export class ParquetSource extends DataSource<string | Blob, ParquetSourceLoader
               {arrowConversionDurationMs: deserializationDurationMs},
               {rowGroupIndex, durationMs: deserializationDurationMs}
             );
-            const batch = createParquetBatchFromArrow(
-              initialization.metadata,
-              projectedSchema,
-              rowGroupIndex,
-              workerBatch.rowGroupRowOffset,
-              arrowTable,
-              workerBatch.rowCount,
-              workerBatch.rowGroupRowIndices
+            const batch = sliceParquetBatch(
+              createParquetBatchFromArrow(
+                initialization.metadata,
+                projectedSchema,
+                rowGroupIndex,
+                workerBatch.rowGroupRowOffset,
+                arrowTable,
+                workerBatch.rowCount,
+                workerBatch.rowGroupRowIndices
+              ),
+              Math.min(workerBatch.rowCount, remainingRows)
             );
             this.recordTelemetry(
               'batch',
-              {batchesEmitted: 1, rowsEmitted: workerBatch.rowCount},
-              {rowGroupIndex, rowCount: workerBatch.rowCount}
+              {batchesEmitted: 1, rowsEmitted: batch.length},
+              {rowGroupIndex, rowCount: batch.length}
             );
             yield batch;
+            remainingRows -= batch.length;
+            if (remainingRows === 0) {
+              limitReached = true;
+              completed = true;
+              return;
+            }
           }
           continue;
         }
@@ -356,7 +633,11 @@ export class ParquetSource extends DataSource<string | Blob, ParquetSourceLoader
           outputRowOffset += outputBatchSize
         ) {
           throwIfAborted(readContext.abortController.signal);
-          const batchRowCount = Math.min(outputBatchSize, outputRowCount - outputRowOffset);
+          const batchRowCount = Math.min(
+            outputBatchSize,
+            outputRowCount - outputRowOffset,
+            remainingRows
+          );
           const batchRowIndices = rowIndices
             ? rowIndices!.slice(outputRowOffset, outputRowOffset + batchRowCount)
             : undefined;
@@ -388,6 +669,12 @@ export class ParquetSource extends DataSource<string | Blob, ParquetSourceLoader
             {rowGroupIndex, rowCount: batchRowCount}
           );
           yield batch;
+          remainingRows -= batch.length;
+          if (remainingRows === 0) {
+            limitReached = true;
+            completed = true;
+            return;
+          }
         }
       }
       completed = true;
@@ -403,11 +690,201 @@ export class ParquetSource extends DataSource<string | Blob, ParquetSourceLoader
       if (!completed && readError === undefined) {
         this.recordTelemetry('cancel', {cancellationCount: 1}, {});
       }
+      const cancelled = readContext.abortController.signal.aborted || readOptions.signal?.aborted;
       readContext.abortController.abort();
       readContext.removeSignalListener();
       this.activeReadControllers.delete(readContext.abortController);
       await Promise.allSettled([...inFlightReads]);
+      const status: ScanExecutionTelemetry['status'] = readError
+        ? cancelled
+          ? 'cancelled'
+          : 'failed'
+        : limitReached || !completed
+          ? 'early-terminated'
+          : 'completed';
+      emitScanExecutionTelemetry(
+        options.onTelemetry,
+        createParquetScanExecutionTelemetry(
+          telemetryBefore,
+          this.getTelemetry(),
+          startedAt,
+          status,
+          limitReached
+            ? 'limit'
+            : !completed && readError === undefined
+              ? 'consumer-return'
+              : undefined,
+          readError
+        )
+      );
+    }
+  }
+
+  /** Produces the physical row-group plan shared by explain and execution. */
+  private async planRowGroups(
+    initialization: ParquetSourceInitialization,
+    readOptions: ParquetSourceReadOptions,
+    signal: AbortSignal
+  ): Promise<ParquetPhysicalRowGroupPlan> {
+    throwIfAborted(signal);
+    const candidateRowGroupIndices = normalizeRowGroupIndices(
+      readOptions.rowGroups,
+      initialization.fileMetadata.row_groups.length
+    );
+    const callbackFilteredRowGroupIndices = readOptions.rowGroupFilter
+      ? candidateRowGroupIndices.filter(rowGroupIndex =>
+          readOptions.rowGroupFilter!(initialization.metadata.rowGroups[rowGroupIndex])
+        )
+      : candidateRowGroupIndices;
+    const spatiallyFilteredRowGroupIndices = readOptions.bbox
+      ? callbackFilteredRowGroupIndices.filter(rowGroupIndex =>
+          canGeoParquetRowGroupMatch(
+            initialization.metadata,
+            initialization.metadata.rowGroups[rowGroupIndex],
+            readOptions.bbox!,
+            readOptions.geometryColumn
+          )
+        )
+      : callbackFilteredRowGroupIndices;
+    const spatialPredicate = readOptions.bbox
+      ? createGeoParquetBoundingBoxPredicate(
+          initialization.metadata,
+          readOptions.bbox,
+          readOptions.geometryColumn
+        )
+      : undefined;
+    const predicate = combineParquetPredicates(readOptions.predicate, spatialPredicate);
+    if (predicate) {
+      validateParquetPredicate(
+        predicate,
+        new Set(initialization.schema.fields.map(field => field.name))
+      );
+    }
+    const statisticsRowGroupIndices = predicate
+      ? spatiallyFilteredRowGroupIndices.filter(rowGroupIndex =>
+          canParquetRowGroupMatch(predicate, initialization.metadata.rowGroups[rowGroupIndex])
+        )
+      : spatiallyFilteredRowGroupIndices;
+    const bloomFilterResult = predicate
+      ? await filterParquetRowGroupsWithBloomFilters(
+          initialization,
+          statisticsRowGroupIndices,
+          predicate,
+          signal
+        )
+      : {rowGroupIndices: statisticsRowGroupIndices, filtersRead: 0, bytesRead: 0};
+    return {
+      predicate,
+      rowGroupIndices: bloomFilterResult.rowGroupIndices,
+      requested: candidateRowGroupIndices.length,
+      prunedByCallback: candidateRowGroupIndices.length - callbackFilteredRowGroupIndices.length,
+      prunedBySpatial:
+        callbackFilteredRowGroupIndices.length - spatiallyFilteredRowGroupIndices.length,
+      prunedByStatistics:
+        spatiallyFilteredRowGroupIndices.length - statisticsRowGroupIndices.length,
+      prunedByBloomFilter:
+        statisticsRowGroupIndices.length - bloomFilterResult.rowGroupIndices.length,
+      bloomFiltersRead: bloomFilterResult.filtersRead,
+      bloomFilterBytesRead: bloomFilterResult.bytesRead
+    };
+  }
+
+  /** Produces explainable page-index and byte-range plans for retained row groups. */
+  private async planPages(
+    initialization: ParquetSourceInitialization,
+    readOptions: ParquetSourceReadOptions,
+    rowGroupPlan: ParquetPhysicalRowGroupPlan,
+    signal: AbortSignal
+  ): Promise<ParquetPageScanPlan[]> {
+    if (!rowGroupPlan.predicate) return [];
+    const columns = normalizeColumns(readOptions.columns, initialization.schema);
+    const predicateColumns = getParquetPredicateColumns(rowGroupPlan.predicate);
+    const decodedColumns =
+      columns.length === 0 ? [] : [...new Set([...columns, ...predicateColumns])];
+    const hasHiddenPredicateColumns =
+      columns.length > 0 && predicateColumns.some(column => !columns.includes(column));
+    const phases = hasHiddenPredicateColumns
+      ? [
+          {
+            phase: 'predicate' as const,
+            columns: predicateColumns.map(column => [column]),
+            predicate: rowGroupPlan.predicate
+          },
+          {
+            phase: 'projection' as const,
+            columns: columns.map(column => [column]),
+            predicate: undefined
+          }
+        ]
+      : [
+          {
+            phase: 'combined' as const,
+            columns: decodedColumns.map(column => [column]),
+            predicate: rowGroupPlan.predicate
+          }
+        ];
+    const plans: ParquetPageScanPlan[] = [];
+    for (const rowGroupIndex of rowGroupPlan.rowGroupIndices) {
+      const rowGroup = initialization.fileMetadata.row_groups[rowGroupIndex];
+      let predicateProvedEmpty = false;
+      for (const phase of phases) {
+        throwIfAborted(signal);
+        if (phase.phase === 'projection' && predicateProvedEmpty) {
+          continue;
+        }
+        await initialization.reader.resolveColumnMetadata(rowGroup, rowGroupIndex, phase.columns);
+        const pagePlan = phase.predicate
+          ? await createParquetPagePruningPlan(
+              initialization.file,
+              rowGroup,
+              initialization.parquetSchema,
+              phase.columns,
+              phase.predicate,
+              signal,
+              {
+                rowGroupOrdinal: rowGroupIndex,
+                int96AsTimestamp: Boolean(this.options.parquet?.int96AsTimestamp),
+                decryptModule: (bytes, module, rowGroupOrdinal, columnOrdinal, columnChunk) =>
+                  initialization.reader.decryptIndexModule(
+                    bytes,
+                    module,
+                    rowGroupOrdinal,
+                    columnOrdinal,
+                    columnChunk
+                  )
+              }
+            )
+          : undefined;
+        plans.push(
+          pagePlan
+            ? Object.freeze({
+                rowGroupIndex,
+                phase: phase.phase,
+                columns: Object.freeze(phase.columns.map(column => Object.freeze([...column]))),
+                rowRanges: Object.freeze(
+                  pagePlan.rowRanges.map(rowRange => Object.freeze({...rowRange}))
+                ),
+                indexesRead: pagePlan.indexCount,
+                totalPages: pagePlan.totalPageCount,
+                selectedPages: pagePlan.selectedPageCount,
+                rowsPruned: pagePlan.prunedRowCount,
+                ranges: Object.freeze(
+                  getParquetPageReadRanges(
+                    rowGroup,
+                    phase.columns,
+                    pagePlan,
+                    initialization.parquetSchema
+                  ).map(range => Object.freeze({...range}))
+                )
+              })
+            : createFullColumnScanPlan(rowGroup, rowGroupIndex, phase.phase, phase.columns)
+        );
+        if (phase.phase === 'predicate' && pagePlan?.rowRanges.length === 0) {
+          predicateProvedEmpty = true;
+        }
+      }
     }
+    return plans;
   }
 
   /** Closes the underlying readable file and aborts active remote requests. */
@@ -421,6 +898,7 @@ export class ParquetSource extends DataSource<string | Blob, ParquetSourceLoader
     }
     await this.readableFile?.close();
     const initialization = await this.initializationPromise?.catch(() => null);
+    initialization?.reader.close();
     if (initialization?.file !== this.readableFile) {
       await initialization?.file.close();
     }
@@ -458,11 +936,17 @@ export class ParquetSource extends DataSource<string | Blob, ParquetSourceLoader
     const rowGroups = options.rowGroups ?? this.options.parquet?.rowGroups;
     const columns = options.columns ?? this.options.parquet?.columns;
     const predicate = options.predicate ?? this.options.parquet?.predicate;
+    const bbox = options.bbox ?? this.options.parquet?.bbox;
+    const limit = options.limit ?? this.options.parquet?.limit;
+    validateTableQueryLimit(limit);
     return {
       rowGroups: rowGroups && [...rowGroups],
       columns: columns && [...columns],
       rowGroupFilter: options.rowGroupFilter ?? this.options.parquet?.rowGroupFilter,
       predicate: predicate ? copyParquetPredicate(predicate) : undefined,
+      limit,
+      bbox: bbox ? ([...bbox] as ParquetSourceReadOptions['bbox']) : undefined,
+      geometryColumn: options.geometryColumn ?? this.options.parquet?.geometryColumn,
       batchSize: options.batchSize ?? this.options.parquet?.batchSize,
       concurrency: options.concurrency ?? this.options.parquet?.concurrency,
       signal: options.signal
@@ -500,7 +984,25 @@ export class ParquetSource extends DataSource<string | Blob, ParquetSourceLoader
     workerOptions: ParquetSourceWorkerOptions | undefined,
     signal: AbortSignal
   ): Promise<ParquetRowGroupReadResult> {
+    if (
+      predicate &&
+      projectedColumnNames &&
+      getParquetPredicateColumns(predicate).some(column => !projectedColumnNames.has(column))
+    ) {
+      return await this.readRowGroupWithLateMaterialization(
+        initialization,
+        rowGroupIndex,
+        columnList,
+        projectedSchema,
+        batchSize,
+        predicate,
+        projectedColumnNames,
+        workerOptions,
+        signal
+      );
+    }
     const rowGroup = initialization.fileMetadata.row_groups[rowGroupIndex];
+    await initialization.reader.resolveColumnMetadata(rowGroup, rowGroupIndex, columnList);
     const pagePlan = predicate
       ? await createParquetPagePruningPlan(
           initialization.file,
@@ -508,7 +1010,19 @@ export class ParquetSource extends DataSource<string | Blob, ParquetSourceLoader
           initialization.parquetSchema,
           columnList,
           predicate,
-          signal
+          signal,
+          {
+            rowGroupOrdinal: rowGroupIndex,
+            int96AsTimestamp: Boolean(this.options.parquet?.int96AsTimestamp),
+            decryptModule: (bytes, module, rowGroupOrdinal, columnOrdinal, columnChunk) =>
+              initialization.reader.decryptIndexModule(
+                bytes,
+                module,
+                rowGroupOrdinal,
+                columnOrdinal,
+                columnChunk
+              )
+          }
         )
       : undefined;
     if (pagePlan) {
@@ -542,7 +1056,8 @@ export class ParquetSource extends DataSource<string | Blob, ParquetSourceLoader
               columnList,
               rowRange,
               pagePlan.pageLocations,
-              signal
+              signal,
+              rowGroupIndex
             )
           )
         )
@@ -551,7 +1066,8 @@ export class ParquetSource extends DataSource<string | Blob, ParquetSourceLoader
             initialization.parquetSchema,
             rowGroup,
             columnList,
-            signal
+            signal,
+            rowGroupIndex
           )
         ];
     throwIfAborted(signal);
@@ -615,7 +1131,7 @@ export class ParquetSource extends DataSource<string | Blob, ParquetSourceLoader
       return Boolean(path && (columnList.length === 0 || fieldIndexOf(columnList, path) >= 0));
     });
     const rangeDescriptors = pagePlan
-      ? getParquetPageReadRanges(rowGroup, columnList, pagePlan)
+      ? getParquetPageReadRanges(rowGroup, columnList, pagePlan, initialization.parquetSchema)
       : selectedColumnChunks.map(getColumnChunkRange);
     const ranges = await Promise.all(
       rangeDescriptors.map(async ({offset, length}) => {
@@ -624,6 +1140,26 @@ export class ParquetSource extends DataSource<string | Blob, ParquetSourceLoader
     );
     throwIfAborted(signal);
 
+    const workerColumnChunks = await Promise.all(
+      selectedColumnChunks.map(async columnChunk => {
+        const descriptor = createParquetSourceWorkerColumnChunk(columnChunk);
+        descriptor.columnOrdinal = rowGroup.columns.indexOf(columnChunk);
+        if (columnChunk.crypto_metadata) {
+          const columnOrdinal = rowGroup.columns.indexOf(columnChunk);
+          const key = await initialization.reader.getColumnKeyForWorker(
+            columnChunk,
+            rowGroupIndex,
+            columnOrdinal
+          );
+          descriptor.encrypted = true;
+          descriptor.keyMetadata = key.keyMetadata?.slice().buffer;
+          descriptor.keyMaterial = key.keyMaterial.slice().buffer;
+        }
+        return descriptor;
+      })
+    );
+    const encryptionContext = initialization.reader.getEncryptionContextForWorker();
+
     let workerResult: ParquetSourceWorkerResult;
     try {
       workerResult = await decodeParquetSourceRowGroupOnWorker(
@@ -633,12 +1169,21 @@ export class ParquetSource extends DataSource<string | Blob, ParquetSourceLoader
           uncompressedByteLength: Number(rowGroup.total_byte_size),
           schemaDefinition: initialization.parquetSchema.schema,
           projectedSchema,
-          columnChunks: selectedColumnChunks.map(createParquetSourceWorkerColumnChunk),
+          columnChunks: workerColumnChunks,
           ranges,
           batchSize: batchSize || Math.max(Number(rowGroup.num_rows), 1),
           predicate: predicate ? copyParquetPredicate(predicate) : undefined,
           pagePlan,
-          preserveBinary: Boolean(this.options.parquet?.preserveBinary)
+          encryption: encryptionContext
+            ? {
+                algorithm: encryptionContext.algorithm,
+                aadPrefix: encryptionContext.aadPrefix?.slice().buffer,
+                fileUnique: encryptionContext.fileUnique.slice().buffer
+              }
+            : undefined,
+          preserveBinary: Boolean(this.options.parquet?.preserveBinary),
+          int96AsTimestamp: Boolean(this.options.parquet?.int96AsTimestamp),
+          verifyPageChecksums: Boolean(this.options.parquet?.verifyPageChecksums)
         },
         workerOptions
       );
@@ -670,6 +1215,72 @@ export class ParquetSource extends DataSource<string | Blob, ParquetSourceLoader
     return {rowGroupIndex, rowCount: workerResult.rowCount, workerResult};
   }
 
+  /** Decodes predicate columns first, avoiding projected-column decoding for empty matches. */
+  private async readRowGroupWithLateMaterialization(
+    initialization: ParquetSourceInitialization,
+    rowGroupIndex: number,
+    columnList: string[][],
+    projectedSchema: Schema,
+    batchSize: number | undefined,
+    predicate: ParquetPredicate,
+    projectedColumnNames: ReadonlySet<string>,
+    workerOptions: ParquetSourceWorkerOptions | undefined,
+    signal: AbortSignal
+  ): Promise<ParquetRowGroupReadResult> {
+    const predicateColumns = getParquetPredicateColumns(predicate);
+    const predicateColumnList = predicateColumns.map(column => [column]);
+    const filterResult = await this.readRowGroup(
+      initialization,
+      rowGroupIndex,
+      predicateColumnList,
+      projectSchema(initialization.schema, predicateColumns),
+      batchSize,
+      predicate,
+      new Set(predicateColumns),
+      workerOptions,
+      signal
+    );
+    const rowIndices = filterResult.rowIndices;
+    const selectedRowIndices = rowIndices || getWorkerRowIndices(filterResult.workerResult);
+    if (!selectedRowIndices || selectedRowIndices.length === 0) {
+      return {rowGroupIndex, rowCount: 0, columns: {}, rowIndices: []};
+    }
+    const projectedColumnList = columnList.filter(columnPath =>
+      projectedColumnNames.has(columnPath[0])
+    );
+    const projectedResult = await this.readRowGroup(
+      initialization,
+      rowGroupIndex,
+      projectedColumnList,
+      projectedSchema,
+      batchSize,
+      undefined,
+      projectedColumnNames,
+      workerOptions,
+      signal
+    );
+    if (workerOptions && projectedResult.workerResult) {
+      return {
+        rowGroupIndex,
+        rowCount: selectedRowIndices.length,
+        rowIndices: selectedRowIndices,
+        workerResult: gatherWorkerProjectedRows(
+          projectedResult.workerResult,
+          selectedRowIndices,
+          batchSize
+        )
+      };
+    }
+    return {
+      rowGroupIndex,
+      rowCount: selectedRowIndices.length,
+      rowIndices: selectedRowIndices,
+      columns: projectedResult.columns
+        ? gatherParquetColumns(projectedResult.columns, selectedRowIndices, projectedColumnNames)
+        : {}
+    };
+  }
+
   /** Records the rows and pages avoided by one conservative page-index plan. */
   private recordPagePruningTelemetry(rowGroupIndex: number, plan: ParquetPagePruningPlan): void {
     this.recordTelemetry(
@@ -692,6 +1303,11 @@ export class ParquetSource extends DataSource<string | Blob, ParquetSourceLoader
     try {
       const reader = new ParquetReader(file, {
         preserveBinary: this.options.parquet?.preserveBinary,
+        int96AsTimestamp: this.options.parquet?.int96AsTimestamp,
+        verifyPageChecksums: this.options.parquet?.verifyPageChecksums,
+        verifyFooterSignature: this.options.parquet?.verifyFooterSignature,
+        keyRetriever: this.options.parquet?.keyRetriever,
+        aadPrefix: this.options.parquet?.aadPrefix,
         signal
       });
       const fileMetadata = await reader.getFileMetadata();
@@ -764,6 +1380,29 @@ export class ParquetSource extends DataSource<string | Blob, ParquetSourceLoader
   }
 }
 
+function getParquetColumnRoles(columnNames: readonly string[]): Record<string, ScanColumnRole> {
+  const roles: Record<string, ScanColumnRole> = {};
+  for (const columnName of columnNames) {
+    const normalizedName = columnName.toLowerCase();
+    if (normalizedName === 'geometry' || normalizedName === 'geom' || normalizedName === 'shape') {
+      roles[columnName] = 'geometry';
+    } else if (
+      normalizedName === 'longitude' ||
+      normalizedName === 'lon' ||
+      normalizedName === 'x'
+    ) {
+      roles[columnName] = 'longitude';
+    } else if (
+      normalizedName === 'latitude' ||
+      normalizedName === 'lat' ||
+      normalizedName === 'y'
+    ) {
+      roles[columnName] = 'latitude';
+    }
+  }
+  return roles;
+}
+
 /** Normalizes a decoded Parquet footer into source metadata. */
 function createParquetSourceMetadata(
   data: string | Blob,
@@ -784,7 +1423,8 @@ function createParquetSourceMetadata(
       rowOffset,
       Number(rowGroup.num_rows),
       Number(rowGroup.total_byte_size),
-      columns
+      columns,
+      rowGroup.sorting_columns
     );
     rowOffset += normalizedRowGroup.rowCount;
     return normalizedRowGroup;
@@ -821,6 +1461,8 @@ function createColumnChunkMetadata(
     columnMetadata.statistics,
     parquetSchema.findField(columnMetadata.path_in_schema)
   );
+  const geospatialStatistics = createGeospatialStatistics(columnMetadata.geospatial_statistics);
+  const sizeStatistics = createSizeStatistics(columnMetadata.size_statistics);
   const compressedByteLength = Number(columnMetadata.total_compressed_size);
   const uncompressedByteLength = Number(columnMetadata.total_uncompressed_size);
   return Object.freeze({
@@ -851,7 +1493,92 @@ function createColumnChunkMetadata(
         ? undefined
         : Number(columnChunk.offset_index_offset),
     offsetIndexByteLength: columnChunk.offset_index_length,
-    statistics
+    bloomFilterOffset:
+      columnMetadata.bloom_filter_offset === undefined
+        ? undefined
+        : Number(columnMetadata.bloom_filter_offset),
+    bloomFilterByteLength: columnMetadata.bloom_filter_length,
+    statistics,
+    sizeStatistics,
+    geospatialStatistics
+  });
+}
+
+/** Normalizes optional Parquet size statistics without inventing missing counts. */
+function createSizeStatistics(
+  statistics:
+    | {
+        unencoded_byte_array_data_bytes?: {toNumber?: () => number} | number;
+        repetition_level_histogram?: Array<{toNumber?: () => number} | number>;
+        definition_level_histogram?: Array<{toNumber?: () => number} | number>;
+      }
+    | undefined
+): ParquetColumnChunkSizeStatistics | undefined {
+  if (!statistics) return undefined;
+  const result: ParquetColumnChunkSizeStatistics = {
+    unencodedByteArrayDataBytes:
+      statistics.unencoded_byte_array_data_bytes === undefined
+        ? undefined
+        : toSafeNumber(statistics.unencoded_byte_array_data_bytes),
+    repetitionLevelHistogram: normalizeSizeStatisticsList(statistics.repetition_level_histogram),
+    definitionLevelHistogram: normalizeSizeStatisticsList(statistics.definition_level_histogram)
+  };
+  if (
+    result.unencodedByteArrayDataBytes === undefined &&
+    result.repetitionLevelHistogram === undefined &&
+    result.definitionLevelHistogram === undefined
+  ) {
+    return undefined;
+  }
+  return Object.freeze({
+    ...result,
+    repetitionLevelHistogram: result.repetitionLevelHistogram
+      ? Object.freeze(result.repetitionLevelHistogram)
+      : undefined,
+    definitionLevelHistogram: result.definitionLevelHistogram
+      ? Object.freeze(result.definitionLevelHistogram)
+      : undefined
+  });
+}
+
+function toSafeNumber(value: {toNumber?: () => number} | number): number | undefined {
+  const numberValue = typeof value === 'number' ? value : value.toNumber?.();
+  return numberValue !== undefined && Number.isSafeInteger(numberValue) && numberValue >= 0
+    ? numberValue
+    : undefined;
+}
+
+/** Converts a Thrift int64 histogram only when every entry is a safe non-negative integer. */
+function normalizeSizeStatisticsList(
+  values: Array<{toNumber?: () => number} | number> | undefined
+): readonly number[] | undefined {
+  if (!values) return undefined;
+  const normalized = values.map(toSafeNumber);
+  return normalized.every((value): value is number => value !== undefined) ? normalized : undefined;
+}
+
+/** Normalizes native Parquet geospatial statistics from the decoded footer. */
+function createGeospatialStatistics(
+  statistics: ParquetThriftGeospatialStatistics | undefined
+): ParquetGeospatialStatistics | undefined {
+  if (!statistics) return undefined;
+  const bbox = statistics.bbox
+    ? Object.freeze({
+        xmin: statistics.bbox.xmin,
+        xmax: statistics.bbox.xmax,
+        ymin: statistics.bbox.ymin,
+        ymax: statistics.bbox.ymax,
+        zmin: statistics.bbox.zmin,
+        zmax: statistics.bbox.zmax,
+        mmin: statistics.bbox.mmin,
+        mmax: statistics.bbox.mmax
+      })
+    : undefined;
+  return Object.freeze({
+    bbox,
+    geometryTypes: statistics.geospatial_types
+      ? Object.freeze([...statistics.geospatial_types])
+      : undefined
   });
 }
 
@@ -933,7 +1660,8 @@ function createRowGroupMetadata(
   rowOffset: number,
   rowCount: number,
   uncompressedByteLength: number,
-  columns: ParquetColumnChunkMetadata[]
+  columns: ParquetColumnChunkMetadata[],
+  sortingColumns: RowGroup['sorting_columns']
 ): ParquetRowGroupMetadata {
   const compressedByteLength = columns.reduce(
     (sum, column) => sum + column.compressedByteLength,
@@ -947,10 +1675,54 @@ function createRowGroupMetadata(
     uncompressedSize: uncompressedByteLength,
     compressedByteLength,
     compressedSize: compressedByteLength,
-    columns: Object.freeze(columns)
+    columns: Object.freeze(columns),
+    sortingColumns: Object.freeze(
+      (sortingColumns || []).map(
+        sortingColumn =>
+          Object.freeze({
+            columnIndex: sortingColumn.column_idx,
+            descending: sortingColumn.descending,
+            nullsFirst: sortingColumn.nulls_first
+          }) satisfies ParquetSortingColumn
+      )
+    )
+  });
+}
+
+/** Describes a phase that reads complete column chunks because no page index is available. */
+function createFullColumnScanPlan(
+  rowGroup: RowGroup,
+  rowGroupIndex: number,
+  phase: ParquetPageScanPlan['phase'],
+  columns: readonly string[][]
+): ParquetPageScanPlan {
+  const selectedColumnChunks = rowGroup.columns.filter(columnChunk => {
+    const path = columnChunk.meta_data?.path_in_schema;
+    return Boolean(
+      path && (columns.length === 0 || columns.some(column => pathMatchesSelection(column, path)))
+    );
+  });
+  const rowCount = Number(rowGroup.num_rows);
+  return Object.freeze({
+    rowGroupIndex,
+    phase,
+    columns: Object.freeze(columns.map(column => Object.freeze([...column]))),
+    rowRanges: Object.freeze([Object.freeze({start: 0, end: rowCount})]),
+    indexesRead: 0,
+    totalPages: 0,
+    selectedPages: 0,
+    rowsPruned: 0,
+    ranges: Object.freeze(
+      selectedColumnChunks.map(columnChunk => Object.freeze(getColumnChunkRange(columnChunk)))
+    )
   });
 }
 
+/** Returns whether a requested path selects a footer leaf or one of its nested children. */
+function pathMatchesSelection(selection: readonly string[], path: readonly string[]): boolean {
+  return selection.length <= path.length && selection.every((part, index) => part === path[index]);
+}
+
 /** Returns the complete contiguous byte range occupied by one Parquet column chunk. */
 function getColumnChunkRange(columnChunk: ColumnChunk): {offset: number; length: number} {
   if (columnChunk.file_path) {
@@ -1048,11 +1820,8 @@ function createParquetBatchFromArrow(
       : undefined
   });
   return {
-    batchType: 'data',
-    shape: 'arrow-table',
+    ...makeTableScanBatch({shape: 'arrow-table', schema, data}),
     schemaType: 'explicit',
-    schema,
-    data,
     length: rowCount,
     metadata: provenance,
     ...provenance
@@ -1173,6 +1942,9 @@ function createParquetTelemetry(): ParquetTelemetry {
     rowGroupsRequested: 0,
     rowGroupsPruned: 0,
     rowGroupsPrunedByStatistics: 0,
+    rowGroupsPrunedByBloomFilter: 0,
+    bloomFiltersRead: 0,
+    bloomFilterBytesRead: 0,
     rowGroupsPrunedByPageIndex: 0,
     pageIndexesRead: 0,
     pagesRead: 0,
@@ -1188,6 +1960,45 @@ function createParquetTelemetry(): ParquetTelemetry {
   };
 }
 
+/** Converts cumulative Parquet counters into one portable read-scoped execution snapshot. */
+function createParquetScanExecutionTelemetry(
+  before: ParquetTelemetry,
+  after: ParquetTelemetry,
+  startedAt: number,
+  status: ScanExecutionTelemetry['status'],
+  earlyTerminationReason?: ScanExecutionTelemetry['earlyTerminationReason'],
+  error?: unknown
+): ScanExecutionTelemetry {
+  const delta = Object.fromEntries(
+    Object.keys(after).map(key => {
+      const telemetryKey = key as keyof ParquetTelemetry;
+      return [key, after[telemetryKey] - before[telemetryKey]];
+    })
+  ) as ParquetTelemetry;
+  const rowsRead = Math.max(delta.predicateRowsTested, delta.rowsEmitted);
+  return Object.freeze({
+    status,
+    sourcesPlanned: 1,
+    sourcesRead:
+      status === 'early-terminated' && earlyTerminationReason === 'limit' && rowsRead === 0 ? 0 : 1,
+    batchesRead: delta.batchesEmitted,
+    batchesDecoded: delta.rowGroupsDecoded,
+    rowsRead,
+    rowsTested: delta.predicateRowsTested || undefined,
+    rowsRetained: delta.predicateRowsMatched || undefined,
+    rowsReturned: delta.rowsEmitted,
+    bytesRead: delta.downloadedBytes,
+    bytesFetched: delta.downloadedBytes,
+    filesOpened: rowsRead || delta.downloadedBytes ? 1 : 0,
+    tasksOpened: delta.rowGroupsDecoded,
+    rowsPruned: delta.rowsPrunedByPageIndex,
+    durationMilliseconds: Date.now() - startedAt,
+    earlyTerminationReason,
+    details: Object.freeze({...delta}),
+    ...(error === undefined ? {} : {error})
+  });
+}
+
 /** Returns a monotonic timestamp when available and falls back to wall-clock time. */
 function getCurrentTime(): number {
   return globalThis.performance?.now() ?? Date.now();
@@ -1259,6 +2070,167 @@ function getSourceName(data: string | Blob, url: string): string {
   return sourceName.replace(/\.parquet$/i, '') || 'parquet';
 }
 
+type ParquetBloomFilterReadResult = {
+  rowGroupIndices: number[];
+  filtersRead: number;
+  bytesRead: number;
+};
+
+/** Reconstructs exact row-group indexes from worker predicate batches. */
+function getWorkerRowIndices(workerResult?: ParquetSourceWorkerResult): number[] {
+  if (!workerResult) return [];
+  return workerResult.batches.flatMap(batch =>
+    batch.rowGroupRowIndices
+      ? [...batch.rowGroupRowIndices]
+      : Array.from({length: batch.rowCount}, (_, index) => batch.rowGroupRowOffset + index)
+  );
+}
+
+/** Gathers projected worker Arrow batches through the shared indexed Arrow table utility. */
+function gatherWorkerProjectedRows(
+  workerResult: ParquetSourceWorkerResult,
+  rowIndices: readonly number[],
+  batchSize: number | undefined
+): ParquetSourceWorkerResult {
+  const tables = workerResult.batches.map(batch => hydrateArrowTable(batch.arrowTable));
+  if (tables.length === 0) {
+    return {...workerResult, rowCount: 0, batches: []};
+  }
+  const table = tables.length === 1 ? tables[0] : tables[0].concat(...tables.slice(1));
+  const indexedTable = new IndexedArrowTable(table, rowIndices);
+  const outputBatchSize = batchSize || Math.max(rowIndices.length, 1);
+  const batches: ParquetSourceWorkerResult['batches'] = [];
+  for (let offset = 0; offset < rowIndices.length; offset += outputBatchSize) {
+    const end = Math.min(offset + outputBatchSize, rowIndices.length);
+    const batchIndexes = rowIndices.slice(offset, end);
+    const batchTable = indexedTable.slice(offset, end).materializeArrowTable();
+    batches.push({
+      rowGroupRowOffset: batchIndexes[0],
+      rowCount: batchIndexes.length,
+      rowGroupRowIndices: [...batchIndexes],
+      arrowTable: dehydrateArrowTable(batchTable)
+    });
+  }
+  return {
+    sourceRowCount: workerResult.sourceRowCount,
+    rowCount: rowIndices.length,
+    batches,
+    decodeDurationMs: workerResult.decodeDurationMs,
+    arrowConversionDurationMs: workerResult.arrowConversionDurationMs
+  };
+}
+
+/** Applies only proven-negative Bloom-filter checks to candidate row groups. */
+async function filterParquetRowGroupsWithBloomFilters(
+  initialization: ParquetSourceInitialization,
+  rowGroupIndices: readonly number[],
+  predicate: ParquetPredicate,
+  signal: AbortSignal
+): Promise<ParquetBloomFilterReadResult> {
+  const rowGroups: number[] = [];
+  let filtersRead = 0;
+  let bytesRead = 0;
+  for (const rowGroupIndex of rowGroupIndices) {
+    const rowGroup = initialization.metadata.rowGroups[rowGroupIndex];
+    const probes = getParquetBloomFilterProbes(predicate, rowGroup);
+    let keepRowGroup = true;
+    for (const probe of probes) {
+      if (
+        probe.column.bloomFilterOffset === undefined ||
+        probe.column.bloomFilterByteLength === undefined
+      ) {
+        continue;
+      }
+      let field: ParquetField;
+      try {
+        field = initialization.parquetSchema.findField([...probe.column.path]);
+      } catch {
+        throwIfAborted(signal);
+        continue;
+      }
+      if (!field.primitiveType) continue;
+      let filter: ReturnType<typeof decodeParquetSplitBlockBloomFilter>;
+      try {
+        const rawColumnOrdinal = initialization.fileMetadata.row_groups[
+          rowGroupIndex
+        ].columns.findIndex(
+          columnChunk =>
+            JSON.stringify(columnChunk.meta_data?.path_in_schema) ===
+            JSON.stringify(probe.column.path)
+        );
+        const rawColumnChunk =
+          rawColumnOrdinal >= 0
+            ? initialization.fileMetadata.row_groups[rowGroupIndex].columns[rawColumnOrdinal]
+            : undefined;
+        const data = await initialization.file.read(
+          probe.column.bloomFilterOffset,
+          probe.column.bloomFilterByteLength,
+          signal
+        );
+        const decodedBloomFilter = rawColumnChunk
+          ? await initialization.reader.decryptBloomFilter(
+              toUint8Array(data),
+              rowGroupIndex,
+              rawColumnOrdinal,
+              rawColumnChunk
+            )
+          : toUint8Array(data);
+        filter = decodeParquetSplitBlockBloomFilter(decodedBloomFilter);
+        filtersRead++;
+        bytesRead += data.byteLength;
+      } catch {
+        throwIfAborted(signal);
+        continue;
+      }
+      if (
+        filter.algorithm !== 'BLOCK' ||
+        filter.hash !== 'XXHASH' ||
+        filter.compression !== 'UNCOMPRESSED'
+      ) {
+        continue;
+      }
+      const mayContainValue = probe.values.some(value => {
+        try {
+          if (value instanceof Date) return true;
+          const physicalValue = getParquetBloomFilterPhysicalValue(value, field);
+          const encoded = encodeParquetBloomFilterValue(
+            physicalValue,
+            field.primitiveType as Parameters<typeof encodeParquetBloomFilterValue>[1],
+            field.typeLength
+          );
+          return checkParquetSplitBlockBloomFilter(
+            filter.bitset,
+            hashParquetBloomFilterValue(encoded)
+          );
+        } catch {
+          throwIfAborted(signal);
+          return true;
+        }
+      });
+      if (!mayContainValue) {
+        keepRowGroup = false;
+        break;
+      }
+    }
+    if (keepRowGroup) rowGroups.push(rowGroupIndex);
+  }
+  return {rowGroupIndices: rowGroups, filtersRead, bytesRead};
+}
+
+/** Converts logical predicate values into the physical values stored in Bloom filters. */
+function getParquetBloomFilterPhysicalValue(
+  value: unknown,
+  field: ParquetField
+): boolean | number | bigint | string | Uint8Array {
+  if (field.originalType?.startsWith('DECIMAL_')) {
+    return toPrimitive(field.originalType as ParquetType, value, field) as
+      | number
+      | bigint
+      | Uint8Array;
+  }
+  return value as boolean | number | bigint | string | Uint8Array;
+}
+
 /** Returns true when at least one HTTP object validator was captured. */
 function hasObjectVersion(version?: ParquetObjectVersion): version is ParquetObjectVersion {
   return Boolean(version?.etag || version?.lastModified);