YAML を NDJSON に変換

NDJSON は改行についての決まりを持つ JSON です。1 行につき値がひとつ、カンマなし、囲む括弧なし。それを作るには、どこかで一つのレコードが終わり次が始まるかを決めなければならず、YAML ファイルの中でそれを言えるのはトップレベルのシーケンスだけです。ハイフンで始まるリストで始まる文書なら、ハイフン一つにつき一行に変換されます。

それ以外はすべて一行になります。ルートにあるマッピングは、中にどれだけ入れ子があっても一つの値でしかないので、Kubernetes のマニフェストや compose ファイル、アプリケーションの設定は数キロバイトの一行として出てきます。これは失敗ではなく、たいていは変換した人が望んだ結果でもありません。だからこそ後付けの注意書きではなく、このページの最初に書いています。

欲しいレコードがキーの下にネストされている場合 ── users というキーがリストを持つ、events というキーがリストを持つ ── この変換は中に手を伸ばしてそれを見つけたりはしません。見るのはルートだけです。直し方はそのリストを変換の前に文書のトップに持ち上げることで、エディタでは最初の行を削除して残りのインデントを外すだけです。

代わりの方法は JSON に変換して jq を使い、抽出とストリーム化を両方こなすことです。配列を取り出して一要素ずつ出力するのは一つの式で済みます。この抽出を繰り返すつもりならスクリプト化できるそちらのほうが良く、一度きりならこの変換ツールのほうが良い選択です。

YAML のアンカーは一つのブロックを一度定義して何度も参照できるようにするもので、パーサーは何かに書き出す前にすべてのエイリアスを完全なコピーへと展開します。だから NDJSON は YAML より大きくなり、場合によってはかなり大きくなります。

ストリームにとってこれはコストではなく要件です。NDJSON を読む側は一行ずつ読み、他の行を見たことがないかもしれません ── それがこの形式の全部で、そのおかげでローダーはファイルを複数のワーカーに分割したり、失敗のあとに再開したりできます。前の行の定義を参照する一行は、この形式が生き延びるために存在する条件そのものの下で壊れてしまいます。重複を減らす作業はロードの後に回すべきで、ファイルの中でやることではありません。

`---` 区切りの YAML ストリームは、概念としてはすでに NDJSON です。1 文書 1 レコードが順番に並んでいます。この一群のフォーマットの中でいちばん構造的に近いものであり、この変換が拒否するただ一つの入力でもあります。パーサーが一つの文書だけを読み、二つ目を見つけると止まってしまうからです。

回避策はツールではなくテキストの編集です。それぞれの `---` をトップレベルのリスト項目のマーカーに置き換え、その下に文書をインデントすれば、まさに期待していたストリームに変換されます。大きなファイルなら sed のワンライナーで、少数の文書ならエディタでも十分です。これはこのパイプラインに欠けている機能であって、どちらの形式の限界でもないと言っておく価値があります。

NDJSON は 2013 年ごろから行指向のツール群の交換形式であり続けていて、行き先によって微妙に求めるものが違います。BigQuery と Snowflake は改行区切りの JSON をそのままロード形式として受け取ります。jq はフラグなしで読み、compact オプションで書き戻します。pandas は lines 引数で読みます。どれもこの出力をそのまま消費できます。

つまずきやすいのは Elasticsearch です。その bulk API は NDJSON の形をしていますが、各文書の前にアクション行を求めるので、普通のレコードだけのファイルは拒否されます。アクション行を挟み込むのは jq や awk の一手間で、これは意図的にここでは行っていません。アクション行はインデックス名や操作を指定するもので、それを知っているのはあなただけだからです。

それぞれの行はコンパクトな JSON です。インデントなし、コロンの後の空白なし、キーは YAML にあった順序のまま。ファイルは UTF-8 で、最後の行も改行で終わります。多くのローダーがそれを要求し、一部は黙って許容します。

値の型は書き出す側ではなく YAML のパーサーから決まります。YAML 1.2 の下では引用符なしの日付は文字列のままなので、日付フィールドはスキーマのヒントなしにローダーがタイムスタンプと認識するものではなく、テキストとして出てきます。大きな整数は静かに危険を招きます。9223372036854775807 と書かれた識別子は 9223372036854776000 として出てきます。JSON の数値が IEEE の倍精度浮動小数点数だからです。変換する前に YAML の中でそれらを引用符で囲めば文字列として渡り、それが識別子として本来あるべき姿です。

項目どうしがキーを共有していないリストも文句を言わずに変換され、各行はそのレコードが持っていたキーだけを運びます。これは同じデータを CSV に変換する場合と比べての実際の利点です。CSV では列はすべてのレコードの和集合でなければならず、欠けたセルは何かで埋めなければなりません。

行き先が同じくらい寛容かどうかは別の問題です。スキーマオンリードのストアはでこぼこした行を喜んで受け取りますが、固定スキーマのテーブルローダーは想定外のフィールドを拒否するか null にします。この変換は YAML が言っていたことをそのまま保ちますし、大きな出力の最初と最後の数行を見て、形がファイル全体でどれだけずれているかを確かめる価値があります。

YAML のコメントは失われ、NDJSON にはそれを置く場所がありません。1 行につき JSON がひとつで、JSON にはコメントの構文がないからです。ヘッダー行もスキーマの宣言もメタデータのブロックもなく、ファイルはレコードだけを運びます。

その欠如はフォーマットとして意図的で、パイプライン側でも尊重する価値があります。ロード処理がソースやバッチの識別子、スキーマのバージョンを知る必要があるなら、それはすべてのレコードの一フィールドか、ファイル名の中に入れてください。前置きの中には入れないことです。NDJSON ファイルの先頭にあるものは何であれレコードとして読まれ、ローダーはそれをレコードとして読もうとします。

その YAML がデータではなく設定であるなら、この変換は何も提供しません。ミニファイされた JSON の一行は、人が気にするあらゆる点で YAML より劣り、どんなストリームの読み手もその設定ファイルを欲しがりません。機械可読にする必要があるなら JSON に変換し、必要がないなら YAML のままにしてください。

この組み合わせが役立つのは、そのファイルが本当にリストであるとき ── エクスポートされたレコード、フィクスチャ、人が手で書いたイベントログ、シードデータ ── で、行き先が行を読むときです。その場合は変換は一瞬で、すべてブラウザーの中で完結し、確かめるべきなのは最初の行と最後の行だけです。