> For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt

# $indexOfArray (expression operator)

## Definition

Searches an array for an occurrence of a specified value and returns the array index of the first occurrence. Array indexes start at zero.

[`$indexOfArray`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/indexofarray.md#mongodb-expression-exp.-indexOfArray) has the following [operator expression syntax:](https://www.mongodb.com/docs/manual/reference/mql/expressions.md#std-label-agg-quick-ref-operator-expressions)

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

| Field | Type | Description |
| --- | --- | --- |
| `<array>` | array | Can be any valid [expression](https://www.mongodb.com/docs/manual/reference/mql/expressions.md#std-label-aggregation-expressions) as long as it resolves to an array. For more information on expressions, see [Expressions.](https://www.mongodb.com/docs/manual/reference/mql/expressions.md#std-label-aggregation-expressions) If the array expression resolves to a value of `null` or refers to a field that is missing, [`$indexOfArray`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/indexofarray.md#mongodb-expression-exp.-indexOfArray) returns `null`. If the array expression does not resolve to an array or `null` nor refers to a missing field, [`$indexOfArray`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/indexofarray.md#mongodb-expression-exp.-indexOfArray) returns an error. |
| `<search value>` | string | Can be any valid [expression](https://www.mongodb.com/docs/manual/reference/mql/expressions.md#std-label-aggregation-expressions). For more information on expressions, see [Expressions.](https://www.mongodb.com/docs/manual/reference/mql/expressions.md#std-label-aggregation-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](https://www.mongodb.com/docs/manual/reference/mql/expressions.md#std-label-aggregation-expressions) 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](https://www.mongodb.com/docs/manual/reference/mql/expressions.md#std-label-aggregation-expressions) 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`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/indexofarray.md#mongodb-expression-exp.-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`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/indexofarray.md#mongodb-expression-exp.-indexOfArray) returns the index of the first `<search expression>` from the starting index position.

[`$indexOfArray`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/indexofarray.md#mongodb-expression-exp.-indexOfArray) returns `null`:

- If `<array expression>` is null, or

- If `<array expression>` refers to a non-existing field in the input document.

[`$indexOfArray`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/indexofarray.md#mongodb-expression-exp.-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`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/indexofarray.md#mongodb-expression-exp.-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:

```javascript
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`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/indexofarray.md#mongodb-expression-exp.-indexOfArray) to find `2` in the `items` array:

```javascript
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:

```javascript
[
   { _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 }
]
```

**See also:**

- [`$indexOfBytes`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/indexofbytes.md#mongodb-expression-exp.-indexOfBytes)

- [`$indexOfCP`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/indexofcp.md#mongodb-expression-exp.-indexOfCP)

- [`$in`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/in.md#mongodb-expression-exp.-in)