yq

https://mikefarah.gitbook.io/yq
Admin
yq is a portable command-line YAML processor that allows you to parse, query, and transform YAML,...
Tokens:156,715
Snippets:1,599
Trust Score:10
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Output of file_index example

Source: https://mikefarah.gitbook.io/yq/operators/file-operators

Expected output of the 'file_index' example.

```output
0
```

--------------------------------

### Sample YAML for filename example

Source: https://mikefarah.gitbook.io/yq/operators/file-operators

Sample input file used in the filename example.

```yaml
a: cat
```

--------------------------------

### Output of filename example

Source: https://mikefarah.gitbook.io/yq/operators/file-operators

Expected output of the 'filename' example.

```output
sample.yml
```

--------------------------------

### Output of multi-file file_index example

Source: https://mikefarah.gitbook.io/yq/operators/file-operators

Expected output of the multi-file file_index example.

```output
0
1
```

--------------------------------

### Sample properties file (small.properties)

Source: https://mikefarah.gitbook.io/yq/operators/load

Sample properties file used in load_props examples.

```properties
this.is = a properties file

```

--------------------------------

### Sample YAML file (thing.yml)

Source: https://mikefarah.gitbook.io/yq/operators/load

Sample YAML file used in load examples.

```yaml
a: apple is included
b: cool

```

--------------------------------

### Sample XML file (small.xml)

Source: https://mikefarah.gitbook.io/yq/operators/load

Sample XML file used in load_xml examples.

```xml
<this>is some xml</this>

```

--------------------------------

### Simple load example

Source: https://mikefarah.gitbook.io/yq/operators/load

Loads a YAML file referenced by a path in the document.

```yaml
myFile: ../../examples/thing.yml

```

```bash
yq 'load(.myFile)' sample.yml

```

```yaml
a: apple is included
b: cool.

```

--------------------------------

### Sample base64 file (base64.txt)

Source: https://mikefarah.gitbook.io/yq/operators/load

Sample base64 encoded file used in load_base64 examples.

```text
bXkgc2VjcmV0IGNoaWxsaSByZWNpcGUgaXMuLi4u

```

--------------------------------

### yq eval command examples

Source: https://mikefarah.gitbook.io/yq/commands/evaluate

Examples of using the eval command: running an expression against multiple files, piping from STDIN with '-', printing a file, creating a new YAML document with -n, and updating a file in place with -i.

```bash
# runs the expression against each file, in series
yq '.a.b | length' f1.yml f2.yml 

# '-' will pipe from STDIN
cat file.yml | yq '.a.b' f1.yml -  f2.yml

# prints out the file
yq sample.yaml 
cat sample.yml | yq e

# prints a new yaml document
yq -n '.a.b.c = "cat"' 

# updates file.yaml directly
yq '.a.b = "cool"' -i file.yaml 
```

--------------------------------

### sample.yml with merge anchors

Source: https://mikefarah.gitbook.io/yq/operators/traverse-read

Sample YAML file with merge anchors used in the legacy and fixed merge anchor examples.

```yaml
foo: &foo
  a: foo_a
  thing: foo_thing
  c: foo_c
bar: &bar
  b: bar_b
  thing: bar_thing
  c: bar_c
foobarList:
  b: foobarList_b
  <<:
    - *foo
    - *bar
  c: foobarList_c
foobar:
  c: foobar_c
  <<: *foo
  thing: foobar_thing
```

--------------------------------

### Simple array_to_map example

Source: https://mikefarah.gitbook.io/yq/operators/array-to-map

A simple example showing how to use the array_to_map operator on a sample.yml file. The input array contains null values and a string, and the output map uses the index of the non-null value as the key.

```yaml
cool:
  - null
  - null
  - hello
```

```bash
yq '.cool |= array_to_map' sample.yml
```

```yaml
cool:
  2: hello
```

--------------------------------

### Sample YAML input for yq logic example

Source: https://mikefarah.gitbook.io/yq/usage/tips-and-tricks

Sample YAML input used to demonstrate replacing if/elif/else logic with yq's with and select expressions.

```yaml
- animal: cat
- animal: dog
- animal: frog
```

--------------------------------

### String length example

Source: https://mikefarah.gitbook.io/yq/operators/length

Returns the length of a string. Given a sample.yml with 'a: cat', the command 'yq '.a | length' sample.yml' outputs 3.

