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

package/dist/parquetjs/parser/parquet-reader.js

@@ -4,15 +4,46 @@
 // Copyright (c) 2017 ironSource Ltd.
 // Forked from https://github.com/kbajalc/parquets under MIT license
 import { ParquetSchema } from "../schema/schema.js";
-import { decodeSchema, decodeDataPages, decodePage } from "./decoders.js";
+import { decodeSchema, decodeDataPages, decodePage, decodeUncompressedDataPages, decodeUncompressedDictionaryBuffer } from "./decoders.js";
+import { scanParquetEncodedPages } from "./encoded-pages.js";
 import { materializeRows } from "../schema/shred.js";
+import { createParquetPageDecompressor } from "../compression.js";
 import { PARQUET_MAGIC, PARQUET_MAGIC_ENCRYPTED } from "../../lib/constants.js";
-import { CompressionCodec, Type } from "../parquet-thrift/index.js";
-import { decodeFileMetadata, getThriftEnum, fieldIndexOf } from "../utils/read-utils.js";
+import { CompressionCodec, Encoding, PageType, Type } from "../parquet-thrift/index.js";
+import { decodeColumnMetadata, decodeFileCryptoMetadata, decodeFileMetadata, decodePageHeader, getThriftEnum, fieldIndexOf, serializeThrift } from "../utils/read-utils.js";
 import { decodeString, readUInt32LE, toUint8Array } from "../utils/binary-utils.js";
 import { CompactInt64 } from "../utils/uint8-array-compact-protocol.js";
+import { createParquetModuleAad, decryptParquetModule, readParquetEncryptedModule, verifyParquetFooterSignature } from "../../lib/parquet-encryption.js";
 /** 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, dictionaryPageOffset) {
+    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) {
+    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');
+}
 /**
  * The parquet envelope reader allows direct, unbuffered access to the individual
  * sections of the parquet file, namely the header, footer and the row groups.
@@ -27,21 +58,114 @@ export class ParquetReader {
         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;
     file;
     metadata = null;
     /** Parsed Parquet schema shared by metadata, iteration, and materialization paths. */
     schema = null;
