yq-yaml-processing

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

yq YAML Processing

yq YAML 处理

Expert knowledge for processing, querying, and transforming YAML data using yq v4+, the lightweight command-line YAML processor with jq-like syntax.

本内容包含使用yq v4+处理、查询和转换YAML数据的专业知识，yq是一款轻量级命令行YAML处理器，语法与jq类似。

When to Use This Skill

何时使用该技能

Use this skill when...	Use another tool instead when...
Querying or modifying YAML files	Processing JSON only (use jq)
Updating Kubernetes manifests	Full Kubernetes management (use kubectl)
Processing GitHub Actions workflows	XML processing (use xmlstarlet)
Merging YAML configurations	Complex data transformations (use scripting)

适用场景	应使用其他工具的场景
查询或修改YAML文件	仅处理JSON（使用jq）
更新Kubernetes清单	完整Kubernetes管理（使用kubectl）
处理GitHub Actions工作流	XML处理（使用xmlstarlet）
合并YAML配置	复杂数据转换（使用脚本）

Core Expertise

核心能力

YAML Operations

Query and filter YAML with path expressions
Transform YAML structure and shape
Multi-document YAML support
Convert between YAML, JSON, XML, and other formats

Configuration Management

Modify Kubernetes manifests
Update GitHub Actions workflows
Process Helm values files
Manage application configurations

YAML操作

使用路径表达式查询和过滤YAML
转换YAML结构和形态
支持多文档YAML
在YAML、JSON、XML等格式之间转换

配置管理

修改Kubernetes清单
更新GitHub Actions工作流
处理Helm值文件
管理应用配置

Essential Commands

必备命令

Basic Querying

基础查询

bash

undefined

bash

undefined

Pretty-print YAML

格式化打印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

undefined

yq '.[0]' array.yaml yq '.items[2]' data.yaml

undefined

Reading YAML

读取YAML

bash

undefined

bash

undefined

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

undefined

yq 'has("fieldName")' file.yaml

undefined

Modifying YAML (In-Place)

修改YAML（原地编辑）

bash

undefined

bash

undefined

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

undefined

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

undefined

Multi-Document YAML

多文档YAML

bash

undefined

bash

undefined

Split multi-document YAML

拆分多文档YAML

yq -s '.metadata.name' multi-doc.yaml

Select specific document (0-indexed)

选择特定文档（从0开始索引）

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

合并YAML文件

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

undefined

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

undefined

Object Operations

对象操作

bash

undefined

bash

undefined

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

undefined

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

undefined

Agentic Optimizations

智能优化命令

Context	Command
Read field	`yq '.field' file.yaml`
Update in-place	`yq -i '.field = "value"' file.yaml`
YAML to JSON	`yq -o=json '.' file.yaml`
Compact JSON	`yq -o=json -I=0 '.' file.yaml`
Filter documents	`yq 'select(.kind == "Deployment")' file.yaml`
Merge configs	`yq eval-all 'select(fileIndex == 0) * select(fileIndex == 1)' base.yaml override.yaml`
Validate YAML	`yq '.' file.yaml`

场景	命令
读取字段	`yq '.field' file.yaml`
原地更新	`yq -i '.field = "value"' file.yaml`
YAML转JSON	`yq -o=json '.' file.yaml`
紧凑JSON输出	`yq -o=json -I=0 '.' file.yaml`
过滤文档	`yq 'select(.kind == "Deployment")' file.yaml`
合并配置	`yq eval-all 'select(fileIndex == 0) * select(fileIndex == 1)' base.yaml override.yaml`
验证YAML	`yq '.' file.yaml`

Quick Reference

快速参考

Operators

运算符

```
.field
```
- Access field
```
.[]
```
- Iterate array/object
```
|
```
- Pipe (chain operations)
```
,
```
- Multiple outputs
```
//
```
- Alternative operator (default value)
```
*
```
- Merge objects (shallow)
```
*+
```
- Deep merge objects

```
.field
```
- 访问字段
```
.[]
```
- 遍历数组/对象
```
|
```
- 管道（链式操作）
```
,
```
- 多输出
```
//
```
- 备选运算符（默认值）
```
*
```
- 合并对象（浅层）
```
*+
```
- 深度合并对象

Functions

函数

```
keys
```
,
```
values
```
- Object keys/values
```
length
```
- Array/object/string length
```
select()
```
- Filter
```
sort_by()
```
- Sort
```
group_by()
```
- Group
```
unique
```
- Remove duplicates
```
has()
```
- Check field existence
```
type
```
- Get value type
```
add
```
- Sum or concatenate
```
del()
```
- Delete field

```
keys
```
,
```
values
```
- 对象键/值
```
length
```
- 数组/对象/字符串长度
```
select()
```
- 过滤
```
sort_by()
```
- 排序
```
group_by()
```
- 分组
```
unique
```
- 去重
```
has()
```
- 检查字段存在性
```
type
```
- 获取值类型
```
add
```
- 求和或拼接
```
del()
```
- 删除字段

Flags

标志位

Flag	Description
`-i`	In-place edit
`-o`	Output format (json, yaml, xml, csv, tsv, props)
`-p`	Input format (json, yaml, xml)
`-I`	Indent (default: 2)
`-r`	Raw output (no quotes)
`-n`	Null input (create from scratch)
`-s`	Split multi-document YAML

标志位	描述
`-i`	原地编辑
`-o`	输出格式（json, yaml, xml, csv, tsv, props）
`-p`	输入格式（json, yaml, xml）
`-I`	缩进（默认：2）
`-r`	原始输出（无引号）
`-n`	空输入（从头创建）
`-s`	拆分多文档YAML

String Functions

字符串函数

```
split()
```
,
```
join()
```
- String/array conversion
```
contains()
```
- String/array contains
```
test()
```
- Regex match
```
sub()
```
,
```
gsub()
```
- String substitution
```
upcase
```
,
```
downcase
```
- Case conversion

For detailed examples, advanced patterns, and best practices, see REFERENCE.md.

```
split()
```
,
```
join()
```
- 字符串/数组转换
```
contains()
```
- 检查字符串/数组包含关系
```
test()
```
- 正则匹配
```
sub()
```
,
```
gsub()
```
- 字符串替换
```
upcase
```
,
```
downcase
```
- 大小写转换

如需详细示例、高级模式和最佳实践，请查看REFERENCE.md。

Resources

资源

Official Documentation: https://mikefarah.gitbook.io/yq/
GitHub Repository: https://github.com/mikefarah/yq

Try with Docker:

docker run --rm -i mikefarah/yq '.key' <<< 'key: value'

Operators Reference: https://mikefarah.gitbook.io/yq/operators/

官方文档: 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/