```yaml
a: cat
```

```bash
yq '.a | length' sample.yml
```

```text
3
```

--------------------------------

### Reduce operator example

Source: https://mikefarah.gitbook.io/yq/operators/reduce

A simple example of the reduce operator that sums all elements in an array.

```yq
.[] as $item ireduce (0; . + $item)
```

--------------------------------

### yes and no are strings example

Source: https://mikefarah.gitbook.io/yq/operators/boolean-operators

Given a sample.yml with `- yes` and `- no`, running `yq '.[] | tag' sample.yml` outputs `!!str` for each, confirming they are strings in YAML 1.2.

```yaml
- yes
- no
```

```bash
yq '.[] | tag' sample.yml
```

```yaml
!!str
!!str
```

--------------------------------

### String equals string - sample.yml

Source: https://mikefarah.gitbook.io/yq/operators/contains

Sample YAML file used for the 'String equals string' example. It contains the string 'meow'.

```yaml
meow

```

--------------------------------

### Encode CSV simple: sample.yml

Source: https://mikefarah.gitbook.io/yq/usage/csv-tsv

Input YAML file for the simple CSV encoding example.

```yaml
- [i, like, csv]
- [because, excel, is, cool]

```

--------------------------------

### Flatten sample.yml input

Source: https://mikefarah.gitbook.io/yq/operators/flatten

Sample YAML file used as input for the flatten operator examples.

```yaml
- 1
- - 2
- - - 3

```

--------------------------------

### and operator example

Source: https://mikefarah.gitbook.io/yq/operators/boolean-operators

Runs `yq --null-input 'true and false'` which outputs `false`.

```bash
yq --null-input 'true and false'
```

```yaml
false
```

--------------------------------

### Install zsh completions for each session

Source: https://mikefarah.gitbook.io/yq/commands/shell-completion

Installs zsh completions for each session. A new shell is required for the setup to take effect.

```bash
yq shell-completion zsh > "${fpath[1]}/_yq"
```

--------------------------------

### Map length example

Source: https://mikefarah.gitbook.io/yq/operators/length

Returns the number of entries in a map. Given a sample.yml with 'a: cat' and 'c: dog', the command 'yq 'length' sample.yml' outputs 2.

```yaml
a: cat
c: dog
```

```bash
yq 'length' sample.yml
```

```text
2
```

--------------------------------

### Array length example

Source: https://mikefarah.gitbook.io/yq/operators/length

Returns the number of elements in an array. Given a sample.yml with four elements, the command 'yq 'length' sample.yml' outputs 4.

```yaml
- 2
- 4
- 6
- 8
```

```bash
yq 'length' sample.yml
```

```text
4
```

--------------------------------

### Add to null with `+`

Source: https://mikefarah.gitbook.io/yq/operators/add

Adding to `null` returns the RHS value. This example uses `--null-input` to start with a null document.

```bash
yq --null-input 'null + "cat"'

```

```yaml
cat

```

--------------------------------

### Get line of value node

Source: https://mikefarah.gitbook.io/yq/operators/line

Returns the line number of the value node for the key 'b' in sample.yml. The line starts from 1, and the output is 3.

```yaml
a: cat
b:
  c: cat
```

```bash
yq '.b | line' sample.yml
```

```text
3
```

--------------------------------

### alias (get)

Source: https://mikefarah.gitbook.io/yq/operators/anchor-and-alias-operators

Gets the alias name of a node.

```APIDOC
## alias

### Description
Gets the alias name of a node.

### Usage
`yq '.a | alias' sample.yml`

### Example
Given `sample.yml`:
```yaml
b: &billyBob meow
a: *billyBob
```

Output:
```yaml
billyBob
```
```

--------------------------------

### anchor (get)

Source: https://mikefarah.gitbook.io/yq/operators/anchor-and-alias-operators

Gets the anchor name of a node.

```APIDOC
## anchor

### Description
Gets the anchor name of a node.

### Usage
`yq '.a | anchor' sample.yml`

### Example
Given `sample.yml`:
```yaml
a: &billyBob cat
```

Output:
```yaml
billyBob
```
```

--------------------------------

### Install fish completions for each session

Source: https://mikefarah.gitbook.io/yq/commands/shell-completion

