Arrays of Documents and $elemMatch

Dot notation reaches a field of every document in an array, such as "ingredients.name"; two such conditions can be met by two different items, and $elemMatch makes them hold for the same item.

Journeyman · MongoDB · Updated

By

After this lesson you can

  • Find documents by a field of the documents in an array, such as ingredients.name, with dot notation
  • Use $elemMatch when two conditions must hold for the same item in an array of documents, and explain why

Key takeaways

  • In an array of documents, "ingredients.name" means the name of any ingredient, and the filter matches when one of them fits.
  • Two dotted conditions on the same array can each be met by a different item, which can match recipes you didn't mean.
  • $elemMatch goes on the array field and matches only when one item meets every condition inside it.
  • Inside $elemMatch, the item's fields are written without the array's name, such as name and amount.
  • One condition on the items needs only dot notation; two or more that must be true of the same item need $elemMatch.

An order holds a list of line items, each with a product and a quantity. A cart holds items with a size and a color. A recipe holds ingredients, each with a name, an amount and a unit. Questions about these lists come up all the time ("orders with more than one of the blue mug", "recipes that use 2 cups of flour"), and they hide a trap: a filter can match two halves of the question on two different items. This lesson shows the trap and the operator that closes it.

The examples use Sunday Kitchen's 40 recipes from Fields Inside Fields: Dot Notation.

A field of every item: "ingredients.name"

Each recipe's ingredients is an array of documents. Here are Hummus's, with a projection that shows only them:

db.recipes.findOne({ _id: 35 }, { ingredients: 1 })
{
  _id: 35,
  ingredients: [
    { name: 'chickpeas', amount: 1, unit: 'cans' },
    { name: 'tahini', amount: 0.25, unit: 'cups' },
    { name: 'lemon', amount: 1, unit: 'whole' },
    { name: 'garlic', amount: 2, unit: 'cloves' }
  ]
}

"What can I cook with the chickpeas in my pantry?" Dot notation from Fields Inside Fields: Dot Notation reaches into an array of documents too. "ingredients.name" (read "ingredients dot name") means the name of any ingredient, and the filter matches when one of them fits:

db.recipes.find({ "ingredients.name": "chickpeas" }, { name: 1 })
[
  { _id: 4, name: 'Chickpea Curry' },
  { _id: 33, name: 'Falafel Wraps' },
  { _id: 35, name: 'Hummus' }
]

The array operators from Querying Arrays: One Value, $all and $size work on a dotted path the same way. Recipes that use both garlic and lemon:

db.recipes.find({ "ingredients.name": { $all: ["garlic", "lemon"] } }, { name: 1 })
[
  { _id: 19, name: 'Lentil Soup' },
  { _id: 22, name: 'Caesar Salad' },
  { _id: 33, name: 'Falafel Wraps' },
  { _id: 35, name: 'Hummus' }
]

Two conditions, two different items

Sunday Kitchen is planning a big baking day and wants the recipes that use at least 2 cups of flour. Every flour amount on the cards is in cups, so it looks like two dotted conditions side by side, an ingredient named flour and an amount of 2 or more:

db.recipes.find({ "ingredients.name": "flour", "ingredients.amount": { $gte: 2 } }, { name: 1 })
[
  { _id: 1, name: 'Saturday Pancakes' },
  { _id: 3, name: 'Lemon Bars' },
  { _id: 6, name: 'Margherita Pizza' },
  { _id: 11, name: 'Banana Bread' },
  { _id: 23, name: 'Chocolate Chip Cookies' },
  { _id: 31, name: 'Apple Crumble' },
  { _id: 39, name: 'Churros' }
]

Seven recipes, and some look wrong. Check Banana Bread's ingredients:

db.recipes.findOne({ _id: 11 }, { name: 1, ingredients: 1 })
{
  _id: 11,
  name: 'Banana Bread',
  ingredients: [
    { name: 'flour', amount: 1.75, unit: 'cups' },
    { name: 'bananas', amount: 3, unit: 'whole' },
    { name: 'sugar', amount: 0.75, unit: 'cups' },
    { name: 'eggs', amount: 2, unit: 'whole' }
  ]
}

Banana Bread uses 1.75 cups of flour. It matched because each condition asked about any ingredient, separately: some ingredient is named flour (the first), and some ingredient has an amount of 2 or more (the bananas, 3 whole). Two different items answered the two halves. Saturday Pancakes, Apple Crumble and Churros got in the same way: each uses less than 2 cups of flour, and some other ingredient has an amount of 2 or more.

It's like asking a friend for "a red shirt in medium" from a pile that holds a red large and a blue medium. Red, yes; medium, yes; but not the same shirt.

Two ingredient lists side by side. On the left, Banana Bread: flour 1.75 cups, bananas 3 whole, sugar 0.75 cups, eggs 2 whole. A check mark labeled name is flour points at the flour row, and a second check mark labeled amount is 2 or more points at the bananas row, two different rows, under the heading matched by two different items. On the right, Lemon Bars: flour 2 cups, sugar 1.5 cups, eggs 4 whole, lemon 3 whole. Both check marks point at the same flour row, under the heading $elemMatch, one item meets both.

$elemMatch: both conditions on the same item

$elemMatch (read "element match"; an element is one item of an array) goes on the array field itself and takes the conditions for one item. A recipe matches only when a single ingredient meets all of them:

db.recipes.find({ ingredients: { $elemMatch: { name: "flour", amount: { $gte: 2 } } } }, { name: 1 })
[
  { _id: 3, name: 'Lemon Bars' },
  { _id: 6, name: 'Margherita Pizza' },
  { _id: 23, name: 'Chocolate Chip Cookies' }
]

Read it aloud: "recipes with an ingredient whose name is flour and whose amount is at least 2". Two details to notice. The operator sits on ingredients, not on "ingredients.name". And inside it, the fields are the item's own, name and amount, with no ingredients. in front, because $elemMatch already stands on each item.

A recipe card that gave some flour in tablespoons would need a third condition, unit: "cups", inside the same braces; $elemMatch takes as many as the item needs.

When you need $elemMatch

The test is how many conditions must be true of the same item:

The question The filter
Uses chickpeas (one condition) { "ingredients.name": "chickpeas" }
Uses garlic and lemon (two items, a condition each) { "ingredients.name": { $all: ["garlic", "lemon"] } }
Uses 2 or more cups of flour (two conditions, one item) { ingredients: { $elemMatch: { name: "flour", amount: { $gte: 2 } } } }

One condition on the items needs only dot notation. Two or more that describe one item, such as its name and its amount, need $elemMatch, or another item can answer half of the question.

Check yourself

2 questions to try on the lesson page.

So what

Lists of documents are how real apps store order lines, cart items and ingredients. You can now search them by any field, and when a question describes one item, $elemMatch keeps a different item from answering half of it.

Key terms

Related