Array Query
Operators

MongoDB treats array fields specially during queries. A query on an array field will match documents where at least one element satisfies the condition — you don't need any special syntax to query arrays.

Implicit Array Matching

// Sample documents
{ _id: 1, tags: ["mongodb", "nosql", "database"] }
{ _id: 2, tags: ["mysql", "sql", "database"] }
{ _id: 3, tags: ["mongodb", "aggregation"] }

// Find documents where tags contains "mongodb"
db.articles.find({ tags: "mongodb" })
// Returns docs 1 and 3 — no $in or special syntax needed
// MongoDB automatically checks if any element equals "mongodb"

// Find by exact full array match (order matters!)
db.articles.find({ tags: ["mongodb", "nosql", "database"] })
// Returns only doc 1 — exact array with that exact order

Dot Notation on Array of Objects

// Documents with embedded arrays of objects
{ _id: 1, scores: [ { subject: "Math", val: 85 }, { subject: "Sci", val: 72 } ] }
{ _id: 2, scores: [ { subject: "Math", val: 40 }, { subject: "Sci", val: 90 } ] }

// Find docs where ANY score object has subject "Math"
db.students.find({ "scores.subject": "Math" })
// Returns both docs 1 and 2

// Find docs where ANY score has val > 80
db.students.find({ "scores.val": { $gt: 80 } })
// Returns doc 1 (85) and doc 2 (90) — checks across ALL elements

$elemMatch matches documents where at least one array element satisfies all the specified criteria simultaneously. It is the solution to the multi-condition same-element problem.

Syntax

{ arrayField: { $elemMatch: { condition1, condition2, ... } } }

$elemMatch on Array of Objects

// Find students with a Math score GREATER THAN 80
// (both conditions must hold on the SAME score object)
db.students.find({
  scores: {
    $elemMatch: { subject: "Math", val: { $gt: 80 } }
  }
})
// Only returns docs where ONE element has subject:"Math" AND val > 80 simultaneously

// Compare: plain dot-notation is misleading
db.students.find({ "scores.subject": "Math", "scores.val": { $gt: 80 } })
// Returns docs where SOME element has subject:"Math"
// AND SOME element (possibly different!) has val > 80
// This can return false positives!

$elemMatch on Array of Primitives

// Sample: { _id: 1, ratings: [70, 45, 90, 30] }

// Find docs with at least one rating between 40 and 60 (same element)
db.col.find({ ratings: { $elemMatch: { $gte: 40, $lte: 60 } } })
// Returns doc 1 because ratings has 45 (satisfies both $gte:40 AND $lte:60)
// Without $elemMatch: { ratings: { $gte:40, $lte:60 } } has DIFFERENT semantics

// Plain range on a primitive array — subtle difference
db.col.find({ ratings: { $gte: 40, $lte: 60 } })
// Matches docs where SOME element >= 40 AND SOME element (possibly different) <= 60
// { ratings: [10, 90] } would match because 90 >= 40 and 10 <= 60!
// { ratings: [10, 90] } would NOT match $elemMatch because no single element qualifies

$elemMatch in Projection

// In a projection, $elemMatch returns only the FIRST matching element
db.students.find(
  { "scores.subject": "Math" },
  { scores: { $elemMatch: { subject: "Math" } } }
)
// Output includes only the first scores element where subject === "Math"
// Other elements are excluded from the projection output
// _id is always returned unless explicitly excluded

Understanding this distinction is critical for writing correct array queries.

Side-by-Side Comparison

// Test dataset
db.students.insertMany([
  { name: "Alice", scores: [ { subject: "Math", val: 85 }, { subject: "Sci", val: 40 } ] },
  { name: "Bob",   scores: [ { subject: "Math", val: 35 }, { subject: "Sci", val: 95 } ] },
  { name: "Carol", scores: [ { subject: "Math", val: 92 }, { subject: "Sci", val: 88 } ] }
])

db.students.find({
  "scores.subject": "Math",
  "scores.val": { $gt: 80 }
})

db.students.find({
  scores: { $elemMatch: {
    subject: "Math",
    val: { $gt: 80 }
  }}
})

Decision Guide

