CSV と JSON

形式が実際に表しているもの

CSV はフィールドをレコードに並べ、一般的にはヘッダーで列名を付けます。 CSV 形式の記述 では、カンマ、改行、埋め込まれた二重引用符に対するクオートのルールを文書化しています。CSV は実務的な方言の集合のままなので、生成側は区切り文字、エンコーディング、ヘッダーの扱いを宣言すべきです。

JSON はオブジェクト、配列、文字列、数値、boolean、null を含む定義済みの構文で値を表現します。 JSON 交換仕様 は、ビジネスフィールドにスキーマを割り当てることなく、これらの型を定義します。構文的に有効なオブジェクトであっても、必須の識別子が欠けていたり、アプリケーションが数値を期待する場所に文字列が入っていたりすることがあります。

複数のオファーを持つ商品を考えてみましょう。JSON では、その商品オブジェクトの中に offers 配列を保持できます。CSV では、商品をオファー行ごとに繰り返すか、別の関連テーブルを作るか、リストをフィールド内にエンコードするかを決める必要があります。どの選択肢も、利用側が出力をどのように解釈しなければならないかを変えてしまいます。

スキーマがテキストフィールドを解釈可能にする

スキーマは、ファイル名では表現できない意味を与えます。CSV フィールドには、宣言された型、単位、必須かどうか、キーが必要です。 W3C の表形式データモデル は、カラムやリレーションシップを含むメタデータとともにテーブルを記述します。これにより、制約が具体化されます。CSV 構文とテーブルの意味論は別レイヤーなのです。

検索エクスポートでは、結果 URL をテキストとして、順位を定義済みの結果カテゴリ内の整数として、取得時刻を合意されたタイムゾーンを持つ値として扱います。先頭のゼロが重要な識別子は文字列として保存します。スプレッドシートの自動型判定に、元の契約内容を決めさせてはいけません。

JSON にも明示的な制約が必要です。キーが欠けている状態と、キーはあるが値が null の状態が同じ意味なのかどうかを決めます。空配列が関連レコードがないことを意味するのか、リレーションシップが利用できないことを意味するのかを明確にします。検証では、ダッシュボードに黙って届いてしまう前に、変更されたフィールド型を拒否すべきです。

入れ子結果のフラット化には行粒度の定義が必要

CSV エクスポートには、各行が何を表しているのかという明確な答えが 1 つ必要です。検索レスポンスにオーガニック検索結果、関連する質問、その他のモジュールが含まれている場合、それぞれの集合は異なるエンティティを記述している可能性があります。それらを位置カラムを共有する単一テーブルにフラット化すると、誤解を招く比較を生み出すことがあります。

クエリ、マーケット、キャプチャごとにオーガニック結果を1件といった粒度を選びます。各エクスポート行にクエリとコンテキストを保存するか、安定したキャプチャ識別子を通じてそれらを紐付けてください。フィールドや並び順の意味が異なる他の結果コレクションは、別のテーブルに保持します。こうすることで、モジュール間に架空の同等性を作り出すことなく、関係性を維持できます。

配列を行に展開する場合は、その「掛け算」を明示します。複数のオファーを持つ商品は、複数のオファーレコードを生み出しますが、複数の別々の商品を生み出すわけではありません。商品数の比較には商品キーを、オファー数の比較にはオファーキーを使います。そうしないと、無害なエクスポート変換がビジネスの合計値を水増しし、カバレッジレポートを歪めてしまうことがあります。

欠損値・数値・テキストには意図的なルールが必要

欠損は変換エラーの最も一般的な原因のひとつです。CSV は汎用的な型付き null を定義していないため、空フィールドは、契約次第で空文字列を意味することもあれば、値の欠如を意味することもあります。明確な表現方法を予約し、受け取り側のパーサーがそれを使用していることを確認してください。

JSON には null がありますが、null は値が利用できない理由までは説明しません。その理由が解釈に影響する場合は、追加のステータスフィールドを使用してください。存在しなかった価格と、パースできなかった価格は異なります。そうしたケースを調査する必要があるときのために、元の値または編集済みの診断情報を保持します。

