yq

a lightweight and portable command-line YAML processor written in go.

COMMANDS

Evaluate

Note that (as of 4.18.1) this is the default command when none is supplied to yq.

Usage:

yq eval [expression] [yaml_file1]... [flags]

Aliases: eval, e

Note that you can pass in - as a filename to pipe from STDIN.

Examples:

# runs the expression against each file, in series
yq '.a.b | length' f1.yml f2.yml 

# '-' will pipe from STDIN
cat file.yml | yq '.a.b' f1.yml -  f2.yml

# prints out the file
yq sample.yaml 
cat sample.yml | yq e

# prints a new yaml document
yq -n '.a.b.c = "cat"' 

# updates file.yaml directly
yq '.a.b = "cool"' -i file.yaml 

Flags:

  -h, --help          help for eval
  -C, --colors        force print with colors
  -e, --exit-status   set exit status if there are no matches or null or false is returned
  -I, --indent int    sets indent level for output (default 2)
  -i, --inplace       update the yaml file inplace of first yaml file given.
  -M, --no-colors     force print with no colors
  -N, --no-doc        Don't print document separators (---)
  -n, --null-input    Don't read input, simply evaluate the expression given. Useful for creating yaml docs from scratch.
  -j, --tojson        output as json. Set indent to 0 to print json in one line.
  -v, --verbose       verbose mode

Evaluate All

Evaluate All is most useful when needing to run expressions that depend on multiple yaml documents or files. Merge is probably the most common reason why evaluate all would be used. Note that eval-all consumes more memory than evaluate.

Like evaluate you can use - to pipe from STDIN.

Usage

yq eval-all [expression] [yaml_file1]... [flags]

Aliases: eval-all, ea

Examples

# merges f2.yml into f1.yml (inplace)
yq eval-all --inplace 'select(fileIndex == 0) * select(fileIndex == 1)' f1.yml f2.yml

# you can merge into a file, piping from STDIN
cat somefile.yml | yq eval-all --inplace 'select(fileIndex == 0) * select(fileIndex == 1)' f1.yml -

Flags

  -h, --help          help for eval-all
  -C, --colors        force print with colors
  -e, --exit-status   set exit status if there are no matches or null or false is returned
  -I, --indent int    sets indent level for output (default 2)
  -i, --inplace       update the yaml file inplace of first yaml file given.
  -M, --no-colors     force print with no colors
  -N, --no-doc        Don't print document separators (---)
  -n, --null-input    Don't read input, simply evaluate the expression given. Useful for creating yaml docs from scratch.
  -j, --tojson        output as json. Set indent to 0 to print json in one line.
  -v, --verbose       verbose mode

OPERATORS

Add

Add behaves differently according to the type of the LHS:

• arrays: concatenate
• number scalars: arithmetic addition
• string scalars: concatenate
• maps: shallow merge (use the multiply operator (*) to deeply merge)

Use += as a relative append assign for things like increment. Note that .a += .x is equivalent to running .a = .a + .x.

Concatenate arrays

Given a sample.yml file of:

a:
  - 1
  - 2
b:
  - 3
  - 4

then

yq '.a + .b' sample.yml

will output

- 1
- 2
- 3
- 4

Concatenate to existing array

Note that the styling of a is kept.

Given a sample.yml file of:

a: [1,2]
b:
  - 3
  - 4

then

yq '.a += .b' sample.yml

will output

a: [1, 2, 3, 4]
b:
  - 3
  - 4

Concatenate null to array

Given a sample.yml file of:

a:
  - 1
  - 2

then

yq '.a + null' sample.yml

will output

- 1
- 2

Append to existing array

Note that the styling is copied from existing array elements

Given a sample.yml file of:

a: ['dog']

then

yq '.a += "cat"' sample.yml

will output

a: ['dog', 'cat']

Prepend to existing array

Given a sample.yml file of:

a:
  - dog

then

yq '.a = ["cat"] + .a' sample.yml

will output

a:
  - cat
  - dog

Add new object to array

Given a sample.yml file of:

a:
  - dog: woof

then

yq '.a + {"cat": "meow"}' sample.yml

will output

- dog: woof
- cat: meow

Relative append

Given a sample.yml file of:

a:
  a1:
    b:
      - cat
  a2:
    b:
      - dog
  a3: {}

then

yq '.a[].b += ["mouse"]' sample.yml

will output

a:
  a1:
    b:
      - cat
      - mouse
  a2:
    b:
      - dog
      - mouse
  a3:
    b:
      - mouse

String concatenation

Given a sample.yml file of:

a: cat
b: meow

then

yq '.a += .b' sample.yml

will output

