Parquet を JSON に変換

Parquet はデータ基盤が渡してくるもので、JSON はそれ以外のほとんどすべてが受け取れるものです。テストの隣に置くフィクスチャー、モック API 用の種データ、エンドポイントが拒否する理由を調べるためにリクエストへ貼り付ける本文、DuckDB を入れずに JSON ビューアーで眺めたい数十行——この変換はそのすき間を埋めます。

対象は小さいものに限ります。Parquet は巨大な表を安く問い合わせるための形式で、列指向の配置も圧縮も、行グループを丸ごと読み飛ばすための統計情報も、この変換では何一つ引き継がれません。テキスト文書として妥当なのは百行程度までで、数百万行には向きません。

ファイルは行の集まりに戻され、2 スペースの字下げをつけたトップレベルの JSON 配列として書かれます。列名はスキーマの綴りのままキーになります。

包む要素も付随するメタデータもありません。行を名前付きのキーの下に入れたいなら `jq '{rows: .}'` を一段挟んでください。配列の長さがそのまま行数なので、抽出データが期待どおりの件数かを最初に確認する手がかりにもなります。

ここがこのページでいちばん驚かれる点です。Parquet の LIST、STRUCT、MAP はいったん JavaScript のオブジェクトとして読まれたあと、文字列に変換されてフィールドに置かれます。2 個の値を持つ `tags` 列は `["a","b"]` にはならず、引用符付きの `"[\"a\",\"b\"]"` になります。

何も失われてはいませんが、一段よけいな手間が必要です。`jq '.[0].tags[0]'` は文字列に添字がないというエラーを返し、`jq '.[0].tags | fromjson | .[0]'` なら正しい値を返します。テストのフィクスチャーに使うなら `jq 'map(.tags |= fromjson)'` で一度だけ展開してから、構造化された版をコミットしておくのが誠実です。

Parquet の日時列は単位とタイムゾーンの旗を footer に持つ整数型ですが、JSON には日付型がないため、それぞれの値は `2026-03-01T08:00:00.000Z` のような ISO 8601 の文字列で書かれます。辞書順に正しくソートでき、`Date.parse` や `datetime.fromisoformat` にもそのまま渡せます。

消えるのは「これは日時である」という宣言そのものです。フィクスチャー用途ならこれで十分ですが、読み込み先に渡すときはタイムゾーンを取り違えないよう、日付として扱うことをあらためて指定する必要があります。

Parquet の 64 ビット整数は JavaScript の数値が正確に表せる 53 ビットを超えることがあります。収まらない値は静かに丸められるのではなく、引用符付きの文字列として書かれます。収まる値はそのまま数値です。

この判断は正しい方向です。1 ずれた注文番号はなかなか気づかれないバグになりますが、あるときは数値であるときは文字列になる列は少なくとも目に見えます。厳格な JSON スキーマがこれを嫌うなら、抽出元のクエリで列全体をテキストにキャストしておいてください。

UTF8 の注釈を持たない Parquet の `BYTE_ARRAY` はテキストではなくバイト列で、JSON に忠実な表現がありません。それぞれの値は小文字の 16 進文字列として書かれ、1 バイトにつき 2 文字、区切りも接頭辞もありません。

16 進表現は可逆で、明らかに文章ではないとわかるのが利点です。ただしバイト数の 2 倍の大きさになるので、大きなバイナリ列で必要のないものは、変換前のクエリで除いておくほうが賢明です。ハッシュ列なら問題ありませんが、埋め込みサムネイル列はそうはいきません。

Parquet の欠損値は JSON の `null` になり、空文字とも 0 とも区別されます。これは区切りテキストの出力先と比べると際立った特徴で、そちらでは null も空文字も 2 つの区切り記号の間に何もない状態に潰れ、あとから見分けがつきません。

フィクスチャーにとってこの違いはすべてです。値の欠如を主張するテストには、欠如を表現できる形式が要り、この変換群の中でそれができるのは JSON だけです。

3 つの方向から一気に膨らみます。Parquet は各列を型付きで一度だけ持ち、繰り返し値を辞書化してページを圧縮しますが、JSON はすべての行で列名を繰り返し、数値を十進の桁として書き、この出力はさらにフィールドごとに改行を入れます。

割合ではなく桁の変化として見込んでください。表が横に広く値が繰り返す場合はさらに大きくなります——5 種類の文字列しか持たないステータス列は Parquet ではほぼゼロコストですが、JSON では全行にフルの長さで現れます。文書全体を 1 個の文字列として組み立ててから保存するため、無料の上限 100 MB より先にメモリーの限界に達することがあります。抽出時に `LIMIT` を付けるほうが安全です。

ファイルを自己記述的にしていた footer は引き継がれません。列名はキーとして残りますが、宣言された型もヌル許容も圧縮方式も行グループの統計も、書き手が残したキーバリューのメタデータも消えます。

DuckDB があれば `DESCRIBE SELECT * FROM 'file.parquet'` を一行実行するだけでスキーマが分かり、どの列が INT64 でどの列が DOUBLE だったかを知っておくと、JSON の中の見慣れない表現の多くが説明できます。ない場合は、まず数行だけ変換して読んでみてください。引用符付きの整数、ISO文字列、エスケープされたネスト列がそれぞれ元の型を語ってくれます。

JavaScript で書かれた Parquet の読み込み処理が初回の変換時に読み込まれ、そのあとの作業はすべてこのタブの中で行われます。ファイル自体はどこにも送られず、ネットワークタブを見ればエンジンの取得だけが起きて、ファイルの送信は起きていないことが確認できます。

この区別は、Parquet が倉庫由来の成果物であるだけに、他の形式より重みを持ちます。この拡張子を持つファイルは、顧客、注文、イベント、給与といった本番テーブルの抽出であることが多く、アップロードすれば報告が必要になるような由来を持っています。ここではその報告自体が不要です。