MongoDB $isArray Operator

Beginner
5 min read
Updated: Oct 2026
3 examples
Live preview
MongoDB $isArray tutorial — check whether a value is an array
Definition

What Is $isArray?

$isArray is a MongoDB aggregation expression that returns true when its argument is a BSON array, and false otherwise. Use it to guard array operators like $size or $concatArrays when mixed types exist.

Remember
$isArray ≈ Array.isArray for aggregation

{ $isArray: <expression> }
{ $isArray: [ <expression> ] }   // same idea

array (even []) → true
string / number / null / missing → false
not a find() filter by itself
UsePrefer
Is this value an array?$isArray
What BSON type is it?$type
How many elements?$size (after $isArray)
Approach

How to Use $isArray in MongoDB

Pass one expression. Branch or filter on the boolean result.

  1. Choose an expression stage ($addFields, $project, or $cond).
  2. Pass the field or expression: { $isArray: "$tags" }.
  3. Use the boolean with $cond, or filter via $expr inside $match.
  4. Only then call array operators like $size on that field.
PieceRequired?Role
ExpressionYesValue to test (field path, literal, or nested expression)
Result—true if BSON array, else false
Common partnerNo$cond / $and before array ops

Pseudocode

Pseudocode
for each document:
    value = evaluate(expression)
    if value is a BSON array:
        result = true
    else:
        result = false   // string, number, null, missing, object, …
    emit { ..., field: result }
Reference

Cheat Sheet

Keep these facts handy while writing type-guard expressions.

TopicDetail
TypeAggregation expression (boolean)
Syntax{ $isArray: <expression> }
Empty array[] → true
Missing fieldfalse (not an error)
Filter docs$match + $expr: { $isArray: "$field" }
Guard pattern$cond: [ { $isArray: "$x" }, { $size: "$x" }, null ]
Try it

Live Preview

Pick a sample value and watch $isArray return true or false.

Simulates $isArray for common BSON shapes (same idea as the mongosh examples).

Result
value = ["js", "db"]
$isArray → true

{ is_array: true }
Trace

Worked Walkthrough — Mixed tags

Some profiles store tags as an array; others store a string or omit the field. $isArray sorts that out first.

Calculation
tags = ["js", "db"]  → $isArray → true
tags = []            → $isArray → true   (empty still counts)
tags = "admin"       → $isArray → false
tags missing         → $isArray → false

Safe size:
  if $isArray(tags):
      count = $size(tags)
  else:
      count = null

Tip: never call $size on a string — guard with $isArray first.
Code

MongoDB Examples

We use a small profiles collection with a mixed-type tags field. First we flag arrays, then we safely count elements. Insert the sample data once in mongosh.

Example 1 — Sample Data

Imagine four user profiles. Some have tags as an array, one has a string, and one has no tags field.

mongosh
db.profiles.insertMany([
  { _id: 1, name: "Ada", tags: ["js", "db"] },
  { _id: 2, name: "Lin", tags: "admin" },
  { _id: 3, name: "Sam", tags: [] },
  { _id: 4, name: "Kai" }
]);

How the Data Is Stored in MongoDB

After the insert, MongoDB keeps four documents in profiles. Run find() to see them:

mongosh
db.profiles.find()

Read those documents like this:

Field in MongoDBExamplePlain English
_id1Profile id for this lesson
name"Ada"User name
tags["js", "db"] or "admin"Sometimes an array, sometimes not
Picture
Ada  tags: ["js", "db"]  → array? yes
Lin  tags: "admin"       → array? no
Sam  tags: []            → array? yes (empty)
Kai  (no tags)           → array? no

How It Works

  1. Insert once. insertMany adds four profile documents.
  2. MongoDB keeps the types you wrote. Arrays stay arrays; strings stay strings.
  3. find() shows the same shape. What you inserted is what you get back—ready for $isArray next.

Example 2 — Flag Arrays

Goal: add tags_is_array so you can see which documents store tags as an array.

mongosh
db.profiles.aggregate([
  {
    $addFields: {
      tags_is_array: { $isArray: "$tags" }
    }
  }
]);

How It Works

  1. Read each tags value. "$tags" may be an array, a string, or missing.
  2. Test the type. $isArray returns a boolean only—it does not change the data.
  3. Empty still counts. Sam’s [] is an array → true.
  4. Missing → false. Kai has no tags field, so the result is false.

Example 3 — Safe $size With $cond

Goal: count tags only when the field is an array. Otherwise store null instead of erroring.

mongosh
db.profiles.aggregate([
  {
    $addFields: {
      tag_count: {
        $cond: [
          { $isArray: "$tags" },
          { $size: "$tags" },
          null
        ]
      }
    }
  }
]);

How It Works

  1. Same stored documents. Still using the four profiles from Example 1.
  2. Guard first. $isArray: "$tags" decides which branch $cond takes.
  3. Array path. Ada → $size = 2; Sam → 0 for the empty list.
  4. Non-array path. Lin and Kai skip $size and get null—no pipeline error.

Edge Cases & Pitfalls

Check these before using $isArray in production pipelines.

syntax

Argument-list brackets

{ $isArray: [ "hello" ] } is false—the value tested is the string. A literal array needs nesting: { $isArray: [ [ "hello" ] ] }.

query

Not a find filter

{ tags: { $isArray: true } } does not work. Filter with $match + $expr.

empty

Empty array is still an array

[] → true. Use $size (after the guard) if you care about length.

size

Guard before $size / $concatArrays

Calling $size on a string or missing field errors. Wrap with $isArray + $cond first.

Analysis

Performance Notes

ApproachCostBest for
$isArrayPer-document type checkMixed-type fields
+ $cond / $sizeStill O(docs)Safe counts on dirty data
$match + $exprScan (expression filter)Keep only array-shaped rows

Type checks are cheap. Prefer cleaning schemas so fields are consistently arrays when possible—then you can skip guards and use indexes more naturally in earlier $match stages.

Remember

Key Takeaways

  • Role: boolean test for “is this a BSON array?”
  • Empty: [] still returns true.
  • Guard: use before $size / $concatArrays.
  • Filter: $match + $expr, not a plain find query.

One line: $isArray answers “is this value an array?”—true or false, before you call array operators.

Frequently Asked Questions

$isArray returns true when the evaluated expression is a BSON array, and false otherwise. Use it inside aggregation expression stages such as $project, $addFields, and $cond.
Use { $isArray: <expression> } or { $isArray: [ <expression> ] }. A field path like "$tags" is the usual form.
Yes. [] is still an array, so $isArray returns true. It checks the BSON type, not whether elements exist.
Use $match with $expr: { $match: { $expr: { $isArray: "$tags" } } }. Plain query syntax like { tags: { $isArray: true } } does not work.
$isArray returns only true or false for arrays. $type returns the BSON type name or number and can identify many types, not just arrays.
The outer brackets are the operator argument list. That form still evaluates the string "hello", which is not an array. To test a literal array, nest it: { $isArray: [ [ "hello" ] ] }.

Next: $isNumber

Test whether an expression resolves to a number.

$isNumber tutorial →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

AWS Certified Developer – Associate (Credly)

9 people found this page helpful

MongoDB $indexOfCP Operator MongoDB $isNumber Operator