y
y
yq
Search…
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:
1
a:
2
b: apple
Copied!
then
1
yq eval '.a' sample.yml
Copied!
will output
1
b: apple
Copied!

Splat

Often used to pipe children into other operators
Given a sample.yml file of:
1
- b: apple
2
- c: banana
Copied!
then
1
yq eval '.[]' sample.yml
Copied!
will output
1
b: apple
2
c: banana
Copied!

Optional Splat

Just like splat, but won't error if you run it against scalars
Given a sample.yml file of:
1
cat
Copied!
then
1
yq eval '.[]' sample.yml
Copied!
will output
1
Copied!

Special characters

Use quotes with brackets around path elements with special characters
Given a sample.yml file of:
1
"{}": frog
Copied!
then
1
yq eval '.["{}"]' sample.yml
Copied!
will output
1
frog
Copied!

Nested special characters

Given a sample.yml file of:
1
a:
2
"key.withdots":
3
"another.key": apple
Copied!
then
1
yq eval '.a["key.withdots"]["another.key"]' sample.yml
Copied!
will output
1
apple
Copied!

Keys with spaces

Use quotes with brackets around path elements with special characters
Given a sample.yml file of:
1
"red rabbit": frog
Copied!
then
1
yq eval '.["red rabbit"]' sample.yml
Copied!
will output
1
frog
Copied!

Dynamic keys

Expressions within [] can be used to dynamically lookup / calculate keys
Given a sample.yml file of:
1
b: apple
2
apple: crispy yum
3
banana: soft yum
Copied!
then
1
yq eval '.[.b]' sample.yml
Copied!
will output
1
crispy yum
Copied!

Children don't exist

Nodes are added dynamically while traversing
Given a sample.yml file of:
1
c: banana
Copied!
then
1
yq eval '.a.b' sample.yml
Copied!
will output
1
null
Copied!

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
- 1
2
- 2
3
- 3
Copied!
then
1
yq eval '.a?' sample.yml
Copied!
will output
1
Copied!

Wildcard matching

Given a sample.yml file of:
1
a:
2
cat: apple
3
mad: things
Copied!
then
1
yq eval '.a."*a*"' sample.yml
Copied!
will output
1
apple
2
things
Copied!

Aliases

Given a sample.yml file of:
1
a: &cat
2
c: frog
3
b: *cat
Copied!
then
1
yq eval '.b' sample.yml
Copied!
will output
1
*cat
Copied!

Traversing aliases with splat

Given a sample.yml file of:
1
a: &cat
2
c: frog
3
b: *cat
Copied!
then
1
yq eval '.b[]' sample.yml
Copied!
will output
1
frog
Copied!

Traversing aliases explicitly

Given a sample.yml file of:
1
a: &cat
2
c: frog
3
b: *cat
Copied!
then
1
yq eval '.b.c' sample.yml
Copied!
will output
1
frog
Copied!

Traversing arrays by index

Given a sample.yml file of:
1
- 1
2
- 2
3
- 3
Copied!
then
1
yq eval '.[0]' sample.yml
Copied!
will output
1
1
Copied!

Traversing nested arrays by index

Given a sample.yml file of:
1
[[], [cat]]
Copied!
then
1
yq eval '.[1][0]' sample.yml
Copied!
will output
1
cat
Copied!

Maps with numeric keys

Given a sample.yml file of:
1
2: cat
Copied!
then
1
yq eval '.[2]' sample.yml
Copied!
will output
1
cat
Copied!

Maps with non existing numeric keys

Given a sample.yml file of:
1
a: b
Copied!
then
1
yq eval '.[0]' sample.yml
Copied!
will output
1
null
Copied!

Traversing merge anchors

Given a sample.yml file of:
1
foo: &foo
2
a: foo_a
3
thing: foo_thing
4
c: foo_c
5
bar: &bar
6
b: bar_b
7
thing: bar_thing
8
c: bar_c
9
foobarList:
10
b: foobarList_b
11
!!merge <<:
12
- *foo
13
- *bar
14
c: foobarList_c
15
foobar:
16
c: foobar_c
17
!!merge <<: *foo
18
thing: foobar_thing
Copied!
then
1
yq eval '.foobar.a' sample.yml
Copied!
will output
1
foo_a
Copied!

Traversing merge anchors with override

Given a sample.yml file of:
1
foo: &foo
2
a: foo_a
3
thing: foo_thing
4
c: foo_c
5
bar: &bar
6
b: bar_b
7
thing: bar_thing
8
c: bar_c
9
foobarList:
10
b: foobarList_b
11
!!merge <<:
12
- *foo
13
- *bar
14
c: foobarList_c
15
foobar:
16
c: foobar_c
17
!!merge <<: *foo
18
thing: foobar_thing
Copied!
then
1
yq eval '.foobar.c' sample.yml
Copied!
will output
1
foo_c
Copied!

Traversing merge anchors with local override

Given a sample.yml file of:
1
foo: &foo
2
a: foo_a
3
thing: foo_thing
4
c: foo_c
5
bar: &bar
6
b: bar_b
7
thing: bar_thing
8
c: bar_c
9
foobarList:
10
b: foobarList_b
11
!!merge <<:
12
- *foo
13
- *bar
14
c: foobarList_c
15
foobar:
16
c: foobar_c
17
!!merge <<: *foo
18
thing: foobar_thing
Copied!
then
1
yq eval '.foobar.thing' sample.yml
Copied!
will output
1
foobar_thing
Copied!

Splatting merge anchors

Given a sample.yml file of:
1
foo: &foo
2
a: foo_a
3
thing: foo_thing
4
c: foo_c
5
bar: &bar
6
b: bar_b
7
thing: bar_thing
8
c: bar_c
9
foobarList:
10
b: foobarList_b
11
!!merge <<:
12
- *foo
13
- *bar
14
c: foobarList_c
15
foobar:
16
c: foobar_c
17
!!merge <<: *foo
18
thing: foobar_thing
Copied!
then
1
yq eval '.foobar[]' sample.yml
Copied!
will output
1
foo_c
2
foo_a
3
foobar_thing
Copied!

Traversing merge anchor lists

Note that the later merge anchors override previous
Given a sample.yml file of:
1
foo: &foo
2
a: foo_a
3
thing: foo_thing
4
c: foo_c
5
bar: &bar
6
b: bar_b
7
thing: bar_thing
8
c: bar_c
9
foobarList:
10
b: foobarList_b
11
!!merge <<:
12
- *foo
13
- *bar
14
c: foobarList_c
15
foobar:
16
c: foobar_c
17
!!merge <<: *foo
18
thing: foobar_thing
Copied!
then
1
yq eval '.foobarList.thing' sample.yml
Copied!
will output
1
bar_thing
Copied!

Splatting merge anchor lists

Given a sample.yml file of:
1
foo: &foo
2
a: foo_a
3
thing: foo_thing
4
c: foo_c
5
bar: &bar
6
b: bar_b
7
thing: bar_thing
8
c: bar_c
9
foobarList:
10
b: foobarList_b
11
!!merge <<:
12
- *foo
13
- *bar
14
c: foobarList_c
15
foobar:
16
c: foobar_c
17
!!merge <<: *foo
18
thing: foobar_thing
Copied!
then
1
yq eval '.foobarList[]' sample.yml
Copied!
will output
1
bar_b
2
foo_a
3
bar_thing
4
foobarList_c
Copied!

Select multiple indices

Given a sample.yml file of:
1
a:
2
- a
3
- b
4
- c
Copied!
then
1
yq eval '.a[0, 2]' sample.yml
Copied!
will output
1
a
2
c
Copied!