Installs fish completions for each session.

```bash
yq shell-completion fish > ~/.config/fish/completions/yq.fish
```

--------------------------------

### Initial context diagram for yq expression

Source: https://mikefarah.gitbook.io/yq/how-it-works

Diagram showing the initial context at the root of the YAML document. The entire document is the starting context for the yq expression.

```text
root
└── items
    ├── name: apple
    │   type: fruit
    ├── name: carrot
    │   type: vegetable
    └── name: banana
        type: fruit
```

--------------------------------

### Install bash completions on macOS

Source: https://mikefarah.gitbook.io/yq/commands/shell-completion

Installs bash completions for each session on macOS.

```bash
yq shell-completion bash > /usr/local/etc/bash_completion.d/yq
```

--------------------------------

### Create new yaml documents: v3 vs v4

Source: https://mikefarah.gitbook.io/yq/upgrading-from-v3

Shows how to create new yaml documents in v3 using the n command and in v4 using the --null-input/-n flag and piping the output to a file.

```bash
yq n b.c cat
```

```bash
yq -n '.b.c = "cat"'
```

--------------------------------

### Install bash completions on Linux

Source: https://mikefarah.gitbook.io/yq/commands/shell-completion

Installs bash completions for each session on Linux.

```bash
yq shell-completion bash > /etc/bash_completion.d/yq 
```

--------------------------------

### Set on empty document: create document with setpath

Source: https://mikefarah.gitbook.io/yq/operators/path

Using --null-input creates a new document from scratch. The output shows the resulting document with the set path.

```bash
yq --null-input 'setpath(["a", "b"]; "things")'
```

```yaml
a:
  b: things
```

--------------------------------

### format_datetime: Get day of week

Source: https://mikefarah.gitbook.io/yq/operators/datetime

Gets the day of the week from a datetime using format_datetime with a format string.

```yaml
a: 2001-12-15
```

```bash
yq '.a | format_datetime("Monday")' sample.yml
```

```text
Saturday
```

--------------------------------

### Sample YAML with unsorted keys

Source: https://mikefarah.gitbook.io/yq/operators/sort-keys

Sample YAML file (sample.yml) with unsorted keys used to demonstrate the sort_keys operator on a single map.

```yaml
c: frog
a: blah
b: bing
```

--------------------------------

### Prefix yaml: v3 vs v4

Source: https://mikefarah.gitbook.io/yq/upgrading-from-v3

Shows how to prefix yaml in v3 using the p command and in v4 using the Create / Collect Into Object operator.

```bash
yq p data1.yaml c.d
```

```bash
yq '{"c": {"d": . }}' data1.yml
```

--------------------------------

### Get line of key node

Source: https://mikefarah.gitbook.io/yq/operators/line

Pipes through the key operator to get the line of the key node for 'b' in sample.yml. The output is 2.

```yaml
a: cat
b:
  c: cat
```

```bash
yq '.b | key | line' sample.yml
```

```text
2
```

--------------------------------

### YAML block scalar for newline example

Source: https://mikefarah.gitbook.io/yq/operators/string-operators

The target YAML structure used in the newline examples: a block scalar 'a: |' containing 'cat'.

```yaml
a: |
  cat
```

--------------------------------

### Create YAML file with yq --null-input

Source: https://mikefarah.gitbook.io/yq/operators/assign-update

Use yq with --null-input to create a YAML file from scratch, setting multiple fields in one expression.

```bash
yq --null-input '.a.b = "cat" | .x = "frog"'
```

```yaml
a:
  b: cat
x: frog
```

--------------------------------

### Get parents

Source: https://mikefarah.gitbook.io/yq/operators/parent

Gets all parent nodes. The expression '.a.b.c | parents' returns a sequence of all ancestors of the node 'c', from the immediate parent up to the root.

```yaml
a:
  b:
    c: cat
```

```bash
yq '.a.b.c | parents' sample.yml
```

```yaml
- c: cat
- b:
    c: cat
- a:
    b:
      c: cat
```

--------------------------------

### Sample YAML data for unwrapScalar

Source: https://mikefarah.gitbook.io/yq/usage/output-format

Sample YAML data used to demonstrate the --unwrapScalar=false flag.

```yaml
a: "Things" # cool stuff

```

--------------------------------

### Compare yaml files: v3 vs v4

