Navigation

$indexOfArray (aggregation)

$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:

{ $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.

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

Consider an inventory collection with the following documents:

{ "_id" : 1, "items" : ["one", "two", "three"] }
{ "_id" : 2, "items" : [1, 2, 3] }
{ "_id" : 3, "items" : [null, null, 2] }
{ "_id" : 4, "items" : null }
{ "_id" : 5, "amount" : 3 }

The following operation uses the $indexOfArray operator to return the array index at which the string foo is located in each items array:

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

The operation returns the following results:

{ "_id" : 1, "index" : "-1" }
{ "_id" : 2, "index" : "1" }
{ "_id" : 3, "index" : "2" }
{ "_id" : 4, "index" : null }
{ "_id" : 5, "index" : null }
Tip
See also:
Give Feedback

On this page

  • Definition
  • Behavior
  • Examples