# Path Expressions *As a general rule, you should wrap paths in quotes to prevent your CLI from processing `*`, `[]` and other special characters.* ## Simple expressions ### Maps `'a.b.c'` ```yaml a: b: c: thing # MATCHES ``` ### Arrays `'a.b[1].c'` ```yaml a: b: - c: thing0 - c: thing1 # MATCHES - c: thing2 ``` #### Appending to arrays (e.g. when using the write command) `'a.b[+].c'` ```yaml a: b: - c: thing0 ``` Will add a new entry: ```yaml a: b: - c: thing0 - c: thing1 # NEW entry from [+] on B array. ``` #### Negative Array indexes Negative array indexes can be used to traverse the array in reverse `'a.b[-1].c'` Will access the last element in the `b` array and yield: ```yaml thing2 ``` ## Splat ### Maps `'a.*.c'` ```yaml a: b1: c: thing # MATCHES d: whatever b2: c: thing # MATCHES f: something irrelevant ``` #### Prefix splat `'bob.item*.cats'` ```yaml bob: item: cats: bananas # MATCHES something: cats: lemons itemThing: cats: more bananas # MATCHES item2: cats: apples # MATCHES thing: cats: oranges ``` ### Arrays `'a.b[*].c'` ```yaml a: b: - c: thing0 # MATCHES d: what..ever - c: thing1 # MATCHES d: blarh - c: thing2 # MATCHES f: thingamabob ``` ## Deep Splat `**` will match arbitrary nodes for both maps and arrays: `'a.**.c'` ```yaml a: b1: c: thing1 # MATCHES d: cat cat b2: c: thing2 # MATCHES d: dog dog b3: d: - f: c: thing3 # MATCHES d: beep - f: g: c: thing4 # MATCHES d: boop - d: mooo ``` ## Search by children nodes You can search children by nodes - note that this will return the *parent* of the matching expression, in the example below the parent(s) will be the matching indices of the 'a' array. We can then navigate down to get 'b.c' of each matching indice. `'a.(b.d==cat).b.c'` ```yaml a: - b: c: thing0 d: leopard ba: fast - b: c: thing1 # MATCHES d: cat ba: meowy - b: c: thing2 d: caterpillar ba: icky - b: c: thing3 # MATCHES d: cat ba: also meowy ``` ### With prefixes `'a.(b.d==cat*).c'` ```yaml a: - b: c: thing0 d: leopard ba: fast - b: c: thing1 # MATCHES d: cat ba: meowy - b: c: thing2 # MATCHES d: caterpillar ba: icky - b: c: thing3 # MATCHES d: cat ba: also meowy ``` ### Matching children values `'animals(.==cat)'` ```yaml animals: - dog - cat # MATCHES - rat ``` this also works in maps, and with prefixes `'animals(.==c*)'` ```yaml animals: friendliest: cow # MATCHES favourite: cat # MATCHES smallest: rat ``` ## Special Characters When your yaml field has special characters that overlap with `yq` path expression characters, you will need to escape them in order for the command to work. ### Keys with dots When specifying a key that has a dot use key lookup indicator. ```yaml b: foo.bar: 7 ``` ```bash yaml r sample.yaml 'b."foo.bar"' ``` ```bash yaml w sample.yaml 'b."foo.bar"' 9 ``` Any valid yaml key can be specified as part of a key lookup. Note that the path is in single quotes to avoid the double quotes being interpreted by your shell. ### Keys (and values) with leading dashes The flag terminator needs to be used to stop the app from attempting to parse the subsequent arguments as flags, if they start if a dash. ```bash yq n -j -- --key --value ``` Will result in ``` --key: --value ``` --- # 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/usage/path-expressions.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.