数値精度もシステム境界をまたぎます。長い識別子を JSON の数値として表現すると、数値精度が限定されたコンシューマーによって解釈される可能性があります。演算に意味がない識別子は文字列として表現してください。金額については、通貨と小数処理を、読み手のデフォルトの浮動小数点変換に頼るのではなく、明示的に定義します。

ストリーミングとファイルサイズは表現形式に依存する

CSV はレコードごとに処理できますが、引用符付きフィールドには改行が含まれる場合があります。そのため、物理的な1行ごとに読み込むだけでは完全な CSV パーサーにはなりません。宣言された方言を理解し、レコード境界とフィールド内の改行を区別できるパーサーを使用してください。

大きな JSON 配列も、適切なパーサーを用いれば段階的に消費できます。Newline-delimited JSON は独立したレコードにとって有用な慣習ですが、通常の1つの JSON ドキュメントと混同せず、明示的に記述されるべきです。プロデューサーとコンシューマーは、どちらか一方が安全にストリーミングを行えるようになる前に、フレーミングに合意しておかなければなりません。

普遍的なサイズ比較の主張は避けてください。JSON はフィールド名を繰り返しますが、CSV はそれを一度だけ書くことが多い一方で、ネスト、欠落フィールド、引用、圧縮などによって結果は変化します。同じレコード、エンコーディング、圧縮設定を用いて、代表的なエクスポートを比較してください。最も小さいファイルが、常に最も検証や統合が容易であるとは限りません。

元のレスポンスと分析用エクスポートは分離しておく

信頼できる検索ワークフローは、構造化されたソースレスポンスを保持し、分析のために目的に合わせたテーブルを生成できます。 Scrapeless Google Search API は構造化された JSON を提供し、どのフィールドを CSV の列にし、どのコンテキストを一緒に運ぶかは、あなたの変換処理が定義します。CSV ファイルは、すべてのソースフィールドの代替ではなく、分析ビューです。

この search-result CSV analysis workflow は、クエリコンテキストと結果カテゴリがエクスポート計画に含まれるべき理由を示します。キャプチャID、ソースコンテキスト、マッピングルールを保持し、アナリストが行を収集イベントまで遡れるようにします。

両形式からは、資格情報やアカウント詳細を除外してください。タスクと保持ポリシーに必要なソース資料だけを残します。取得計画には最新の Scrapeless pricing を使用し、変換と保存のコストは、データを生成したリクエストとは切り離して計測してください。

契約とコンシューマーに基づいて形式を選ぶ

受け取り側のシステムが長方形のテーブルを期待し、列が安定しており、人がスプレッドシートで直接確認する必要がある場合は CSV を選びます。サービスがネストした関係、オプションのコレクション、構造化レスポンス内の型付きスカラ値を必要とする場合は JSON を選びます。一方がソースレコードでもう一方が意図的な射影である場合は、両方を使用します。

納品前に、想定されるコンシューマーを使って出力をパースしてください。正しい粒度でのレコード数、識別子の保持、非 ASCII テキスト、引用符、改行、欠損値を確認します。ネストや複数値を含む例を受け入れ用データセットに含め、単純な行だけを処理しても変換が通過できないようにしておきます。

意味が変わるときはスキーマにバージョンを付けてください。列の追加は、あるインポーターには互換的でも、別のインポーターには破壊的かもしれません。既存列の意味を変えることは、名前を変えるよりも悪影響が大きい場合があります。マッピングを文書化し、ファイルが受け取られる境界で検証してください。

結論

CSV と JSON の選択は、レコードの形状とコンシューマーのニーズに従うべきです。型とキーを定義し、フラット化前に行の粒度を選び、受け取り側システムでエクスポートファイルをテストします。ネストされた詳細が必要な場合はソース JSON を保持し、正確な分析に必要なコンテキストを運ぶ CSV ビューを作成してください。

参考文献

• Google Search API structured output
• Scrapeless Google Search API
• 検索結果のCSVデータセットの計画