yq
v4.x
v4.x
  • yq
  • How It Works
  • Recipes
  • Upgrading from V3
  • Commands
    • Evaluate
    • Evaluate All
    • Shell Completion
  • Operators
    • Add
    • Alternative (Default value)
    • Anchor and Alias Operators
    • Array to Map
    • Assign (Update)
    • Boolean Operators
    • Collect into Array
    • Column
    • Comment Operators
    • Compare Operators
    • Contains
    • Create, Collect into Object
    • Date Time
    • Delete
    • Divide
    • Document Index
    • Encode / Decode
    • Entries
    • Env Variable Operators
    • Equals
    • Eval
    • File Operators
    • Filter Operator
    • Flatten
    • Group By
    • Has
    • Keys
    • Kind
    • Length
    • Line
    • Load
    • Min
    • Map
    • Max
    • Modulo
    • Multiply (Merge)
    • Omit
    • Parent
    • Path
    • Pick
    • Pipe
    • Pivot
    • Recursive Descent (Glob)
    • Reduce
    • Reverse
    • Select
    • Shuffle
    • Slice Array
    • Sort
    • Sort Keys
    • Split into Documents
    • String Operators
    • Style
    • Subtract
    • Tag
    • To Number
    • Traverse (Read)
    • Union
    • Unique
    • Variable Operators
    • With
  • Usage
    • Output format
    • Working with CSV, TSV
    • Working with JSON
    • Working with Properties
    • Working with XML
    • Working with LUA
    • Working with TOML
    • Working with Shell Output
    • Front Matter
    • Split into multiple files
    • GitHub Action
    • Tips, Tricks, Troubleshooting
  • Github Page
Powered by GitBook
On this page
  • Simple map navigation
  • Splat
  • Optional Splat
  • Special characters
  • Nested special characters
  • Keys with spaces
  • Dynamic keys
  • Children don't exist
  • Optional identifier
  • Wildcard matching
  • Aliases
  • Traversing aliases with splat
  • Traversing aliases explicitly
  • Traversing arrays by index
  • Traversing nested arrays by index
  • Maps with numeric keys
  • Maps with non existing numeric keys
  • Traversing merge anchors
  • Traversing merge anchors with override
  • Traversing merge anchors with local override
  • Splatting merge anchors
  • Traversing merge anchor lists
  • Splatting merge anchor lists
  • Select multiple indices

Was this helpful?

  1. Operators

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

Last updated 2 years ago

Was this helpful?