Cheatsheets - jq / yq

Last Updated: 2023-02-14

Basic Info

• jq: for JSON
  • written in portable C; 0 external dependencies.
  • Source: https://github.com/stedolan/jq
• yq: for YAML
  • written in Go; can download a dependency free binary.
  • Doc: https://mikefarah.gitbook.io/yq
  • Install: https://github.com/mikefarah/yq/#install
  • Source: https://github.com/mikefarah/yq

Select

$ jq '.name' file.json
$ yq '.name' file.yaml

# used with pipes
$ cat file.json | jq '.a.b[0].c'
$ cat file.yaml | yq '.a.b[0].c'

# pretty print
$ cat file.json | jq

Multiple fields:

# from top level
$ cat file.json | jq '. | {field1, field2}'

# from sub level
$ cat file.json | jq '.results[] | {id, name}'

Extract as text values instead of JSON (getting rid of quotes), use -r:

$ cat file.json | jq -r '.a.b[0].c'

Slice an array

$ echo '["a", "b", "c", "d"]' | jq '.[1:3]'

Filter

# get "name" of id 1
$ cat file.json | jq '.results[] | select(.id == "1") | {name}'

# get result with multiple filters
$ cat file.json | jq '.results[] | select((.id == "1") and (.name="a"))'

# filter with substrings
$ cat file.json | jq '.results[] | select(.name | contains("ab"))'

# filter with regex
$ cat file.json | jq '.results[] | select(.name | test("Joe\s+Smith"))'

Functions

Selectors start with .. Functions do not.

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

• keys: get keys of the objects.
• length: get the length of the array or the number of the keys. (e.g. select non-empty arrays select(.my_array | length > 0))
• flatten: flatten nested arrays.
• unique: get the unique values of an array.
• join: join the elements using a separator (e.g. cat file.json | jq '[.a, .b] | join(" ")'))

Create new objects

$ echo '{ "a": 1, "b": 2 }' | jq '{ a: .b, b: .a }'
# { "a": 2, "b": 1 }

Inplace Update

$ yq -i '.a.b[0].c = "cool"' file.yaml

Delete Values

$ jq 'del(.somekey)' input.json