$indexOfArray (aggregation)

Definition

• $indexOfArray

New in version 3.4.

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

$indexOfArray has the following operatorexpression syntax:

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

FieldTypeDescription<array>stringCan be any valid expression as longas it resolves to an array. For more information on expressions, seeExpressions.

If the array expression resolves to a value of null or refers toa field that is missing, $indexOfArray returnsnull.

If the array expression does not resolve to an array or null norrefers to a missing field, $indexOfArray returns anerror.<search value>stringCan be any valid expression. Formore information on expressions, see Expressions.<start>integerOptional. An integer, or a number that can be represented as integers (such as2.0), that specifies the starting index position for the search. Canbe any valid expression thatresolves to a non-negative integral number.

If unspecified, the starting index position for the search is thebeginning of the string.<end>integerOptional. An integer, or a number that can be represented as integers (such as2.0), that specifies the ending index position for the search. Canbe any valid expression thatresolves to a non-negative integral number. If you specify a<end> index value, you should also specify a <start> indexvalue; 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 theend of the string.

Behavior

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

$indexOfArray returns null:

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

$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 thatcan be represented as a negative integer, like -5.0).

$indexOfArray returns -1:

• If the 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.

Examples

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 toreturn 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 }

See also

$indexOfBytes, $indexOfCP, and $in