MongoDB $isArray Operator

What You’ll Learn

The $isArray operator checks whether a value is an array. It returns true or false — useful for data validation, defensive pipeline logic, and filtering documents before applying array operators like $filter or $size.

Definition and Usage

In MongoDB’s aggregation framework, the $isArray operator evaluates an expression and returns true when the result is a BSON array, and false for all other types (strings, numbers, objects, null, missing fields, and so on). This is especially helpful when your collection has inconsistent schemas — some documents may store tags as an array while others store a single string.

Use $isArray as a guard before array-specific operators. For example, only run $size or $filter when the field is actually an array, preventing pipeline errors on malformed documents.

📝 Syntax

The $isArray operator takes a single expression to evaluate:

{ $isArray: <expression> }

Common Patterns

// Check a document field
{ $isArray: "$tags" }

// Filter documents where tags is an array
{ $match: { $expr: { $isArray: "$tags" } } }

// Guard before array logic in $cond
{ $cond: [
    { $isArray: "$items" },
  { $size: "$items" },
  0
] }

Syntax Rules

• <expression> — can be a field path ("$tags"), a literal array, or another expression.
• Returns true for arrays, including empty arrays [].
• Returns false for strings, objects, numbers, booleans, null, and missing fields.
• Use inside $project, $addFields, $cond, and $match (with $expr).
• Does not work as a standalone query operator like { tags: { $isArray: true } }.

Examples Gallery

Walk through sample product data with mixed field types, validate arrays with $project, and filter safely in $match.

[
  { "_id": ObjectId("609c26812e9274a86871bc6a"), "name": "MongoDB Guide", "tags": ["database", "mongodb"] },
  { "_id": ObjectId("609c26812e9274a86871bc6b"), "name": "Chess Set", "tags": "games" },
  { "_id": ObjectId("609c26812e9274a86871bc6c"), "name": "Coffee Mug", "tags": [] },
  { "_id": ObjectId("609c26812e9274a86871bc6d"), "name": "Notebook" }
]

db.products.aggregate([
  {
    $project: {
      name: 1,
      tags: 1,
      tagsIsArray: {
        $isArray: "$tags"
      }
    }
  }
])

// MongoDB Guide  → tagsIsArray: true   (tags: ["database", "mongodb"])
// Chess Set      → tagsIsArray: false  (tags: "games" — a string)
// Coffee Mug     → tagsIsArray: true   (tags: [] — empty but still an array)
// Notebook       → tagsIsArray: false  (tags field missing)

db.products.aggregate([
  {
    $match: {
      $expr: {
        $isArray: "$tags"
      }
    }
  },
  {
    $project: {
      name: 1,
      tags: 1
    }
  }
])

// MongoDB Guide  → included (tags is array)
// Coffee Mug     → included (tags is empty array)
// Chess Set      → excluded (tags is string)
// Notebook       → excluded (tags missing)

db.products.aggregate([
  {
    $project: {
      name: 1,
      tagCount: {
        $cond: [
          { $isArray: "$tags" },
          { $size: "$tags" },
          0
        ]
      }
    }
  }
])

// MongoDB Guide  → tagCount: 2
// Chess Set      → tagCount: 0  (string — $size skipped)
// Coffee Mug     → tagCount: 0  (empty array)
// Notebook       → tagCount: 0  (missing field)

db.products.aggregate([
  {
    $project: {
      name: 1,
      tags: 1,
      needsTagFix: {
        $not: {
          $isArray: "$tags"
        }
      }
    }
  },
  {
    $match: {
      needsTagFix: true
    }
  }
])

db.products.aggregate([
  {
    $project: {
      name: 1,
      activeTags: {
        $cond: [
          { $isArray: "$tags" },
          {
            $filter: {
              input: "$tags",
              as: "tag",
              cond: { $ne: [ "$$tag", "" ] }
            }
          },
          []
        ]
      }
    }
  }
])

🚀 Use Cases

• Schema validation — detect documents where a field should be an array but is stored as a string or object.
• Defensive pipelines — guard $size, $filter, $map, and $indexOfArray with an $isArray check.
• Data cleanup — find and flag malformed records before migration or ETL jobs.
• Conditional processing — branch logic in $cond based on whether input is array-shaped.

💡 Best Practices