a: catmeow
b: meow

Number addition - float

If the lhs or rhs are floats then the expression will be calculated with floats.

Given a sample.yml file of:

a: 3
b: 4.9

then

yq '.a = .a + .b' sample.yml

will output

a: 7.9
b: 4.9

Number addition - int

If both the lhs and rhs are ints then the expression will be calculated with ints.

Given a sample.yml file of:

a: 3
b: 4

then

yq '.a = .a + .b' sample.yml

will output

a: 7
b: 4

Increment numbers

Given a sample.yml file of:

a: 3
b: 5

then

yq '.[] += 1' sample.yml

will output

a: 4
b: 6

Date addition

You can add durations to dates. Assumes RFC3339 date time format, see date-time operators for more information.

Given a sample.yml file of:

a: 2021-01-01T00:00:00Z

then

yq '.a += "3h10m"' sample.yml

will output

a: 2021-01-01T03:10:00Z

Date addition - custom format

You can add durations to dates. See date-time operators for more information.

Given a sample.yml file of:

a: Saturday, 15-Dec-01 at 2:59AM GMT

then

yq 'with_dtf("Monday, 02-Jan-06 at 3:04PM MST", .a += "3h1m")' sample.yml

will output

a: Saturday, 15-Dec-01 at 6:00AM GMT

Add to null

Adding to null simply returns the rhs

Running

yq --null-input 'null + "cat"'

will output

cat

Add maps to shallow merge

Adding objects together shallow merges them. Use * to deeply merge.

Given a sample.yml file of:

a:
  thing:
    name: Astuff
    value: x
  a1: cool
b:
  thing:
    name: Bstuff
    legs: 3
  b1: neat

then

yq '.a += .b' sample.yml

will output

a:
  thing:
    name: Bstuff
    legs: 3
  a1: cool
  b1: neat
b:
  thing:
    name: Bstuff
    legs: 3
  b1: neat

Custom types: that are really strings

When custom tags are encountered, yq will try to decode the underlying type.

Given a sample.yml file of:

a: !horse cat
b: !goat _meow

then

yq '.a += .b' sample.yml

will output

a: !horse cat_meow
b: !goat _meow

Custom types: that are really numbers

When custom tags are encountered, yq will try to decode the underlying type.

Given a sample.yml file of:

a: !horse 1.2
b: !goat 2.3

then

yq '.a += .b' sample.yml

will output

a: !horse 3.5
b: !goat 2.3

Alternative (Default value)

This operator is used to provide alternative (or default) values when a particular expression is either null or false.

LHS is defined

Given a sample.yml file of:

a: bridge

then

yq '.a // "hello"' sample.yml

will output

bridge

LHS is not defined

Given a sample.yml file of:

{}

then

yq '.a // "hello"' sample.yml

will output

hello

LHS is null

Given a sample.yml file of:

a: ~

then

yq '.a // "hello"' sample.yml

will output

hello

LHS is false

Given a sample.yml file of:

a: false

then

yq '.a // "hello"' sample.yml

will output

hello

RHS is an expression

Given a sample.yml file of:

a: false
b: cat

then

yq '.a // .b' sample.yml

will output

cat

Update or create - entity exists

This initialises a if it’s not present

Given a sample.yml file of:

a: 1

then

yq '(.a // (.a = 0)) += 1' sample.yml

will output

a: 2

Update or create - entity does not exist

This initialises a if it’s not present

Given a sample.yml file of:

b: camel

then

yq '(.a // (.a = 0)) += 1' sample.yml

will output

b: camel
a: 1

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

Array to Map

Use this operator to convert an array to..a map. The indices are used as map keys, null values in the array are skipped over.

Behind the scenes, this is implemented using reduce:

(.[] | select(. != null) ) as $i ireduce({}; .[$i | key] = $i)

Simple example

Given a sample.yml file of:

cool:
  - null
  - null
  - hello

then

yq '.cool |= array_to_map' sample.yml

will output

cool:
  2: hello

Assign (Update)

This operator is used to update node values. It can be used in either the:

plain form: =

Which will set the LHS node values equal to the RHS node values. The RHS expression is run against the matching nodes in the pipeline.

relative form: |=

This will do a similar thing to the plain form, but the RHS expression is run with each LHS node as context. This is useful for updating values based on old values, e.g. increment.

Flags

• c clobber custom tags

Create yaml file

Running

yq --null-input '.a.b = "cat" | .x = "frog"'

will output

a:
  b: cat
x: frog

Update node to be the child value

Given a sample.yml file of:

a:
  b:
    g: foof

then

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

will output

a:
  g: foof

Double elements in an array

Given a sample.yml file of:

