

Path Expressions

Path expressions are used to deeply navigate and match particular yaml nodes.

As a general rule, you should wrap paths in quotes in the CLI to prevent your interpreter from processing '*, []' and other special characters.

Simple expressions¶

Maps¶

a.b.c

a:
  b:
    c: thing # MATCHES

Arrays¶

a.b[1].c

a:
  b:
  - c: thing0 
  - c: thing1 # MATCHES
  - c: thing2

Appending to arrays¶

(e.g. when using the write command)

a.b[+].c

a:
  b:
  - c: thing0

Will add a new entry:

a:
  b:
  - c: thing0 
  - c: thing1 # NEW entry from [+] on B array.

Splat¶

Maps¶

a.*.c

a:
  b1:
    c: thing # MATCHES
  b2:
    c: thing # MATCHES

Arrays¶

a.b[*].c

a:
  b:
  - c: thing0 # MATCHES
  - c: thing1 # MATCHES
  - c: thing2 # MATCHES

Deep Splat¶

'**' will match arbitrary nodes for both maps and arrays:

a.**.c

a:
  b1:
    c: thing1 # MATCHES
  b2:
    c: thing2 # MATCHES
  b3:
    d:
    - f:
        c: thing3 # MATCHES
    - f:
        g:
          c: thing4 # MATCHES

Finding parents with particular children nodes¶

a.(b.d==cat).b.c

a:
  - b:
      c: thing0
      d: leopard
    ba: fast
  - b:
      c: thing1 # MATCHES
      d: cat
    ba: meowy
  - b:
      c: thing2
      d: caterpillar
    ba: icky
  - b:
      c: thing3 # MATCHES
      d: cat
    ba: also meowy

With prefixes¶

a.(b.d==cat*).c

a:
  - b:
      c: thing0
      d: leopard
    ba: fast
  - b:
      c: thing1 # MATCHES
      d: cat
    ba: meowy
  - b:
      c: thing2 # MATCHES
      d: caterpillar
    ba: icky
  - b:
      c: thing3 # MATCHES
      d: cat
    ba: also meowy

Special Characters¶

Keys with dots¶

When specifying a key that has a dot use key lookup indicator.

b:
  foo.bar: 7

yaml r sample.yaml 'b[foo.bar]'

yaml w sample.yaml 'b[foo.bar]' 9

Any valid yaml key can be specified as part of a key lookup.

Note that the path is in quotes to avoid the square brackets being interpreted by your shell.

Keys (and values) with leading dashes¶

If a key or value has leading dashes, yq won't know that you are passing a value as opposed to a flag (and you will get a 'bad flag syntax' error).

To fix that, you will need to tell it to stop processing flags by adding '--' after the last flag like so:

yq n -t -- --key --value

Will result in

--key: --value