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
  • Merge one map
  • Merge multiple maps
  • Override
  • Get anchor
  • Set anchor
  • Set anchor relatively using assign-update
  • Get alias
  • Set alias
  • Set alias to blank does nothing
  • Set alias relatively using assign-update
  • Explode alias and anchor
  • Explode with no aliases or anchors
  • Explode with alias keys
  • Explode with merge anchors
  • Dereference and update a field

Was this helpful?

  1. Operators

Anchor and Alias Operators

Use the alias and anchor operators to read and write yaml aliases and anchors. The explode operator normalises a yaml file (dereference (or expands) aliases and remove anchor names).

yq supports merge aliases (like <<: *blah) however this is no longer in the standard yaml spec (1.2) and so yq will automatically add the !!merge tag to these nodes as it is effectively a custom tag.

Merge one map

see https://yaml.org/type/merge.html

Given a sample.yml file of:

- &CENTER
  x: 1
  y: 2
- &LEFT
  x: 0
  y: 2
- &BIG
  r: 10
- &SMALL
  r: 1
- !!merge <<: *CENTER
  r: 10

then

yq '.[4] | explode(.)' sample.yml

will output

x: 1
y: 2
r: 10

Merge multiple maps

see https://yaml.org/type/merge.html

Given a sample.yml file of:

- &CENTER
  x: 1
  y: 2
- &LEFT
  x: 0
  y: 2
- &BIG
  r: 10
- &SMALL
  r: 1
- !!merge <<:
    - *CENTER
    - *BIG

then

yq '.[4] | explode(.)' sample.yml

will output

r: 10
x: 1
y: 2

Override

see https://yaml.org/type/merge.html

Given a sample.yml file of:

- &CENTER
  x: 1
  y: 2
- &LEFT
  x: 0
  y: 2
- &BIG
  r: 10
- &SMALL
  r: 1
- !!merge <<:
    - *BIG
    - *LEFT
    - *SMALL
  x: 1

then

yq '.[4] | explode(.)' sample.yml

will output

r: 10
x: 1
y: 2

Get anchor

Given a sample.yml file of:

a: &billyBob cat

then

yq '.a | anchor' sample.yml

will output

billyBob

Set anchor

Given a sample.yml file of:

a: cat

then

yq '.a anchor = "foobar"' sample.yml

will output

a: &foobar cat

Set anchor relatively using assign-update

Given a sample.yml file of:

a:
  b: cat

then

yq '.a anchor |= .b' sample.yml

will output

a: &cat
  b: cat

Get alias

Given a sample.yml file of:

b: &billyBob meow
a: *billyBob

then

yq '.a | alias' sample.yml

will output

billyBob

Set alias

Given a sample.yml file of:

b: &meow purr
a: cat

then

yq '.a alias = "meow"' sample.yml

will output

b: &meow purr
a: *meow

Set alias to blank does nothing

Given a sample.yml file of:

b: &meow purr
a: cat

then

yq '.a alias = ""' sample.yml

will output

b: &meow purr
a: cat

Set alias relatively using assign-update

Given a sample.yml file of:

b: &meow purr
a:
  f: meow

then

yq '.a alias |= .f' sample.yml

will output

b: &meow purr
a: *meow

Explode alias and anchor

Given a sample.yml file of:

f:
  a: &a cat
  b: *a

then

yq 'explode(.f)' sample.yml

will output

f:
  a: cat
  b: cat

Explode with no aliases or anchors

Given a sample.yml file of:

a: mike

then

yq 'explode(.a)' sample.yml

will output

a: mike

Explode with alias keys

Given a sample.yml file of:

f:
  a: &a cat
  *a: b

then

yq 'explode(.f)' sample.yml

will output

f:
  a: cat
  cat: b

Explode with 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 'explode(.)' sample.yml

will output

foo:
  a: foo_a
  thing: foo_thing
  c: foo_c
bar:
  b: bar_b
  thing: bar_thing
  c: bar_c
foobarList:
  b: bar_b
  thing: foo_thing
  c: foobarList_c
  a: foo_a
foobar:
  c: foo_c
  a: foo_a
  thing: foobar_thing

Dereference and update a field

Use explode with multiply to dereference an object

Given a sample.yml file of:

item_value: &item_value
  value: true
thingOne:
  name: item_1
  !!merge <<: *item_value
thingTwo:
  name: item_2
  !!merge <<: *item_value

then

yq '.thingOne |= explode(.) * {"value": false}' sample.yml

will output

item_value: &item_value
  value: true
thingOne:
  name: item_1
  value: false
thingTwo:
  name: item_2
  !!merge <<: *item_value
PreviousAlternative (Default value)NextArray to Map

Last updated 2 years ago

Was this helpful?