- 1
- 2
- 3

then

yq '.[] |= . * 2' sample.yml

will output

- 2
- 4
- 6

Update node from another file

Note this will also work when the second file is a scalar (string/number)

Given a sample.yml file of:

a: apples

And another sample another.yml file of:

b: bob

then

yq eval-all 'select(fileIndex==0).a = select(fileIndex==1) | select(fileIndex==0)' sample.yml another.yml

will output

a:
  b: bob

Update node to be the sibling value

Given a sample.yml file of:

a:
  b: child
b: sibling

then

yq '.a = .b' sample.yml

will output

a: sibling
b: sibling

Updated multiple paths

Given a sample.yml file of:

a: fieldA
b: fieldB
c: fieldC

then

yq '(.a, .c) = "potato"' sample.yml

will output

a: potato
b: fieldB
c: potato

Update string value

Given a sample.yml file of:

a:
  b: apple

then

yq '.a.b = "frog"' sample.yml

will output

a:
  b: frog

Update string value via |=

Note there is no difference between = and |= when the RHS is a scalar

Given a sample.yml file of:

a:
  b: apple

then

yq '.a.b |= "frog"' sample.yml

will output

a:
  b: frog

Update deeply selected results

Note that the LHS is wrapped in brackets! This is to ensure we don’t first filter out the yaml and then update the snippet.

Given a sample.yml file of:

a:
  b: apple
  c: cactus

then

yq '(.a[] | select(. == "apple")) = "frog"' sample.yml

will output

a:
  b: frog
  c: cactus

Update array values

Given a sample.yml file of:

- candy
- apple
- sandy

then

yq '(.[] | select(. == "*andy")) = "bogs"' sample.yml

will output

- bogs
- apple
- bogs

Update empty object

Given a sample.yml file of:

{}

then

yq '.a.b |= "bogs"' sample.yml

will output

a:
  b: bogs

Update node value that has an anchor

Anchor will remain

Given a sample.yml file of:

a: &cool cat

then

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

will output

a: &cool dog

Update empty object and array

Given a sample.yml file of:

{}

then

yq '.a.b.[0] |= "bogs"' sample.yml

will output

a:
  b:
    - bogs

Custom types are maintained by default

Given a sample.yml file of:

a: !cat meow
b: !dog woof

then

yq '.a = .b' sample.yml

will output

a: !cat woof
b: !dog woof

Custom types: clobber

Use the c option to clobber custom tags

Given a sample.yml file of:

a: !cat meow
b: !dog woof

then

yq '.a =c .b' sample.yml

will output

a: !dog woof
b: !dog woof

Boolean Operators

The or and and operators take two parameters and return a boolean result.

not flips a boolean from true to false, or vice versa.

any will return true if there are any true values in an array sequence, and all will return true if all elements in an array are true.

any_c(condition) and all_c(condition) are like any and all but they take a condition expression that is used against each element to determine if it’s true. Note: in jq you can simply pass a condition to any or all and it simply works - yq isn’t that clever..yet

These are most commonly used with the select operator to filter particular nodes.

Related Operators

• equals / not equals (==, !=) operators here
• comparison (>=, < etc) operators here
• select operator here

or example

Running

yq --null-input 'true or false'

will output

true

“yes” and “no” are strings

In the yaml 1.2 standard, support for yes/no as booleans was dropped - they are now considered strings. See ‘10.2.1.2. Boolean’ in https://yaml.org/spec/1.2.2/

Given a sample.yml file of:

- yes
- no

then

yq '.[] | tag' sample.yml

will output

!!str
!!str

and example

Running

yq --null-input 'true and false'

will output

false

Matching nodes with select, equals and or

Given a sample.yml file of:

- a: bird
  b: dog
- a: frog
  b: bird
- a: cat
  b: fly

then

yq '[.[] | select(.a == "cat" or .b == "dog")]' sample.yml

will output

- a: bird
  b: dog
- a: cat
  b: fly

any returns true if any boolean in a given array is true

Given a sample.yml file of:

- false
- true

then

yq 'any' sample.yml

will output

true

any returns false for an empty array

Given a sample.yml file of:

[]

then

yq 'any' sample.yml

will output

false

any_c returns true if any element in the array is true for the given condition.

Given a sample.yml file of:

a:
  - rad
  - awesome
b:
  - meh
  - whatever

then

yq '.[] |= any_c(. == "awesome")' sample.yml

will output

a: true
b: false

all returns true if all booleans in a given array are true

Given a sample.yml file of:

- true
- true

then

yq 'all' sample.yml

will output

true

all returns true for an empty array

Given a sample.yml file of:

[]

then

