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

package/src/parquetjs/parser/parquet-reader.ts

@@ -7,11 +7,28 @@
 import type {ReadableFile} from '@loaders.gl/loader-utils';
 
 import {ParquetSchema} from '../schema/schema';
-import {decodeSchema, decodeDataPages, decodePage} from './decoders';
+import type {ParquetEncodedColumnChunk} from '../../parquet-encoded-page-types';
+import {
+  decodeSchema,
+  decodeDataPages,
+  decodePage,
+  decodeUncompressedDataPages,
+  decodeUncompressedDictionaryBuffer
+} from './decoders';
+import {scanParquetEncodedPages} from './encoded-pages';
 import {materializeRows} from '../schema/shred';
+import {createParquetPageDecompressor, type ParquetPageDecompressor} from '../compression';
 
 import {PARQUET_MAGIC, PARQUET_MAGIC_ENCRYPTED} from '../../lib/constants';
-import {ColumnChunk, CompressionCodec, FileMetaData, RowGroup, Type} from '../parquet-thrift/index';
+import {
+  ColumnChunk,
+  CompressionCodec,
+  Encoding,
+  FileMetaData,
+  PageType,
+  RowGroup,
+  Type
+} from '../parquet-thrift/index';
 import {
   ParquetRowGroup,
   ParquetCompression,
@@ -20,7 +37,15 @@ import {
   ParquetReaderContext,
   type ParquetLevelBuffer
 } from '../schema/declare';
-import {decodeFileMetadata, getThriftEnum, fieldIndexOf} from '../utils/read-utils';
+import {
+  decodeColumnMetadata,
+  decodeFileCryptoMetadata,
+  decodeFileMetadata,
+  decodePageHeader,
+  getThriftEnum,
+  fieldIndexOf,
+  serializeThrift
+} from '../utils/read-utils';
 import {decodeString, readUInt32LE, toUint8Array} from '../utils/binary-utils';
 import {CompactInt64} from '../utils/uint8-array-compact-protocol';
 import type {
@@ -28,10 +53,55 @@ import type {
   ParquetPageLocations,
   ParquetRowRange
 } from '../../lib/parquet-page-index';
+import {
+  createParquetModuleAad,
+  decryptParquetModule,
+  readParquetEncryptedModule,
+  verifyParquetFooterSignature,
+  type ParquetEncryptionAlgorithm,
+  type ParquetKeyRetriever
+} from '../../lib/parquet-encryption';
+import type {ParquetEncryptionModule} from '../../lib/parquet-encryption';
 
 /** Bounds concurrent range requests when a row group contains unusually many selected columns. */
 const MAXIMUM_CONCURRENT_COLUMN_READS = 16;
 
+/**
+ * Returns whether column metadata guarantees that every data page can decode directly into an
+ * Arrow-compatible byte buffer. Level encodings are included in the metadata encoding set and do
+ * not prevent the byte-array fast path.
+ */
+function hasOnlyArrowByteArrayDataPageEncodings(
+  encodings: Encoding[],
+  dictionaryPageOffset: number | undefined
+): boolean {
+  if (dictionaryPageOffset !== undefined || encodings.length === 0) {
+    return false;
+  }
+  for (const encoding of encodings) {
+    if (
+      encoding !== Encoding.PLAIN &&
+      encoding !== Encoding.DELTA_LENGTH_BYTE_ARRAY &&
+      encoding !== Encoding.DELTA_BYTE_ARRAY &&
+      encoding !== Encoding.RLE &&
+      encoding !== Encoding.BIT_PACKED
+    ) {
+      return false;
+    }
+  }
+  return true;
+}
+
+/** Returns the algorithm name represented by the Thrift encryption union. */
+function getEncryptionAlgorithm(value: {
+  AES_GCM_V1?: unknown;
+  AES_GCM_CTR_V1?: unknown;
+}): ParquetEncryptionAlgorithm {
+  if (value.AES_GCM_V1) return 'AES_GCM_V1';
+  if (value.AES_GCM_CTR_V1) return 'AES_GCM_CTR_V1';
+  throw new Error('Unsupported Parquet encryption algorithm');
+}
+
 export type ParquetReaderProps = {
   /** Maximum dictionary-page read size. */
   defaultDictionarySize?: number;
@@ -43,8 +113,22 @@ export type ParquetReaderProps = {
   useTypedValueBuffers?: boolean;
   /** Decode repetition and definition levels into compact unsigned typed arrays. */
   useTypedLevelBuffers?: boolean;
+  /** Decode eligible PLAIN BYTE_ARRAY columns into Arrow-compatible contiguous buffers. */
+  useArrowByteArrayBuffers?: boolean;
+  /** Verify page-header CRC values when present. Disabled by default for throughput. */
+  verifyPageChecksums?: boolean;
+  /** Decode legacy INT96 values as epoch nanoseconds for Arrow timestamp columns. */
+  int96AsTimestamp?: boolean;
+  /** Verify plaintext-footer signatures when present. Enabled by default. */
+  verifyFooterSignature?: boolean;
   /** Abort signal forwarded to every underlying random-access read. */
   signal?: AbortSignal;
+  /** Resolves modular-encryption keys from the file's key metadata. */
+  keyRetriever?: ParquetKeyRetriever;
+  /** AAD prefix for files that intentionally omit it from FileCryptoMetaData. */
+  aadPrefix?: Uint8Array;
+  /** Pre-resolved encryption context used by worker-local readers. */
+  encryptionContext?: ParquetReaderEncryptionContext;
 };
 
 /** Properties for initializing a ParquetRowGroupReader */
@@ -57,6 +141,26 @@ export type ParquetIterationProps = {
   signal?: AbortSignal;
 };
 
+type NormalizedParquetReaderProps = Required<
+  Omit<ParquetReaderProps, 'signal' | 'keyRetriever' | 'aadPrefix' | 'encryptionContext'>
+> &
+  Pick<ParquetReaderProps, 'signal' | 'keyRetriever' | 'aadPrefix' | 'encryptionContext'>;
+
+/** File-level parameters needed to authenticate modular-encrypted modules. */
+type ParquetEncryptionContext = {
+  algorithm: ParquetEncryptionAlgorithm;
+  aadPrefix?: Uint8Array;
+  fileUnique: Uint8Array;
+  footerKeyMetadata?: Uint8Array;
+  footerSigningKeyMetadata?: Uint8Array;
+};
+
+/** File-level encryption parameters needed to decrypt worker-transferred page modules. */
+export type ParquetReaderEncryptionContext = Pick<
+  ParquetEncryptionContext,
+  'algorithm' | 'aadPrefix' | 'fileUnique' | 'footerKeyMetadata'
+>;
+
 /**
  * The parquet envelope reader allows direct, unbuffered access to the individual
  * sections of the parquet file, namely the header, footer and the row groups.
@@ -64,32 +168,154 @@ export type ParquetIterationProps = {
  * rows from a parquet file use the ParquetReader instead
  */
 export class ParquetReader {
-  static defaultProps: Required<Omit<ParquetReaderProps, 'signal'>> & {signal?: AbortSignal} = {
+  static defaultProps: NormalizedParquetReaderProps = {
     // max ArrayBuffer size in js is 2Gb
     defaultDictionarySize: 2147483648,
     preserveBinary: false,
     retainByteArrayViews: false,
     useTypedValueBuffers: false,
     useTypedLevelBuffers: false,
-    signal: undefined
+    useArrowByteArrayBuffers: false,
+    verifyPageChecksums: false,
+    int96AsTimestamp: false,
+    verifyFooterSignature: true,
+    signal: undefined,
+    keyRetriever: undefined,
+    aadPrefix: undefined,
+    encryptionContext: undefined
   };
 
-  props: Required<Omit<ParquetReaderProps, 'signal'>> & {signal?: AbortSignal};
+  props: NormalizedParquetReaderProps;
   file: ReadableFile;
   metadata: Promise<FileMetaData> | null = null;
   /** Parsed Parquet schema shared by metadata, iteration, and materialization paths. */
   private schema: Promise<ParquetSchema> | null = null;
+  /** Encryption parameters decoded from plaintext or encrypted footer metadata. */
+  private encryptionContext?: ParquetEncryptionContext;
+  /** Resolved keys shared by encrypted modules in this reader instance. */
+  private readonly encryptionKeyCache = new Map<string, Promise<ArrayBuffer | ArrayBufferView>>();
+  /** Compression backends selected once and shared by every page in this reader. */
+  private readonly pageDecompressors = new Map<ParquetCompression, ParquetPageDecompressor>();
 
   constructor(file: ReadableFile, props?: ParquetReaderProps) {
     this.file = file;
     this.props = {...ParquetReader.defaultProps, ...props};
+    this.encryptionContext = this.props.encryptionContext;
+  }
+
+  /** Whether the decoded footer describes an encrypted Parquet file. */
+  get encrypted(): boolean {
+    return Boolean(this.encryptionContext);
+  }
+
+  /** Whether this reader decodes legacy INT96 values as epoch nanoseconds. */
+  get int96AsTimestamp(): boolean {
+    return this.props.int96AsTimestamp;
+  }
+
+  /** Returns a cloneable snapshot of the file encryption context for worker decoding. */
+  getEncryptionContextForWorker(): ParquetReaderEncryptionContext | undefined {
+    const encryptionContext = this.encryptionContext;
+    if (!encryptionContext) return undefined;
+    return {
+      algorithm: encryptionContext.algorithm,
+      aadPrefix: encryptionContext.aadPrefix && new Uint8Array(encryptionContext.aadPrefix),
+      fileUnique: new Uint8Array(encryptionContext.fileUnique),
+      footerKeyMetadata:
+        encryptionContext.footerKeyMetadata && new Uint8Array(encryptionContext.footerKeyMetadata)
+    };
+  }
+
+  /** Resolves one column key on the caller thread before transferring encrypted ranges. */
+  async getColumnKeyForWorker(
+    columnChunk: ColumnChunk,
+    rowGroupOrdinal: number,
+    columnOrdinal: number
+  ): Promise<{keyMetadata?: Uint8Array; keyMaterial: Uint8Array}> {
+    if (!this.encryptionContext || !this.props.keyRetriever) {
+      throw new Error('Encrypted Parquet worker reads require parquet.keyRetriever');
+    }
+    const keyMetadata = this.getColumnKeyMetadata(columnChunk);
+    const keyMaterial = await this.props.keyRetriever(keyMetadata, {
+      algorithm: this.encryptionContext.algorithm,
+      aad: createParquetModuleAad(
+        this.encryptionContext.aadPrefix,
+        this.encryptionContext.fileUnique,
+        'data-page',
+        rowGroupOrdinal,
+        columnOrdinal,
+        0
+      )
+    });
+    const keyBytes =
+      keyMaterial instanceof ArrayBuffer
+        ? new Uint8Array(keyMaterial)
+        : new Uint8Array(keyMaterial.buffer, keyMaterial.byteOffset, keyMaterial.byteLength);
+    return {keyMetadata, keyMaterial: keyBytes};
   }
 
   close(): void {
+    this.encryptionKeyCache.clear();
+    this.pageDecompressors.clear();
     // eslint-disable-next-line @typescript-eslint/no-floating-promises
     this.file.close();
   }
 
+  /** Returns the reader-scoped decoder for one Parquet compression method. */
+  private getPageDecompressor(compression: ParquetCompression): ParquetPageDecompressor {
+    let decompressor = this.pageDecompressors.get(compression);
+    if (!decompressor) {
+      decompressor = createParquetPageDecompressor(compression);
+      this.pageDecompressors.set(compression, decompressor);
+    }
+    return decompressor;
+  }
+
+  /** Reads a byte range, retaining a zero-copy view when the complete file is already in memory. */
+  private async readBytes(
+    start: number,
+    length: number,
+    signal?: AbortSignal
+  ): Promise<Uint8Array> {
+    const effectiveSignal = signal ?? this.props.signal;
+    if (effectiveSignal?.aborted) {
+      throw new Error('Request aborted');
+    }
+    if (this.file.handle instanceof ArrayBuffer) {
+      return new Uint8Array(this.file.handle, start, length);
+    }
+    return toUint8Array(await this.file.read(start, length, effectiveSignal));
+  }
+
+  /** Returns a reader-scoped key resolver that avoids repeating key-provider work per module. */
+  private getCachedKeyRetriever(): ParquetKeyRetriever {
+    const keyRetriever = this.props.keyRetriever;
+    if (!keyRetriever) {
+      throw new Error('Encrypted Parquet requires parquet.keyRetriever');
+    }
+    return (keyMetadata, context) => {
+      const encryptionContext = this.encryptionContext;
+      const cacheKey = createEncryptionKeyCacheKey(
+        context.algorithm,
+        keyMetadata,
+        context.aad,
+        encryptionContext?.aadPrefix?.byteLength ?? this.props.aadPrefix?.byteLength,
+        encryptionContext?.fileUnique.byteLength
+      );
+      let keyPromise = this.encryptionKeyCache.get(cacheKey);
+      if (!keyPromise) {
+        keyPromise = Promise.resolve().then(() => keyRetriever(keyMetadata, context));
+        this.encryptionKeyCache.set(cacheKey, keyPromise);
+        void keyPromise.catch(() => {
+          if (this.encryptionKeyCache.get(cacheKey) === keyPromise) {
+            this.encryptionKeyCache.delete(cacheKey);
+          }
+        });
+      }
+      return keyPromise;
+    };
+  }
+
   // HIGH LEVEL METHODS
 
   /** Yield one row at a time */
@@ -130,7 +356,8 @@ export class ParquetReader {
         schema,
         metadata.row_groups[rowGroupIndex],
         columnList,
-        props?.signal
+        props?.signal,
+        rowGroupIndex
       );
       yield rowGroup;
     }
@@ -175,13 +402,12 @@ export class ParquetReader {
 
   /** Metadata is stored in the footer */
   async readHeader(signal?: AbortSignal): Promise<void> {
-    const arrayBuffer = await this.file.read(0, PARQUET_MAGIC.length, signal ?? this.props.signal);
-    const magic = decodeString(toUint8Array(arrayBuffer));
+    const magic = decodeString(await this.readBytes(0, PARQUET_MAGIC.length, signal));
     switch (magic) {
       case PARQUET_MAGIC:
         break;
       case PARQUET_MAGIC_ENCRYPTED:
-        throw new Error('Encrypted parquet file not supported');
+        break;
       default:
         throw new Error(`Invalid parquet file (magic=${magic})`);
     }
@@ -190,34 +416,258 @@ export class ParquetReader {
   /** Metadata is stored in the footer */
   async readFooter(signal?: AbortSignal): Promise<FileMetaData> {
     const trailerLen = PARQUET_MAGIC.length + 4;
-    const arrayBuffer = await this.file.read(
-      this.file.size - trailerLen,
-      trailerLen,
-      signal ?? this.props.signal
-    );
-    const trailer = toUint8Array(arrayBuffer);
+    const trailer = await this.readBytes(this.file.size - trailerLen, trailerLen, signal);
 
     const magic = decodeString(trailer, 4);
+    const metadataSize = readUInt32LE(trailer, 0);
+    const metadataOffset = this.file.size - metadataSize - trailerLen;
+    if (magic === PARQUET_MAGIC_ENCRYPTED) {
+      return await this.readEncryptedFooter(metadataSize, metadataOffset, signal);
+    }
     if (magic !== PARQUET_MAGIC) {
       throw new Error(`Not a valid parquet file (magic="${magic})`);
     }
 
-    const metadataSize = readUInt32LE(trailer, 0);
-    const metadataOffset = this.file.size - metadataSize - trailerLen;
     if (metadataOffset < PARQUET_MAGIC.length) {
       throw new Error(`Invalid metadata size ${metadataOffset}`);
     }
 
-    const arrayBuffer2 = await this.file.read(
-      metadataOffset,
-      metadataSize,
-      signal ?? this.props.signal
-    );
-    const metadataBuf = toUint8Array(arrayBuffer2);
+    const metadataBuf = await this.readBytes(metadataOffset, metadataSize, signal);
     // let metadata = new parquet_thrift.FileMetaData();
     // parquet_util.decodeThrift(metadata, metadataBuf);
 
-    const {metadata} = decodeFileMetadata(metadataBuf);
+    const decoded = decodeFileMetadata(metadataBuf);
+    const {metadata} = decoded;
+    this.setEncryptionContext(metadata);
+    if (this.props.verifyFooterSignature && this.encryptionContext?.footerSigningKeyMetadata) {
+      // The compact-protocol decoder may consume bytes from the signature that
+      // happen to look like valid Thrift fields. The format defines the
+      // signature as the final fixed 28 bytes of the footer range, so use the
+      // physical boundary rather than the decoder's consumed length.
+      const signatureOffset = metadataBuf.byteLength - 28;
+      if (signatureOffset < decoded.length) {
+        throw new Error('Invalid Parquet plaintext-footer signature boundary');
+      }
+      const signature = metadataBuf.subarray(signatureOffset);
+      const encryptionContext = this.encryptionContext;
+      if (!this.props.keyRetriever) {
+        throw new Error('Signed Parquet footer requires parquet.keyRetriever');
+      }
+      await verifyParquetFooterSignature(metadataBuf.subarray(0, signatureOffset), signature, {
+        algorithm: encryptionContext.algorithm,
+        aad: createParquetModuleAad(
+          encryptionContext.aadPrefix,
+          encryptionContext.fileUnique,
+          'footer'
+        ),
+        keyMetadata: encryptionContext.footerSigningKeyMetadata,
+        keyRetriever: this.getCachedKeyRetriever()
+      });
+    }
+    return metadata;
+  }
+
+  /** Reads and decrypts an encrypted footer after the standard trailer. */
+  private async readEncryptedFooter(
+    metadataSize: number,
+    metadataOffset: number,
+    signal?: AbortSignal
+  ): Promise<FileMetaData> {
+    if (!this.props.keyRetriever) {
+      throw new Error('Encrypted Parquet footer requires parquet.keyRetriever');
+    }
+    const encryptedFooter = await this.readBytes(metadataOffset, metadataSize, signal);
+    const cryptoMetadata = decodeFileCryptoMetadata(encryptedFooter);
+    const algorithm = getEncryptionAlgorithm(cryptoMetadata.metadata.encryption_algorithm);
+    const algorithmMetadata =
+      cryptoMetadata.metadata.encryption_algorithm.AES_GCM_V1 ||
+      cryptoMetadata.metadata.encryption_algorithm.AES_GCM_CTR_V1;
+    const aadPrefix = algorithmMetadata?.aad_prefix || this.props.aadPrefix;
+    if (!algorithmMetadata?.aad_file_unique) {
+      throw new Error('Encrypted Parquet footer is missing aad_file_unique');
+    }
+    const aad = createParquetModuleAad(aadPrefix, algorithmMetadata.aad_file_unique, 'footer');
+    const plaintext = await decryptParquetModule(encryptedFooter.subarray(cryptoMetadata.length), {
+      algorithm,
+      aad,
+      keyMetadata: cryptoMetadata.metadata.key_metadata,
+      keyRetriever: this.getCachedKeyRetriever()
+    });
+    this.encryptionContext = {
+      algorithm,
+      aadPrefix,
+      fileUnique: algorithmMetadata.aad_file_unique,
+      footerKeyMetadata: cryptoMetadata.metadata.key_metadata
+    };
+    const metadata = decodeFileMetadata(plaintext).metadata;
+    return metadata;
+  }
+
+  /** Records the encryption parameters exposed by plaintext-footer files. */
+  private setEncryptionContext(metadata: FileMetaData): void {
+    const encryptionAlgorithm = metadata.encryption_algorithm;
+    if (!encryptionAlgorithm) return;
+    const algorithm = getEncryptionAlgorithm(encryptionAlgorithm);
+    const algorithmMetadata = encryptionAlgorithm.AES_GCM_V1 || encryptionAlgorithm.AES_GCM_CTR_V1;
+    if (!algorithmMetadata?.aad_file_unique) {
+      throw new Error('Encrypted Parquet footer is missing aad_file_unique');
+    }
+    this.encryptionContext = {
+      algorithm,
+      aadPrefix: algorithmMetadata.aad_prefix || this.props.aadPrefix,
+      fileUnique: algorithmMetadata.aad_file_unique,
+      footerSigningKeyMetadata: metadata.footer_signing_key_metadata
+    };
+  }
+
+  /** Resolves only the selected encrypted columns, using crypto metadata paths before decryption. */
+  async resolveColumnMetadata(
+    rowGroup: RowGroup,
+    rowGroupOrdinal: number,
+    selectedColumnPaths?: readonly string[][]
+  ): Promise<void> {
+    for (let columnOrdinal = 0; columnOrdinal < rowGroup.columns.length; columnOrdinal++) {
+      const columnChunk = rowGroup.columns[columnOrdinal];
+      const path = getColumnChunkPath(columnChunk);
+      if (
+        selectedColumnPaths &&
+        path &&
+        !selectedColumnPaths.some(
+          selectedPath => fieldIndexOf([Array.from(selectedPath)], path) >= 0
+        )
+      ) {
+        continue;
+      }
+      if (columnChunk.encrypted_column_metadata && !columnChunk.meta_data) {
+        columnChunk.meta_data = await this.getColumnMetadata(
+          columnChunk,
+          rowGroupOrdinal,
+          getPhysicalColumnOrdinal(columnChunk, columnOrdinal)
+        );
+      }
+    }
+  }
+
+  /** Decrypts one encrypted column index or offset index module for selective planning. */
+  async decryptIndexModule(
+    bytes: Uint8Array,
+    module: 'column-index' | 'offset-index',
+    rowGroupOrdinal: number,
+    columnOrdinal: number,
+    columnChunk: ColumnChunk
+  ): Promise<Uint8Array> {
+    if (!columnChunk.crypto_metadata) return bytes;
+    const encryptionContext = this.encryptionContext;
+    if (!encryptionContext || !this.props.keyRetriever) {
+      throw new Error('Encrypted Parquet indexes require parquet.keyRetriever');
+    }
+    const aad = createParquetModuleAad(
+      encryptionContext.aadPrefix,
+      encryptionContext.fileUnique,
+      module,
+      rowGroupOrdinal,
+      columnOrdinal
+    );
+    return await decryptParquetModule(bytes, {
+      algorithm: encryptionContext.algorithm,
+      aad,
+      keyMetadata: this.getColumnKeyMetadata(columnChunk),
+      keyRetriever: this.getCachedKeyRetriever()
+    });
+  }
+
+  /** Decrypts the encrypted Bloom-filter header and bitset modules for one column chunk. */
+  async decryptBloomFilter(
+    bytes: Uint8Array,
+    rowGroupOrdinal: number,
+    columnOrdinal: number,
+    columnChunk: ColumnChunk
+  ): Promise<Uint8Array> {
+    if (!columnChunk.crypto_metadata) return bytes;
+    const encryptionContext = this.encryptionContext;
+    if (!encryptionContext || !this.props.keyRetriever) {
+      throw new Error('Encrypted Parquet Bloom filters require parquet.keyRetriever');
+    }
+    const header = readParquetEncryptedModule(bytes);
+    const bitset = readParquetEncryptedModule(bytes, header.nextOffset);
+    const keyMetadata = this.getColumnKeyMetadata(columnChunk);
+    const headerBytes = await decryptParquetModule(header.bytes, {
+      algorithm: encryptionContext.algorithm,
+      aad: createParquetModuleAad(
+        encryptionContext.aadPrefix,
+        encryptionContext.fileUnique,
+        'bloom-filter-header',
+        rowGroupOrdinal,
+        columnOrdinal
+      ),
+      keyMetadata,
+      keyRetriever: this.getCachedKeyRetriever()
+    });
+    const bitsetBytes = await decryptParquetModule(bitset.bytes, {
+      algorithm: encryptionContext.algorithm,
+      aad: createParquetModuleAad(
+        encryptionContext.aadPrefix,
+        encryptionContext.fileUnique,
+        'bloom-filter-bitset',
+        rowGroupOrdinal,
+        columnOrdinal
+      ),
+      keyMetadata,
+      keyRetriever: this.getCachedKeyRetriever()
+    });
+    const plaintext = new Uint8Array(headerBytes.byteLength + bitsetBytes.byteLength);
+    plaintext.set(headerBytes);
+    plaintext.set(bitsetBytes, headerBytes.byteLength);
+    return plaintext;
+  }
+
+  /** Resolves a column's plaintext metadata, decrypting column-specific metadata when present. */
+  private async getColumnMetadata(
+    columnChunk: ColumnChunk,
+    rowGroupOrdinal: number,
+    columnOrdinal: number
+  ): Promise<NonNullable<ColumnChunk['meta_data']>> {
+    if (!columnChunk.encrypted_column_metadata) {
+      if (!columnChunk.meta_data) {
+        throw new Error('Parquet column metadata is missing');
+      }
+      return columnChunk.meta_data;
+    }
+    if (!this.props.keyRetriever) {
+      throw new Error('Encrypted Parquet column metadata requires parquet.keyRetriever');
+    }
+    const encryptionContext = this.encryptionContext;
+    if (!encryptionContext) {
+      throw new Error('Encrypted Parquet column metadata has no file encryption context');
+    }
+    const columnKey = columnChunk.crypto_metadata?.ENCRYPTION_WITH_COLUMN_KEY;
+    const usesFooterKey = Boolean(columnChunk.crypto_metadata?.ENCRYPTION_WITH_FOOTER_KEY);
+    if (!columnKey && !usesFooterKey) {
+      throw new Error('Encrypted Parquet column metadata has no key reference');
+    }
+    const aad = createParquetModuleAad(
+      encryptionContext.aadPrefix,
+      encryptionContext.fileUnique,
+      'column-metadata',
+      rowGroupOrdinal,
+      columnOrdinal
+    );
+    const plaintext = await decryptParquetModule(columnChunk.encrypted_column_metadata, {
+      algorithm: encryptionContext.algorithm,
+      aad,
+      keyMetadata:
+        columnKey?.key_metadata ??
+        encryptionContext.footerKeyMetadata ??
+        encryptionContext.footerSigningKeyMetadata,
+      keyRetriever: this.getCachedKeyRetriever()
+    });
+    const metadata = decodeColumnMetadata(plaintext).metadata;
+    if (
+      columnKey &&
+      JSON.stringify(metadata.path_in_schema) !== JSON.stringify(columnKey.path_in_schema)
+    ) {
+      throw new Error('Encrypted Parquet column metadata path does not match crypto metadata');
+    }
     return metadata;
   }
 
@@ -226,12 +676,48 @@ export class ParquetReader {
     schema: ParquetSchema,
     rowGroup: RowGroup,
     columnList: string[][],
-    signal?: AbortSignal
+    signal?: AbortSignal,
+    rowGroupOrdinal = 0
   ): Promise<ParquetRowGroup> {
-    const selectedColumnChunks = rowGroup.columns.filter(columnChunk => {
-      const columnKey = columnChunk.meta_data?.path_in_schema;
-      return columnList.length === 0 || fieldIndexOf(columnList, columnKey!) >= 0;
-    });
+    await this.resolveColumnMetadata(rowGroup, rowGroupOrdinal, columnList);
+    const selectedColumnChunks: Array<{
+      columnChunk: ColumnChunk;
+      metadata: NonNullable<ColumnChunk['meta_data']>;
+      columnOrdinal: number;
+    }> = [];
+    for (let columnOrdinal = 0; columnOrdinal < rowGroup.columns.length; columnOrdinal++) {
+      const columnChunk = rowGroup.columns[columnOrdinal];
+      const path = getColumnChunkPath(columnChunk);
+      if (columnList.length > 0 && (!path || fieldIndexOf(columnList, path) < 0)) {
+        continue;
+      }
+      const physicalColumnOrdinal = getPhysicalColumnOrdinal(columnChunk, columnOrdinal);
+      const metadata =
+        columnChunk.meta_data ||
+        (await this.getColumnMetadata(columnChunk, rowGroupOrdinal, physicalColumnOrdinal));
+      if (columnList.length === 0 || fieldIndexOf(columnList, metadata.path_in_schema) >= 0) {
+        selectedColumnChunks.push({columnChunk, metadata, columnOrdinal: physicalColumnOrdinal});
+      }
+    }
+    if (
+      this.file.handle instanceof ArrayBuffer &&
+      selectedColumnChunks.every(
+        ({columnChunk, metadata}) =>
+          (columnChunk.file_path === undefined || columnChunk.file_path === null) &&
+          !columnChunk.crypto_metadata &&
+          getThriftEnum(CompressionCodec, metadata.codec) === 'UNCOMPRESSED'
+      )
+    ) {
+      return {
+        rowCount: Number(rowGroup.num_rows),
+        columnData: Object.fromEntries(
+          selectedColumnChunks.map(({columnChunk, metadata}) => [
+            metadata.path_in_schema.join(),
+            this.readUncompressedColumnChunkFromMemory(schema, columnChunk, metadata)
+          ])
+        )
+      };
+    }
     const columnEntries: Array<readonly [string, ParquetColumnChunk]> = [];
     for (
       let batchStart = 0;
@@ -244,10 +730,27 @@ export class ParquetReader {
       );
       columnEntries.push(
         ...(await Promise.all(
-          columnBatch.map(async columnChunk => {
-            const columnKey = columnChunk.meta_data!.path_in_schema.join();
-            const columnData = await this.readColumnChunk(schema, columnChunk, signal);
-            return [columnKey, columnData] as const;
+          columnBatch.map(({columnChunk, metadata, columnOrdinal}) => {
+            const columnKey = metadata.path_in_schema.join();
+            if (
+              this.file.handle instanceof ArrayBuffer &&
+              (columnChunk.file_path === undefined || columnChunk.file_path === null) &&
+              !columnChunk.crypto_metadata &&
+              getThriftEnum(CompressionCodec, metadata.codec) === 'UNCOMPRESSED'
+            ) {
+              return [
+                columnKey,
+                this.readUncompressedColumnChunkFromMemory(schema, columnChunk, metadata)
+              ] as const;
+            }
+            return this.readColumnChunk(
+              schema,
+              columnChunk,
+              signal,
+              rowGroupOrdinal,
+              columnOrdinal,
+              metadata
+            ).then(columnData => [columnKey, columnData] as const);
           })
         ))
       );
@@ -258,23 +761,104 @@ export class ParquetReader {
     };
   }
 
-  /** Reads independently materializable flat columns for one logical row range using page indexes. */
+  /**
+   * Reads selected column chunks as encoded page descriptors without materializing values.
+   *
+   * Page headers, encryption, checksums, and optional decompression remain reader concerns. Value,
+   * dictionary, and level decoding is deliberately left to the downstream consumer.
+   */
+  async readRowGroupEncodedPages(
+    schema: ParquetSchema,
+    rowGroup: RowGroup,
+    columnList: string[][],
+    preserveCompression: ReadonlySet<string>,
+    signal?: AbortSignal,
+    rowGroupOrdinal = 0
+  ): Promise<readonly ParquetEncodedColumnChunk[]> {
+    await this.resolveColumnMetadata(rowGroup, rowGroupOrdinal, columnList);
+    const selectedColumnChunks: Array<{
+      columnChunk: ColumnChunk;
+      metadata: NonNullable<ColumnChunk['meta_data']>;
+      columnOrdinal: number;
+    }> = [];
+    for (let columnOrdinal = 0; columnOrdinal < rowGroup.columns.length; columnOrdinal++) {
+      const columnChunk = rowGroup.columns[columnOrdinal];
+      const path = getColumnChunkPath(columnChunk);
+      if (columnList.length > 0 && (!path || fieldIndexOf(columnList, path) < 0)) continue;
+      const physicalColumnOrdinal = getPhysicalColumnOrdinal(columnChunk, columnOrdinal);
+      const metadata =
+        columnChunk.meta_data ||
+        (await this.getColumnMetadata(columnChunk, rowGroupOrdinal, physicalColumnOrdinal));
+      if (columnList.length === 0 || fieldIndexOf(columnList, metadata.path_in_schema) >= 0) {
+        selectedColumnChunks.push({
+          columnChunk,
+          metadata,
+          columnOrdinal: physicalColumnOrdinal
+        });
+      }
+    }
+    const columns: ParquetEncodedColumnChunk[] = [];
+    for (
+      let batchStart = 0;
+      batchStart < selectedColumnChunks.length;
+      batchStart += MAXIMUM_CONCURRENT_COLUMN_READS
+    ) {
+      columns.push(
+        ...(await Promise.all(
+          selectedColumnChunks
+            .slice(batchStart, batchStart + MAXIMUM_CONCURRENT_COLUMN_READS)
+            .map(async ({columnChunk, metadata, columnOrdinal}) => {
+              const encodedColumn = await this.readColumnChunkEncodedPages(
+                schema,
+                columnChunk,
+                preserveCompression,
+                signal,
+                rowGroupOrdinal,
+                columnOrdinal,
+                metadata
+              );
+              return encodedColumn;
+            })
+        ))
+      );
+    }
+    return Object.freeze(columns);
+  }
+
+  /** Reads independently materializable non-repeated columns for one row range using page indexes. */
   async readRowGroupRange(
     schema: ParquetSchema,
     rowGroup: RowGroup,
     columnList: string[][],
     rowRange: ParquetRowRange,
     pageLocations: ParquetPageLocations,
-    signal?: AbortSignal
+    signal?: AbortSignal,
+    rowGroupOrdinal = 0
   ): Promise<ParquetRowGroup> {
-    const selectedColumnChunks = rowGroup.columns.filter(columnChunk => {
-      const columnKey = columnChunk.meta_data?.path_in_schema;
-      return columnList.length === 0 || fieldIndexOf(columnList, columnKey!) >= 0;
-    });
+    await this.resolveColumnMetadata(rowGroup, rowGroupOrdinal, columnList);
+    const selectedColumnChunks: Array<{
+      columnChunk: ColumnChunk;
+      metadata: NonNullable<ColumnChunk['meta_data']>;
+      columnOrdinal: number;
+    }> = [];
+    for (let columnOrdinal = 0; columnOrdinal < rowGroup.columns.length; columnOrdinal++) {
+      const columnChunk = rowGroup.columns[columnOrdinal];
+      const path = getColumnChunkPath(columnChunk);
+      if (columnList.length > 0 && (!path || fieldIndexOf(columnList, path) < 0)) {
+        continue;
+      }
+      const physicalColumnOrdinal = getPhysicalColumnOrdinal(columnChunk, columnOrdinal);
+      const metadata =
+        columnChunk.meta_data ||
+        (await this.getColumnMetadata(columnChunk, rowGroupOrdinal, physicalColumnOrdinal));
+      if (columnList.length === 0 || fieldIndexOf(columnList, metadata.path_in_schema) >= 0) {
+        selectedColumnChunks.push({columnChunk, metadata, columnOrdinal: physicalColumnOrdinal});
+      }
+    }
     const columnEntries = await Promise.all(
-      selectedColumnChunks.map(async columnChunk => {
-        const columnKey = columnChunk.meta_data!.path_in_schema.join();
-        const pages = pageLocations[columnChunk.meta_data!.path_in_schema.join('.')];
+      selectedColumnChunks.map(async ({columnChunk, metadata, columnOrdinal}) => {
+        const columnKey = metadata.path_in_schema.join();
+        const pages = pageLocations[JSON.stringify(metadata.path_in_schema)];
         if (!pages) {
           throw new Error(`Parquet offset index missing for ${columnKey}`);
         }
@@ -283,7 +867,10 @@ export class ParquetReader {
           columnChunk,
           rowRange,
           pages,
-          signal
+          signal,
+          rowGroupOrdinal,
+          columnOrdinal,
+          metadata
         );
         return [columnKey, columnData] as const;
       })
@@ -294,41 +881,118 @@ export class ParquetReader {
     };
   }
 
+  /**
+   * Each row group contains column chunks for all the columns.
+   */
+  private readUncompressedColumnChunkFromMemory(
+    schema: ParquetSchema,
+    columnChunk: ColumnChunk,
+    metadata: NonNullable<ColumnChunk['meta_data']>
+  ): ParquetColumnChunk {
+    if (!(this.file.handle instanceof ArrayBuffer)) {
+      throw new Error('Synchronous Parquet column reads require an in-memory ArrayBuffer');
+    }
+    const field = schema.findField(metadata.path_in_schema);
+    const type: PrimitiveType = getThriftEnum(Type, metadata.type) as PrimitiveType;
+    if (type !== field.primitiveType) {
+      throw new Error(`chunk type not matching schema: ${type}`);
+    }
+
+    const pagesOffset = Number(metadata.data_page_offset);
+    const dictionaryPageOffset = metadata.dictionary_page_offset;
+    const validDictionaryPageOffset =
+      dictionaryPageOffset !== undefined && Number(dictionaryPageOffset) > 0
+        ? Number(dictionaryPageOffset)
+        : undefined;
+    const chunkOffset = Math.min(pagesOffset, validDictionaryPageOffset ?? pagesOffset);
+    const chunkEnd = chunkOffset + Number(metadata.total_compressed_size);
+    const chunkSize = Math.min(this.file.size - chunkOffset, Math.max(0, chunkEnd - chunkOffset));
+    const chunkBuffer = new Uint8Array(this.file.handle, chunkOffset, chunkSize);
+    const pagesRelativeOffset = pagesOffset - chunkOffset;
+    const pagesSize = Math.min(
+      chunkBuffer.length - pagesRelativeOffset,
+      Math.max(0, chunkEnd - pagesOffset)
+    );
+    const context: ParquetReaderContext = {
+      type,
+      rLevelMax: field.rLevelMax,
+      dLevelMax: field.dLevelMax,
+      compression: 'UNCOMPRESSED',
+      column: field,
+      numValues: metadata.num_values,
+      dictionary: [],
+      decompressPage: this.getPageDecompressor('UNCOMPRESSED'),
+      preserveBinary: this.props.preserveBinary,
+      retainByteArrayViews: this.props.retainByteArrayViews,
+      useTypedValueBuffers: this.props.useTypedValueBuffers,
+      useTypedLevelBuffers: this.props.useTypedLevelBuffers,
+      useArrowByteArrayBuffers: this.props.useArrowByteArrayBuffers,
+      // Metadata proves whether the decoder may skip its otherwise duplicated page-header scan.
+      // Keep the scan for mixed/unknown encodings: it is both a correctness guard and fallback.
+      hasOnlyArrowByteArrayDataPages: hasOnlyArrowByteArrayDataPageEncodings(
+        metadata.encodings,
+        validDictionaryPageOffset
+      ),
+      verifyPageChecksums: this.props.verifyPageChecksums,
+      int96AsTimestamp: this.props.int96AsTimestamp
+    };
+    let dictionary: unknown[] | undefined;
+    if (validDictionaryPageOffset !== undefined) {
+      const dictionaryRelativeOffset = validDictionaryPageOffset - chunkOffset;
+      const dictionarySize = Math.min(
+        Math.max(0, pagesOffset - validDictionaryPageOffset),
+        chunkBuffer.length - dictionaryRelativeOffset,
+        this.props.defaultDictionarySize
+      );
+      dictionary = decodeUncompressedDictionaryBuffer(
+        chunkBuffer.subarray(dictionaryRelativeOffset, dictionaryRelativeOffset + dictionarySize),
+        context
+      );
+    }
+    return decodeUncompressedDataPages(
+      chunkBuffer.subarray(pagesRelativeOffset, pagesRelativeOffset + pagesSize),
+      {...context, dictionary}
+    );
+  }
+
   /**
    * Each row group contains column chunks for all the columns.
    */
   async readColumnChunk(
     schema: ParquetSchema,
     colChunk: ColumnChunk,
-    signal?: AbortSignal
+    signal?: AbortSignal,
+    rowGroupOrdinal = 0,
+    columnOrdinal = 0,
+    resolvedMetadata?: NonNullable<ColumnChunk['meta_data']>
   ): Promise<ParquetColumnChunk> {
     if (colChunk.file_path !== undefined && colChunk.file_path !== null) {
       throw new Error('external references are not supported');
     }
 
-    const field = schema.findField(colChunk.meta_data?.path_in_schema!);
-    const type: PrimitiveType = getThriftEnum(Type, colChunk.meta_data?.type!) as any;
+    const metadata = resolvedMetadata || colChunk.meta_data;
+    if (!metadata) {
+      throw new Error('Parquet column metadata is missing');
+    }
+    const field = schema.findField(metadata.path_in_schema);
+    const type: PrimitiveType = getThriftEnum(Type, metadata.type) as any;
 
     if (type !== field.primitiveType) {
       throw new Error(`chunk type not matching schema: ${type}`);
     }
 
-    const compression: ParquetCompression = getThriftEnum(
-      CompressionCodec,
-      colChunk.meta_data?.codec!
-    ) as any;
+    const compression: ParquetCompression = getThriftEnum(CompressionCodec, metadata.codec) as any;
 
-    const pagesOffset = Number(colChunk.meta_data?.data_page_offset!);
-    const dictionaryPageOffset = colChunk.meta_data?.dictionary_page_offset;
+    const pagesOffset = Number(metadata.data_page_offset);
+    const dictionaryPageOffset = metadata.dictionary_page_offset;
     const validDictionaryPageOffset =
       dictionaryPageOffset !== undefined && Number(dictionaryPageOffset) > 0
         ? Number(dictionaryPageOffset)
         : undefined;
     const chunkOffset = Math.min(pagesOffset, validDictionaryPageOffset ?? pagesOffset);
-    const chunkEnd = chunkOffset + Number(colChunk.meta_data?.total_compressed_size!);
+    const chunkEnd = chunkOffset + Number(metadata.total_compressed_size);
     const chunkSize = Math.min(this.file.size - chunkOffset, Math.max(0, chunkEnd - chunkOffset));
-    const arrayBuffer = await this.file.read(chunkOffset, chunkSize, signal ?? this.props.signal);
-    const chunkBuffer = toUint8Array(arrayBuffer);
+    const chunkBuffer = await this.readBytes(chunkOffset, chunkSize, signal);
     const pagesRelativeOffset = pagesOffset - chunkOffset;
     const pagesSize = Math.min(
       chunkBuffer.length - pagesRelativeOffset,
@@ -341,13 +1005,23 @@ export class ParquetReader {
       dLevelMax: field.dLevelMax,
       compression,
       column: field,
-      numValues: colChunk.meta_data?.num_values,
+      numValues: metadata.num_values,
       dictionary: [],
+      decompressPage: this.getPageDecompressor(compression),
       // Options - TBD is this the right place for these?
       preserveBinary: this.props.preserveBinary,
       retainByteArrayViews: this.props.retainByteArrayViews,
       useTypedValueBuffers: this.props.useTypedValueBuffers,
-      useTypedLevelBuffers: this.props.useTypedLevelBuffers
+      useTypedLevelBuffers: this.props.useTypedLevelBuffers,
+      useArrowByteArrayBuffers: this.props.useArrowByteArrayBuffers,
+      // Avoid parsing every page header twice when trusted column metadata already establishes the
+      // direct Arrow byte-array invariant. Unknown/mixed encodings retain the defensive scan.
+      hasOnlyArrowByteArrayDataPages: hasOnlyArrowByteArrayDataPageEncodings(
+        metadata.encodings,
+        validDictionaryPageOffset
+      ),
+      verifyPageChecksums: this.props.verifyPageChecksums,
+      int96AsTimestamp: this.props.int96AsTimestamp
     };
 
     let dictionary: any[] | undefined;
@@ -363,30 +1037,243 @@ export class ParquetReader {
         dictionaryRelativeOffset,
         dictionaryRelativeOffset + dictionarySize
       );
-      dictionary = await decodeDictionaryBuffer(dictionaryBuffer, context);
+      const decodedDictionaryBuffer = colChunk.crypto_metadata
+        ? await this.decryptColumnPages(
+            dictionaryBuffer,
+            context,
+            rowGroupOrdinal,
+            columnOrdinal,
+            this.getColumnKeyMetadata(colChunk),
+            true
+          )
+        : dictionaryBuffer;
+      dictionary = await decodeDictionaryBuffer(decodedDictionaryBuffer, context);
     }
 
     dictionary = context.dictionary?.length ? context.dictionary : dictionary;
-    const pagesBuf = chunkBuffer.subarray(pagesRelativeOffset, pagesRelativeOffset + pagesSize);
+    const pagesBuf = colChunk.crypto_metadata
+      ? await this.decryptColumnPages(
+          chunkBuffer.subarray(pagesRelativeOffset, pagesRelativeOffset + pagesSize),
+          context,
+          rowGroupOrdinal,
+          columnOrdinal,
+          this.getColumnKeyMetadata(colChunk)
+        )
+      : chunkBuffer.subarray(pagesRelativeOffset, pagesRelativeOffset + pagesSize);
     return await decodeDataPages(pagesBuf, {...context, dictionary});
   }
 
-  /** Reads and decodes only the contiguous data pages overlapping one flat-column row range. */
+  /** Reads one column chunk as encoded dictionaries, levels, and values for deferred decoding. */
+  async readColumnChunkEncodedPages(
+    schema: ParquetSchema,
+    columnChunk: ColumnChunk,
+    preserveCompression: ReadonlySet<string>,
+    signal?: AbortSignal,
+    rowGroupOrdinal = 0,
+    columnOrdinal = 0,
+    resolvedMetadata?: NonNullable<ColumnChunk['meta_data']>
+  ): Promise<ParquetEncodedColumnChunk> {
+    if (columnChunk.file_path !== undefined && columnChunk.file_path !== null) {
+      throw new Error('external references are not supported');
+    }
+    const metadata = resolvedMetadata || columnChunk.meta_data;
+    if (!metadata) throw new Error('Parquet column metadata is missing');
+    const field = schema.findField(metadata.path_in_schema);
+    const physicalType: PrimitiveType = getThriftEnum(Type, metadata.type) as PrimitiveType;
+    if (physicalType !== field.primitiveType) {
+      throw new Error(`chunk type not matching schema: ${physicalType}`);
+    }
+    const compression = getThriftEnum(CompressionCodec, metadata.codec) as ParquetCompression;
+    const dataPageOffset = Number(metadata.data_page_offset);
+    const dictionaryPageOffset = metadata.dictionary_page_offset;
+    const validDictionaryPageOffset =
+      dictionaryPageOffset !== undefined && Number(dictionaryPageOffset) > 0
+        ? Number(dictionaryPageOffset)
+        : undefined;
+    const chunkOffset = Math.min(dataPageOffset, validDictionaryPageOffset ?? dataPageOffset);
+    const chunkEnd = chunkOffset + Number(metadata.total_compressed_size);
+    const chunkByteLength = Math.min(
+      this.file.size - chunkOffset,
+      Math.max(0, chunkEnd - chunkOffset)
+    );
+    const chunkBuffer = await this.readBytes(chunkOffset, chunkByteLength, signal);
+    const dataPageRelativeOffset = dataPageOffset - chunkOffset;
+    const dataPageByteLength = Math.min(
+      chunkBuffer.byteLength - dataPageRelativeOffset,
+      Math.max(0, chunkEnd - dataPageOffset)
+    );
+    const context = {
+      column: field,
+      compression,
+      decompressPage: this.getPageDecompressor(compression),
+      preserveCompression,
+      verifyPageChecksums: this.props.verifyPageChecksums
+    };
+
+    let dictionary;
+    if (validDictionaryPageOffset !== undefined) {
+      const dictionaryRelativeOffset = validDictionaryPageOffset - chunkOffset;
+      const dictionaryByteLength = Math.min(
+        Math.max(0, dataPageOffset - validDictionaryPageOffset),
+        chunkBuffer.byteLength - dictionaryRelativeOffset,
+        this.props.defaultDictionarySize
+      );
+      const dictionaryBuffer = chunkBuffer.subarray(
+        dictionaryRelativeOffset,
+        dictionaryRelativeOffset + dictionaryByteLength
+      );
+      const plaintextDictionaryBuffer = columnChunk.crypto_metadata
+        ? await this.decryptColumnPages(
+            dictionaryBuffer,
+            {
+              type: physicalType,
+              rLevelMax: field.rLevelMax,
+              dLevelMax: field.dLevelMax,
+              compression,
+              column: field
+            },
+            rowGroupOrdinal,
+            columnOrdinal,
+            this.getColumnKeyMetadata(columnChunk),
+            true
+          )
+        : dictionaryBuffer;
+      dictionary = (await scanParquetEncodedPages(plaintextDictionaryBuffer, context))[0];
+    }
+
+    const dataPageBuffer = chunkBuffer.subarray(
+      dataPageRelativeOffset,
+      dataPageRelativeOffset + dataPageByteLength
+    );
+    const plaintextDataPageBuffer = columnChunk.crypto_metadata
+      ? await this.decryptColumnPages(
+          dataPageBuffer,
+          {
+            type: physicalType,
+            rLevelMax: field.rLevelMax,
+            dLevelMax: field.dLevelMax,
+            compression,
+            column: field
+          },
+          rowGroupOrdinal,
+          columnOrdinal,
+          this.getColumnKeyMetadata(columnChunk)
+        )
+      : dataPageBuffer;
+    const pages = await scanParquetEncodedPages(plaintextDataPageBuffer, context);
+    return Object.freeze({
+      path: Object.freeze([...metadata.path_in_schema]),
+      physicalType,
+      typeLength: field.typeLength,
+      maxRepetitionLevel: field.rLevelMax,
+      maxDefinitionLevel: field.dLevelMax,
+      compression,
+      valueCount: Number(metadata.num_values),
+      dictionary,
+      pages: Object.freeze(pages)
+    });
+  }
+
+  /** Decrypts the length-prefixed page header and data modules in one column chunk. */
+  private async decryptColumnPages(
+    encryptedPages: Uint8Array,
+    context: ParquetReaderContext,
+    rowGroupOrdinal: number,
+    columnOrdinal: number,
+    keyMetadata: Uint8Array | undefined,
+    includesDictionary = false,
+    dataPageOrdinalStart = 0
+  ): Promise<Uint8Array> {
+    if (!this.encryptionContext || !this.props.keyRetriever) {
+      throw new Error('Encrypted Parquet pages require parquet.keyRetriever');
+    }
+    const plaintextPages: Uint8Array[] = [];
+    let offset = 0;
+    let dataPageOrdinal = dataPageOrdinalStart;
+    let pageIndex = 0;
+    while (offset < encryptedPages.length) {
+      const headerModule = readParquetEncryptedModule(encryptedPages, offset);
+      offset = headerModule.nextOffset;
+      const dictionaryPage = includesDictionary && pageIndex === 0;
+      const headerModuleType: ParquetEncryptionModule = dictionaryPage
+        ? 'dictionary-page-header'
+        : 'data-page-header';
+      const headerAad = createParquetModuleAad(
+        this.encryptionContext.aadPrefix,
+        this.encryptionContext.fileUnique,
+        headerModuleType,
+        rowGroupOrdinal,
+        columnOrdinal,
+        dictionaryPage ? undefined : dataPageOrdinal
+      );
+      const headerBytes = await decryptParquetModule(headerModule.bytes, {
+        algorithm: this.encryptionContext.algorithm,
+        aad: headerAad,
+        keyMetadata,
+        keyRetriever: this.getCachedKeyRetriever()
+      });
+      const {pageHeader} = decodePageHeader(headerBytes);
+      const pageType = getThriftEnum(PageType, pageHeader.type);
+      const dataModule = readParquetEncryptedModule(encryptedPages, offset);
+      offset = dataModule.nextOffset;
+      const dataAad = createParquetModuleAad(
+        this.encryptionContext.aadPrefix,
+        this.encryptionContext.fileUnique,
+        dictionaryPage ? 'dictionary-page' : 'data-page',
+        rowGroupOrdinal,
+        columnOrdinal,
+        dictionaryPage ? undefined : dataPageOrdinal
+      );
+      const dataBytes = await decryptParquetModule(dataModule.bytes, {
+        algorithm: this.encryptionContext.algorithm,
+        aad: dataAad,
+        keyMetadata,
+        keyRetriever: this.getCachedKeyRetriever(),
+        page: true
+      });
+      plaintextPages.push(serializeThrift(pageHeader), dataBytes);
+      if (pageType !== 'DICTIONARY_PAGE') dataPageOrdinal++;
+      pageIndex++;
+    }
+    const plaintextLength = plaintextPages.reduce((total, page) => total + page.length, 0);
+    const plaintext = new Uint8Array(plaintextLength);
+    let plaintextOffset = 0;
+    for (const page of plaintextPages) {
+      plaintext.set(page, plaintextOffset);
+      plaintextOffset += page.length;
+    }
+    return plaintext;
+  }
+
+  /** Resolves the key metadata reference for an encrypted column. */
+  private getColumnKeyMetadata(columnChunk: ColumnChunk): Uint8Array | undefined {
+    return (
+      columnChunk.crypto_metadata?.ENCRYPTION_WITH_COLUMN_KEY?.key_metadata ??
+      this.encryptionContext?.footerKeyMetadata ??
+      this.encryptionContext?.footerSigningKeyMetadata
+    );
+  }
+
+  /** Reads and decodes contiguous data pages that begin and end on complete row boundaries. */
   async readColumnChunkRange(
     schema: ParquetSchema,
     columnChunk: ColumnChunk,
     rowRange: ParquetRowRange,
     pages: readonly ParquetDataPageLocation[],
-    signal?: AbortSignal
+    signal?: AbortSignal,
+    rowGroupOrdinal = 0,
+    columnOrdinal = 0,
+    resolvedMetadata?: NonNullable<ColumnChunk['meta_data']>
   ): Promise<ParquetColumnChunk> {
     if (columnChunk.file_path !== undefined && columnChunk.file_path !== null) {
       throw new Error('external references are not supported');
     }
-    const columnMetadata = columnChunk.meta_data!;
-    const field = schema.findField(columnMetadata.path_in_schema);
-    if (field.path.length !== 1 || field.repetitionType === 'REPEATED' || field.rLevelMax !== 0) {
-      throw new Error('Selective Parquet page reads currently require flat primitive columns');
+    const columnMetadata = resolvedMetadata || columnChunk.meta_data;
+    if (!columnMetadata) {
+      throw new Error('Parquet column metadata is missing');
     }
+    const encrypted = Boolean(columnChunk.crypto_metadata);
+    const field = schema.findField(columnMetadata.path_in_schema);
     const type: PrimitiveType = getThriftEnum(Type, columnMetadata.type) as any;
     if (type !== field.primitiveType) {
       throw new Error(`chunk type not matching schema: ${type}`);
@@ -401,39 +1288,102 @@ export class ParquetReader {
     if (!overlappingPages.length) {
       throw new Error('Parquet page plan does not overlap the requested row range');
     }
-    const firstPage = overlappingPages[0];
+    let firstPageIndex = pages.indexOf(overlappingPages[0]);
     const lastPage = overlappingPages[overlappingPages.length - 1];
+    let firstPage = pages[firstPageIndex];
     const context: ParquetReaderContext = {
       type,
       rLevelMax: field.rLevelMax,
       dLevelMax: field.dLevelMax,
       compression,
       column: field,
-      numValues: new CompactInt64(lastPage.endRowIndex - firstPage.firstRowIndex),
+      // Repeated leaves have one level entry per physical value, not one per logical row. Let the
+      // page decoder consume the selected page range and preserve all repetition levels.
+      numValues:
+        field.rLevelMax === 0
+          ? new CompactInt64(lastPage.endRowIndex - firstPage.firstRowIndex)
+          : undefined,
       dictionary: [],
+      decompressPage: this.getPageDecompressor(compression),
       preserveBinary: this.props.preserveBinary,
       retainByteArrayViews: this.props.retainByteArrayViews,
-      useTypedValueBuffers: this.props.useTypedValueBuffers
+      useTypedValueBuffers: this.props.useTypedValueBuffers,
+      useArrowByteArrayBuffers: this.props.useArrowByteArrayBuffers,
+      verifyPageChecksums: this.props.verifyPageChecksums,
+      int96AsTimestamp: this.props.int96AsTimestamp
     };
 
     let dictionary: any[] | undefined;
     const dictionaryPageOffset = Number(columnMetadata.dictionary_page_offset);
     if (Number.isSafeInteger(dictionaryPageOffset) && dictionaryPageOffset > 0) {
       const dictionaryLength = Math.max(0, pages[0].offset - dictionaryPageOffset);
-      const dictionaryBuffer = toUint8Array(
-        await this.file.read(dictionaryPageOffset, dictionaryLength, signal ?? this.props.signal)
-      );
-      dictionary = await decodeDictionaryBuffer(dictionaryBuffer, context);
+      const dictionaryBuffer = await this.readBytes(dictionaryPageOffset, dictionaryLength, signal);
+      const decodedDictionaryBuffer = encrypted
+        ? await this.decryptColumnPages(
+            dictionaryBuffer,
+            context,
+            rowGroupOrdinal,
+            columnOrdinal,
+            this.getColumnKeyMetadata(columnChunk),
+            true
+          )
+        : dictionaryBuffer;
+      dictionary = await decodeDictionaryBuffer(decodedDictionaryBuffer, context);
     }
 
+    if (field.rLevelMax !== 0) {
+      // Probe predecessor pages independently, then decode the final range once. This avoids
+      // quadratic re-decoding when a large repeated row spans many pages.
+      while (firstPageIndex > 0) {
+        const probeBuffer = await this.readBytes(
+          firstPage.offset,
+          firstPage.compressedByteLength,
+          signal
+        );
+        const decodedProbeBuffer = encrypted
+          ? await this.decryptColumnPages(
+              probeBuffer,
+              context,
+              rowGroupOrdinal,
+              columnOrdinal,
+              this.getColumnKeyMetadata(columnChunk),
+              false,
+              firstPageIndex
+            )
+          : probeBuffer;
+        const probe = await decodeDataPages(decodedProbeBuffer, {...context, dictionary});
+        if (probe.rlevels[0] === 0) {
+          break;
+        }
+        firstPage = pages[--firstPageIndex];
+      }
+    }
     const dataLength = lastPage.offset + lastPage.compressedByteLength - firstPage.offset;
-    const dataBuffer = toUint8Array(
-      await this.file.read(firstPage.offset, dataLength, signal ?? this.props.signal)
-    );
-    const decoded = await decodeDataPages(dataBuffer, {...context, dictionary});
+    const dataBuffer = await this.readBytes(firstPage.offset, dataLength, signal);
+    const decodedDataBuffer = encrypted
+      ? await this.decryptColumnPages(
+          dataBuffer,
+          context,
+          rowGroupOrdinal,
+          columnOrdinal,
+          this.getColumnKeyMetadata(columnChunk),
+          false,
+          firstPageIndex
+        )
+      : dataBuffer;
+    const decoded = await decodeDataPages(decodedDataBuffer, {...context, dictionary});
+    if (field.rLevelMax !== 0) {
+      const rowStart = rowRange.start - firstPage.firstRowIndex;
+      return sliceRepeatedColumnChunk(
+        decoded,
+        Math.max(0, rowStart),
+        rowRange.end - rowRange.start,
+        field.dLevelMax
+      );
+    }
     const relativeStart = rowRange.start - firstPage.firstRowIndex;
     const relativeEnd = relativeStart + rowRange.end - rowRange.start;
-    return sliceFlatColumnChunk(decoded, field.dLevelMax, relativeStart, relativeEnd);
+    return sliceNonRepeatedColumnChunk(decoded, field.dLevelMax, relativeStart, relativeEnd);
   }
 
   /**
@@ -465,16 +1415,59 @@ export class ParquetReader {
       this.file.size - dictionaryPageOffset,
       this.props.defaultDictionarySize
     );
-    const arrayBuffer = await this.file.read(
-      dictionaryPageOffset,
-      dictionarySize,
-      signal ?? this.props.signal
-    );
-    const pagesBuf = toUint8Array(arrayBuffer);
+    const pagesBuf = await this.readBytes(dictionaryPageOffset, dictionarySize, signal);
     return await decodeDictionaryBuffer(pagesBuf, context);
   }
 }
 
+/** Returns a column path available without decrypting column metadata when possible. */
+function getColumnChunkPath(columnChunk: ColumnChunk): string[] | undefined {
+  return (
+    columnChunk.meta_data?.path_in_schema ??
+    columnChunk.crypto_metadata?.ENCRYPTION_WITH_COLUMN_KEY?.path_in_schema
+  );
+}
+
+/** Builds a stable cache key while preserving module scope for context-dependent key providers. */
+function createEncryptionKeyCacheKey(
+  algorithm: ParquetEncryptionAlgorithm,
+  keyMetadata: Uint8Array | undefined,
+  aad: Uint8Array,
+  aadPrefixByteLength: number | undefined,
+  fileUniqueByteLength: number | undefined
+): string {
+  const metadataKey = keyMetadata ? Array.from(keyMetadata).join(',') : 'footer';
+  if (fileUniqueByteLength === undefined) {
+    return `${algorithm}:${metadataKey}:aad:${Array.from(aad).join(',')}`;
+  }
+
+  const moduleOffset = (aadPrefixByteLength ?? 0) + fileUniqueByteLength;
+  if (moduleOffset + 5 > aad.byteLength) {
+    return `${algorithm}:${metadataKey}:aad:${Array.from(aad).join(',')}`;
+  }
+
+  const moduleType = aad[moduleOffset];
+  if (moduleType === 0) {
+    return `${algorithm}:${metadataKey}:footer`;
+  }
+  const view = new DataView(
+    aad.buffer,
+    aad.byteOffset + moduleOffset,
+    aad.byteLength - moduleOffset
+  );
+  const rowGroupOrdinal = view.getInt16(1, true);
+  const columnOrdinal = view.getInt16(3, true);
+  return `${algorithm}:${metadataKey}:module:${moduleType}:row-group:${rowGroupOrdinal}:column:${columnOrdinal}`;
+}
+
+/** Returns the original row-group ordinal for a worker-reduced column list. */
+function getPhysicalColumnOrdinal(columnChunk: ColumnChunk, fallbackOrdinal: number): number {
+  return (
+    (columnChunk as ColumnChunk & {parquetColumnOrdinal?: number}).parquetColumnOrdinal ??
+    fallbackOrdinal
+  );
+}
+
 /** Decodes one dictionary page from an already-read column-chunk range. */
 async function decodeDictionaryBuffer(
   dictionaryBuffer: Uint8Array,
@@ -485,8 +1478,8 @@ async function decodeDictionaryBuffer(
   return decodedPage.dictionary!;
 }
 
-/** Slices one decoded flat column chunk while preserving optional-value alignment. */
-function sliceFlatColumnChunk(
+/** Slices one decoded non-repeated column chunk while preserving optional-value alignment. */
+function sliceNonRepeatedColumnChunk(
   columnChunk: ParquetColumnChunk,
   definitionLevelMaximum: number,
   start: number,
@@ -504,7 +1497,39 @@ function sliceFlatColumnChunk(
   };
 }
 
-/** Counts defined primitive values represented by one flat level interval. */
+/** Slices a repeated column by logical rows while preserving its level/value alignment. */
+function sliceRepeatedColumnChunk(
+  columnChunk: ParquetColumnChunk,
+  rowStart: number,
+  rowCount: number,
+  definitionLevelMaximum: number
+): ParquetColumnChunk {
+  const rowStarts: number[] = [];
+  for (let levelIndex = 0; levelIndex < columnChunk.rlevels.length; levelIndex++) {
+    if (columnChunk.rlevels[levelIndex] === 0) {
+      rowStarts.push(levelIndex);
+    }
+  }
+  const levelStart = rowStarts[rowStart];
+  const endRow = rowStart + rowCount;
+  const levelEnd = rowStarts[endRow] ?? columnChunk.rlevels.length;
+  if (levelStart === undefined || endRow > rowStarts.length || levelEnd < levelStart) {
+    throw new Error('Parquet repeated page range does not contain the requested rows');
+  }
+  const valueStart = countDefinedValues(columnChunk.dlevels, definitionLevelMaximum, 0, levelStart);
+  const valueEnd =
+    valueStart +
+    countDefinedValues(columnChunk.dlevels, definitionLevelMaximum, levelStart, levelEnd);
+  return {
+    rlevels: columnChunk.rlevels.slice(levelStart, levelEnd),
+    dlevels: columnChunk.dlevels.slice(levelStart, levelEnd),
+    values: columnChunk.values.slice(valueStart, valueEnd) as typeof columnChunk.values,
+    count: levelEnd - levelStart,
+    pageHeaders: columnChunk.pageHeaders
+  };
+}
+
+/** Counts defined primitive values represented by one non-repeated level interval. */
 function countDefinedValues(
   definitionLevels: ParquetLevelBuffer,
   definitionLevelMaximum: number,