yq/operators/select.md

# Select

Select is used to filter arrays and maps by a boolean expression.

## Related Operators

- equals / not equals (`==`, `!=`) operators [here](https://mikefarah.gitbook.io/yq/operators/equals)
- comparison (`>=`, `<` etc) operators [here](https://mikefarah.gitbook.io/yq/operators/compare)
- boolean operators (`and`, `or`, `any` etc) [here](https://mikefarah.gitbook.io/yq/operators/boolean-operators)

## Select elements from array using wildcard prefix
Given a sample.yml file of:
```yaml
- cat
- goat
- dog
```
then
```bash
yq '.[] | select(. == "*at")' sample.yml
```
will output
```yaml
cat
goat
```

## Select elements from array using wildcard suffix
Given a sample.yml file of:
```yaml
- go-kart
- goat
- dog
```
then
```bash
yq '.[] | select(. == "go*")' sample.yml
```
will output
```yaml
go-kart
goat
```

## Select elements from array using wildcard prefix and suffix
Given a sample.yml file of:
```yaml
- ago
- go
- meow
- going
```
then
```bash
yq '.[] | select(. == "*go*")' sample.yml
```
will output
```yaml
ago
go
going
```

## Select elements from array with regular expression
See more regular expression examples under the [`string` operator docs](https://mikefarah.gitbook.io/yq/operators/string-operators).

Given a sample.yml file of:
```yaml
- this_0
- not_this
- nor_0_this
- thisTo_4
```
then
```bash
yq '.[] | select(test("[a-zA-Z]+_[0-9]$"))' sample.yml
```
will output
```yaml
this_0
thisTo_4
```

## Select items from a map
Given a sample.yml file of:
```yaml
things: cat
bob: goat
horse: dog
```
then
```bash
yq '.[] | select(. == "cat" or test("og$"))' sample.yml
```
will output
```yaml
cat
dog
```

## Use select and with_entries to filter map keys
Given a sample.yml file of:
```yaml
name: bob
legs: 2
game: poker
```
then
```bash
yq 'with_entries(select(.key | test("ame$")))' sample.yml
```
will output
```yaml
name: bob
game: poker
```

## Select multiple items in a map and update
Note the brackets around the entire LHS.

Given a sample.yml file of:
```yaml
a:
  things: cat
  bob: goat
  horse: dog
```
then
```bash
yq '(.a.[] | select(. == "cat" or . == "goat")) |= "rabbit"' sample.yml
```
will output
```yaml
a:
  things: rabbit
  bob: rabbit
  horse: dog
```

## Piping select to a literal

{% hint style="warning" %}

_Note_ that piping `select()` to a literal value produces that literal for each match. When there are no matches, the literal is still produced once:

Given a sample.yml file of:
```yaml
a: 1
```
then
```bash
yq '(.a | select(. == 999) | "matched") // "default"' sample.yml
```
will output
```yaml
matched
```

Since `.a` is `1`, not `999`, you might expect `"default"` here.

The select does filter correctly when not followed by a literal:
```bash
yq '.a | select(. == 999)' sample.yml
```
will output nothing (empty).

**Workaround**: Return the matched value itself, or use `with()`:
```bash
yq '(.a | select(. == 1)) // "default"' sample.yml
```

{% endhint %}