yq 'all' sample.yml

will output

true

all_c returns true if all elements in the array are true for the given condition.

Given a sample.yml file of:

a:
  - rad
  - awesome
b:
  - meh
  - 12

then

yq '.[] |= all_c(tag == "!!str")' sample.yml

will output

a: true
b: false

Not true is false

Running

yq --null-input 'true | not'

will output

false

Not false is true

Running

yq --null-input 'false | not'

will output

true

String values considered to be true

Running

yq --null-input '"cat" | not'

will output

false

Empty string value considered to be true

Running

yq --null-input '"" | not'

will output

false

Numbers are considered to be true

Running

yq --null-input '1 | not'

will output

false

Zero is considered to be true

Running

yq --null-input '0 | not'

will output

false

Null is considered to be false

Running

yq --null-input '~ | not'

will output

true

Collect into Array

This creates an array using the expression between the square brackets.

Collect empty

Running

yq --null-input '[]'

will output

[]

Collect single

Running

yq --null-input '["cat"]'

will output

- cat

Collect many

Given a sample.yml file of:

a: cat
b: dog

then

yq '[.a, .b]' sample.yml

will output

- cat
- dog

Column

Returns the column of the matching node. Starts from 1, 0 indicates there was no column data.

Column is the number of characters that precede that node on the line it starts.

Returns column of value node

Given a sample.yml file of:

a: cat
b: bob

then

yq '.b | column' sample.yml

will output

4

Returns column of key node

Pipe through the key operator to get the column of the key

Given a sample.yml file of:

a: cat
b: bob

then

yq '.b | key | column' sample.yml

will output

1

First column is 1

Given a sample.yml file of:

a: cat

then

yq '.a | key | column' sample.yml

will output

1

No column data is 0

Running

yq --null-input '{"a": "new entry"} | column'

will output

0

Comment Operators

Use these comment operators to set or retrieve comments. Note that line comments on maps/arrays are actually set on the key node as opposed to the value (map/array). See below for examples.

Like the = and |= assign operators, the same syntax applies when updating comments:

plain form: =

This will set the LHS nodes’ comments equal to the expression on the RHS. The RHS is run against the matching nodes in the pipeline

relative form: |=

This is similar to the plain form, but it evaluates the RHS with each matching LHS node as context. This is useful if you want to set the comments as a relative expression of the node, for instance its value or path.

Set line comment

Set the comment on the key node for more reliability (see below).

Given a sample.yml file of:

a: cat

then

yq '.a line_comment="single"' sample.yml

will output

a: cat # single

Set line comment of a maps/arrays

For maps and arrays, you need to set the line comment on the key node. This will also work for scalars.

Given a sample.yml file of:

a:
  b: things

then

yq '(.a | key) line_comment="single"' sample.yml

will output

a: # single
  b: things

Use update assign to perform relative updates

Given a sample.yml file of:

a: cat
b: dog

then

yq '.. line_comment |= .' sample.yml

will output

a: cat # cat
b: dog # dog

Where is the comment - map key example

The underlying yaml parser can assign comments in a document to surprising nodes. Use an expression like this to find where you comment is. ‘p’ indicates the path, ‘isKey’ is if the node is a map key (as opposed to a map value). From this, you can see the ‘hello-world-comment’ is actually on the ‘hello’ key

Given a sample.yml file of:

hello: # hello-world-comment
  message: world

then

yq '[... | {"p": path | join("."), "isKey": is_key, "hc": headComment, "lc": lineComment, "fc": footComment}]' sample.yml

will output

- p: ""
  isKey: false
  hc: ""
  lc: ""
  fc: ""
- p: hello
  isKey: true
  hc: ""
  lc: hello-world-comment
  fc: ""
- p: hello
  isKey: false
  hc: ""
  lc: ""
  fc: ""
- p: hello.message
  isKey: true
  hc: ""
  lc: ""
  fc: ""
- p: hello.message
  isKey: false
  hc: ""
  lc: ""
  fc: ""

Retrieve comment - map key example

From the previous example, we know that the comment is on the ‘hello’ key as a lineComment

Given a sample.yml file of:

hello: # hello-world-comment
  message: world

then

yq '.hello | key | line_comment' sample.yml

will output

hello-world-comment

Where is the comment - array example

The underlying yaml parser can assign comments in a document to surprising nodes. Use an expression like this to find where you comment is. ‘p’ indicates the path, ‘isKey’ is if the node is a map key (as opposed to a map value). From this, you can see the ‘under-name-comment’ is actually on the first child

Given a sample.yml file of:

name:
  # under-name-comment
  - first-array-child

then

