Skip to content
Studio 3T - The professional GUI, IDE and client for MongoDB
  • Tools
    • Aggregation Editor
    • IntelliShell
    • Visual Query Builder
    • Export Wizard
    • Import Wizard
    • Query Code
    • SQL Query
    • Connect
    • Schema Explorer
    • Compare
    • SQL ⇔ MongoDB Migration
    • Data Masking
    • Task Scheduler
    • Reschema
    • More Tools and Features
  • Solutions
  • Resources
    • Knowledge Base
    • MongoDB Tutorials & Courses
    • Tool/Feature Documentation
    • Blog
    • Community
    • Testimonials
    • Whitepapers
    • Reports
  • Contact us
    • Contact
    • Sales Support
    • Feedback and Support
    • Careers
    • About Us
  • Store
    • Buy Now
    • Preferred Resellers
    • Team Pricing
  • Download
  • My 3T
search

Academy 3T

  • Explore our courses
    • MongoDB 101: Getting Started
    • MongoDB 201: Querying MongoDB Data
    • MongoDB 301: Aggregation
  • Get certified

Querying Embedded Documents in MongoDB Arrays

MongoDB 201: Querying MongoDB Data Querying Embedded Documents in MongoDB Arrays

In the previous tutorial in this course, you learned how to query MongoDB documents that contain fields defined with the Array data type.

An Array field can contain zero or more values (an array) of any supported type, including the Object type, which is used for embedded documents.

However, the examples in the last section were limited to arrays that contained only String values, making the querying process fairly straightforward. 

When an array contains embedded documents, you must be careful how you define your queries so you don’t end up with unexpected or misleading results.

Although this can be said of any query, documents embedded in an array present additional challenges. If you don’t get the query right, you could easily retrieve the wrong data.

In this section, you’ll learn how to create find statements that query a collection based on the embedded documents in an array.

To build and run these queries, you’ll use IntelliShell and Visual Query Builder, both Studio 3T features. Although Visual Query Builder tends to be best suited to simpler queries when it comes to embedded documents, it is still important to understand how it differs from querying arrays that contain other types of values.

Got other features and functionalities you’d like to see in tools for MongoDB? Join the 3T Research Program and help shape our product roadmap.

Querying embedded documents in a MongoDB array

Querying documents based on an array that contains embedded documents is a little different from querying other types of array values.

Although many of the fundamentals are the same, the way you define your search conditions can vary, depending on what you’re trying to achieve.

Suppose you have a MongoDB database that includes the warehouses collection, which stores information about the inventories available at your company’s warehouses.

Now suppose you add the following three documents to the collection:

db.warehouses.insertMany( [
  {
    _id: 1,
    warehouse : "warehouse1",  
    inventory : [
      { product: "widgetA", in_stock: 24 },
      { product: "widgetB", in_stock: 137 },
      { product: "widgetC", in_stock: 99 } ]
  },
  {
    _id: 2,
    warehouse : "warehouse2",
    inventory : [
      { product: "widgetA", in_stock: 99 },
      { product: "widgetC", in_stock: 12 },
      { product: "widgetG", in_stock: 122 } ]
  },
  {
    _id: 3,
    warehouse : "warehouse3",  
    inventory : [
      { product: "widgetC", in_stock: 89 },
      { product: "widgetD", in_stock: 99 },
      { product: "widgetF", in_stock: 43 } ]
  } ] );

Each document includes the inventory field, which is defined with the Array data type, as indicated by the set of square brackets that follow the field name.

The brackets enclose the embedded documents that make up the array’s values.

Each embedded document includes the product field and in_stock field, along with their respective values.

Now suppose you need to know which warehouses have at least 90 widgetC products in stock. In an attempt to discover this information, you might try the following find statement:

db.warehouses.find({
  "inventory.product": "widgetC", 
  "inventory.in_stock": { $gte: 90 } } );

The statement specifies that the product value must equal widgetC and the in_stock value must be at least 90.

The second search condition uses the greater than or equal to ($gte) comparison operator to specify the acceptable number of products.

Unfortunately, the find statement returns all three documents, even though the first document is the only one whose warehouse has at least 90 widgetC products.

This is because each document includes the widgetC product and each one includes a quantity that is greater than or equal to 90.

The search engine is indifferent to whether the product value and in_stock value are in the same embedded document, only that the array as a whole contains these values.

