yq-yaml-processing

yq による YAML 処理

jq に似た構文を持つ軽量なコマンドライン YAML プロセッサー、yq v4+ を使用して YAML データを処理、クエリ、変換するための専門知識です。

このスキルを使用する場面

このスキルを使用する場面...	代わりに別のスキルを使用する場面...
YAML ファイルをクエリまたは変更する場合	入力が JSON のみの場合 — jq-json-processing を使用してください
コメントとキーの順序を保持したまま YAML をインプレース編集する場合	YAML、JSON、CSV、TOML にまたがる複数ステップの変換を行う場合 — nushell-data-processing を使用してください
Kubernetes マニフェストまたは Actions ワークフローを対象に更新する場合	Kubernetes を全面的に管理する場合（kubectl を使用してください）、または XML を扱う場合（xmlstarlet を使用してください）
YAML 設定をマージする場合	多数のファイルにまたがって集計またはグループ化する場合 — nushell-data-processing を使用してください

主な専門知識

YAML 操作

• パス式を使って YAML をクエリおよびフィルター処理する
• YAML の構造と形式を変換する
• 複数ドキュメントの YAML をサポートする
• YAML、JSON、XML、その他の形式を相互に変換する

設定管理

• Kubernetes マニフェストを変更する
• GitHub Actions ワークフローを更新する
• Helm の values ファイルを処理する
• アプリケーション設定を管理する

基本コマンド

基本的なクエリ

# Pretty-print YAML
yq '.' file.yaml

# Extract specific field
yq '.fieldName' file.yaml

# Extract nested field
yq '.spec.containers[0].name' pod.yaml

# Access array element
yq '.[0]' array.yaml
yq '.items[2]' data.yaml

YAML の読み取り

# Read specific field
yq '.metadata.name' deployment.yaml

# Read nested structure
yq '.spec.template.spec.containers[].image' deployment.yaml

# Read with default value
yq '.optional // "default"' file.yaml

# Check if field exists
yq 'has("fieldName")' file.yaml

YAML の変更（インプレース）

# Update field value
yq -i '.metadata.name = "new-name"' file.yaml

# Update nested field
yq -i '.spec.replicas = 3' deployment.yaml

# Add new field
yq -i '.metadata.labels.app = "myapp"' file.yaml

# Delete field
yq -i 'del(.spec.nodeSelector)' file.yaml

# Append to array
yq -i '.items += {"name": "new-item"}' file.yaml

# Update all matching elements
yq -i '(.items[] | select(.name == "foo")).status = "active"' file.yaml

複数ドキュメントの YAML

# Split multi-document YAML
yq -s '.metadata.name' multi-doc.yaml

# Select specific document (0-indexed)
yq 'select(document_index == 0)' multi-doc.yaml

# Process all documents
yq eval-all '.' multi-doc.yaml

# Filter documents
yq 'select(.kind == "Deployment")' k8s-resources.yaml

# Combine YAML files
yq eval-all '. as $item ireduce ({}; . * $item)' file1.yaml file2.yaml

オブジェクト操作

# Get all keys
yq 'keys' file.yaml

# Select specific fields
yq '{name, version}' file.yaml

# Merge objects
yq '. * {"updated": true}' file.yaml
yq eval-all 'select(fileIndex == 0) * select(fileIndex == 1)' base.yaml override.yaml

# Deep merge
yq eval-all '. as $item ireduce ({}; . *+ $item)' base.yaml override.yaml

JSON 出力（パイプ処理用）

# YAML to JSON
yq -o=json '.' file.yaml

# Compact single-line JSON — the form to pipe into jq or a tool that reads stdin
yq -o=json -I=0 '.' file.yaml

クイックリファレンス

演算子

• .field - フィールドにアクセス
• .[] - 配列／オブジェクトを反復処理
• | - パイプ（操作を連結）
• , - 複数の出力
• // - 代替演算子（デフォルト値）
• * - オブジェクトをマージ（浅いマージ）
• *+ - オブジェクトをディープマージ

関数

• keys、values - オブジェクトのキー／値
• length - 配列／オブジェクト／文字列の長さ
• select() - フィルター処理
• sort_by() - ソート
• group_by() - グループ化
• unique - 重複を削除
• has() - フィールドの有無を確認
• type - 値の型を取得
• add - 合計または連結
• del() - フィールドを削除

フラグ

フラグ	説明
-i	インプレース編集
-o	出力形式（json、yaml、xml、csv、tsv、props）
-p	入力形式（json、yaml、xml）
-I	インデント（デフォルト：2）
-r	生の出力（引用符なし）
-n	null 入力（最初から作成）
-s	複数ドキュメントの YAML を分割

文字列関数

• split()、join() - 文字列／配列の変換
• contains() - 文字列／配列に含まれるか確認
• test() - 正規表現によるマッチ
• sub()、gsub() - 文字列の置換
• upcase、downcase - 大文字／小文字の変換

詳しい例、高度なパターン、ベストプラクティスについては、REFERENCE.md を参照してください。

リソース

• 公式ドキュメント：https://mikefarah.gitbook.io/yq/
• GitHub リポジトリ：https://github.com/mikefarah/yq
• Docker で試す：docker run --rm -i mikefarah/yq '.key' <<< 'key: value'
• 演算子リファレンス：https://mikefarah.gitbook.io/yq/operators/