JSON and its Query

A wildcard expression creates a list projection, which is a projection over a JSON array.

下面是 List projection 的例子。假设有下面 JSON 数据，我们想要得到 people 中的所有的 first 名字。

{
  "people": [
    {"first": "James", "last": "d"},
    {"first": "Jacob", "last": "e"},
    {"first": "Jayden", "last": "f"},
    {"missing": "different"}
  ],
  "foo": {"bar": "baz"}
}

使用 people[*].first 可得到 people 中的所有的 first 名字，即：

people[*].first    ----> [ "James", "Jacob", "Jayden" ]

如果只想得到第 2 个和第 3 个 first 名字，可以这样：

people[1:3].first   ----> [ "Jacob", "Jayden" ]

前面介绍的 List projection 仅可应用在 JSON 数组上。使用这节介绍的 Object Projection 可以应用在 JSON 对象上。

You can create an object projection using the * syntax. This will create a list of the values of the JSON object, and project the right hand side of the projection onto the list of values.

如，有下面 JSON 数据：

{
  "ops": {
    "functionA": {"numArgs": 2},
    "functionB": {"numArgs": 3},
    "functionC": {"variadic": true}
  }
}

应用查询条件 ops.*.numArgs 后，可以得到 [ 2, 3 ] ，即：

ops.*.numArgs      ----> [ 2, 3 ]

怎么理解它呢？把 Object projection 分解为 LHS(left hand side)和 RHS(right hand side)，即：LHS 为 ops，RHS 为 numArgs。
当 LHS 执行后，得到下面数组：

[{"numArgs": 2}, {"numArgs": 3}, {"variadic": true}]

再应用 RHS 到上面数组中，得到：

[ 2, 3, null]

而 null 不出现在最终结果中，所以最终结果为：

[ 2, 3 ]

Flatten Projections 用 [] 表示，它有什么用呢？请看下面例子。

假设有下面 JSON 数据：

{
  "reservations": [
    {
      "instances": [
        {"state": "running"},
        {"state": "stopped"}
      ]
    },
    {
      "instances": [
        {"state": "terminated"},
        {"state": "runnning"}
      ]
    }
  ]
}

我们想得到一个列表里包含所有的状态，即想得到 ["running", "stopped", "terminated", "running"] ，怎么办呢？
如果使用前面介绍的 List projection reservations[*].instances[*].state 作为查询会得到 [["running", "stopped"], ["terminated", "running"]] ，它不是想要的结果。
使用 Flatten Projection reservations[].instances[].state 作为查询可以得到 ["running", "stopped", "terminated", "running"] 。

[
  [0, 1],
  2,
  [3],
  4,
  [5, [6, 7]]
]

[]        ---->   [ 0, 1, 2, 3, 4, 5, [ 6, 7 ] ]
[][]      ---->   [ 0, 1, 2, 3, 4, 5, 6, 7 ]

A filter expression is defined for an array and has the general form LHS [? <expression> <comparator> <expression>] RHS.

例如，想要在下面 JSON 数据中找到所有 state 为 runing 的 machines 的名字。

{
  "machines": [
    {"name": "a", "state": "running"},
    {"name": "b", "state": "stopped"},
    {"name": "b", "state": "running"}
  ]
}

使用 machines[?state=='running'].name 能实现目标，即：

machines[?state=='running'].name      ----> [ "a", "b" ]

直接看例子，我们想找到下面 JSON 数据中 myarray 中所有包含关键字 foo 的元素。

{
  "myarray": [
    "foo",
    "foobar",
    "barfoo",
    "bar",
    "baz",
    "barbaz",
    "barfoobaz"
  ]
}

用 myarray[?contains(@, 'foo') == `true`] 可以实现上面的任务，即：

myarray[?contains(@, 'foo') == `true`]      ---->  [ "foo", "foobar", "barfoo", "barfoobaz" ]

The @ character in the example above refers to the current element being evaluated in myarray.

某 vaule 如果是字符串，输出时会有双引号，比如：

$ echo '{"key1": "value1"}' | jq '.key1'                # 输出 key1 对应 value，由于它是字符串，会有双引号
"value1"

通过指定选项 --raw-output 后，可以去除上面多余的双引号，比如：

$ echo '{"key1": "value1"}' | jq --raw-output '.key1'   # 增加选项 --raw-output 后，没有双引号了
value1

使用 .[index] 可以根据下标取出数组中的元素，比如：

