yq/pkg/yqlib/doc/operators/traverse-read.md

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