Source: https://mikefarah.gitbook.io/yq/upgrading-from-v3

Shows how to compare yaml files in v3 using the compare command and in v4 using diff with process substitution and the -P flag.

```bash
yq compare --prettyPrint file1.yml file2.yml 
```

```bash
diff <(yq -P file1.yml) <(yq -P file2.yml)
```

--------------------------------

### Get the top (root) parent

Source: https://mikefarah.gitbook.io/yq/operators/parent

Gets the top (root) parent using a negative index. 'parent(-1)' returns the root node, which is the top-level mapping.

```yaml
a:
  b:
    c: cat
```

```bash
yq '.a.b.c | parent(-1)' sample.yml
```

```yaml
a:
  b:
    c: cat
```

--------------------------------

### Get parent attribute

Source: https://mikefarah.gitbook.io/yq/operators/parent

Gets an attribute of the parent node. The expression '.. | select(. == "banana") | parent.name' returns the 'name' attribute of the parent of the node with value 'banana', which is 'sam'.

```yaml
a:
  fruit: apple
  name: bob
b:
  fruit: banana
  name: sam
```

```bash
yq '.. | select(. == "banana") | parent.name' sample.yml
```

```yaml
sam
```

--------------------------------

### Match string example

Source: https://mikefarah.gitbook.io/yq/operators/equals

Given a sample.yml file with a list of strings, this yq command checks if each element matches the pattern '*at'. Outputs true for 'cat' and 'goat', false for 'dog'.

```yaml
- cat
- goat
- dog
```

```yq
yq '.[] | (. == "*at")' sample.yml
```

```yaml
true
true
false
```

--------------------------------

### path with select

Source: https://mikefarah.gitbook.io/yq/operators/path

Gets the path of nodes that match a select condition.

```APIDOC
## path with select

### Description
Use the `path` operator with `select` to get the path of matching nodes.

### Usage
`yq '.a.[] | select(. == "dog") | path' sample.yml`

### Example
Given sample.yml:
```
a:
  - cat
  - dog
```

Command:
```
yq '.a.[] | select(. == "dog") | path' sample.yml
```

Output:
```
- a
- 1
```

```

--------------------------------

### to_json

Source: https://mikefarah.gitbook.io/yq/operators/encode-decode

Documentation for the to_json encode operator, including usage and examples.

```APIDOC
## to_json

### Description
Encodes the piped-in object structure as a JSON string. Optionally accepts an indent value to control formatting.

### Usage
`yq '.b = (.a | to_json)' sample.yml`

### Parameters
- **indent** (integer) - Optional - Number of spaces to indent the JSON output. Use 0 to print on a single line.

### Example
Given `sample.yml`:
```yaml
a:
  cool: thing
```

Command:
```
yq '.b = (.a | to_json)' sample.yml
```

Output:
```yaml
a:
  cool: thing
b: |
  {
    "cool": "thing"
  }
```

### Example with indent 0
Command:
```
yq '.b = (.a | to_json(0))' sample.yml
```

Output:
```yaml
a:
  cool: thing
b: '{"cool":"thing"}'
```
```

--------------------------------

### Matching nodes with select, equals and or

Source: https://mikefarah.gitbook.io/yq/operators/boolean-operators

Given a sample.yml with three objects, running `yq '[.[] | select(.a == "cat" or .b == "dog")]' sample.yml` filters and outputs the matching nodes.

```yaml
- a: bird
  b: dog
- a: frog
  b: bird
- a: cat
  b: fly
```

```bash
yq '[.[] | select(.a == "cat" or .b == "dog")]' sample.yml
```

```yaml
- a: bird
  b: dog
- a: cat
  b: fly
```

--------------------------------

### Simple map navigation with yq '.a'

Source: https://mikefarah.gitbook.io/yq/operators/traverse-read

Navigates a simple map with the traverse operator. Given sample.yml containing a map with key 'a', the command yq '.a' sample.yml outputs the value of that key.

```yaml
a:
  b: apple
```

```bash
yq '.a' sample.yml
```

```yaml
b: apple
```

--------------------------------

### path | .[-1] with select

Source: https://mikefarah.gitbook.io/yq/operators/path

Gets the index of matching nodes using select and path.

