第 02 章「データを持つ ── JSON/CSV/YAMLで考える」の主張の 2 番目の角度 を裏付ける。

章のどの主張に対応するか

表(行と列) → CSV / 階層(ネスト) → JSON / 設定(コメント付き) → YAML 一つのプロジェクトで全部使ってもいい。

JSON / CSV を Claude に渡したときの認識率: ほぼ 100%。

(章本文より)

example-1 が「Excel → CSV → pandas 集計」だったのに対し、このフォルダは:

3 形式の相互変換 + 完全往復(データが壊れない)
jq での JSON クエリ(階層データ向き)
awk での CSV クエリ(表データ向き)

を実演する。

やること

顧客マスタ data/customers.csv(15 行)を入力に
convert.py で CSV → JSON → CSV 往復(完全一致を確認)
CSV → YAML にも変換(可読性の比較)
jq で JSON に対する3種類のクエリ
awk で同じ処理を CSV に対して(jq と awk の対応表)

構成

example-2/
├── README.md
├── convert.py        ── CSV ⇄ JSON / CSV → YAML
├── Makefile          ── 変換 + クエリ
├── results.md
├── data/customers.csv
└── out/
    ├── customers.json
    ├── customers.yaml
    ├── customers-roundtrip.csv  (元と完全一致)
    ├── q-pro.json               (jq: プロプランだけ)
    └── q-region-mrr.json        (jq: 地域別 MRR)

実行

pip install pyyaml
sudo apt install jq
make clean && make all

なぜこれが「実例」になるのか

業務で出会うデータは、形が違うだけで本質は同じ:

取引先がくれた Excel → CSV にする
API から落とした JSON → そのまま使うか CSV に
設定ファイル → YAML

これらは 3 形式とも 完全に往復できる。データが壊れない。だから、組織の入口で受け取った形式から、自分の作業形式(扱いやすい 1 つ)に変換して使い、出口で必要な形式に戻せばいい。

しかも、それぞれの形式に そのまま使えるクエリツール がある:

形式	クエリ	例
JSON	`jq`	`jq '.[] \| select(.plan=="プロ")'`
CSV	`awk` `cut` `sort`	`awk -F, '$4=="プロ"'`
YAML	`yq` または `jq`(YAML→JSON 変換後)

これが章で言う「用途で使い分ける、変換は変換層に押し込む」の具体形。

計測結果 — 第 02 章 example-2

実行環境: Linux 6.18 / Python 3.x / jq 1.7

形式変換の速度とサイズ

=== 形式変換 ===
  CSV → list[dict] :    0.2 ms
  → JSON           :    0.1 ms  ( 1942 B)
  → YAML           :    1.5 ms  ( 1320 B)
  JSON → CSV 往復   :    0.1 ms

  CSV ⇄ JSON ⇄ CSV 完全往復: ✓ 一致

形式	サイズ(15 顧客)	1 顧客あたり
CSV	約 700 B	47 B
JSON	約 1,940 B	130 B
YAML	約 1,320 B	88 B

CSV が最も小さい(キー名を 1 回しか書かないため)。JSON はキーが毎行繰り返されるので冗長。YAML はその中間。

業務でのデータの大半は表(行と列) なので、保存は CSV が経済的。階層が必要なら JSON。設定なら YAML。

jq クエリ

1. プロプランだけ抽出

jq '.[] | select(.plan == "プロ") | {name, region, monthly_yen}' out/customers.json

{ "name": "鈴木商店", "region": "大阪", "monthly_yen": 4980 }
{ "name": "田中株式会社", "region": "東京", "monthly_yen": 4980 }
{ "name": "小林技研", "region": "大阪", "monthly_yen": 4980 }
{ "name": "山本印刷", "region": "徳島", "monthly_yen": 4980 }
{ "name": "木村電機", "region": "北海道", "monthly_yen": 4980 }

2. 地域別の MRR 合計

jq 'group_by(.region) | map({region:.[0].region, customers:length, mrr:(map(.monthly_yen)|add)})
    | sort_by(-.mrr)' out/customers.json

大阪    : 3 顧客 / MRR 11,940 円
東京    : 4 顧客 / MRR  8,920 円
北海道  : 3 顧客 / MRR  7,940 円
徳島    : 3 顧客 / MRR  7,940 円
沖縄    : 2 顧客 / MRR  2,960 円

3. 全顧客の MRR 合計

jq '[.[] | .monthly_yen] | add' out/customers.json
# → 39700

awk で CSV に対して同じこと

awk -F, 'NR>1 {a[$3]+=$5; n[$3]++} END {for (r in a) printf "%s : %d / %d\n", r, n[r], a[r]}' \
    data/customers.csv | sort

北海道 : 3 顧客 / MRR 7940 円
大阪   : 3 顧客 / MRR 11940 円
徳島   : 3 顧客 / MRR 7940 円
東京   : 4 顧客 / MRR 8920 円
沖縄   : 2 顧客 / MRR 2960 円

jq と awk で結果は 完全一致。形式は違うが、データは同じ。

YAML 抜粋

- customer_id: C001
  name: 山田農園
  region: 徳島
  plan: スタンダード
  monthly_yen: 1980
  started: '2025-08-01'
- customer_id: C002
  name: 鈴木商店
  ...

設定ファイルや短い人手編集データには YAML が読みやすい。

「Excel と何が違うのか」

Excel ファイルでも同じ集計はできる(ピボットテーブル)。違いは:

Excel: マウス操作、操作の記録は残らない、来月の自分は手順を忘れる
jq / awk: コマンドが記録、Makefile に書けば来月も同じ結果

これが章で言う「処理の再現性」と「形式と道具の対応」の具体形。

再現手順

pip install pyyaml
sudo apt install jq
make clean && make all

CSV ⇄ JSON ⇄ YAML 相互変換 + jq / awk クエリ