Read

Returns matching nodes/values of a path expression for a given yaml document

yq r <yaml_file|json_file> <path_expression>

Returns the matching nodes of the path expression for the given yaml file (or STDIN).

See docs for path expression for more details.

Basic

Given a sample.yaml file of:

b:
  c: 2

then

yq r sample.yaml b.c

will output the value of '2'.

From Stdin

Given a sample.yaml file of:

cat sample.yaml | yq r - b.c

will output the value of '2'.

Default values

Using the --defaultValue/-D flag you can specify a default value to be printed when no matching nodes are found for an expression

yq r sample.yaml --defaultValue frog path.not.there

will yield (assuming path.not.there does not match any nodes):

frog

Printing matching paths

By default, yq will only print the value of the path expression for the yaml document. By specifying --printMode or -p you can print the matching paths.

a:
  thing_a: 
    animal: cat
  other: 
    animal: frog
  thing_b: 
    vehicle: car

Path Only

yq r --printMode p "a.thing*.*"

will print

a.thing_a.animal
a.thing_b.vehicle

Path and Value

yq r --printMode pv "a.thing*.*"

will print

a.thing_a.animal: cat
a.thing_b.vehicle: car

Collect results into an array

By default, results are printed out line by line as independent matches. This is handy for both readability as well as piping into tools like xargs. However, if you would like to collect the matching results into an array then use the --collect/-c flag. This is particularly useful with the length flag described below.

Given:

a:
  thing_a: 
    animal: cat
  other: 
    animal: frog
  thing_b: 
    vehicle: car

yq r sample.yaml --collect a.*.animal

will print

- cat
- frog

Printing length of the results

Use the --length/-l flag to print the length of results. For arrays this will be the number of items, objects the number of entries and scalars the length of the value.

Given

animals:
  - cats
  - dog
  - cheetah

yq r sample.yml --length animals

will print

3

Length of filtered results

By default, filtered results are printed independently so you will get the length of each result printed on a separate line:

yq r sample.yaml --length --printMode pv 'animals.(.==c*)'

animals.[0]: 4
animals.[2]: 7

However, you'll often want to know the count of the filtered results - use the --collect flag to collect the results in the array. The length will then return the size of the array.

yq r sample.yaml --length --collect 'animals.(.==c*)' 

2

Anchors and Aliases

The read command will print out the anchors of a document and can also traverse them.

Lets take a look at a simple example file:

foo: &foo
  a: 1

foobar: *foo

Printing anchors

yq r sample.yml foo

will print out

&foo
a: 1

Similarly,

yq r sample.yml foobar

prints out

*foo

Traversing anchors

To traverse an anchor, we need to either explicitly reference merged in values:

yq r sample.yml foobar.a

to get

1

or we can use deep splat to get all the values

yq r sample.yml -p pv "foobar.**"

prints

foobar.a: 1

The same methods work for the <<: [*blah, *thing]anchors.

Exploding Anchors

By default anchors are not exploded (or expanded/de-referenced) for viewing, and the yaml is shown as-is. Use the --explodeAnchors/-X flag to show the anchor values.

Given sample.yml:

foo: &foo
  a: original
  thing: coolasdf
  thirsty: yep

bar: &bar
  b: 2
  thing: coconut
  c: oldbar

foobarList:
  <<: [*foo,*bar]
  c: newbar

Then

yq r -X sample.yml foobarList

yields

c: newbar
b: 2
thing: coconut
a: original
thirsty: yep

Note that yq processes the merge anchor list in reverse order, to ensure that the last items in the list override the preceding.

Multiple Documents

Reading from a single document

Given a sample.yaml file of:

something: else
---
b:
  c: 2

then

yq r -d1 sample.yaml b.c

will output the value of '2'.

Read from all documents

Reading all documents will return the result as an array. This can be converted to json using the '-j' flag if desired.

Given a sample.yaml file of:

name: Fred
age: 22
---
name: Stella
age: 23
---
name: Android
age: 232

then

yq r -d'*' sample.yaml name

will output:

Fred
Stella
Android