mirror of
https://github.com/taigrr/yq
synced 2025-01-18 04:53:17 -08:00
327 lines
4.7 KiB
Markdown
327 lines
4.7 KiB
Markdown
---
|
|
description: Returns matching nodes/values of a path expression for a given yaml document
|
|
---
|
|
|
|
# Read
|
|
|
|
```text
|
|
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](../usage/path-expressions.md) for more details.
|
|
|
|
## Basic
|
|
|
|
Given a sample.yaml file of:
|
|
|
|
```yaml
|
|
b:
|
|
c: 2
|
|
```
|
|
|
|
then
|
|
|
|
```bash
|
|
yq r sample.yaml b.c
|
|
```
|
|
|
|
will output the value of '2'.
|
|
|
|
## From Stdin
|
|
|
|
Given a sample.yaml file of:
|
|
|
|
```bash
|
|
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
|
|
|
|
```text
|
|
yq r sample.yaml --defaultValue frog path.not.there
|
|
```
|
|
|
|
will yield \(assuming `path.not.there` does not match any nodes\):
|
|
|
|
```text
|
|
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.
|
|
|
|
```yaml
|
|
a:
|
|
thing_a:
|
|
animal: cat
|
|
other:
|
|
animal: frog
|
|
thing_b:
|
|
vehicle: car
|
|
```
|
|
|
|
### Path Only
|
|
|
|
```bash
|
|
yq r --printMode p "a.thing*.*"
|
|
```
|
|
|
|
will print
|
|
|
|
```text
|
|
a.thing_a.animal
|
|
a.thing_b.vehicle
|
|
```
|
|
|
|
### Path and Value
|
|
|
|
```bash
|
|
yq r --printMode pv "a.thing*.*"
|
|
```
|
|
|
|
will print
|
|
|
|
```text
|
|
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:
|
|
|
|
```yaml
|
|
a:
|
|
thing_a:
|
|
animal: cat
|
|
other:
|
|
animal: frog
|
|
thing_b:
|
|
vehicle: car
|
|
```
|
|
|
|
```text
|
|
yq r sample.yaml --collect a.*.animal
|
|
```
|
|
|
|
will print
|
|
|
|
```text
|
|
- 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
|
|
|
|
```text
|
|
animals:
|
|
- cats
|
|
- dog
|
|
- cheetah
|
|
```
|
|
|
|
```text
|
|
yq r sample.yml --length animals
|
|
```
|
|
|
|
will print
|
|
|
|
```text
|
|
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:
|
|
|
|
```text
|
|
yq r sample.yaml --length --printMode pv 'animals.(.==c*)'
|
|
```
|
|
|
|
```text
|
|
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.
|
|
|
|
```text
|
|
yq r sample.yaml --length --collect 'animals.(.==c*)'
|
|
```
|
|
|
|
```text
|
|
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:
|
|
|
|
```yaml
|
|
foo: &foo
|
|
a: 1
|
|
|
|
foobar: *foo
|
|
```
|
|
|
|
### Printing anchors
|
|
|
|
```bash
|
|
yq r sample.yml foo
|
|
```
|
|
|
|
will print out
|
|
|
|
```yaml
|
|
&foo
|
|
a: 1
|
|
```
|
|
|
|
Similarly,
|
|
|
|
```text
|
|
yq r sample.yml foobar
|
|
```
|
|
|
|
prints out
|
|
|
|
```yaml
|
|
*foo
|
|
```
|
|
|
|
### Traversing anchors
|
|
|
|
To traverse an anchor, we need to either explicitly reference merged in values:
|
|
|
|
```text
|
|
yq r sample.yml foobar.a
|
|
```
|
|
|
|
to get
|
|
|
|
```text
|
|
1
|
|
```
|
|
|
|
or we can use deep splat to get all the values
|
|
|
|
```bash
|
|
yq r sample.yml -p pv "foobar.**"
|
|
```
|
|
|
|
prints
|
|
|
|
```yaml
|
|
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:
|
|
|
|
```yaml
|
|
foo: &foo
|
|
a: original
|
|
thing: coolasdf
|
|
thirsty: yep
|
|
|
|
bar: &bar
|
|
b: 2
|
|
thing: coconut
|
|
c: oldbar
|
|
|
|
foobarList:
|
|
<<: [*foo,*bar]
|
|
c: newbar
|
|
```
|
|
|
|
Then
|
|
|
|
```text
|
|
yq r -X sample.yml foobarList
|
|
```
|
|
|
|
yields
|
|
|
|
```text
|
|
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:
|
|
|
|
```yaml
|
|
something: else
|
|
---
|
|
b:
|
|
c: 2
|
|
```
|
|
|
|
then
|
|
|
|
```bash
|
|
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:
|
|
|
|
```yaml
|
|
name: Fred
|
|
age: 22
|
|
---
|
|
name: Stella
|
|
age: 23
|
|
---
|
|
name: Android
|
|
age: 232
|
|
```
|
|
|
|
then
|
|
|
|
```bash
|
|
yq r -d'*' sample.yaml name
|
|
```
|
|
|
|
will output:
|
|
|
|
```text
|
|
Fred
|
|
Stella
|
|
Android
|
|
```
|
|
|