$elemMatch: Matching Array Sub-Documents

The Sub-Document Array Pattern

// Example: student with per-subject scores
db.students.insertMany([
  {
    name: 'Alice',
    scores: [
      { subject: 'math', score: 95, grade: 'A' },
      { subject: 'english', score: 72, grade: 'C' }
    ]
  },
  {
    name: 'Bob',
    scores: [
      { subject: 'math', score: 68, grade: 'D' },
      { subject: 'english', score: 91, grade: 'A' }
    ]
  }
]);

The Spread Field Problem Revisited

// Problematic query - spread field issue
db.students.find({
  'scores.subject': 'math',
  'scores.grade': 'A'
});
// Returns BOTH Alice AND Bob!
// Alice: scores[0] has subject='math', scores[0] has grade='A' -> correct match
// Bob:   scores[0] has subject='math' + scores[1] has grade='A' -> false positive!

$elemMatch Fixes the Spread Problem

// Correct query with $elemMatch
db.students.find({
  scores: {
    $elemMatch: {
      subject: 'math',
      grade: 'A'
    }
  }
});
// Returns ONLY Alice (scores[0] has BOTH subject='math' AND grade='A')
// Bob is excluded: no single element satisfies both conditions

Using Range Operators Inside $elemMatch

// Find students with a math score above 80
db.students.find({
  scores: {
    $elemMatch: {
      subject: 'math',
      score: { $gt: 80 }
    }
  }
});
// Returns Alice (math score is 95 > 80)

// With $in inside $elemMatch
db.students.find({
  scores: {
    $elemMatch: {
      subject: { $in: ['math', 'science'] },
      grade: 'A'
    }
  }
});

Negating $elemMatch Results

// Students who do NOT have a math A
db.students.find({
  scores: {
    $not: {
      $elemMatch: {
        subject: 'math',
        grade: 'A'
      }
    }
  }
});
// Returns Bob (his math score is D, not A)

$elemMatch in Projection

// Project only the FIRST matching scores element
db.students.find(
  { name: 'Alice' },
  {
    name: 1,
    scores: {
      $elemMatch: { subject: 'math' }
    }
  }
);
// Returns:
// { name: 'Alice', scores: [{ subject: 'math', score: 95, grade: 'A' }] }
// Only the math element is included, english is excluded

$elemMatch Projection vs $ Positional

// $ positional: returns the element matched by the query filter
db.students.find(
  { 'scores.subject': 'math' },
  { 'scores.$': 1 }
);

// $elemMatch projection: different filter from query
db.students.find(
  { name: 'Alice' },  // query doesn't filter scores
  { scores: { $elemMatch: { grade: 'A' } } }  // but project only A-grade scores
);

Deeply Nested Array Sub-Documents

// Document with nested arrays
// { courses: [{ name: 'Math', lessons: [{ id: 1, score: 95 }] }] }

// Query nested array with chained dot notation
db.curriculum.find({ 'courses.lessons.score': { $gt: 90 } });

// More precise with $elemMatch (one level)
db.curriculum.find({
  courses: {
    $elemMatch: {
      name: 'Math',
      'lessons.score': { $gt: 90 }  // dot notation within $elemMatch
    }
  }
});

Indexing for $elemMatch Queries

// Index on scores.subject for efficient $elemMatch queries
db.students.createIndex({ 'scores.subject': 1 });

// This $elemMatch query can use the index to find 'math' entries,
// then applies the grade: 'A' condition on those candidates
db.students.find({
  scores: {
    $elemMatch: {
      subject: 'math',  // <-- indexed, drives the IXSCAN
      grade: 'A'        // <-- applied after index lookup
    }
  }
});

$elemMatch With $exists and $type

// Find docs with at least one scores element that has a 'notes' field
db.students.find({
  scores: {
    $elemMatch: {
      notes: { $exists: true }
    }
  }
});

// Find docs with a scores element where score is a string (data quality check)
db.students.find({
  scores: {
    $elemMatch: {
      score: { $type: 'string' }  // should be a number!
    }
  }
});

Real-World Example: E-Commerce Orders

// Find orders containing 'product-123' with qty > 5
db.orders.find({
  lineItems: {
    $elemMatch: {
      productId: 'product-123',
      qty: { $gt: 5 }
    }
  }
});

// Also useful for status-filtered sub-documents:
db.projects.find({
  tasks: {
    $elemMatch: {
      assignee: 'alice',
      status: 'in-progress',
      priority: { $gte: 3 }
    }
  }
});

Quick Check

Lesson Recap