First Operator

Returns the first matching element in an array, or first matching value in a map.

Can be given an expression to match with, otherwise will just return the first.

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
  b: firstCat
- a: apple
- a: cat
  b: secondCat

then

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

will output

a: cat
b: firstCat

First matching element from array with numeric condition

Given a sample.yml file of:

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

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
  b: firstTrue
- a: false
- a: true
  b: secondTrue

then

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

will output

a: true
b: firstTrue

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: 7
- a: cat
  b: 3
- a: apple
  b: 5

then

yq 'first(.b > 4 and .b < 6)' sample.yml

will output

a: apple
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: 101

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