$ echo '["a","b","c","d","e"]' |jq '.[2]'                 # 取出下标为 2 的元素
"c"
$ echo '["a","b","c","d","e"]' |jq --raw-output '.[2]'    # --raw-output 可以去除字符串输出的双引号
c

使用 .[start:end] 可以进行 slice 操作，比如：

$ echo '["a","b","c","d","e"]' |jq '.[2:4]'
[
  "c",
  "d"
]

使用 .[] 可以返回数组中所有元素，比如：

$ echo '["a","b","c","d","e"]' |jq '.[]'                   # 返回所有元素
"a"
"b"
"c"
"d"
"e"

$ echo '[{"name":"JSON", "good":true}, {"name":"XML", "good":false}]' |jq '.[]'   # 返回所有元素
{
  "name": "JSON",
  "good": true
}
{
  "name": "XML",
  "good": false
}

如果是 object（而不是数组），则 .[] 返回所有 key 对应的 value，比如：

$ echo  '{"foo": 42, "bar": "less interesting data"}' |jq '.[]'         # 返回所有 key 对应的 value
42
"less interesting data"

考虑例子：

$ echo '[1, 2, 3]' | jq '.[] | . * 2'
2
4
6

如果把输出结果构建为数组呢？答案是开始处增加 [ ，结果处增加 ] ，比如：

$ echo '[1, 2, 3]' | jq '[ .[] | . * 2 ]'
[
  2,
  4,
  6
]

下面是从数组中选择出元素 id 字段大于等于 200 的数据：

$ echo '[
{
 "id": 100,
 "name": "Alice",
 "other": "This is Alice"
},
{
 "id": 200,
 "name": "Bob",
 "other": "This is Bob"
},
{
 "id": 300,
 "name": "Carol",
 "other": "No information"
}
]' | jq '.[] | select(.id >= 200)'            # 选择出 id >= 200 的元素
{
  "id": 200,
  "name": "Bob",
  "other": "This is Bob"
}
{
  "id": 300,
  "name": "Carol",
  "other": "No information"
}

上面例子返回的数据是两个 object，利用节 3.2.4 介绍的语法可以把返回结果构造为数组，比如：

$ echo '[
{
 "id": 100,
 "name": "Alice",
 "other": "This is Alice"
},
{
 "id": 200,
 "name": "Bob",
 "other": "This is Bob"
},
{
 "id": 300,
 "name": "Carol",
 "other": "No information"
}
]' | jq '[ .[] | select(.id >= 200) ]'        # 选择出 id >= 200 的元素，把结果构造为数组
[
  {
    "id": 200,
    "name": "Bob",
    "other": "This is Bob"
  },
  {
    "id": 300,
    "name": "Carol",
    "other": "No information"
  }
]

下面是从数组中选择出元素 name 等于 Bob 的元素：

echo '[
{
 "id": 100,
 "name": "Alice",
 "other": "This is Alice"
},
{
 "id": 200,
 "name": "Bob",
 "other": "This is Bob"
},
{
 "id": 300,
 "name": "Carol",
 "other": "No information"
}
]' | jq '.[] | select(.name == "Bob")'        # 选择出 name 等于 Bob 的元素
{
  "id": 200,
  "name": "Bob",
  "other": "This is Bob"
}

下面是从数组中选择出元素 other 包含 This 的元素（利用 contains 关键字），把结果构造为数组：

$ echo '[
{
 "id": 100,
 "name": "Alice",
 "other": "This is Alice"
},
{
 "id": 200,
 "name": "Bob",
 "other": "This is Bob"
},
{
 "id": 300,
 "name": "Carol",
 "other": "No information"
}
]' | jq '[.[] | select(.other | contains("This"))]'   # 选择出 other 包含 This 的元素，把结果构造为数组
[
  {
    "id": 100,
    "name": "Alice",
    "other": "This is Alice"
  },
  {
    "id": 200,
    "name": "Bob",
    "other": "This is Bob"
  }
]

下面是利用 and 关键字进行两个条件同时过滤的例子：

$ echo '[
{
 "id": 100,
 "name": "Alice",
 "other": "This is Alice"
},
{
 "id": 200,
 "name": "Bob",
 "other": "This is Bob"
},
{
 "id": 300,
 "name": "Carol",
 "other": "No information"
}
]' | jq '[.[] | select((.other | contains("This")) and .id >= 200)]'
[
  {
    "id": 200,
    "name": "Bob",
    "other": "This is Bob"
  }
]