ml-explore / ml-explore/mlx-data

Parquet as a stream source: Python-level, or native alongside CSVReader/JSONLReader?

Open
#114 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
C++
Stars
483
Forks
62
PR merge metrics
No merged PRs in 30d

Description

mlx-data reads CSV, JSONL and text, and fetches from S3, but has no Parquet support and no prior issue about it. Parquet is where most tabular training data now lives (it is the format under Iceberg and Delta). Today you either convert to JSONL first — losing the column projection that makes Parquet worth using — or build the stream outside mlx-data and lose the pipeline ops.

I would like to contribute this. Two shapes, and I would rather agree on which before writing it.

A lazy Parquet stream already works with no changes to mlx-data:

def samples(path, columns=None, batch_size=1024):
    for batch in pq.ParquetFile(path).iter_batches(batch_size, columns=columns):
        for row in batch.to_pylist():
            yield {k: v.encode() if isinstance(v, str) else v
                   for k, v in row.items() if v is not None}

dset = dx.stream_python_iterable(lambda: samples("data.parquet"))

Option 1 — dx.stream_parquet_reader(...) in python/mlx/data/, wrapping the above. Small, and the dependency lands only on Python (pyarrow, an optional extra), never on the C++ core. Cost: to_pylist() builds a Python object per value and holds the GIL, so throughput is well below native and it interacts badly with prefetch.

Option 2 — a native mlx/data/stream/ParquetReader beside CSVReader and JSONLReader, via Arrow C++, producing Arrays with no Python objects in the path. Arrow does the format work, so it should be in the range of CSVReader (243 lines) and JSONLReader (588).

The ask: which option, and for option 2, is an optional Arrow C++ dependency behind MLX_HAS_PARQUET acceptable? I am happy to start with option 1 regardless, with correctness tests for the cases Parquet gets silently wrong rather than loudly — required columns carrying no definition-level data, encoding differing per row group within one file, "no dictionary page" not implying PLAIN, BYTE_ARRAY that is not UTF-8.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reading the existing CSVReader and JSONLReader implementations alongside python/mlx/data/. Compare the proposed Python iterable and native Arrow C++ paths, including their dependency and performance tradeoffs. Done means maintainers have chosen an approach and the implementation includes correctness tests for the listed Parquet edge cases.

Written by the indexing model from the issue text.

Assessment

Tech stack
cpp, python
Domain
data-engineering
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.