yq/pkg/yqlib/doc/operators/first.md

First matching element from array

Given a sample.yml file of:

- a: banana
- a: cat
- a: apple

then

yq 'first(.a == "cat")' sample.yml

will output

a: cat

First matching element from array with multiple matches

Given a sample.yml file of:

- a: banana
- a: cat
- a: apple
- a: cat

then

yq 'first(.a == "cat")' sample.yml

will output

a: cat

First matching element from array with numeric condition

Given a sample.yml file of:

- a: 10
- a: 100
- a: 1

then

yq 'first(.a > 50)' sample.yml

will output

a: 100

First matching element from array with boolean condition

Given a sample.yml file of:

- a: false
- a: true
- a: false

then

yq 'first(.a == true)' sample.yml

will output

a: true

First matching element from array with null values

Given a sample.yml file of:

- a: null
- a: cat
- a: apple

then

yq 'first(.a != null)' sample.yml

will output

a: cat

First matching element from array with complex condition

Given a sample.yml file of:

- a: dog
  b: 5
- a: cat
  b: 3
- a: apple
  b: 7

then

yq 'first(.b > 4)' sample.yml

will output

a: dog
b: 5

First matching element from map

Given a sample.yml file of:

x:
  a: banana
y:
  a: cat
z:
  a: apple

then

yq 'first(.a == "cat")' sample.yml

will output

a: cat

First matching element from map with numeric condition

Given a sample.yml file of:

x:
  a: 10
y:
  a: 100
z:
  a: 1

then

yq 'first(.a > 50)' sample.yml

will output

a: 100

First matching element from nested structure

Given a sample.yml file of:

items:
  - a: banana
  - a: cat
  - a: apple

then

yq '.items | first(.a == "cat")' sample.yml

will output

a: cat

First matching element with no matches

Given a sample.yml file of:

- a: banana
- a: cat
- a: apple

then

yq 'first(.a == "dog")' sample.yml

will output

First matching element from empty array

Given a sample.yml file of:

[]

then

yq 'first(.a == "cat")' sample.yml

will output

First matching element from scalar node

Given a sample.yml file of:

hello

then

yq 'first(. == "hello")' sample.yml

will output

First matching element from null node

Given a sample.yml file of:

null

then

yq 'first(. == "hello")' sample.yml

will output

First matching element with string condition

Given a sample.yml file of:

- a: banana
- a: cat
- a: apple

then

yq 'first(.a | test("^c"))' sample.yml

will output

a: cat

First matching element with length condition

Given a sample.yml file of:

- a: hi
- a: hello
- a: world

then

yq 'first(.a | length > 4)' sample.yml

will output

a: hello

First matching element from array of strings

Given a sample.yml file of:

- banana
- cat
- apple

then

yq 'first(. == "cat")' sample.yml

will output

cat

First matching element from array of numbers

Given a sample.yml file of:

- 10
- 100
- 1

then

yq 'first(. > 50)' sample.yml

will output

100

First element with no filter from array

Given a sample.yml file of:

- 10
- 100
- 1

then

yq 'first' sample.yml

will output

10

First element with no filter from array of maps

Given a sample.yml file of:

- a: 10
- a: 100

then

yq 'first' sample.yml

will output

a: 10