jqlang/jq 1.3 使用手册：JSON数据处理完全指南

jqlang/jq 1.3 使用手册：JSON数据处理完全指南

jq Command-line JSON processor 项目地址: https://gitcode.com/gh_mirrors/jq/jq

什么是jq？

jq是一个轻量级且功能强大的命令行JSON处理器。它允许你通过编写简单的"过滤器"来转换、查询和操作JSON数据。与传统的编程语言不同，jq采用流式数据处理模型，通过组合各种过滤器来实现复杂的数据处理任务。

核心概念：过滤器

在jq中，一切操作都是通过过滤器完成的。过滤器有以下特点：

1. 输入输出模型：每个过滤器都接受输入并产生输出
2. 组合性：过滤器可以通过管道(|)或逗号(,)组合
3. 多结果输出：某些过滤器可以产生多个输出值

即使是简单的值如"hello"或42也是过滤器——它们忽略输入，总是产生相同的输出。

基础过滤器详解

1. 身份过滤器 .

最简单的过滤器，原样输出输入值。常用于JSON格式化：

echo '{"name":"John"}' | jq '.'

2. 对象属性访问 .field

访问JSON对象的属性：

echo '{"name":"John","age":30}' | jq '.name'
# 输出: "John"

如果字段不存在，返回null。

3. 数组索引访问 .[index]

访问数组元素（从0开始）：

echo '["a","b","c"]' | jq '.[1]'
# 输出: "b"

支持Python风格的切片语法：

echo '[0,1,2,3,4]' | jq '.[1:3]'
# 输出: [1,2]

4. 数组展开 .[]

将数组展开为多个输出：

echo '[1,2,3]' | jq '.[]'
# 输出: 
# 1
# 2
# 3

5. 多值输出 , 运算符

同时应用多个过滤器：

echo '{"x":1,"y":2}' | jq '.x, .y'
# 输出:
# 1
# 2

6. 管道 | 运算符

将一个过滤器的输出作为下一个的输入：

echo '[{"name":"Alice"},{"name":"Bob"}]' | jq '.[] | .name'
# 输出:
# "Alice"
# "Bob"

数据类型与构造器

jq支持JSON的所有数据类型：数字、字符串、布尔值、数组、对象和null。

1. 数组构造 []

echo '{"a":1,"b":2}' | jq '[.a, .b]'
# 输出: [1,2]

2. 对象构造 {}

echo '{"name":"John","age":30}' | jq '{username: .name, years: .age}'
# 输出: {"username":"John","years":30}

快捷语法（字段名相同可省略值部分）：

echo '{"name":"John","age":30}' | jq '{name, age}'
# 输出: {"name":"John","age":30}

常用内置运算符与函数

1. 加法 +

根据类型执行不同操作：

• 数字：算术加法
• 数组：连接
• 字符串：拼接
• 对象：合并（右侧值优先）

echo '{"a":[1,2],"b":[3,4]}' | jq '.a + .b'
# 输出: [1,2,3,4]

2. 减法 -

支持数字减法和数组元素移除：

echo '["a","b","c"]' | jq '. - ["b"]'
# 输出: ["a","c"]

3. 长度函数 length

返回字符串字符数、数组元素数或对象键值对数：

echo '["a","bb","ccc"]' | jq 'map(length)'
# 输出: [1,2,3]

4. 键列表函数 keys

返回对象键名或数组索引的排序列表：

echo '{"b":1,"a":2}' | jq 'keys'
# 输出: ["a","b"]

5. 存在检查函数 has

检查键或索引是否存在：

echo '{"a":1}' | jq 'has("a")'
# 输出: true

命令行选项精要

jq提供多种控制输入输出的选项：

1. -n/--null-input：不使用输入，以null作为输入
2. -R/--raw-input：不解析为JSON，按行读取原始文本
3. -s/--slurp：将所有输入读取为单个数组
4. -c/--compact-output：紧凑输出（非美化）
5. -r/--raw-output：直接输出字符串（不加引号）
6. --arg name value：定义变量供jq程序使用

实用技巧

1. JSON格式化：最简单的jq用法

   curl -s https://api.example.com/data | jq '.'
   

2. 提取嵌套数据：

   echo '{"user":{"name":"John","friends":["Alice","Bob"]}}' | jq '.user.friends[0]'
   

3. 数据转换：

   echo '[{"name":"Alice"},{"name":"Bob"}]' | jq 'map(.name)'
   

4. 多步骤处理：

   echo '{"items":[{"price":10},{"price":20}]}' | jq '.items | map(.price) | add'
   

jq的强大之处在于过滤器的组合能力，通过灵活组合各种简单过滤器，可以实现复杂的数据处理任务，而无需编写冗长的代码。

jq Command-line JSON processor 项目地址: https://gitcode.com/gh_mirrors/jq/jq