Traverse (Read)

This is the simplest (and perhaps most used) operator. It is used to navigate deeply into yaml structures.

NOTE --yaml-fix-merge-anchor-to-spec flag

yq doesn't merge anchors <<: to spec, in some circumstances it incorrectly overrides existing keys when the spec documents not to do that.

To minimise disruption while still fixing the issue, a flag has been added to toggle this behaviour. This will first default to false; and log warnings to users. Then it will default to true (and still allow users to specify false if needed)

See examples of the flag differences below, where LEGACY is the flag off; and FIXED is with the flag on.

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 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

Select multiple indices

Given a sample.yml file of:

a:
  - a
  - b
  - c

then

yq '.a[0, 2]' sample.yml

will output

a
c

LEGACY: Traversing merge anchors with override

This is legacy behaviour, see --yaml-fix-merge-anchor-to-spec

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

LEGACY: Traversing merge anchor lists

Note that the later merge anchors override previous, but this is legacy behaviour, see --yaml-fix-merge-anchor-to-spec

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

LEGACY: Splatting merge anchors

With legacy override behaviour, see --yaml-fix-merge-anchor-to-spec

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

LEGACY: Splatting merge anchor lists

With legacy override behaviour, see --yaml-fix-merge-anchor-to-spec

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

FIXED: Traversing merge anchors with override

Set --yaml-fix-merge-anchor-to-spec=true to get this correct merge behaviour.

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

foobar_c

FIXED: Traversing merge anchor lists

Set --yaml-fix-merge-anchor-to-spec=true to get this correct merge behaviour. Note that the keys earlier in the merge anchors sequence override later ones

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

foo_thing

FIXED: Splatting merge anchors

Set --yaml-fix-merge-anchor-to-spec=true to get this correct merge behaviour. Note that the keys earlier in the merge anchors sequence override later ones

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_a
foobar_thing
foobar_c

FIXED: Splatting merge anchor lists

Set --yaml-fix-merge-anchor-to-spec=true to get this correct merge behaviour. Note that the keys earlier in the merge anchors sequence override later ones

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

foobarList_b
foo_thing
foobarList_c
foo_a