yq '[... | {"p": path | join("."), "isKey": is_key, "hc": headComment, "lc": lineComment, "fc": footComment}]' sample.yml

will output

- p: ""
  isKey: false
  hc: ""
  lc: ""
  fc: ""
- p: name
  isKey: true
  hc: ""
  lc: ""
  fc: ""
- p: name
  isKey: false
  hc: ""
  lc: ""
  fc: ""
- p: name.0
  isKey: false
  hc: under-name-comment
  lc: ""
  fc: ""

Retrieve comment - array example

From the previous example, we know that the comment is on the first child as a headComment

Given a sample.yml file of:

name:
  # under-name-comment
  - first-array-child

then

yq '.name[0] | headComment' sample.yml

will output

under-name-comment

Set head comment

Given a sample.yml file of:

a: cat

then

yq '. head_comment="single"' sample.yml

will output

# single
a: cat

Set head comment of a map entry

Given a sample.yml file of:

f: foo
a:
  b: cat

then

yq '(.a | key) head_comment="single"' sample.yml

will output

f: foo
# single
a:
  b: cat

Set foot comment, using an expression

Given a sample.yml file of:

a: cat

then

yq '. foot_comment=.a' sample.yml

will output

a: cat
# cat

Remove comment

Given a sample.yml file of:

a: cat # comment
b: dog # leave this

then

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

will output

a: cat
b: dog # leave this

Remove (strip) all comments

Note the use of ... to ensure key nodes are included.

Given a sample.yml file of:

# hi

a: cat # comment
# great
b: # key comment

then

yq '... comments=""' sample.yml

will output

a: cat
b:

Get line comment

Given a sample.yml file of:

# welcome!

a: cat # meow
# have a great day

then

yq '.a | line_comment' sample.yml

will output

meow

Get head comment

Given a sample.yml file of:

# welcome!

a: cat # meow

# have a great day

then

yq '. | head_comment' sample.yml

will output

welcome!

Head comment with document split

Given a sample.yml file of:

# welcome!
---
# bob
a: cat # meow

# have a great day

then

yq 'head_comment' sample.yml

will output

welcome!
bob

Get foot comment

Given a sample.yml file of:

# welcome!

a: cat # meow

# have a great day
# no really

then

yq '. | foot_comment' sample.yml

will output

have a great day
no really

Compare Operators

Comparison operators (>, >=, <, <=) can be used for comparing scalar values of the same time.

The following types are currently supported:

• numbers
• strings
• datetimes

Related Operators

• equals / not equals (==, !=) operators here
• boolean operators (and, or, any etc) here
• select operator here

Compare numbers (>)

Given a sample.yml file of:

a: 5
b: 4

then

yq '.a > .b' sample.yml

will output

true

Compare equal numbers (>=)

Given a sample.yml file of:

a: 5
b: 5

then

yq '.a >= .b' sample.yml

will output

true

Compare strings

Compares strings by their bytecode.

Given a sample.yml file of:

a: zoo
b: apple

then

yq '.a > .b' sample.yml

will output

true

Compare date times

You can compare date times. Assumes RFC3339 date time format, see date-time operators for more information.

Given a sample.yml file of:

a: 2021-01-01T03:10:00Z
b: 2020-01-01T03:10:00Z

then

yq '.a > .b' sample.yml

will output

true

Both sides are null: > is false

Running

yq --null-input '.a > .b'

will output

false

Both sides are null: >= is true

Running

yq --null-input '.a >= .b'

will output

true

Contains

This returns true if the context contains the passed in parameter, and false otherwise. For arrays, this will return true if the passed in array is contained within the array. For strings, it will return true if the string is a substring.

{% hint style=“warning” %}

Note that, just like jq, when checking if an array of strings contains another, this will use contains and not equals to check each string. This means an expression like contains(["cat"]) will return true for an array ["cats"].

See the “Array has a subset array” example below on how to check for a subset.

{% endhint %}

Array contains array

Array is equal or subset of

Given a sample.yml file of:

- foobar
- foobaz
- blarp

then

yq 'contains(["baz", "bar"])' sample.yml

will output

true

Array has a subset array

Subtract the superset array from the subset, if there’s anything left, it’s not a subset

Given a sample.yml file of:

- foobar
- foobaz
- blarp

then

yq '["baz", "bar"] - . | length == 0' sample.yml

will output

false

Object included in array

Given a sample.yml file of:

"foo": 12
"bar":
  - 1
  - 2
  - "barp": 12
    "blip": 13

then

yq 'contains({"bar": [{"barp": 12}]})' sample.yml

will output

true

Object not included in array

Given a sample.yml file of:

