Comment on page
Traverse (Read)

This is the simplest (and perhaps most used) operator. It is used to navigate deeply into yaml structures.
Simple map navigation
Given a sample.yml file of:
a:
  b: apple
then
yq '.a' sample.yml
will output
b: apple
Splat
Often used to pipe children into other operators
Given a sample.yml file of:
- b: apple
- c: banana
then
yq '.[]' sample.yml
will output
b: apple
c: banana
Optional Splat
Just like splat, but won't error if you run it against scalars
Given a sample.yml file of:
cat
then
yq '.[]' sample.yml
will output
​
Special characters
Use quotes with square brackets around path elements with special characters
Given a sample.yml file of:
"{}": frog
then
yq '.["{}"]' sample.yml
will output
frog
Nested special characters
Given a sample.yml file of:
a:
  "key.withdots":
    "another.key": apple
then
yq '.a["key.withdots"]["another.key"]' sample.yml
will output
apple
Keys with spaces
Use quotes with square brackets around path elements with special characters
Given a sample.yml file of:
"red rabbit": frog
then
yq '.["red rabbit"]' sample.yml
will output
frog
Dynamic keys
Expressions within [] can be used to dynamically lookup / calculate keys
Given a sample.yml file of:
b: apple
apple: crispy yum
banana: soft yum
then
yq '.[.b]' sample.yml
will output
crispy yum
Children don't exist
Nodes are added dynamically while traversing
Given a sample.yml file of:
c: banana
then
yq '.a.b' sample.yml
will output
null
Optional identifier
Like jq, does not output an error when the yaml is not an array or object as expected
Given a sample.yml file of:
- 1
- 2
- 3
then
yq '.a?' sample.yml
will output
​
Wildcard matching
Given a sample.yml file of:
a:
  cat: apple
  mad: things
then
yq '.a."*a*"' sample.yml
will output
apple
things
Aliases
Given a sample.yml file of:
a: &cat
  c: frog
b: *cat
then
yq '.b' sample.yml
will output
*cat
Traversing aliases with splat
Given a sample.yml file of:
a: &cat
  c: frog
b: *cat
then
yq '.b[]' sample.yml
will output
frog
Traversing aliases explicitly
Given a sample.yml file of:
a: &cat
  c: frog
b: *cat
then
yq '.b.c' sample.yml
will output
frog
Traversing arrays by index
Given a sample.yml file of:
- 1
- 2
- 3
then
yq '.[0]' sample.yml
will output
1
Traversing nested arrays by index
Given a sample.yml file of:
[[], [cat]]
then
yq '.[1][0]' sample.yml
will output
cat
Maps with numeric keys
Given a sample.yml file of:
2: cat
then
yq '.[2]' sample.yml
will output
cat
Maps with non existing numeric keys
Given a sample.yml file of:
a: b
then
yq '.[0]' sample.yml
will output
null
Traversing merge anchors
Given a sample.yml file of:
foo: &foo
  a: foo_a
  thing: foo_thing
  c: foo_c
bar: &bar
  b: bar_b
  thing: bar_thing
  c: bar_c
foobarList:
  b: foobarList_b
  !!merge <<:
    - *foo
    - *bar
  c: foobarList_c
foobar:
  c: foobar_c
  !!merge <<: *foo
  thing: foobar_thing
then
yq '.foobar.a' sample.yml
will output
foo_a
Traversing merge anchors with override
Given a sample.yml file of:
foo: &foo
  a: foo_a
  thing: foo_thing
  c: foo_c
bar: &bar
  b: bar_b
  thing: bar_thing
  c: bar_c
foobarList:
  b: foobarList_b
  !!merge <<:
    - *foo
    - *bar
  c: foobarList_c
foobar:
  c: foobar_c
  !!merge <<: *foo
  thing: foobar_thing
then
yq '.foobar.c' sample.yml
will output
foo_c
Traversing merge anchors with local override
Given a sample.yml file of:
foo: &foo
  a: foo_a
  thing: foo_thing
  c: foo_c
bar: &bar
  b: bar_b
  thing: bar_thing
  c: bar_c
foobarList:
  b: foobarList_b
  !!merge <<:
    - *foo
    - *bar
  c: foobarList_c
foobar:
  c: foobar_c
  !!merge <<: *foo
  thing: foobar_thing
then
yq '.foobar.thing' sample.yml
will output
foobar_thing
Splatting merge anchors
Given a sample.yml file of:
foo: &foo
  a: foo_a
  thing: foo_thing
  c: foo_c
bar: &bar
  b: bar_b
  thing: bar_thing
  c: bar_c
foobarList:
  b: foobarList_b
  !!merge <<:
    - *foo
    - *bar
  c: foobarList_c
foobar:
  c: foobar_c
  !!merge <<: *foo
  thing: foobar_thing
then
yq '.foobar[]' sample.yml
will output
foo_c
foo_a
foobar_thing
Traversing merge anchor lists
Note that the later merge anchors override previous
Given a sample.yml file of:
foo: &foo
  a: foo_a
  thing: foo_thing
  c: foo_c
bar: &bar
  b: bar_b
  thing: bar_thing
  c: bar_c
foobarList:
  b: foobarList_b
  !!merge <<:
    - *foo
    - *bar
  c: foobarList_c
foobar:
  c: foobar_c
  !!merge <<: *foo
  thing: foobar_thing
then
yq '.foobarList.thing' sample.yml
will output
bar_thing
Splatting merge anchor lists
Given a sample.yml file of:
foo: &foo
  a: foo_a
  thing: foo_thing
  c: foo_c
bar: &bar
  b: bar_b
  thing: bar_thing
  c: bar_c
foobarList:
  b: foobarList_b
  !!merge <<:
    - *foo
    - *bar
  c: foobarList_c
foobar:
  c: foobar_c
  !!merge <<: *foo
  thing: foobar_thing
then
yq '.foobarList[]' sample.yml
will output
bar_b
foo_a
bar_thing
foobarList_c
Select multiple indices
Given a sample.yml file of:
a:
  - a
  - b
  - c
then
yq '.a[0, 2]' sample.yml
will output
a
c
To Number
Union
Last modified 8mo ago