NDJSONとは？ストリーミングレコード、構文、およびユースケース

Scrapeless Scraping APIは、独立したレコードが行指向のストリーミングまたはストレージを必要とする場合に、ダウンストリームパイプラインがNDJSONとして構成できる構造化されたJSONを返します。

NDJSONとは何ですか？

NDJSONは、改行文字で区切られたJSON値のシーケンスのためのテキストフォーマットです。各物理行には、1つの完全なJSONテキストが含まれています。消費者は行を読み込み、その行をJSONとして解析し、得られた値を処理し、次のレコードに移動します。

申し訳ありませんが、そのテキストは提供されていません。テキストを教えていただければ、翻訳いたします。 NDJSON仕様 各JSONテキストはJSONルールに準拠する必要があり、改行で終わる必要があります。UTF-8を指定し、解析のためにLFおよびCRLFを行区切りとして受け入れ、推奨しています。 application/x-ndjson with the .ndjson 拡張。

NDJSONはJSONに関するフレーミング規則であり、新しいオブジェクトモデルではありません。一行には技術的には任意のJSON値を含むことができますが、ログ、大量取り込み、エクスポート、およびデータパイプラインにおいては1行あたり1オブジェクトというパターンが支配的です。JSON文法は以下によって定義されたもののままです。 RFC 8259.

NDJSONファイルはどのようなものですか？

製品観測ストリームには、3つの独立したレコードが含まれている可能性があります：

{"sku":"A-17","price":34.5,"currency":"USD"}
{"sku":"B-08","price":28,"currency":"USD"}
{"sku":"C-31","price":null,"currency":"EUR"}

開いている配列の角括弧、レコード間のカンマ、または閉じる角括弧はありません。各行は独自に解析できます。最終行は、テキストビューアが最終デリミタを常に表示しない場合でも、NDJSONシリアル化ルールに従って改行で終わる必要があります。

整形されたJSONは、一つのNDJSONレコードとしては機能しません。なぜなら、インデントが値を複数の物理行に書き込むからです。プロデューサーは各値をコンパクト形式でシリアライズするべきです。論理行ブレークを含む文字列は、JSONがそれをエスケープするため、有効のままです：

{"id":41,"message":"first line\nsecond line"}

2つの文字バックスラッシュと n JSON文字列内に留まる。JSONパーサーは、レコードフレーミングが成功した後にラインブレーク文字を再構築します。

NDJSONとJSON配列

なぜNDJSONはストリーミングに適しているのか

標準JSONは、2つの隣接するトップレベルの値の間の境界を定義していません。書き込みは {}{} パーサーを標準セパレーターなしに残します。NDJSONはその役割を改行に割り当てます。リーダーは、バランスの取れたブレースをスキャンする必要はありません。なぜなら、JSON文字列内のブレースは普通の文字であり、物理的な行の境界がレコードを終了させるからです。

プロデューサーはレコードが準備できたときに各行をフラッシュすることができます。消費者は、そのストリームインターフェースを通じてバックプレッシャーを適用し、1行を解析し、値を検証し、処理後にメモリを解放できます。これにより、メモリ使用量は最大レコードやパイプラインバッファに関連付けられ、データセット全体には依存しません。

NDJSONは唯一のJSONシーケンスフォーマットではありません。 RFC 7464はJSONテキストシーケンスを定義します 各JSONテキストの前にASCIIレコードセパレーター文字を使用しています。そのフレーミングは、レコードの境界が単に行の終了に依存しないため、きれいに印刷された値を許容できます。プロデューサーと消費者は、どのシーケンスフォーマットを使用するかで合意する必要があります。

NDJSONレコードデザイン

強力なNDJSONストリームは、各行に独立して処理されるのに十分なコンテキストを与えます。複数のイベント形状が1つのストリームを共有する場合は、安定したレコードタイプまたはスキーマバージョンを含めます。輸送が同じ論理レコードを複数回配信する可能性がある場合は、重複除去をサポートする識別子を含めます。文書化された形式およびタイムゾーンセマンティクスでのみ、イベントと観察時間を追加します。

契約が明示的にエンコードされたバイトを必要としない限り、大きなバイナリコンテンツを行指向JSONに含めないでください。Base64はサイズを増加させ、非常に長いレコードを生成します。より良いイベントは、制御されたオブジェクト参照を持つか、取得時の承認対象の整合性メタデータを持つ場合があります。

順序は明示的でなければなりません。NDJSONは物理的な行の順序を保持しますが、分散プロデューサー、パーティション、および並列消費者は観測された処理順序を変更することがあります。エンティティ内で順序が重要な場合は、シーケンスまたはバージョンを含め、ギャップや順序外レコードの処理方法を定義します。

スキーマ検証

有効なJSONは必ずしも有効なビジネスレコードではありません。行は、必要な識別子が欠けていたり、契約で文字列を期待している場所に数字を保存している場合でも、正常に解析されることがあります。使用する前に、各解析された値をレコードスキーマに対して検証してください。

複数のレコードタイプを持つストリームは、安定した識別子に基づいてスキーマを選択できます。ディスパッチャーは、不明なタイプを拒否するか、制御された検疫パスにルートするべきです。スキーマバージョンは互換性を定義する必要があり、消費者はオプションのフィールドが追加されても継続できます。

