MongoDB $indexOfArray Operator

What You’ll Learn

The $indexOfArray operator finds the position of a value inside an array. It returns a zero-based index (like JavaScript’s indexOf) or -1 when the value is not found. Use it in aggregation pipelines to locate tags, statuses, or items in embedded arrays.

Definition and Usage

In MongoDB’s aggregation framework, the $indexOfArray operator searches an array for the first occurrence of a value and returns its zero-based index. For example, searching [ "js", "mongodb", "node" ] for "mongodb" returns 1. If the value is absent, the result is -1.

You can optionally pass start and end indexes to search only part of the array. This is useful when you need the position of a value after a certain point, or when working with sliced data.

📝 Syntax

The $indexOfArray operator takes an array expression, a search value, and optional range bounds:

{
  $indexOfArray: [
    <array expression>,
    <search expression>,
    <start>,   // optional, default 0
    <end>      // optional, default array length
  ]
}

Common Patterns

// Basic search in a field array
{ $indexOfArray: [ "$tags", "mongodb" ] }

// Search from index 2 onward
{ $indexOfArray: [ "$scores", 90, 2 ] }

// Check if value exists (index >= 0)
{ $gte: [
    { $indexOfArray: [ "$tags", "featured" ] },
    0
] }

Syntax Rules

• First argument — the array to search (field path like "$tags" or a literal array).
• Second argument — the value to find (literal, field reference, or expression).
• start — optional zero-based index where the search begins (default 0).
• end — optional index before which the search stops (default array length).
• Returns -1 when the search value is not found in the specified range.
• Use inside stages like $project, $addFields, $set, and $cond.

Examples Gallery

Walk through sample article data, find tag positions with $project, and combine $indexOfArray with other operators for practical patterns.

[
  { "_id": ObjectId("609c26812e9274a86871bc6a"), "title": "Intro to MongoDB", "tags": ["database", "mongodb", "nosql"] },
  { "_id": ObjectId("609c26812e9274a86871bc6b"), "title": "Node Basics", "tags": ["javascript", "node", "backend"] },
  { "_id": ObjectId("609c26812e9274a86871bc6c"), "title": "CSS Grid", "tags": ["css", "layout", "frontend"] }
]

db.articles.aggregate([
  {
    $project: {
      title: 1,
      tags: 1,
      mongoTagIndex: {
        $indexOfArray: [ "$tags", "mongodb" ]
      }
    }
  }
])

// Intro to MongoDB  → mongoTagIndex: 1  (tags[1] is "mongodb")
// Node Basics       → mongoTagIndex: -1 (tag not present)
// CSS Grid          → mongoTagIndex: -1 (tag not present)

db.orders.aggregate([
  {
    $project: {
      orderId: 1,
      statusHistory: 1,
      pendingAfterStep2: {
        $indexOfArray: [
          "$statusHistory",
          "pending",
          2
        ]
      }
    }
  }
])

// ["placed", "paid", "pending", "shipped"]
//   → pendingAfterStep2: 2

// ["placed", "pending", "paid", "shipped"]
//   → pendingAfterStep2: -1 (index 1 is skipped because start is 2)

db.articles.aggregate([
  {
    $project: {
      title: 1,
      hasFeaturedTag: {
        $gte: [
          { $indexOfArray: [ "$tags", "featured" ] },
          0
        ]
      }
    }
  }
])

// tags includes "featured" → hasFeaturedTag: true
// tags without "featured"  → hasFeaturedTag: false

db.articles.aggregate([
  {
    $project: {
      title: 1,
      category: {
        $cond: [
          {
            $gte: [
              { $indexOfArray: [ "$tags", "mongodb" ] },
              0
            ]
          },
          "database",
          "general"
        ]
      }
    }
  }
])

db.articles.aggregate([
  {
    $addFields: {
      mongoIndex: {
        $indexOfArray: [ "$tags", "mongodb" ]
      }
    }
  },
  {
    $project: {
      title: 1,
      tagAfterMongo: {
        $arrayElemAt: [
          "$tags",
          { $add: [ "$mongoIndex", 1 ] }
        ]
      }
    }
  }
])

🚀 Use Cases

• Tag and category lookup — find where a label appears in a document’s tag array.
• Workflow timelines — locate the first "pending" or "approved" step in a status history.
• Existence checks in aggregation — convert index >= 0 into boolean flags for reporting.
• Array navigation — combine with $arrayElemAt to read elements before or after a found position.

💡 Best Practices