```APIDOC
## path | .[-1] with select

### Description
Get the array index of matching nodes by combining `select`, `path`, and `.[-1]`.

### Usage
`yq '.a.[] | select(. == "dog") | path | .[-1]' sample.yml`

### Example
Given sample.yml:
```
a:
  - cat
  - dog
```

Command:
```
yq '.a.[] | select(. == "dog") | path | .[-1]' sample.yml
```

Output:
```
1
```

```

--------------------------------

### First column is 1

Source: https://mikefarah.gitbook.io/yq/operators/column

Given a sample.yml file with a single key 'a', the command 'yq '.a | key | column' sample.yml' outputs '1', confirming the first column is 1.

```yaml
a: cat

```

```bash
yq '.a | key | column' sample.yml

```

```text
1

```

--------------------------------

### Create YAML from scratch with yq --null-input

Source: https://mikefarah.gitbook.io/yq/operators/create-collect-into-object

Creates a YAML object from scratch using the --null-input flag. The output is a simple object with a single key-value pair.

```bash
yq --null-input '{"wrap": "frog"}'
```

```yaml
wrap: frog
```

--------------------------------

### Create a new YAML file with yq -n

Source: https://mikefarah.gitbook.io/yq/usage/tips-and-tricks

Creates a new YAML file with the specified content using the -n flag to start with a blank document and redirects the output to newfile.yml.

```bash
yq -n '.someNew="content"' > newfile.yml
```

--------------------------------

### all returns true for an empty array

Source: https://mikefarah.gitbook.io/yq/operators/boolean-operators

Given a sample.yml with `[]`, running `yq 'all' sample.yml` outputs `true`.

```yaml
[]
```

```bash
yq 'all' sample.yml
```

```yaml
true
```

--------------------------------

### or operator example

Source: https://mikefarah.gitbook.io/yq/operators/boolean-operators

Runs `yq --null-input 'true or false'` which outputs `true`.

```bash
yq --null-input 'true or false'
```

```yaml
true
```

--------------------------------

### Get filename (of current document)

Source: https://mikefarah.gitbook.io/yq/operators/file-operators

Outputs the filename of the current document. For sample.yml, the output is 'sample.yml'.

```bash
yq 'filename' sample.yml
```

--------------------------------

### Sample YAML with nested maps and arrays

Source: https://mikefarah.gitbook.io/yq/operators/sort-keys

Sample YAML file (sample.yml) with nested maps and arrays used to demonstrate recursive key sorting. Note that array elements are left unsorted.

```yaml
bParent:
  c: dog
  array:
    - 3
    - 1
    - 2
aParent:
  z: donkey
  x:
    - c: yum
      b: delish
    - b: ew
      a: apple
```

--------------------------------

### Create YAML from scratch with multiple objects using yq

Source: https://mikefarah.gitbook.io/yq/operators/create-collect-into-object

Creates a YAML document from scratch with multiple nested objects using the --null-input flag and assignment expressions. The output is a YAML object with two nested keys.

```bash
yq --null-input '(.a.b = "foo") | (.d.e = "bar")'
```

```yaml
a:
  b: foo
d:
  e: bar
```

--------------------------------

### Multiple documents: v3 vs v4

Source: https://mikefarah.gitbook.io/yq/upgrading-from-v3

Shows how to read from a specific document in v3 using -d and in v4 using the documentIndex operator.

```bash
yq r -d1 sample.yaml 'b.c'
```

```bash
yq 'select(documentIndex == 1) | .b.c' sample.yml
```

--------------------------------

### Find nodes: v3 vs v4

Source: https://mikefarah.gitbook.io/yq/upgrading-from-v3

Shows how to find nodes matching a condition in v3 and the equivalent v4 expression using select.

```bash
yq r sample.yaml 'a.(b.d==cat).f'
```

```bash
yq '.a | select(.b.d == "cat") | .f' sample.yaml
```

--------------------------------

### contains

Source: https://mikefarah.gitbook.io/yq/operators/contains

Documentation for the `contains` operator in yq, including usage and examples for arrays, objects, and strings.

