yq
v3.x
v3.x
  • yq
  • Upgrading from V2
  • Commands
    • Read
    • Validate
    • Compare
    • Write
    • Create
    • Delete
    • Merge
    • Prefix
    • Shell Completion
  • Usage
    • Output format
    • Path Expressions
    • Value Parsing
    • Working with JSON
  • Github Page
Powered by GitBook
On this page

Was this helpful?

Last updated 4 years ago

Was this helpful?

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

Simple expressions

Maps

'a.b.c'

Arrays

'a.b[1].c'

Appending to arrays

(e.g. when using the write command)

'a.b[+].c'

Will add a new entry:

Negative Array indexes

Negative array indexes can be used to traverse the array in reverse

'a.b[-1].c'

Will access the last element in the b array and yield:

Splat

Maps

'a.*.c'

Prefix splat

'bob.item*.cats'

Arrays

'a.b[*].c'

Deep Splat

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

'a.**.c'

Search by children nodes

You can search children by nodes - note that this will return the parent of the matching expression, in the example below the parent(s) will be the matching indices of the 'a' array. We can then navigate down to get 'b.c' of each matching indice.

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

With prefixes

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

Matching children values

'animals(.==cat)'

this also works in maps, and with prefixes

'animals(.==c*)'

Special Characters

When your yaml field has special characters that overlap with yq path expression characters, you will need to escape them in order for the command to work.

Keys with dots

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

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

Note that the path is in single quotes to avoid the double quotes being interpreted by your shell.

Keys (and values) with leading dashes

The flag terminator needs to be used to stop the app from attempting to parse the subsequent arguments as flags, if they start if a dash.

Will result in

a:
  b:
    c: thing # MATCHES
a:
  b:
  - c: thing0 
  - c: thing1 # MATCHES
  - c: thing2
a:
  b:
  - c: thing0
a:
  b:
  - c: thing0 
  - c: thing1 # NEW entry from [+] on B array.
thing2
a:
  b1:
    c: thing # MATCHES
    d: whatever
  b2:
    c: thing # MATCHES
    f: something irrelevant
bob:
  item:
    cats: bananas # MATCHES
  something:
    cats: lemons
  itemThing:
    cats: more bananas # MATCHES
  item2:
    cats: apples # MATCHES
  thing:
    cats: oranges
a:
  b:
  - c: thing0 # MATCHES
    d: what..ever
  - c: thing1 # MATCHES
    d: blarh
  - c: thing2 # MATCHES
    f: thingamabob
a:
  b1:
    c: thing1 # MATCHES
    d: cat cat
  b2:
    c: thing2 # MATCHES
    d: dog dog
  b3:
    d:
    - f:
        c: thing3 # MATCHES
        d: beep
    - f:
        g:
          c: thing4 # MATCHES
          d: boop
    - d: mooo
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
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
animals:
  - dog
  - cat # MATCHES  
  - rat
animals:
  friendliest: cow # MATCHES
  favourite: cat # MATCHES
  smallest: rat
b:
  foo.bar: 7
yaml r sample.yaml 'b."foo.bar"'
yaml w sample.yaml 'b."foo.bar"' 9
yq n -j -- --key --value
--key: --value
  1. Usage

Path Expressions

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

PreviousOutput formatNextValue Parsing
  • Simple expressions
  • Maps
  • Arrays
  • Splat
  • Maps
  • Arrays
  • Deep Splat
  • Search by children nodes
  • With prefixes
  • Matching children values
  • Special Characters
  • Keys with dots
  • Keys (and values) with leading dashes