Visit complete MongoDB roadmap

← Back to Topics List

Embedded Documents and Arrays

In MongoDB, one of the powerful features is the ability to store complex data structures like Embedded Documents Arrays. These are essentially arrays of sub-documents (also known as nested documents) that can be stored within a single document. This allows us to model complex data relationships in a highly efficient way while maintaining good performance.

What are Embedded Documents Arrays?

Embedded Documents Arrays are used when you need to represent a ‘one-to-many’ or hierarchical relationship between data. Instead of using separate collections and references, you can embed the related documents directly into the main document using an array.

Here’s an example of a document containing an embedded array of sub-documents:

    _id: 1,
    name: 'John Doe',
    addresses: [
            street: '123 Main St',
            city: 'New York',
            zipcode: '10001'
            street: '456 Broadway',
            city: 'Los Angeles',
            zipcode: '90001'

In this example, the addresses field represents an array of embedded sub-documents that contain the address details for the user.


Embedded Documents Arrays offer a few key advantages:

  • Read/Write Performance: Since related data is stored together within the same document, read and write operations can be faster, as they don’t require multiple queries or updates.
  • Data Consistency: By storing related data together, you can easily maintain consistency and ensure that related data is always in-sync without having to rely on joins or cross-references.
  • Scalability: Embedded arrays can be nested, allowing you to represent complex data structures while maintaining the benefits of a flexible schema and high performance.

When to Use Embedded Documents Arrays

Consider using Embedded Documents Arrays when:

  • You have a one-to-many relationship
  • The embedded data does not grow unbounded
  • The embedded data is strongly related to the parent document
  • You can benefit from improved read/write performance

Keep in mind that MongoDB has a document size limitation of 16MB, so if you expect the embedded data to grow over time, you should consider alternative approaches, such as using separate collections and referencing them instead.

Querying Embedded Documents Arrays

Querying documents with embedded arrays is easy thanks to MongoDB’s built-in array query operators, such as $elemMatch, $all, and $size. You can also use dot notation to search and update embedded sub-documents.

For example, to find all users with a specific street address, you would use the following query:

db.users.find({ 'addresses.street': '123 Main St' });

Overall, Embedded Documents Arrays are a powerful feature in MongoDB, allowing you to store complex data relationships in a performant and efficient manner. Use them wisely to take full advantage of MongoDB’s flexibility and scalability.

Community is the 6th most starred project on GitHub and is visited by hundreds of thousands of developers every month.

Roadmaps Best Practices Guides Videos Store YouTube by Kamran Ahmed

Community created roadmaps, articles, resources and journeys to help you choose your path and grow in your career.

© · FAQs · Terms · Privacy


The leading DevOps resource for Kubernetes, cloud-native computing, and the latest in at-scale development, deployment, and management.