In an attempt to rectify this situation, you might try the following find statement, which separates the name of the array from the embedded document elements:

db.warehouses.find({  
   inventory: { product: "widgetC", in_stock: { $gte: 90 } } } );

This time, the statement returns no documents because the search engine is looking for an exact match, which is not possible with the $gte comparison operator.

To match the values exactly, you would need to use a statement such as the following, which specifies the exact product amount:

db.warehouses.find({ 
  inventory: { product: "widgetC", in_stock: 99 } } );

Although the statement returns the first document, as it should, this approach is effective only if you know the exact number of items in stock, which was not your original intent.

This approach also requires that you specify all elements in the array in the order they’re listed. If a document’s elements are in a different order, the document will not be included in the search results, even if the field values match.

A better approach is to use the $elemMatch operator, which returns documents containing an array element that matches the specified criteria. The following syntax shows how to use the operator:

{ <array_field>: { $elemMatch: { <search_condition> [ ,...n ] } } }

First, you specify the array field, then the $elemMatch keyword, and finally one or more search conditions, with everything enclosed in the appropriate curly braces. For example, to find warehouses that have at least 90 widgetC products, you would run the following find statement:

db.warehouses.find(
  { inventory: { $elemMatch: 
    { product: "widgetC", in_stock: { $gte: 90 } } } } );

The argument passed into the find method starts with the array field name (inventory), followed by the $elemMatch operator and two search conditions, which specify the target product name and number of items. 

For a document to be returned, at least one of the array’s embedded documents must match the two search conditions.

In this case, only the first document will be returned because it represents the only warehouse that has at least 90 widgetC products on hand.

By the end of this section, you will learn how to:

  • Use the $elemMatch operator to query embedded documents
  • Use conditional operators to query embedded documents
  • Use Visual Query Builder to query embedded documents

What you will need:

  • Access to a MongoDB Atlas cluster
  • Access to the customers collection in the sales database
