Columnar / Parquet / Parser

The reader behind the tools.

A TypeScript Parquet reader for browsers and Node, with metadata inspection, column decoding and nested record assembly.

This library is proprietary and is not currently distributed on npm. The examples below document its API for authorized users; there is no public installation command.

Try it in the explorer →Understand the format

Read a file in memory

Use ParquetReader when you already have an ArrayBuffer. Initialize the codecs your file needs before decoding compressed data.

import { ParquetReader, initCompression, initZstd } from 'parquet-ts';

await initCompression();
await initZstd(); // when reading Zstandard-compressed files

const reader = ParquetReader.fromArrayBuffer(buffer);
const schema = reader.getSchema();
const records = reader.readRecords();

Read ranges on demand

AsyncParquetReader accepts a File, Blob, ArrayBuffer, or a custom ByteSource with size and read(offset, length). It opens from the file's tail, then fetches requested chunks and indexes.

import { AsyncParquetReader, columnToArray } from 'parquet-ts';

const reader = await AsyncParquetReader.open(file);
const metadata = reader.getMetadata();
const path = reader.getSchema().columns[0].path;
const column = await reader.readColumn(path, { rowGroups: [0] });
const values = columnToArray(column);
const bytesRead = reader.getBytesRead();

Codec initialization is also required for compressed async reads. Opening may read more than the footer alone. Decoding requires memory for the selected chunk; reading all records still materializes the result. The explorer adds a worker around this API to keep decoding off the UI thread.

Values and column paths

readColumn returns physical values and definition/repetition levels. Use columnToArray to include null positions. readRecords assembles nested records and applies logical types.

Logical type	Record value
STRING, ENUM, JSON	string; JSON is not parsed into an object
DATE, TIMESTAMP, INT96	Date; timestamps lose sub-millisecond precision, with bigint milliseconds outside the Date range
DECIMAL	Decimal string, preserving precision
INT64 / unsigned 64-bit INTEGER	bigint
LIST / MAP / struct	Array / Map / object with no prototype
Unannotated binary	Uint8Array

Use array paths to distinguish a literal dotted field ['a.b'] from a nested field ['a', 'b']. Records preserve both. The convenience readColumns object throws on colliding dot-joined keys. Use Object.hasOwn and Object.entries on records instead of inherited object methods.

Inspection APIs

getMetadata and getSchema: footer metadata and the schema tree.
getColumnPages: page headers and bytes for encoding inspection.
getColumnIndex and getOffsetIndex: page indexes, when written.
getRowGroupStatistics: statistics subject to type and writer trust rules.
canSkipRowGroup: whether trusted statistics prove a predicate cannot match. Missing statistics do not prove a group is skippable.

Supported features and limits

Data pages V1 and V2; plain, dictionary, RLE, delta and byte-stream-split encodings; nested lists, maps and structs. Compression support includes Snappy, Gzip, LZ4, LZ4_RAW and opt-in Zstandard.

Split-block Bloom filters can be inspected and probed through the library; equality scan exclusion is opt-in and still checks rows after positive probes. Brotli, LZO, encrypted data and external column chunks are unsupported. Malformed and unsupported input is reported through ParquetError.

This is an educational reader with cross-writer fixture and malformed-input tests. The supported surface is bounded; it is not a substitute for validating your workload against an established reader.