Querying Arrays: One Value, $all and $size

A filter on an array field matches when any item fits, $in matches when any item is one of a list, $all asks for every value in a list, and $size counts the items; an exact array match is rarely what you want.

Apprentice · MongoDB · Updated

By

After this lesson you can

  • Find documents whose array holds a value, or any of several values, with a plain filter or $in
  • Match arrays by their items with $all and by their length with $size, and explain why an exact array match is rarely wanted

Key takeaways

  • A filter like tags "vegan" matches a recipe when any item in its tags list is "vegan".
  • $in on an array field matches when any item equals any value in the list.
  • $all matches when the array holds every value in the list, in any order, with other items allowed.
  • $size matches an array with exactly that many items.
  • Giving a whole list as the value asks for exactly that list, in that order, so it's rarely what you want.

A blog post has a list of topics, a shirt comes in a list of sizes, and a recipe has a list of tags. Every time an app shows "posts tagged JavaScript" or "shirts that come in medium", it's asking about a list. You'll filter on lists in almost every app you build, and they behave differently from a field with one value.

The examples use Sunday Kitchen's 40 recipes from Fields Inside Fields: Dot Notation. Each recipe's tags is an array: a list of values in square brackets, such as tags: ["vegan", "spicy"].

One value matches any item

Sunday Kitchen wants a page for its vegan recipes. tags is a list, so you might expect to need a special operator. You don't. Ask for the value, the way you'd ask for one cuisine:

db.recipes.find({ tags: "vegan" }, { name: 1, tags: 1 })
[
  { _id: 4, name: 'Chickpea Curry', tags: [ 'vegan', 'spicy' ] },
  { _id: 7, name: 'Black Bean Tacos', tags: [ 'vegan', 'kid-friendly' ] },
  { _id: 13, name: 'Veggie Stir-Fry', tags: [ 'vegan' ] },
  { _id: 19, name: 'Lentil Soup', tags: [ 'vegan', 'soup' ] },
  { _id: 20, name: 'Guacamole', tags: [ 'vegan', 'no-cook' ] },
  { _id: 26, name: 'Ratatouille', tags: [ 'vegan', 'make-ahead' ] },
  { _id: 28, name: 'Mango Sticky Rice', tags: [ 'sweet', 'vegan' ] },
  { _id: 33, name: 'Falafel Wraps', tags: [ 'vegan' ] },
  { _id: 35, name: 'Hummus', tags: [ 'vegan', 'no-cook' ] }
]

Think of a grocery bag: "is there milk in it?" doesn't care what else is in the bag. When a field holds an array, MongoDB looks at every item, and the filter matches if any one item is "vegan". Chickpea Curry is also spicy, and Mango Sticky Rice is also sweet; they're found all the same.

$in from Comparison Operators: $gt, $lt, $in and More works on a list too: it matches when any item equals any value in its list. A cozy-night page wants soups and noodle dishes:

db.recipes.find({ tags: { $in: ["soup", "noodles"] } }, { name: 1, tags: 1 })
[
  { _id: 5, name: 'Pad Thai', tags: [ 'noodles' ] },
  { _id: 8, name: 'Miso Soup', tags: [ 'soup' ] },
  { _id: 14, name: 'Beef Pho', tags: [ 'soup', 'noodles' ] },
  { _id: 19, name: 'Lentil Soup', tags: [ 'vegan', 'soup' ] },
  { _id: 29, name: 'Minestrone', tags: [ 'soup', 'make-ahead' ] },
  { _id: 37, name: 'Shoyu Ramen', tags: [ 'soup', 'noodles' ] },
  { _id: 40, name: 'Tomato Soup', tags: [ 'soup', 'kid-friendly' ] }
]

Beef Pho has both tags and is found once.

$all: every one of these

Now the page wants recipes that are vegan and spicy. Combining Conditions: $and, $or and $not warned about writing a field twice: only the last one counts, so { tags: "vegan", tags: "spicy" } means { tags: "spicy" }. $all (read "all") takes a list and matches when the array holds every value in it:

db.recipes.find({ tags: { $all: ["vegan", "spicy"] } }, { name: 1, tags: 1 })
[ { _id: 4, name: 'Chickpea Curry', tags: [ 'vegan', 'spicy' ] } ]

The order in the list doesn't matter, and the array may hold other items too. Recipes tagged both sweet and bake-sale:

db.recipes.find({ tags: { $all: ["sweet", "bake-sale"] } }, { name: 1, tags: 1 })
[
  { _id: 3, name: 'Lemon Bars', tags: [ 'sweet', 'bake-sale' ] },
  { _id: 11, name: 'Banana Bread', tags: [ 'sweet', 'bake-sale' ] },
  {
    _id: 23,
    name: 'Chocolate Chip Cookies',
    tags: [ 'sweet', 'bake-sale', 'kid-friendly' ]
  }
]

Chocolate Chip Cookies are also kid-friendly, and $all doesn't mind.

An exact list, and why it's rarely wanted

Give a whole list as the value, without $all, and the filter asks for exactly that list:

db.recipes.find({ tags: ["sweet", "bake-sale"] }, { name: 1, tags: 1 })
[
  { _id: 3, name: 'Lemon Bars', tags: [ 'sweet', 'bake-sale' ] },
  { _id: 11, name: 'Banana Bread', tags: [ 'sweet', 'bake-sale' ] }
]

The cookies are gone: their list has a third tag. Swap the two values, and even Lemon Bars and Banana Bread drop out:

db.recipes.countDocuments({ tags: ["bake-sale", "sweet"] })
0

An exact match wants the same items, the same number of them, in the same order. A cook who adds one more tag to a card would quietly break the page. When the question is "has these tags", use $all.

Three recipe cards with their tag lists: Lemon Bars with sweet and bake-sale, Banana Bread with sweet and bake-sale, and Chocolate Chip Cookies with sweet, bake-sale and kid-friendly. A bracket labeled $all sweet and bake-sale covers all three cards. A shorter bracket labeled exact list sweet and bake-sale covers only the first two, because the cookies have a third tag.

$size: how many items

$size (read "size") matches an array with exactly that many items. One recipe carries three tags:

db.recipes.find({ tags: { $size: 3 } }, { name: 1, tags: 1 })
[
  {
    _id: 23,
    name: 'Chocolate Chip Cookies',
    tags: [ 'sweet', 'bake-sale', 'kid-friendly' ]
  }
]

And the cards with a single tag, which a cook might want to tag more fully:

db.recipes.countDocuments({ tags: { $size: 1 } })
21

$size takes one exact number. It can't take a comparison, so "two or more tags" is a question for later tools, not for $size.

The question The filter
Has this tag { tags: "vegan" }
Has any of these tags { tags: { $in: ["soup", "noodles"] } }
Has all of these tags { tags: { $all: ["vegan", "spicy"] } }
Has exactly this many tags { tags: { $size: 3 } }
Is exactly this list, in this order { tags: ["sweet", "bake-sale"] }

Check yourself

2 questions to try on the lesson page.

So what

Lists are everywhere in real documents. A plain value finds any item, $in any of several, $all every one of them, and $size the count, and none of them breaks when a list gains one more item.

Key terms

Related