+    /** Encryption parameters decoded from plaintext or encrypted footer metadata. */
+    encryptionContext;
+    /** Resolved keys shared by encrypted modules in this reader instance. */
+    encryptionKeyCache = new Map();
+    /** Compression backends selected once and shared by every page in this reader. */
+    pageDecompressors = new Map();
     constructor(file, props) {
         this.file = file;
         this.props = { ...ParquetReader.defaultProps, ...props };
+        this.encryptionContext = this.props.encryptionContext;
+    }
+    /** Whether the decoded footer describes an encrypted Parquet file. */
+    get encrypted() {
+        return Boolean(this.encryptionContext);
+    }
+    /** Whether this reader decodes legacy INT96 values as epoch nanoseconds. */
+    get int96AsTimestamp() {
+        return this.props.int96AsTimestamp;
+    }
+    /** Returns a cloneable snapshot of the file encryption context for worker decoding. */
+    getEncryptionContextForWorker() {
+        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, rowGroupOrdinal, columnOrdinal) {
+        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() {
+        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. */
+    getPageDecompressor(compression) {
+        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. */
+    async readBytes(start, length, signal) {
+        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. */
+    getCachedKeyRetriever() {
+        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 */
     async *rowIterator(props) {
@@ -71,7 +195,7 @@ export class ParquetReader {
             if (!Number.isInteger(rowGroupIndex) || rowGroupIndex < 0 || rowGroupIndex >= rowGroupCount) {
                 throw new Error(`Invalid Parquet row-group index ${rowGroupIndex}`);
             }
-            const rowGroup = await this.readRowGroup(schema, metadata.row_groups[rowGroupIndex], columnList, props?.signal);
+            const rowGroup = await this.readRowGroup(schema, metadata.row_groups[rowGroupIndex], columnList, props?.signal, rowGroupIndex);
             yield rowGroup;
         }
     }
@@ -109,13 +233,12 @@ export class ParquetReader {
     // LOW LEVEL METHODS
     /** Metadata is stored in the footer */
     async readHeader(signal) {
-        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})`);
         }
@@ -123,37 +246,234 @@ export class ParquetReader {
     /** Metadata is stored in the footer */
     async readFooter(signal) {
         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;
     }
-    /** Data is stored in row groups (similar to Apache Arrow record batches) */
-    async readRowGroup(schema, rowGroup, columnList, signal) {
-        const selectedColumnChunks = rowGroup.columns.filter(columnChunk => {
-            const columnKey = columnChunk.meta_data?.path_in_schema;
-            return columnList.length === 0 || fieldIndexOf(columnList, columnKey) >= 0;
+    /** Reads and decrypts an encrypted footer after the standard trailer. */
+    async readEncryptedFooter(metadataSize, metadataOffset, signal) {
+        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. */
+    setEncryptionContext(metadata) {
+        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, rowGroupOrdinal, selectedColumnPaths) {
+        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, module, rowGroupOrdinal, columnOrdinal, columnChunk) {
+        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, rowGroupOrdinal, columnOrdinal, columnChunk) {
+        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. */
+    async getColumnMetadata(columnChunk, rowGroupOrdinal, columnOrdinal) {
+        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;
+    }
+    /** Data is stored in row groups (similar to Apache Arrow record batches) */
+    async readRowGroup(schema, rowGroup, columnList, signal, rowGroupOrdinal = 0) {
+        await this.resolveColumnMetadata(rowGroup, rowGroupOrdinal, columnList);
+        const selectedColumnChunks = [];
+        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 = [];
         for (let batchStart = 0; batchStart < selectedColumnChunks.length; batchStart += MAXIMUM_CONCURRENT_COLUMN_READS) {
             const columnBatch = selectedColumnChunks.slice(batchStart, batchStart + MAXIMUM_CONCURRENT_COLUMN_READS);
-            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];
+            columnEntries.push(...(await Promise.all(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)
+                    ];
+                }
+                return this.readColumnChunk(schema, columnChunk, signal, rowGroupOrdinal, columnOrdinal, metadata).then(columnData => [columnKey, columnData]);
             }))));
         }
         return {
@@ -161,19 +481,66 @@ export class ParquetReader {
             columnData: Object.fromEntries(columnEntries)
         };
     }
-    /** Reads independently materializable flat columns for one logical row range using page indexes. */
-    async readRowGroupRange(schema, rowGroup, columnList, rowRange, pageLocations, signal) {
-        const selectedColumnChunks = rowGroup.columns.filter(columnChunk => {
-            const columnKey = columnChunk.meta_data?.path_in_schema;
-            return columnList.length === 0 || fieldIndexOf(columnList, columnKey) >= 0;
-        });
-        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('.')];
+    /**
+     * 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, rowGroup, columnList, preserveCompression, signal, rowGroupOrdinal = 0) {
+        await this.resolveColumnMetadata(rowGroup, rowGroupOrdinal, columnList);
+        const selectedColumnChunks = [];
+        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 = [];
+        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, rowGroup, columnList, rowRange, pageLocations, signal, rowGroupOrdinal = 0) {
+        await this.resolveColumnMetadata(rowGroup, rowGroupOrdinal, columnList);
+        const selectedColumnChunks = [];
+        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, 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}`);
             }
-            const columnData = await this.readColumnChunkRange(schema, columnChunk, rowRange, pages, signal);
+            const columnData = await this.readColumnChunkRange(schema, columnChunk, rowRange, pages, signal, rowGroupOrdinal, columnOrdinal, metadata);
             return [columnKey, columnData];
         }));
         return {
@@ -184,26 +551,80 @@ export class ParquetReader {
     /**
      * Each row group contains column chunks for all the columns.
      */
-    async readColumnChunk(schema, colChunk, signal) {
+    readUncompressedColumnChunkFromMemory(schema, columnChunk, metadata) {
+        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 = getThriftEnum(Type, metadata.type);
+        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 = {
+            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;
+        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, colChunk, signal, rowGroupOrdinal = 0, columnOrdinal = 0, resolvedMetadata) {
         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 = getThriftEnum(Type, colChunk.meta_data?.type);
+        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 = getThriftEnum(Type, metadata.type);
         if (type !== field.primitiveType) {
             throw new Error(`chunk type not matching schema: ${type}`);
         }
-        const compression = getThriftEnum(CompressionCodec, colChunk.meta_data?.codec);
-        const pagesOffset = Number(colChunk.meta_data?.data_page_offset);
-        const dictionaryPageOffset = colChunk.meta_data?.dictionary_page_offset;
+        const compression = getThriftEnum(CompressionCodec, metadata.codec);
+        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, Math.max(0, chunkEnd - pagesOffset));
         const context = {
@@ -212,35 +633,174 @@ 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;
         if (validDictionaryPageOffset !== undefined) {
             const dictionaryRelativeOffset = validDictionaryPageOffset - chunkOffset;
             const dictionarySize = Math.min(Math.max(0, pagesOffset - validDictionaryPageOffset), chunkBuffer.length - dictionaryRelativeOffset, this.props.defaultDictionarySize);
             const dictionaryBuffer = chunkBuffer.subarray(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. */
-    async readColumnChunkRange(schema, columnChunk, rowRange, pages, signal) {
+    /** Reads one column chunk as encoded dictionaries, levels, and values for deferred decoding. */
+    async readColumnChunkEncodedPages(schema, columnChunk, preserveCompression, signal, rowGroupOrdinal = 0, columnOrdinal = 0, resolvedMetadata) {
         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 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 = getThriftEnum(Type, metadata.type);
+        if (physicalType !== field.primitiveType) {
+            throw new Error(`chunk type not matching schema: ${physicalType}`);
+        }
+        const compression = getThriftEnum(CompressionCodec, metadata.codec);
+        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. */
+    async decryptColumnPages(encryptedPages, context, rowGroupOrdinal, columnOrdinal, keyMetadata, includesDictionary = false, dataPageOrdinalStart = 0) {
+        if (!this.encryptionContext || !this.props.keyRetriever) {
+            throw new Error('Encrypted Parquet pages require parquet.keyRetriever');
+        }
+        const plaintextPages = [];
+        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 = 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. */
+    getColumnKeyMetadata(columnChunk) {
+        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, columnChunk, rowRange, pages, signal, rowGroupOrdinal = 0, columnOrdinal = 0, resolvedMetadata) {
+        if (columnChunk.file_path !== undefined && columnChunk.file_path !== null) {
+            throw new Error('external references are not supported');
+        }
+        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 = getThriftEnum(Type, columnMetadata.type);
         if (type !== field.primitiveType) {
             throw new Error(`chunk type not matching schema: ${type}`);
@@ -250,33 +810,67 @@ 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 = {
             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;
         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);
     }
     /**
      * Getting dictionary for allows to flatten values by indices.
@@ -296,19 +890,47 @@ export class ParquetReader {
             return [];
         }
         const dictionarySize = Math.min(Math.max(0, pagesOffset - dictionaryPageOffset), 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) {
+    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, keyMetadata, aad, aadPrefixByteLength, fileUniqueByteLength) {
+    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, fallbackOrdinal) {
+    return (columnChunk.parquetColumnOrdinal ??
+        fallbackOrdinal);
+}
 /** Decodes one dictionary page from an already-read column-chunk range. */
 async function decodeDictionaryBuffer(dictionaryBuffer, context) {
     const cursor = { buffer: dictionaryBuffer, offset: 0, size: dictionaryBuffer.length };
     const decodedPage = await decodePage(cursor, context);
     return decodedPage.dictionary;
 }
-/** Slices one decoded flat column chunk while preserving optional-value alignment. */
-function sliceFlatColumnChunk(columnChunk, definitionLevelMaximum, start, end) {
+/** Slices one decoded non-repeated column chunk while preserving optional-value alignment. */
+function sliceNonRepeatedColumnChunk(columnChunk, definitionLevelMaximum, start, end) {
     const valueStart = countDefinedValues(columnChunk.dlevels, definitionLevelMaximum, 0, start);
     const valueEnd = valueStart + countDefinedValues(columnChunk.dlevels, definitionLevelMaximum, start, end);
     return {
@@ -319,7 +941,32 @@ function sliceFlatColumnChunk(columnChunk, definitionLevelMaximum, start, end) {
         pageHeaders: columnChunk.pageHeaders
     };
 }
-/** 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, rowStart, rowCount, definitionLevelMaximum) {
+    const rowStarts = [];
+    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),
+        count: levelEnd - levelStart,
+        pageHeaders: columnChunk.pageHeaders
+    };
+}
+/** Counts defined primitive values represented by one non-repeated level interval. */
 function countDefinedValues(definitionLevels, definitionLevelMaximum, start, end) {
     let count = 0;
     for (let index = start; index < Math.min(end, definitionLevels.length); index++) {