For AI agents: a documentation index is available at https://www.mongodb.com/docs/llms.txt — markdown versions of all pages are available by appending .md to any URL path.

Query an Array

You can query arrays in MongoDB using the following methods:

➤ Use the Select your language drop-down menu in the upper-right to set the language of the following examples or select MongoDB Compass.

This page provides examples of query operations on array fields using the db.collection.find() method in mongosh.

The examples on this page use data from the sample_mflix dataset. For details on how to load this dataset into your self-managed MongoDB deployment, see Load the Sample Dataset. If you made any modifications to the sample databases, you may need to drop and recreate the databases to run the examples on this page.

Match an Array

To specify equality condition on an array, use the query document { <field>: <value> } where <value> is the exact array to match, including the order of the elements.

The following example queries for all documents where genres is an array with exactly two elements, "Action" and "Comedy", in the specified order:

db.movies.find( { genres: ["Action", "Comedy"] } )

To find an array that contains both "Action" and "Comedy" regardless of order or other elements in the array, use the $all operator:

db.movies.find( { genres: { $all: ["Action", "Comedy"] } } )

Query an Array for an Element

To query if the array field contains at least one element with the specified value, use the filter { <field>: <value> } where <value> is the element value.

The following example queries for all documents where the genres array contains the string "Short" as one of its elements:

db.movies.find( { genres: "Short" } )

To specify conditions on the elements in the array field, use query operators in the query filter document:

{ <array field>: { <operator1>: <value1>, ... } }

The following example queries for all documents where the cast array contains at least one element that matches the regular expression ^A:

db.movies.find( { cast: { $regex: "^A" } } )

Specify Multiple Conditions for Array Elements

When you specify compound conditions on array elements, you can query for documents where either:

  • A single array element meets all the specified conditions

  • Different array elements collectively meet all the conditions, with each element satisfying one or more conditions

Query an Array with Compound Filter Conditions on the Array Elements

The following example queries for documents where the cast array contains elements that in some combination satisfy the query conditions. One element can satisfy the $regex: "^A" condition and another element can satisfy the $ne: "Adam Sandler" condition, or a single element can satisfy both:

db.movies.find(   { cast: { $regex: "^A", $ne: "Adam Sandler" } })

Query for an Array Element that Meets Multiple Criteria

Use the $elemMatch operator to specify multiple criteria on array elements so that at least one array element satisfies all the specified criteria.

The following example queries for documents where the cast array contains at least one element that both matches the regular expression ^A and is not equal to "Adam Sandler":

db.movies.find(   { cast: { $elemMatch: { $regex: "^A", $ne: "Adam Sandler" } } })

Query for an Element by the Array Index Position

Use dot notation to specify query conditions for an element at a particular index or position of the array. The array uses zero-based indexing.

Note

When you query using dot notation, the field and nested field must be inside quotation marks.

The following example queries for all documents where the first element in the array cast equals "Tom Hanks":

db.movies.find( { "cast.0": "Tom Hanks" } )

Query an Array by Array Length

Use the $size operator to query for arrays by number of elements.

The following example selects documents where genres has 3 elements:

db.movies.find( { genres: { $size: 3 } } )

Query an Array with MongoDB Atlas

The example in this section uses the sample movies dataset. To learn how to load the sample dataset into your MongoDB Atlas deployment, see Load Sample Data.

To query an array in MongoDB Atlas, follow these steps:

1

In the MongoDB Atlas UI, go to the Clusters page for your project.

  1. If it's not already displayed, select the organization that contains your desired project from the Organizations menu in the navigation bar.

  2. If it's not already displayed, select your project from the Projects menu in the navigation bar.

  3. In the sidebar, click Clusters under the Database heading.

    The Clusters page displays.

2

Navigate to the collection.

  1. For the cluster that contains the sample data, click Browse Collections.

  2. In the left navigation pane, select the sample_mflix database.

  3. Select the movies collection.

3

Specify a query filter document.

To query a document that contains an array, specify a query filter document. A query filter document uses query operators to specify search conditions. Use the following example documents to query array fields in the sample_mflix.movies collection.

To apply a query filter, copy an example document into the Filter search bar and click Apply.

To specify an equality condition on an array, use the query document { <field>: <value> } where <value> is the exact array to match, including the order of the elements. The following example finds documents where genres contains the ["Action", "Comedy"] array in the specified order:

{ genres: ["Action", "Comedy"] }

To find an array that contains both Action and Comedy regardless of order or other elements in the array, use the $all operator:

{ genres: { $all: ["Action", "Comedy"] } }

Additional Query Tutorials

For additional query examples, see:

Back
Embedded Documents
Next
Arrays of Embedded Documents
Select your language
Rate this page

On this page