```APIDOC
## contains

### Description
Returns `true` if the context contains the passed in parameter, and `false` otherwise. For arrays, returns `true` if the passed in array is contained within the array. For strings, returns `true` if the string is a substring.

### Usage
`yq 'contains(<parameter>)' sample.yml`

### Parameters
- **parameter** (any) - Required - The value to check for containment. For arrays, this is an array; for strings, this is a string.

### Examples

#### Array contains array
Given a sample.yml file of:
```
- foobar
- foobaz
- blarp
```

then
```
yq 'contains(["baz", "bar"])' sample.yml
```

will output
```
true
```

#### Array has a subset array
Given a sample.yml file of:
```
- foobar
- foobaz
- blarp
```

then
```
yq '["baz", "bar"] - . | length == 0' sample.yml
```

will output
```
false
```

#### Object included in array
Given a sample.yml file of:
```
"foo": 12
"bar":
  - 1
  - 2
  - "barp": 12
    "blip": 13
```

then
```
yq 'contains({"bar": [{"barp": 12}]})' sample.yml
```

will output
```
true
```

#### Object not included in array
Given a sample.yml file of:
```
"foo": 12
"bar":
  - 1
  - 2
  - "barp": 12
    "blip": 13
```

then
```
yq 'contains({"foo": 12, "bar": [{"barp": 15}]})' sample.yml
```

will output
```
false
```

#### String contains substring
Given a sample.yml file of:
```
foobar
```

then
```
yq 'contains("bar")' sample.yml
```

will output
```
true
```

#### String equals string
Given a sample.yml file of:
```
meow
```

then
```
yq 'contains("meow")' sample.yml
```

will output
```
true
```
```

--------------------------------

### system(command; args)

Source: https://mikefarah.gitbook.io/yq/operators/system-operators

Documentation for the system operator in yq, which runs external commands and uses their output as values in expressions.

```APIDOC
## system(command; args)

### Description
Runs an external command and uses its output as a value in the expression. The current matched node's value is serialised and piped to the command via stdin. The command's stdout (with trailing newline stripped) is returned as a string.

### Usage
```
yq --security-enable-system-operator --null-input '.field = system("command"; "arg1")'
```

### Parameters
- **command** (string) - Required - The command to execute.
- **args** (string or array of strings) - Optional - Argument(s) to pass to the command, separated from the command by `;`.

### Security
Disabled by default. Must be enabled with `--security-enable-system-operator`. When disabled, an error is returned instead of running the command.

### Example
Given a sample.yml file of:
```
country: Australia
```

then
```
yq --security-enable-system-operator '.country = system("/usr/bin/echo"; "test")' sample.yml
```

will output
```
country: test
```

### Example (without arguments)
Given a sample.yml file of:
```
a: hello
```

then
```
yq --security-enable-system-operator '.a = system("/usr/bin/echo")' sample.yml
```

will output
```
a: ""
```

### Error when disabled
Given a sample.yml file of:
```
country: Australia
```

then
```
yq '.country = system("/usr/bin/echo"; "test")' sample.yml
```

will output
```
Error: system operations are disabled, use --security-enable-system-operator to enable
```
```

--------------------------------

### Array has a subset array - output

Source: https://mikefarah.gitbook.io/yq/operators/contains

Output of the 'Array has a subset array' example. It prints 'false'.

```text
false

```

--------------------------------

### Recursively match nodes: v3 vs v4

Source: https://mikefarah.gitbook.io/yq/upgrading-from-v3

Shows how to recursively match nodes in v3 and the equivalent v4 expression using the recursive descent operator .. and select.

```bash
yq r sample.yaml 'thing.**.name'
```

```bash
yq '.thing | .. | select(has("name"))' sample.yaml
```

--------------------------------

### Array contains array - output

Source: https://mikefarah.gitbook.io/yq/operators/contains

Output of the 'Array contains array' example. It prints 'true'.

```text
true

```

--------------------------------

### Update documents: v3 vs v4

Source: https://mikefarah.gitbook.io/yq/upgrading-from-v3

Shows how to update a path in v3 using the w command and in v4 using the assignment operator =.

```bash
yq w sample.yaml 'a.b.c' fred
```

```bash
yq '.a.b.c = "fred"' sample.yaml
```

--------------------------------

### path | .[-1]

Source: https://mikefarah.gitbook.io/yq/operators/path

Gets the key or index of matching nodes by taking the last element of the path array.

```APIDOC
## path | .[-1]

### Description
You can get the key/index of matching nodes by using the `path` operator to return the path array then piping that through `.[-1]` to get the last element of that array, the key.

### Usage
`yq '.a.b | path | .[-1]' sample.yml`

### Example
Given sample.yml:
```
a:
  b: cat
