yq/pkg/yqlib/doc/Traverse.md

This is the simplest (and perhaps most used) operator, it is used to navigate deeply into yaml structurse.

Simple map navigation

Given a sample.yml file of:

a: {b: apple}
'': null

then

yq eval '.a' sample.yml

will output

{b: apple}

Splat

Often used to pipe children into other operators

Given a sample.yml file of:

- b: apple
  '': null
- c: banana
  '': null

then

yq eval '.[]' sample.yml

will output

b: apple
'': null
c: banana
'': null

Special characters

Use quotes around path elements with special characters

Given a sample.yml file of:

"{}": frog
'': null

then

yq eval '."{}"' sample.yml

will output

frog

Children don't exist

Nodes are added dynamically while traversing

Given a sample.yml file of:

c: banana
'': null

then

yq eval '.a.b' sample.yml

will output

null

Wildcard matching

Given a sample.yml file of:

a: {cat: apple, mad: things}
'': null

then

yq eval '.a."*a*"' sample.yml

will output

apple
things

Aliases

Given a sample.yml file of:

a: &cat {c: frog}
b: *cat
'': null

then

yq eval '.b' sample.yml

will output

*cat

Traversing aliases with splat

Given a sample.yml file of:

a: &cat {c: frog}
b: *cat
'': null

then

yq eval '.b.[]' sample.yml

will output

frog

Traversing aliases explicitly

Given a sample.yml file of:

a: &cat {c: frog}
b: *cat
'': null

then

yq eval '.b.c' sample.yml

will output

frog

Traversing arrays by index

Given a sample.yml file of:

- 1
- 2
- 3

then

yq eval '.[0]' sample.yml

will output

1

Maps with numeric keys

Given a sample.yml file of:

2: cat
'': null

then

yq eval '.[2]' sample.yml

will output

Maps with non existing numeric keys

Given a sample.yml file of:

a: b
'': null

then

yq eval '.[0]' sample.yml

will output

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
'': null

then

yq eval '.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
'': null

then

yq eval '.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
'': null

then

yq eval '.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
'': null

then

yq eval '.foobar.[]' sample.yml

will output

foobar_c
*foo
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
'': null

then

yq eval '.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
'': null

then

yq eval '.foobarList.[]' sample.yml

will output

foobarList_b
[*foo, *bar]
foobarList_c