Querying Embedded Documents in MongoDB

Embedded Documents

MongoDB documents can contain other documents as field values. These nested structures, called embedded or subdocuments, let you model related data within a single document instead of splitting it across multiple collections. This is one of MongoDB's key differences from relational databases.

// Example document with embedded subdocuments
{
  _id: ObjectId("..."),
  name: "Alice Johnson",
  email: "alice@example.com",
  address: {
    street: "123 Main St",
    city: "San Francisco",
    state: "CA",
    zip: "94105"
  },
  company: {
    name: "TechCorp",
    role: "Engineer",
    department: {
      name: "Backend",
      floor: 3
    }
  }
}

Dot Notation Queries

Use dot notation to query fields inside embedded documents. Enclose the dotted path in quotes:

// Find users in San Francisco
db.users.find({ "address.city": "San Francisco" })

// Query deeply nested fields
db.users.find({ "company.department.name": "Backend" })

// Combine with query operators
db.users.find({
  "address.state": "CA",
  "company.role": { $in: ["Engineer", "Manager"] }
})

Exact Subdocument Match

You can match an entire subdocument, but the match must be exact -- including field order:

// Exact match - field order matters!
db.users.find({
  address: {
    street: "123 Main St",
    city: "San Francisco",
    state: "CA",
    zip: "94105"
  }
})

// This will NOT match if the document has extra fields
// or if fields are in a different order.
// Prefer dot notation for partial matching.

Updating Embedded Fields

Use dot notation with update operators to modify specific nested fields without replacing the entire subdocument:

// Update a single nested field
db.users.updateOne(
  { email: "alice@example.com" },
  { $set: { "address.zip": "94106" } }
)

// Update multiple nested fields
db.users.updateOne(
  { email: "alice@example.com" },
  {
    $set: {
      "company.role": "Senior Engineer",
      "company.department.floor": 5
    }
  }
)

// Add a new field to the embedded document
db.users.updateOne(
  { email: "alice@example.com" },
  { $set: { "address.country": "US" } }
)

Projecting Embedded Fields

Use dot notation in projections to return only specific nested fields:

// Return only the city from the address
db.users.find(
  {},
  { name: 1, "address.city": 1, "address.state": 1 }
)

// Result:
// { _id: ..., name: "Alice", address: { city: "San Francisco", state: "CA" } }

Arrays of Embedded Documents

Dot notation also works with arrays of subdocuments. Combine with $elemMatch for precise matching:

// Document: { orders: [{ product: "A", qty: 5 }, { product: "B", qty: 2 }] }

// Find by nested field in array
db.customers.find({ "orders.product": "A" })

// Multiple conditions on same array element
db.customers.find({
  orders: { $elemMatch: { product: "A", qty: { $gte: 5 } } }
})

Key Takeaways

• Use dot notation (in quotes) to query and update nested fields.
• Exact subdocument matching requires all fields in the correct order -- prefer dot notation.
• Dot notation with $set updates specific nested fields without overwriting the whole subdocument.
• Combine dot notation with $elemMatch for arrays of embedded documents.