The 12 JSON-to-CSV Edge Cases That Will Ruin Your Data Pipeline

# データパイプラインを台無しにする12のJSONからCSVへのエッジケース

ネストされた配列がフィンテックに120万ドルの報告エラーをもたらしたとき

昨年の3月、フィンテッククライアントのCFOから夜11時にパニックのSlackメッセージが届きました。彼らの四半期ボード報告書には、内部ダッシュボードと一致しない収益数値が示されていました。その不一致は？120万ドルです。6週間にわたり、彼らの自動JSONからCSVへの変換がネストされた取引配列を静かに破損させており、誰もそれに気づくことがなかったのです。ボードデッキはすでに投資家の手に渡っていました。

根本原因は非常にシンプルでした：彼らの決済処理業者のWebhookが、ネストされたJSON配列として取引データを提供していました—一つの取引は、独自の税計算を持つ複数の品目を持つことができます。彼らのETLパイプラインがこれをCSVに平坦化した際、各子アイテムに対して親レコードが複製されましたが、取引合計を重複排除することには失敗しました。全ての多品目取引が何度もカウントされてしまいました。

これはジュニアエンジニアのミスではありませんでした。これは5万以上のGitHubスターを持つ人気のオープンソースライブラリを使用しているシニアチームのミスでした。このライブラリは単純なJSON構造には完璧に機能しました。しかし、実際のSaaSデータは単純ではありません。それはネストされ、不一致で、製造中にのみ明らかになるエッジケースが満載です—通常は最悪の瞬間に。

私はSaaS企業のために8年間ETLパイプラインを構築してきました。初期段階のスタートアップから、月に数十億のイベントを処理する上場企業まで。午前3時にデータ破損のデバッグを行い、数ヶ月間静かに失敗したパイプラインを再構築し、JSONからCSVへの変換がデータ整合性の問題が隠れている場所であることを学びました。データベースではありません。APIでもありません。その「簡単に動作する」と誰もが仮定する、見た目は些細な変換ステップの中にあります。

月に20億イベントを処理するパイプラインの構築

私のバックグラウンドは、高ボリュームのSaaSプラットフォームにおけるデータエンジニアリングです。私は、毎日5億以上のイベントを処理するマーケティングオートメーションツールの取り込みパイプライン、1億以上のユーザーからのクリックストリームデータを扱う分析プラットフォーム、単一の破損したレコードが規制違反を引き起こす可能性のある金融システムのために取り込みパイプラインを構築してきました。

私が繰り返し見るパターン：チームはデータベースのスケーリングとAPIの最適化に焦点を当てますが、データ変換を後回しにします。彼らは50ミリ秒を節約するPostgresクエリの最適化に数週間を費やしますが、静かに0.01%のレコードを破損するナイーブなJSONからCSVへの変換器を使用します。その0.01%は時間とともに累積し、あなたがボードに対してメトリクスが現実と一致しない理由を説明することになります。

JSONからCSVへの変換は、ほとんどのデータパイプラインにおける重要な接点にあります。これは、構造化された階層データが分析ツール、スプレッドシート、レガシーシステムのための表形式に平坦化される場所です。この変換は本質的に情報損失を伴います—CSVはネストされた構造を表現できません—しかし、ほとんどの実装はこの損失をうまく扱いません。彼らは、データを平坦化する方法に関して暗黙的な決定を行いますが、それらの決定を文書化したり、結果を検証したりしません。

ツールは役立ちません。ほとんどのJSONからCSVライブラリは単純なユースケースのために構築されています：一貫したスキーマを持つフラットなオブジェクトです。彼らは、オプションのフィールド、ネストされた配列、多形的な型および不一致な構造を含む実際のAPI応答を与えると、故障します。そして、彼らは静かに壊れます。エラーはありません。警告はありません。ただ微妙に破損したデータがあり、誰かが財務報告書を実行するまで正常に見えます。

私はJSONからCSVへの変換を、データベースの移行やAPI契約と同じ厳格さを必要とする重要なシステムコンポーネントとして扱うことを学びました。それは、包括的なテスト、エッジケースの明確な処理、およびあらゆるステップでの検証を意味します。実際には以下のようになります。

ShopifyのWebhookがクライアントの在庫システムをほぼ破壊した方法

3年前、私は複数のプラットフォームからデータを集約するeコマース分析会社と仕事をしました。彼らは一見単純なパイプラインを持っていました：Shopify、Stripe、および他のサービスからWebhookを取り込み、CSVに変換し、データウェアハウスにロードし、商人向けにレポートを生成することです。

ある月曜日の朝、彼らのサポートチームはチケットに溺れました。商人たちは不可能な在庫数を見ていました—マイナスの在庫数、売り切れているにもかかわらず「在庫あり」と表示される製品、実際の販売と一致しない注文数量です。分析プラットフォームのデータは完全に誤っており、誰かが気づくまで3日間間違っていました。

犯人はShopifyのバリアント構造でした。ShopifyのAPIでは、製品は複数のバリアント（サイズ、色など）を持つことができ、それぞれのバリアントに自分自身の在庫数があります。JSON構造は次のようになります：

```json

{

"product_id": "12345",

"title": "Tシャツ",

"variants": [

{"id": "v1", "size": "S", "inventory": 10},

{"id": "v2", "size": "M", "inventory": 15},

{"id": "v3", "size": "L", "inventory": 8}

]

}

```

彼らのCSV変換器は、バリアントごとに1行を作成することでこれを平坦化しましたが、合理的に思えます。しかし、エッジケースは次のとおりです：バリアントが売り切れ、Shopifyがバリアント配列からそれを削除したとき、変換器はそれの行を作成しませんでした。下流のシステムは「行が欠如している」を「変更なし」と解釈しましたが、「在庫がゼロになった」というわけではありません。製品は売り切れたにもかかわらず、在庫ありとして表示されました。

修正には明示的な処理が必要でした：バリアントを平坦化する際には、すべての既知のバリアントIDの参照リストを維持し、JSONから消えたバリアントのために明示的にゼロ在庫の行を記述する必要がありました。これにより、「単純な」変換が履歴データの追跡を必要とする状態を持つ操作になりました。

最も危険なデータバグは、もっともらしい出力を生成するものです。もし変換がクラッシュしたり、明らかに間違ったデータを生成したりしていたら、彼らはすぐにそれに気付いたでしょう。代わりに、完全に正常に見えるCSVファイルを生成しました—ただし、重要な情報が欠けていました。

このパターンは、私が構築したすべてのSaaS統合において繰り返されます。エッジケースは異例のシナリオではありません—それはAPIがデータを表現する方法の通常の変動です。しかし、ほとんどの変換ツールはそれらを異例として扱うため、静かに失敗します。

JSONからCSVライブラリの比較: 実際に本番で壊れるもの

Node.js、Python、およびGoの各主要なJSONからCSVライブラリをテストしました。実際のSaaSデータを与えると壊れるものは以下の通りです：

「本番準備完了」列は、このライブラリを広範囲のテストと検証なしで財務データに信頼できるかどうかを反映しています。ほとんどのライブラリは単純なケースでは問題なく機能しますが、あなたの要件と一致しないかもしれないエッジケースについて暗黙の決定を下します。

重要な洞察：ネストされたJSONをCSVに平Flatten化する「正しい」方法はありません。それはあなたのユースケースに依存します。アーカイブのためにデータを保持していますか？分析のためにデータを準備していますか？エンドユーザー向けにレポートを生成していますか？各ユースケースは、ネストされた構造、欠落フィールド、および型の不一致に関して異なる処理を要求します。

フィンテッククライアントについて私は…