"foo": 12
"bar":
  - 1
  - 2
  - "barp": 12
    "blip": 13

then

yq 'contains({"foo": 12, "bar": [{"barp": 15}]})' sample.yml

will output

false

String contains substring

Given a sample.yml file of:

foobar

then

yq 'contains("bar")' sample.yml

will output

true

String equals string

Given a sample.yml file of:

meow

then

yq 'contains("meow")' sample.yml

will output

true

Create, Collect into Object

This is used to construct objects (or maps). This can be used against existing yaml, or to create fresh yaml documents.

Collect empty object

Running

yq --null-input '{}'

will output

{}

Wrap (prefix) existing object

Given a sample.yml file of:

name: Mike

then

yq '{"wrap": .}' sample.yml

will output

wrap:
  name: Mike

Using splat to create multiple objects

Given a sample.yml file of:

name: Mike
pets:
  - cat
  - dog

then

yq '{.name: .pets.[]}' sample.yml

will output

Mike: cat
Mike: dog

Working with multiple documents

Given a sample.yml file of:

name: Mike
pets:
  - cat
  - dog
---
name: Rosey
pets:
  - monkey
  - sheep

then

yq '{.name: .pets.[]}' sample.yml

will output

Mike: cat
Mike: dog
---
Rosey: monkey
Rosey: sheep

Creating yaml from scratch

Running

yq --null-input '{"wrap": "frog"}'

will output

wrap: frog

Creating yaml from scratch with multiple objects

Running

yq --null-input '(.a.b = "foo") | (.d.e = "bar")'

will output

a:
  b: foo
d:
  e: bar

Date Time

Various operators for parsing and manipulating dates.

Date time formattings

This uses Golang’s built in time library for parsing and formatting date times.

When not specified, the RFC3339 standard is assumed 2006-01-02T15:04:05Z07:00 for parsing.

To specify a custom parsing format, use the with_dtf operator. The first parameter sets the datetime parsing format for the expression in the second parameter. The expression can be any valid yq expression tree.

yq 'with_dtf("myformat"; .a + "3h" | tz("Australia/Melbourne"))'

See the library docs for examples of formatting options.

Timezones

This uses Golang’s built in LoadLocation function to parse timezones strings. See the library docs for more details.

Durations

Durations are parsed using Golang’s built in ParseDuration function.

You can add durations to time using the + operator.

Format: from standard RFC3339 format

Providing a single parameter assumes a standard RFC3339 datetime format. If the target format is not a valid yaml datetime format, the result will be a string tagged node.

Given a sample.yml file of:

a: 2001-12-15T02:59:43.1Z

then

yq '.a |= format_datetime("Monday, 02-Jan-06 at 3:04PM")' sample.yml

will output

a: Saturday, 15-Dec-01 at 2:59AM

Format: from custom date time

Use with_dtf to set a custom datetime format for parsing.

Given a sample.yml file of:

a: Saturday, 15-Dec-01 at 2:59AM

then

yq '.a |= with_dtf("Monday, 02-Jan-06 at 3:04PM"; format_datetime("2006-01-02"))' sample.yml

will output

a: 2001-12-15

Format: get the day of the week

Given a sample.yml file of:

a: 2001-12-15

then

yq '.a | format_datetime("Monday")' sample.yml

will output

Saturday

Now

Given a sample.yml file of:

a: cool

then

yq '.updated = now' sample.yml

will output

a: cool
updated: 2021-05-19T01:02:03Z

From Unix

Converts from unix time. Note, you don’t have to pipe through the tz operator :)

Running

yq --null-input '1675301929 | from_unix | tz("UTC")'

will output

2023-02-02T01:38:49Z

To Unix

Converts to unix time

Running

yq --null-input 'now | to_unix'

will output

1621386123

Timezone: from standard RFC3339 format

Returns a new datetime in the specified timezone. Specify standard IANA Time Zone format or ‘utc’, ’local’. When given a single parameter, this assumes the datetime is in RFC3339 format.

Given a sample.yml file of:

a: cool

then

yq '.updated = (now | tz("Australia/Sydney"))' sample.yml

will output

a: cool
updated: 2021-05-19T11:02:03+10:00

Timezone: with custom format

Specify standard IANA Time Zone format or ‘utc’, ’local’

Given a sample.yml file of:

a: Saturday, 15-Dec-01 at 2:59AM GMT

then

yq '.a |= with_dtf("Monday, 02-Jan-06 at 3:04PM MST"; tz("Australia/Sydney"))' sample.yml

will output

a: Saturday, 15-Dec-01 at 1:59PM AEDT

Add and tz custom format

Specify standard IANA Time Zone format or ‘utc’, ’local’

