$indexOfArray (aggregation)¶

On this page

Definition
Behavior
Example

Definition¶

$indexOfArray¶

New in version 3.4.

Searches an array for an occurrence of a specified value and returns the array index (zero-based) of the first occurrence. If the value is not found, returns -1.

$indexOfArray has the following operator expression syntax:

copy

{ $indexOfArray: [ <array expression>, <search expression>, <start>, <end> ] }

Field	Type	Description
`<array>`	string	Can be any valid expression as long as it resolves to an array. For more information on expressions, see Expressions. If the array expression resolves to a value of `null` or refers to a field that is missing, `$indexOfArray` returns `null`. If the array expression does not resolve to an array or `null` nor refers to a missing field, `$indexOfArray` returns an error.
`<search value>`	string	Can be any valid expression. For more information on expressions, see Expressions.
`<start>`	integer	Optional. An integer, or a number that can be represented as integers (such as 2.0), that specifies the starting index position for the search. Can be any valid expression that resolves to a non-negative integral number. If unspecified, the starting index position for the search is the beginning of the string.
`<end>`	integer	Optional. An integer, or a number that can be represented as integers (such as 2.0), that specifies the ending index position for the search. Can be any valid expression that resolves to a non-negative integral number. If you specify a `<end>` index value, you should also specify a `<start>` index value; otherwise, `$indexOfArray` uses the `<end>` value as the `<start>` index value instead of the `<end>` value. If unspecified, the ending index position for the search is the end of the string.

Behavior¶

If the <search expression> is found multiple times within the <array expression>, then $indexOfArray returns the index of the first <search expression> from the starting index position.

$indexOfArray returns null:

If <array expression> is null, or
If <array expression> refers to a non-existing field in the input document.

$indexOfArray returns an error:

If <array expression> is not an array and not null, or
If <start> or <end> is a negative integer (or a value that can be represented as a negative integer, like -5.0).

$indexOfArray returns -1:

If the <search expression> is not found in the array, or
If <start> is a number greater than <end>, or
If <start> is a number greater than the length of the array.

Example	Results
`{ $indexOfArray: [ [ "a", "abc" ], "a" ] }`	`0`
`{ $indexOfArray: [ [ "a", "abc", "de", ["de"] ], ["de"] ] }`	`3`
`{ $indexOfArray: [ [ 1, 2 ], 5 ] }`	`-1`
`{ $indexOfArray: [ [ 1, 2, 3 ], [1, 2] ] }`	`-1`
`{ $indexOfArray: [ [ 10, 9, 9, 8, 9 ], 9, 3 ] }`	`4`
`{ $indexOfArray: [ [ "a", "abc", "b" ], "b", 0, 1 ] }`	`-1`
`{ $indexOfArray: [ [ "a", "abc", "b" ], "b", 1, 0 ] }`	`-1`
`{ $indexOfArray: [ [ "a", "abc", "b" ], "b", 20 ] }`	`-1`
`{ $indexOfArray: [ [ null, null, null ], null ] }`	`0`
`{ $indexOfArray: [ null, "foo" ] }`	`null`
`{ $indexOfArray: [ "foo", "foo" ] }`	Error

Example¶

The example uses this inventory collection:

copy

db.inventory.insertMany( [
   { _id: 0, items: [ "one", "two", "three" ] },
   { _id: 1, items: [ 1, 2, 3 ] },
   { _id: 2, items: [ 1, 2, 3, 2 ] },
   { _id: 3, items: [ null, null, 2 ] },
   { _id: 4, items: [ 2, null, null, 2 ] },
   { _id: 5, items: null },
   { _id: 6, amount: 3 }
] )

The following example uses $indexOfArray to find 2 in the items array:

copy

db.inventory.aggregate( [ {
   $project: {
      index: { $indexOfArray: [ "$items", 2 ] }
   }
} ] )

The example returns:

The first array index for the value 2 in each items array, if found. Array indexes start at 0.
-1 for the index if 2 is not in the items array.
null for the index if items is not an array or items does not exist.

Example output:

[
   { _id: 0, index: -1 },
   { _id: 1, index: 1 },
   { _id: 2, index: 1 },
   { _id: 3, index: 2 },
   { _id: 4, index: 0 },
   { _id: 5, index: null },
   { _id: 6, index: null }
]