Lesson Content
0% Complete 0/3 Steps
Lesson 5, Exercise 1: Using the $elemMatch operator to query embedded documents
Lesson 5, Exercise 2: Using conditional operators to query embedded documents
Lesson 5, Exercise 3: Using Visual Query Builder to query embedded documents
Test your skills: Querying Embedded Documents in Arrays
Previous Lesson
Back to Course
Next Topic
  • Course Home Expand All
    Performing MongoDB CRUD Operations
    4 Topics | 1 Quiz
    Lesson 1, Exercise 1: Adding a document to a collection
    Lesson 1, Exercise 2: Viewing a document in a collection
    Lesson 1, Exercise 3: Updating a document in a collection
    Lesson 1, Exercise 4: Deleting a document from a collection
    Test your skills: Performing CRUD Operations
    Building MongoDB find() Queries
    4 Topics | 1 Quiz
    Lesson 2: The MongoDB find method
    Lesson 2, Exercise 1: Using IntelliShell to build and run find statements
    Lesson 2, Exercise 2: Using Visual Query Builder to build and run find statements
    Lesson 2, Exercise 3: Using Query Code and IntelliShell to modify and run a find statement
    Test your skills: Building MongoDB find() Queries
    Working with the MongoDB Aggregation Pipeline
    6 Topics | 1 Quiz
    Lesson 3: Introducing the MongoDB aggregate method
    Lesson 3, Exercise 1: Filtering the documents in the aggregation pipeline
    Lesson 3, Exercise 2: Grouping the documents in the aggregation pipeline
    Lesson 3, Exercise 3: Adding and removing fields in the aggregation pipeline
    Lesson 3, Exercise 4: Changing the field order in the aggregation pipeline
    Lesson 3, Exercise 5: Sorting the documents in the aggregation pipeline
    Test your skills: Working with the MongoDB Aggregation Pipeline
    Querying Arrays Using MongoDB $elemMatch
    4 Topics | 1 Quiz
    Lesson 4, Exercise 1: Using IntelliShell to query single and multiple values in an array
    Lesson 4, Exercise 2: Using Visual Query Builder to query a single array value
    Lesson 4, Exercise 3: Using Visual Query Builder to query multiple array values
    Test your skills: Querying Arrays Using MongoDB $elemMatch
    MongoDB 201 Mid-Course Feedback
    Querying Embedded Documents in MongoDB Arrays
    3 Topics | 1 Quiz
    Lesson 5, Exercise 1: Using the $elemMatch operator to query embedded documents
    Lesson 5, Exercise 2: Using conditional operators to query embedded documents
    Lesson 5, Exercise 3: Using Visual Query Builder to query embedded documents
    Test your skills: Querying Embedded Documents in Arrays
    Querying MongoDB with SQL SELECT Statements
    2 Topics | 1 Quiz
    Lesson 6, Exercise 1: Using the SQL Query tool to run SQL statements
    Lesson 6, Exercise 2: Using the SQL Query tool to aggregate collection data
    Test your skills: Querying MongoDB with SQL
    Working with MongoDB Views
    3 Topics | 1 Quiz
    Lesson 7, Exercise 1: Creating a MongoDB view
    Lesson 7, Exercise 2: Querying a MongoDB view
    Lesson 7, Exercise 3: Modifying and deleting a MongoDB view
    Test your skills: Working with MongoDB Views
    Course Extras
    Return to MongoDB 201: Querying MongoDB Data
  • Studio 3T

    MongoDB Enterprise Certified Technology PartnerSince 2014, 3T has been helping thousands of MongoDB developers and administrators with their everyday jobs by providing the finest MongoDB tools on the market. We guarantee the best compatibility with current and legacy releases of MongoDB, continue to deliver new features with every new software release, and provide high quality support.

    Find us on FacebookFind us on TwitterFind us on YouTubeFind us on LinkedIn

    Education

    • Free MongoDB Tutorials
    • Connect to MongoDB
    • Connect to MongoDB Atlas
    • Import Data to MongoDB
    • Export MongoDB Data
    • Build Aggregation Queries
    • Query MongoDB with SQL
    • Migrate from SQL to MongoDB

    Resources

    • Feedback and Support
    • Sales Support
    • Knowledge Base
    • FAQ
    • Reports
    • White Papers
    • Testimonials
    • Discounts

    Company

    • About Us
    • Blog
    • Careers
    • Legal
    • Press
    • Privacy Policy
    • EULA

    © 2023 3T Software Labs Ltd. All rights reserved.

    • Privacy Policy
    • Cookie settings
    • Impressum

    We value your privacy

    With your consent, we and third-party providers use cookies and similar technologies on our website to analyse your use of our site for market research or advertising purposes ("analytics and marketing") and to provide you with additional functions (“functional”). This may result in the creation of pseudonymous usage profiles and the transfer of personal data to third countries, including the USA, which may have no adequate level of protection for the processing of personal data.

    By clicking “Accept all”, you consent to the storage of cookies and the processing of personal data for these purposes, including any transfers to third countries. By clicking on “Decline all”, you do not give your consent and we will only store cookies that are necessary for our website. You can customize the cookies we store on your device or change your selection at any time - thus also revoking your consent with effect for the future - under “Manage Cookies”, or “Cookie Settings” at the bottom of the page. You can find further information in our Privacy Policy.
    Accept all
    Decline all
    Manage cookies
    ✕

    Privacy Preference Center

    With your consent, we and third-party providers use cookies and similar technologies on our website to analyse your use of our site for market research or advertising purposes ("analytics and marketing") and to provide you with additional functions (“functional”). This may result in the creation of pseudonymous usage profiles and the transfer of personal data to third countries, including the USA, which may have no adequate level of protection for the processing of personal data. Please choose for which purposes you wish to give us your consent and store your preferences by clicking on “Accept selected”. You can find further information in our Privacy Policy.

    Accept all cookies

    Manage consent preferences

    Essential cookies are strictly necessary to provide an online service such as our website or a service on our website which you have requested. The website or service will not work without them.

    Performance cookies allow us to collect information such as number of visits and sources of traffic. This information is used in aggregate form to help us understand how our websites are being used, allowing us to improve both our website’s performance and your experience.

    Google Analytics

    Google Ads

    Bing Ads

    Facebook

    LinkedIn

    Quora

    Hotjar

    Functional cookies collect information about your preferences and choices and make using the website a lot easier and more relevant. Without these cookies, some of the site functionality may not work as intended.

    HubSpot

    Social media cookies are cookies used to share user behaviour information with a third-party social media platform. They may consequently effect how social media sites present you with information in the future.

    Accept selected