Given a sample.yml file of:

a: Saturday, 15-Dec-01 at 2:59AM GMT

then

yq '.a |= with_dtf("Monday, 02-Jan-06 at 3:04PM MST"; tz("Australia/Sydney"))' sample.yml

will output

a: Saturday, 15-Dec-01 at 1:59PM AEDT

Date addition

Given a sample.yml file of:

a: 2021-01-01T00:00:00Z

then

yq '.a += "3h10m"' sample.yml

will output

a: 2021-01-01T03:10:00Z

Date subtraction

You can subtract durations from dates. Assumes RFC3339 date time format, see date-time operators for more information.

Given a sample.yml file of:

a: 2021-01-01T03:10:00Z

then

yq '.a -= "3h10m"' sample.yml

will output

a: 2021-01-01T00:00:00Z

Date addition - custom format

Given a sample.yml file of:

a: Saturday, 15-Dec-01 at 2:59AM GMT

then

yq 'with_dtf("Monday, 02-Jan-06 at 3:04PM MST"; .a += "3h1m")' sample.yml

will output

a: Saturday, 15-Dec-01 at 6:00AM GMT

Date script with custom format

You can embed full expressions in with_dtf if needed.

Given a sample.yml file of:

a: Saturday, 15-Dec-01 at 2:59AM GMT

then

yq 'with_dtf("Monday, 02-Jan-06 at 3:04PM MST"; .a = (.a + "3h1m" | tz("Australia/Perth")))' sample.yml

will output

a: Saturday, 15-Dec-01 at 2:00PM AWST

Delete

Deletes matching entries in maps or arrays.

Delete entry in map

Given a sample.yml file of:

a: cat
b: dog

then

yq 'del(.b)' sample.yml

will output

a: cat

Delete nested entry in map

Given a sample.yml file of:

a:
  a1: fred
  a2: frood

then

yq 'del(.a.a1)' sample.yml

will output

a:
  a2: frood

Delete entry in array

Given a sample.yml file of:

- 1
- 2
- 3

then

yq 'del(.[1])' sample.yml

will output

- 1
- 3

Delete nested entry in array

Given a sample.yml file of:

- a: cat
  b: dog

then

yq 'del(.[0].a)' sample.yml

will output

- b: dog

Delete no matches

Given a sample.yml file of:

a: cat
b: dog

then

yq 'del(.c)' sample.yml

will output

a: cat
b: dog

Delete matching entries

Given a sample.yml file of:

a: cat
b: dog
c: bat

then

yq 'del( .[] | select(. == "*at") )' sample.yml

will output

b: dog

Recursively delete matching keys

Given a sample.yml file of:

a:
  name: frog
  b:
    name: blog
    age: 12

then

yq 'del(.. | select(has("name")).name)' sample.yml

will output

a:
  b:
    age: 12

Divide

Divide behaves differently according to the type of the LHS:

• strings: split by the divider
• number: arithmetic division

String split

Given a sample.yml file of:

a: cat_meow
b: _

then

yq '.c = .a / .b' sample.yml

will output

a: cat_meow
b: _
c:
  - cat
  - meow

Number division

The result during division is calculated as a float

Given a sample.yml file of:

a: 12
b: 2.5

then

yq '.a = .a / .b' sample.yml

will output

a: 4.8
b: 2.5

Number division by zero

Dividing by zero results in +Inf or -Inf

Given a sample.yml file of:

a: 1
b: -1

then

yq '.a = .a / 0 | .b = .b / 0' sample.yml

will output

a: !!float +Inf
b: !!float -Inf

Document Index

Use the documentIndex operator (or the di shorthand) to select nodes of a particular document.

Retrieve a document index

Given a sample.yml file of:

a: cat
---
a: frog

then

yq '.a | document_index' sample.yml

will output

0
---
1

Retrieve a document index, shorthand

Given a sample.yml file of:

a: cat
---
a: frog

then

yq '.a | di' sample.yml

will output

0
---
1

Filter by document index

Given a sample.yml file of:

a: cat
---
a: frog

then

yq 'select(document_index == 1)' sample.yml

will output

a: frog

Filter by document index shorthand

Given a sample.yml file of:

a: cat
---
a: frog

then

yq 'select(di == 1)' sample.yml

will output

a: frog

Print Document Index with matches

Given a sample.yml file of:

a: cat
---
a: frog

then

yq '.a | ({"match": ., "doc": document_index})' sample.yml

will output

match: cat
doc: 0
---
match: frog
doc: 1

Encode / Decode

Encode operators will take the piped in object structure and encode it as a string in the desired format. The decode operators do the opposite, they take a formatted string and decode it into the relevant object structure.

