4.7 KiB
description
| description |
|---|
| Returns matching nodes/values of a path expression for a given yaml document |
Read
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