# Read ``` yq r ``` Returns the matching nodes of the path expression for the given yaml file (or STDIN). See docs for [path expression](/yq/v3.x/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 ``` 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. ```yaml a: thing_a: animal: cat other: animal: frog thing_b: vehicle: car ``` ### Path Only ```bash yq r --printMode p "a.thing*.*" ``` will print ``` a.thing_a.animal a.thing_b.vehicle ``` ### Path and Value ```bash 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: ```yaml 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: ```yaml foo: &foo a: 1 foobar: *foo ``` ### Printing anchors ```bash yq r sample.yml foo ``` will print out ```yaml &foo a: 1 ``` Similarly, ``` yq r sample.yml foobar ``` prints out ```yaml *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 ```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 ``` 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: ```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: ``` Fred Stella Android ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://mikefarah.gitbook.io/yq/v3.x/commands/read.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.