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