```

Command:
```
yq '.a.b | path | .[-1]' sample.yml
```

Output:
```
b
```

```

--------------------------------

### Get map keys with yq keys

Source: https://mikefarah.gitbook.io/yq/operators/keys

Shows the keys operator on a map. Given a sample.yml with two key-value pairs, running yq 'keys' sample.yml outputs a YAML list of the map keys in order.

```yaml
dog: woof
cat: meow
```

```bash
yq 'keys' sample.yml
```

```yaml
- dog
- cat
```

--------------------------------

### Get file index (of current file)

Source: https://mikefarah.gitbook.io/yq/operators/file-operators

Outputs the index of the current file. For sample.yml, the output is '0'.

```bash
yq 'file_index' sample.yml
```

--------------------------------

### Read with default value: v3 vs v4

Source: https://mikefarah.gitbook.io/yq/upgrading-from-v3

Shows how to read a path with a default value in v3 using --defaultValue and in v4 using the alternative operator //.

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

```bash
yq '.path.not.there // "frog"' sample.yaml
```

--------------------------------

### Encode simple YAML to XML with yq -o=xml

Source: https://mikefarah.gitbook.io/yq/usage/xml

Given a sample.yml file with a simple key-value pair, running yq -o=xml sample.yml outputs the corresponding XML element.

```yaml
cat: purrs

```

```bash
yq -o=xml sample.yml

```

```xml
<cat>purrs</cat>

```

--------------------------------

### yq 'pivot'

Source: https://mikefarah.gitbook.io/yq/operators/pivot

Documentation for the yq pivot operator, including usage and examples for various input types.

```APIDOC
## yq 'pivot'

### Description
Emulates the `PIVOT` function supported by several popular RDBMS systems. It transposes a sequence of sequences or maps, turning rows into columns.

### Usage
`yq 'pivot' sample.yml`

### Behavior
- For a sequence of sequences, the pivot operation transposes the rows and columns.
- For heterogeneous sequences, missing values are padded to null.
- For a sequence of maps, the pivot operation groups values by key, creating a map of sequences.
- For heterogeneous maps, missing values are padded to null.

### Examples

#### Pivot a sequence of sequences
Given `sample.yml`:
```yaml
- - foo
  - bar
  - baz
- - sis
  - boom
  - bah
```

Running `yq 'pivot' sample.yml` outputs:
```yaml
- - foo
  - sis
- - bar
  - boom
- - baz
  - bah
```

#### Pivot sequence of heterogeneous sequences
Given `sample.yml`:
```yaml
- - foo
  - bar
  - baz
- - sis
  - boom
  - bah
  - blah
```

Running `yq 'pivot' sample.yml` outputs:
```yaml
- - foo
  - sis
- - bar
  - boom
- - baz
  - bah
- -
  - blah
```

#### Pivot sequence of maps
Given `sample.yml`:
```yaml
- foo: a
  bar: b
  baz: c
- foo: x
  bar: y
  baz: z
```

Running `yq 'pivot' sample.yml` outputs:
```yaml
foo:
  - a
  - x
bar:
  - b
  - y
baz:
  - c
  - z
```

#### Pivot sequence of heterogeneous maps
Given `sample.yml`:
```yaml
- foo: a
  bar: b
  baz: c
- foo: x
  bar: y
  baz: z
  what: ever
```

Running `yq 'pivot' sample.yml` outputs:
```yaml
foo:
  - a
  - x
bar:
  - b
  - y
baz:
  - c
  - z
what:
  -
  - ever
```
```

--------------------------------

### Sample YAML input for indent flag

Source: https://mikefarah.gitbook.io/yq/usage/output-format

Sample YAML input used to demonstrate the effect of the --indent/-I flag on indentation.

```yaml
apples:
  collection:
  - name: Green
  - name: Blue
  favourite: Pink Lady

```

--------------------------------

### Roundtrip XML with doctype and declaration using yq

Source: https://mikefarah.gitbook.io/yq/usage/xml

Shows how yq parses XML processing instructions and directives into nodes, but the underlying XML parser loses whitespace information. The input file sample.xml is processed with the command `yq sample.xml`, producing output where the processing instruction and directive are placed on the same line as the opening <apple> tag.