Note that you can optionally pass an indent value to the encode functions (see below).

These operators are useful to process yaml documents that have stringified embedded yaml/json/props in them.

See CSV and TSV documentation for accepted formats.

XML uses the --xml-attribute-prefix and xml-content-name flags to identify attributes and content fields.

Base64 assumes rfc4648 encoding. Encoding and decoding both assume that the content is a utf-8 string and not binary content.

Encode value as json string

Given a sample.yml file of:

a:
  cool: thing

then

yq '.b = (.a | to_json)' sample.yml

will output

a:
  cool: thing
b: |
  {
    "cool": "thing"
  }  

Encode value as json string, on one line

Pass in a 0 indent to print json on a single line.

Given a sample.yml file of:

a:
  cool: thing

then

yq '.b = (.a | to_json(0))' sample.yml

will output

a:
  cool: thing
b: '{"cool":"thing"}'

Encode value as json string, on one line shorthand

Pass in a 0 indent to print json on a single line.

Given a sample.yml file of:

a:
  cool: thing

then

yq '.b = (.a | @json)' sample.yml

will output

a:
  cool: thing
b: '{"cool":"thing"}'

Decode a json encoded string

Keep in mind JSON is a subset of YAML. If you want idiomatic yaml, pipe through the style operator to clear out the JSON styling.

Given a sample.yml file of:

a: '{"cool":"thing"}'

then

yq '.a | from_json | ... style=""' sample.yml

will output

cool: thing

Encode value as props string

Given a sample.yml file of:

a:
  cool: thing

then

yq '.b = (.a | @props)' sample.yml

will output

a:
  cool: thing
b: |
  cool = thing  

Decode props encoded string

Given a sample.yml file of:

a: |-
  cats=great
  dogs=cool as well  

then

yq '.a |= @propsd' sample.yml

will output

a:
  cats: great
  dogs: cool as well

Decode csv encoded string

Given a sample.yml file of:

a: |-
  cats,dogs
  great,cool as well  

then

yq '.a |= @csvd' sample.yml

will output

a:
  - cats: great
    dogs: cool as well

Decode tsv encoded string

Given a sample.yml file of:

a: |-
  cats	dogs
  great	cool as well  

then

yq '.a |= @tsvd' sample.yml

will output

a:
  - cats: great
    dogs: cool as well

Encode value as yaml string

Indent defaults to 2

Given a sample.yml file of:

a:
  cool:
    bob: dylan

then

yq '.b = (.a | to_yaml)' sample.yml

will output

a:
  cool:
    bob: dylan
b: |
  cool:
    bob: dylan  

Encode value as yaml string, with custom indentation

You can specify the indentation level as the first parameter.

Given a sample.yml file of:

a:
  cool:
    bob: dylan

then

yq '.b = (.a | to_yaml(8))' sample.yml

will output

a:
  cool:
    bob: dylan
b: |
  cool:
          bob: dylan  

Decode a yaml encoded string

Given a sample.yml file of:

a: 'foo: bar'

then

yq '.b = (.a | from_yaml)' sample.yml

will output

a: 'foo: bar'
b:
  foo: bar

Update a multiline encoded yaml string

Given a sample.yml file of:

a: |
  foo: bar
  baz: dog  

then

yq '.a |= (from_yaml | .foo = "cat" | to_yaml)' sample.yml

will output

a: |
  foo: cat
  baz: dog  

Update a single line encoded yaml string

Given a sample.yml file of:

a: 'foo: bar'

then

yq '.a |= (from_yaml | .foo = "cat" | to_yaml)' sample.yml

will output

a: 'foo: cat'

Encode array of scalars as csv string

Scalars are strings, numbers and booleans.

Given a sample.yml file of:

- cat
- thing1,thing2
- true
- 3.40

then

yq '@csv' sample.yml

will output

cat,"thing1,thing2",true,3.40

Encode array of arrays as csv string

Given a sample.yml file of:

- - cat
  - thing1,thing2
  - true
  - 3.40
- - dog
  - thing3
  - false
  - 12

then

yq '@csv' sample.yml

will output

cat,"thing1,thing2",true,3.40
dog,thing3,false,12

Encode array of arrays as tsv string

Scalars are strings, numbers and booleans.

Given a sample.yml file of:

- - cat
  - thing1,thing2
  - true
  - 3.40
- - dog
  - thing3
  - false
  - 12

then

yq '@tsv' sample.yml

will output

cat	thing1,thing2	true	3.40
dog	thing3	false	12

Encode value as xml string

Given a sample.yml file of:

a:
  cool:
    foo: bar
    +@id: hi