$all matches documents where the array field contains all of the specified values (order doesn't matter, extra elements are allowed).

Syntax and Basic Usage

{ arrayField: { $all: [value1, value2, ...] } }

// Find articles that have BOTH "mongodb" AND "nosql" tags
db.articles.find({ tags: { $all: ["mongodb", "nosql"] } })
// Matches if tags contains at least these two — extra tags are fine
// Order of values in $all does not matter
// Order of elements in the document array does not matter

$all vs $in

// $all — array must contain ALL listed values (intersection = all)
db.articles.find({ tags: { $all: ["mongodb", "nosql"] } })
// Only returns docs with BOTH "mongodb" AND "nosql"

// $in — array contains AT LEAST ONE of the listed values (union)
db.articles.find({ tags: { $in: ["mongodb", "nosql"] } })
// Returns docs with "mongodb" OR "nosql" (or both)

$all with $elemMatch — AND conditions on embedded docs

// Find docs where the array has BOTH:
//   - an element with qty >= 5, AND
//   - an element with qty <= 10 AND price < 1 (same element!)
db.inventory.find({
  items: {
    $all: [
      { $elemMatch: { qty: { $gte: 5 } } },
      { $elemMatch: { qty: { $lte: 10 }, price: { $lt: 1 } } }
    ]
  }
})
// Each $elemMatch in the $all array defines one required element
// Useful for requiring multiple distinct elements each satisfying their own conditions

$size matches documents where the array field has exactly the specified number of elements.

Basic Usage

// Find documents where tags array has exactly 3 elements
db.articles.find({ tags: { $size: 3 } })

// Find documents where items array has exactly 1 element
db.orders.find({ items: { $size: 1 } })

// Find documents where the comments array is empty
db.posts.find({ comments: { $size: 0 } })

$size Cannot Use Operators

// INVALID — throws an error
db.articles.find({ tags: { $size: { $gt: 2 } } })
// Error: $size needs a number as argument

// VALID — only exact integer
db.articles.find({ tags: { $size: 3 } })

$size in Aggregation

// In aggregation, use the $size expression operator (different from query $size)
db.articles.aggregate([
  { $project: { tagCount: { $size: "$tags" } } }
])
// Returns the count as a field — works with $match and $filter too

// Use $size expression with $match for range-based filtering in aggregation
db.articles.aggregate([
  { $match: { $expr: { $gt: [ { $size: "$tags" }, 2 ] } } }
])
// Finds docs where tags array has MORE THAN 2 elements
// $expr allows aggregation expressions inside query context

Because $size only supports exact integers, range-based length queries (e.g., "arrays with more than 3 elements") require alternative approaches.

Index Existence Trick

// Arrays are zero-indexed. If index N exists, the array has at least N+1 elements.
// Find docs where tags array has AT LEAST 3 elements (index 2 must exist)
db.articles.find({ "tags.2": { $exists: true } })
// "tags.2" is the 3rd element (0-indexed). If it exists, arr.length >= 3

// Find docs where tags has AT MOST 2 elements (index 2 must NOT exist)
db.articles.find({ "tags.2": { $exists: false } })
// If index 2 doesn't exist, array has 0, 1, or 2 elements

// Combine for exact range — between 2 and 4 elements
db.articles.find({
  "tags.1": { $exists: true },  // at least 2 elements
  "tags.4": { $exists: false }  // fewer than 5 elements
})
// Result: docs where tags has exactly 2, 3, or 4 elements

$expr + $size Aggregation Expression

// Use $expr to bridge aggregation expressions into find() queries
// Find docs where tags has MORE THAN 2 elements
db.articles.find({
  $expr: { $gt: [ { $size: "$tags" }, 2 ] }
})

// Find docs where tags has BETWEEN 2 and 5 elements (inclusive)
db.articles.find({
  $expr: {
    $and: [
      { $gte: [ { $size: "$tags" }, 2 ] },
      { $lte: [ { $size: "$tags" }, 5 ] }
    ]
  }
})

Workaround Comparison

Common Patterns Cheat Sheet

// Array contains a value
db.col.find({ tags: "mongodb" })

// Array contains any of these values
db.col.find({ tags: { $in: ["mongodb", "nosql"] } })

// Array contains ALL of these values
db.col.find({ tags: { $all: ["mongodb", "nosql"] } })

// At least one element satisfies multiple conditions simultaneously
db.col.find({ scores: { $elemMatch: { subject: "Math", val: { $gte: 80 } } } })

// Exact array length
db.col.find({ tags: { $size: 3 } })

// Array length > 2 (index existence workaround)
db.col.find({ "tags.2": { $exists: true } })

// Array length > 2 ($expr workaround)
db.col.find({ $expr: { $gt: [{ $size: "$tags" }, 2] } })

// Nested array range — same element constraint
db.col.find({ ratings: { $elemMatch: { $gte: 40, $lte: 60 } } })