```xml
<?xml version="1.0"?>
<!DOCTYPE config SYSTEM "/etc/iwatch/iwatch.dtd" >
<apple>
  <?coolioo version="1.0"?>
  <!CATYPE meow purr puss >
  <b>things</b>
</apple>

```

```bash
yq sample.xml
```

```xml
<?xml version="1.0"?>
<!DOCTYPE config SYSTEM "/etc/iwatch/iwatch.dtd" >
<apple><?coolioo version="1.0"?><!CATYPE meow purr puss >
  <b>things</b>
</apple>

```

--------------------------------

### String equals string - yq command

Source: https://mikefarah.gitbook.io/yq/operators/contains

yq command to check if the string equals 'meow'. Returns true for this example.

```bash
yq 'contains("meow")' sample.yml

```

--------------------------------

### Object not included in array - yq command

Source: https://mikefarah.gitbook.io/yq/operators/contains

yq command to check if the object is not included in the array. Returns false for this example.

```bash
yq 'contains({"foo": 12, "bar": [{"barp": 15}]})' sample.yml

```

--------------------------------

### Roundtrip: sample from web

Source: https://mikefarah.gitbook.io/yq/usage/toml

Roundtrip test for a sample TOML document from the web. The input file contains a full TOML example with tables, arrays, and inline tables. Running `yq '.' sample.toml` outputs the same content, confirming that yq preserves the structure and comments. Note the comment `# [servers] yq can't do this one yet` indicates a limitation with that table.

```toml
# This is a TOML document
title = "TOML Example"

[owner]
name = "Tom Preston-Werner"
dob = 1979-05-27T07:32:00-08:00

[database]
enabled = true
ports = [8000, 8001, 8002]
data = [["delta", "phi"], [3.14]]
temp_targets = { cpu = 79.5, case = 72.0 }

# [servers] yq can't do this one yet
[servers.alpha]
ip = "10.0.0.1"
role = "frontend"

[servers.beta]
ip = "10.0.0.2"
role = "backend"

```

```bash
yq '.' sample.toml

```

```toml
# This is a TOML document
title = "TOML Example"

[owner]
name = "Tom Preston-Werner"
dob = 1979-05-27T07:32:00-08:00

[database]
enabled = true
ports = [8000, 8001, 8002]
data = [["delta", "phi"], [3.14]]
temp_targets = { cpu = 79.5, case = 72.0 }

# [servers] yq can't do this one yet
[servers.alpha]
ip = "10.0.0.1"
role = "frontend"

[servers.beta]
ip = "10.0.0.2"
role = "backend"

```

--------------------------------

### Object included in array - yq command

Source: https://mikefarah.gitbook.io/yq/operators/contains

yq command to check if the object is included in the array. Returns true for this example.

```bash
yq 'contains({"bar": [{"barp": 12}]})' sample.yml

```

--------------------------------

### Integer modulo with yq

Source: https://mikefarah.gitbook.io/yq/operators/modulo

Integer modulo example. The input file sample.yml has integer values for a and b. The yq expression assigns the remainder of a divided by b to a, producing the output shown.

```yaml
a: 13
b: 2
```

```bash
yq '.a = .a % .b' sample.yml
```

```yaml
a: 1
b: 2
```

--------------------------------

### Get alias with yq '.a | alias'

Source: https://mikefarah.gitbook.io/yq/operators/anchor-and-alias-operators

Given a sample.yml with an alias, the yq command '.a | alias' outputs the alias name.

```yaml
b: &billyBob meow
a: *billyBob

```

```bash
yq '.a | alias' sample.yml

```

```yaml
billyBob

```

--------------------------------

### Use with_entries to update keys

Source: https://mikefarah.gitbook.io/yq/operators/entries

with_entries is syntactic sugar for to_entries | op | from_entries. This example updates map keys by prefixing them.

```APIDOC
## Use with_entries to update keys

### Description
with_entries is syntactic sugar for to_entries | op | from_entries. This example updates map keys by prefixing them.

### Usage
`yq 'with_entries(.key |= "KEY_" + .)' sample.yml`

### Input Example
```yaml
a: 1
b: 2
```

### Output Example
```yaml
KEY_a: 1
KEY_b: 2
```
```
Tokens:
Raw