jq usage examples

jq is a very powerful command line tool for processing JSON data. Here is a record of some of the operations used by jq recently, for direct reference when you have similar needs in the future.

Basic operation

The command line usage of jq is as follows:

$ jq -h
jq - commandline JSON processor [version 1.5]
Usage: jq [options] <jq filter> [file...]

This article focuses on the commonly used <jq filter>. Most of the operations can be tested directly online with jq play .

Output raw JSON data

The default is to output as is without specifying a filter, or you can use the . filter

$ echo '{"url": "mozillazg.com"}' |jq .
{
  "url": "mozillazg.com"
}

jq play online running link:https://jqplay.org/s/KhRuUFCP2h

object operation

Get the value of a key

.key, .foo.bar, .["key"]

$ echo '{"url": "mozillazg.com"}' |jq .url
"mozillazg.com"
$ echo '{"url": "mozillazg.com"}' | jq '.["url"]'
"mozillazg.com"

jq play: https://jqplay.org/s/Tn7NUbP4Dr

You can put a question mark after it to indicate that no error will be reported when the input is not an object .key? :

$ echo '1' |jq '.a'
jq: error (at <stdin>:1): Cannot index number with string "a"
$ echo '1' |jq '.a?'
$

The ? rule fits all correct filters, and adding ? can ignore the error message

An array of all the keys

keys

$ echo '{"url": "mozillazg.com", "name": "mozillazg"}' |jq keys
[
  "name",
  "url"
]

jq play: https://jqplay.org/s/_5KiPRS75r

All values

.[]

$ echo '{"url": "mozillazg.com", "name": "mozillazg"}' |jq .[]
"mozillazg.com"
"mozillazg"

jq play: https://jqplay.org/s/6HRvEND8AB

An array of all values

[.[]]

$ echo '{"url": "mozillazg.com", "name": "mozillazg"}' |jq [.[]]
[
  "mozillazg.com",
  "mozillazg"
]

jq play: https://jqplay.org/s/JGIX6hTt_8

Array operations

Fetch all elements

.[]

$ echo '[{"name": "tom"}, {"name": "mozillazg"}]' |jq .[]
{
  "name": "tom"
}
{
  "name": "mozillazg"
}

jq play: https://jqplay.org/s/Y9UgK_4xxE

slice

.[1], .[0:2]

$ echo '[{"name": "tom"}, {"name": "mozillazg"}, {"name": "jim"}]' |jq .[1]
{
  "name": "mozillazg"
}
$ echo '[{"name": "tom"}, {"name": "mozillazg"}, {"name": "jim"}]' |jq .[0:2]
[
  {
    "name": "tom"
  },
  {
    "name": "mozillazg"
  }
]

jq play: https://jqplay.org/s/seNL7hW38W

Manipulating arrays of objects

For example, to retrieve the value of name from an array element:

$ echo '[{"name": "foo"},{"name": "bar"},{"name": "foobar"}]' |jq .[].name
"foo"
"bar"
"foobar"

jq play: https://jqplay.org/s/Z5qjhJnRyn

It is also possible to use the following pipeline operations that will be mentioned below.:

$ echo '[{"name": "foo"},{"name": "bar"},{"name": "foobar"}]' |jq '.[]|.name'
"foo"
"bar"
"foobar"

If you want to recompose the result into an array, you can do so:

$ echo '[{"name": "foo"},{"name": "bar"},{"name": "foobar"}]' |jq [.[].name]
[
  "foo",
  "bar",
  "foobar"
]

You can also use the map that will be mentioned below:

$ echo '[{"name": "foo"},{"name": "bar"},{"name": "foobar"}]' |jq 'map(.name)'
[
  "foo",
  "bar",
  "foobar"
]

Use multiple filters

,

$ echo '{"url": "mozillazg.com", "name": "mozillazg"}' |jq '.url, .name'
"mozillazg.com"
"mozillazg"

jq play: https://jqplay.org/s/02CPHO1ESj

Advanced Operations

Pipeline (to do secondary or multiple processing of the processed results)

You can use | to implement a pipeline like function:

$ echo '{"url": "mozillazg.com", "name": "mozillazg"}' |jq '.|.url'
"mozillazg.com"

