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 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
- c: banana

then

yq eval '.[]' 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 eval '.[]' sample.yml

will output

Special characters

Use quotes with brackets around path elements with special characters

Given a sample.yml file of:

"{}": frog

then

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

will output

frog

Nested special characters

Given a sample.yml file of:

a:
"key.withdots":
"another.key": apple

then

yq eval '.a["key.withdots"]["another.key"]' sample.yml

will output

apple

Keys with spaces

Use quotes with brackets around path elements with special characters

Given a sample.yml file of:

"red rabbit": frog

then

yq eval '.["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 eval '.[.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 eval '.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 eval '.a?' sample.yml

will output

Wildcard matching

Given a sample.yml file of:

a:
cat: apple
mad: things

then

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

will output

apple
things

Aliases

Given a sample.yml file of:

a: &cat
c: frog
b: *cat

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

then

yq eval '.b[]' sample.yml

will output

frog

Traversing aliases explicitly

Given a sample.yml file of:

a: &cat
c: frog
b: *cat

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

Traversing nested arrays by index

Given a sample.yml file of:

[[], [cat]]

then

yq eval '.[1][0]' sample.yml

will output

cat

Maps with numeric keys

Given a sample.yml file of:

2: cat

then

yq eval '.[2]' sample.yml

will output

cat

Maps with non existing numeric keys

Given a sample.yml file of:

a: b

then

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

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

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

then

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

then

yq eval '.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 eval '.a[0, 2]' sample.yml

will output

a
c