レコードレベルの検証により、バッチは受け入れ可能なレコードの位置を失うことなく、特定の失敗を報告できます。物理行番号、利用可能な場合のバイトオフセット、スキーマエラー、および安全に編集されたレコード識別子を保存します。秘密情報や敏感なペイロードをエラーログにコピーしないでください。

一般的なNDJSON使用例

NDJSON、CSV、およびParquet

NDJSONは入れ子構造のJSONを保持し、オプションのフィールドを持つレコードを許可します。CSVは、すべてのレコードが1つのフラットテーブル行である場合、よりコンパクトで親しみやすいです。Parquetは、多くのレコードにわたる繰り返し分析のための型付きカラムストレージを追加します。

一般的なパイプラインは、JSONを収集または受信し、生のNDJSONを書き込み、付加的なトレース可能性のためにレコードを検証および正規化し、分析クエリのためにParquetを公開します。CSVは、スプレッドシートユーザーへの選択されたフラットエクスポートに引き続き役立ちます。各段階には異なる消費者があり、それぞれ異なる最適なフォーマットがあります。

圧縮と分割

テキストレコードは、キーと値のパターンが繰り返されるため、しばしば良好に圧縮されます。全ファイル圧縮は、ストレージと転送サイズを削減しますが、一部のコーデックは圧縮ストリームの中間から読み取るのを難しくします。分割可能な圧縮または独立に圧縮されたチャンクは、並列処理にとってより適しているかもしれません。

完全なレコード境界でのみ分割してください。JSON文字列の真ん中でのバイト範囲のカットは無効な断片を生成します。並列アクセスが必要なシステムは、ブロックインデックスを維持したり、ストリームを複数のオブジェクトにチャンクしたり、選択的な読み取りのために構築されたストレージフォーマットを使用したりできます。

有効なNDJSONファイルを連結すると、通常は各入力が改行で終了している場合、有効な行のフレーミングが保持されます。1つのファイルが最終のデリミタを欠く場合、その最後のレコードは次のファイルの最初のレコードにぶつかる可能性があります。ライターは、シリアル化されたレコードを常に終了し、最後のものも含めるべきです。

セキュリティと運用限界

総バイト数、行の長さ、ネストの深さ、文字列の長さ、数値の大きさ、および許可されるプロパティの数に制限を適用してください。単一のNDJSON行は、アプリケーションが境界を強制しない限り、任意の大きさになる可能性があります。有界バッファまたはストリーミング戦略で読み取り、メモリを使い果たすことなく、大きすぎるレコードを報告します。

フィールドをコマンドやテンプレートとして実行しないでください。HTML、SQL、シェル、またはログのコンテキストに入るときは、値をエスケープします。NDJSONレコードが後にプレーンテキストに変換されるときのログフォージングに対して保護します。1つのファイルが複数のテナントのデータを含む可能性がある場合、ストリームおよびレコードレベルでの承認を保持します。

NDJSONを信頼性を持って処理する方法

1. ストリームをUTF-8として開きます。 無効なバイトシーケンスがどのように報告されるかを定義します。静的な置換は識別子を変更する可能性があります。
2. 1つの制約された物理行を読み取ります。 合意された行の終了を受け入れ、最大レコードサイズを強制します。
3. 契約に従って空行を処理します。 無視するか拒否するかを決定し、そのルールを一貫して適用します。
4. 1つのJSON値を解析します。 その行の後ろの非ホワイトスペースコンテンツを拒否し、重複メンバーの動作を定義します。
5. レコードスキーマを検証します。 タイプ、必須プロパティ、値の制限、およびサポートされているバージョンを確認します。
6. 可能な場合は冪等的に処理します。 安定したレコード識別子は、レコードが複数回現れるときの重複した副作用を防ぐのに役立ちます。
7. 安全に進捗を記録します。 チェックポイントは、完了していない行が処理されたと主張せずに、耐久性のあるレコードまたはバイト境界を特定する必要があります。

NDJSONを使用しないべき時

ペイロードが小さく、トップレベルメタデータを持つ必要があるか、きれいな印刷から利益を得る場合は通常のJSONドキュメントを使用します。データがスプレッドシート消費者向けのフラットテーブルである場合はCSVを使用します。分析エンジンがカラムプルーニング、型付きストレージ、および大規模データセット全体での圧縮を必要とする場合はParquetを使用します。

個々の値が人間による編集用の非エスケープの物理行形式を含む必要がある場合、NDJSONは適していません。レコードセパレーターに基づくJSONシーケンスまたはフレーム化されたバイナリプロトコルがその要件により適している可能性があります。

結論

NDJSONはJSON交換に実用的な1つのルールを追加します：各行は1つの完全なJSON値です。そのルールは、追記に優しいファイル、ストリーミングパーサー、レコードレベルの検証、および制約メモリをサポートします。ビジネススキーマ、順序保証、セキュリティポリシー、または配信セマンティクスは定義しません。信頼できるNDJSONワークフローは、コンパクトなUTF-8レコード、明示的なスキーマ、サイズ制限、安定した識別子、明確な空行の動作、行を意識したチェックポイントを使用します。