jq play: https://jqplay.org/s/L5bu1ovLr-

$ echo '{"url": "mozillazg.com", "tests": [{"foobar": "v1"}, {"foobar": "v2"}]}' |jq '.tests |.[] |.foobar'
"v1"
"v2"

jq play: https://jqplay.org/s/9UcLXKEgaT

You can also use the shell's | implementation directly:

$ echo '{"url": "mozillazg.com", "name": "mozillazg"}' |jq '.' | jq '.url'
"mozillazg.com"

$ echo '{"url": "mozillazg.com", "tests": [{"foobar": "v1"}, {"foobar": "v2"}]}' |jq '.tests' | jq '.[]' | jq '.foobar'
"v1"
"v2"

Get the length of the content (string, length of an array)

length can get the length of a string or an array:

$ echo '{"url": "mozillazg.com", "name": "mozillazg"}' |jq '.url|length'
13
$ echo '["mozillazg.com", "mozillazg"]' |jq '.|length'
2

jq play: https://jqplay.org/s/9TqdXbe0lo

map

map(foo) can operate on each item of an array and then merge the results:

$ echo '["mozillazg.com", "mozillazg"]' | jq 'map(length)'
[
  13,
  9
]

jq play: https://jqplay.org/s/BjgdGsjPem

filter(select)

select(foo) can be used to select an input item and return only the items that match the conditions:

$ echo '["mozillazg.com", "mozillazg"]' | jq 'map(select(.|length > 9))'
[
  "mozillazg.com"
]

jq play: https://jqplay.org/s/8Zrwy7dDxW

String interpolation, splicing/join

You can use \(foo) to implement the string interpolation function:

$ echo '{"url": "mozillazg.com", "name": "mozillazg"}' |jq '"hi \(.name)"'
"hi mozillazg"

Note that it should be enclosed in double quotes to indicate that it is a string.

jq play: https://jqplay.org/s/k90JFcDqPz

String concatenation using + :

$ echo '{"url": "mozillazg.com", "name": "mozillazg"}' |jq '"hi " + .name'
"hi mozillazg"

Output the raw string value instead of the JSON serialized string value

Use the -r option to output the raw value of the string instead of the serialized value of json:

$ echo '{"value": "{\"url\": \"mozillazg.com\"}"}' |jq .value
"{\"url\": \"mozillazg.com\"}"

echo '{"value": "{\"url\": \"mozillazg.com\"}"}' |jq -r .value
{"url": "mozillazg.com"}

if/elif/else

You can use if ... then ... elif ... then ... else ... end to implement conditional judgments:

$ echo '[0, 1, 2, 3]' \
| jq 'map(if . == 0 then "zero" elif . == 1 then "one" elif . == 2 then "two" else "many" end)'
[
  "zero",
  "one",
  "two",
  "many"
]

jq play: https://jqplay.org/s/y8WwvHISH4

Constructing objects or arrays

New objects or arrays can be constructed with {} and [] .

object:

$ echo '["mozillazg.com", "mozillazg"]' |jq '{name: .[1]}'
{
  "name": "mozillazg"
}

jq play: https://jqplay.org/s/sccwJi75jb

Array:

$ echo '{"url": "mozillazg.com", "name": "mozillazg"}' |jq '[.name, .url]'
[
  "mozillazg",
  "mozillazg.com"
]

jq play: https://jqplay.org/s/LYflwM4kJM

$ echo '{"name": "mozillazg", "ages": [1, 2]}' | jq '{name, age: .ages[]}'
{
  "name": "mozillazg",
  "age": 1
}
{
  "name": "mozillazg",
  "age": 2
}

jq play: https://jqplay.org/s/s1GiNkp_Ed

Array join

join:

$ echo '["mozillazg.com", "mozillazg"]' | jq '.|join(" | ")'
"mozillazg.com | mozillazg"

jq play: https://jqplay.org/s/1ckAfiLKA3

String split

split:

$ echo '"mozillazg.com | mozillazg"' |jq 'split(" | ")'
[
  "mozillazg.com",
  "mozillazg"
]

jq play: https://jqplay.org/s/_7uGMWvmUh

For more functions and usage, see the official docs

References


Comments

comments powered by Disqus