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.

Read Documents

In MongoDB, a Read operation consists of querying the database. This page provides examples.

You can query documents in MongoDB with 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 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.

Select All Documents in a Collection

To select all documents in the collection, pass an empty document as the query filter parameter to the find method. The query filter parameter determines the select criteria:

db.movies.find( {} )

This operation uses an empty query predicate of {}, which corresponds to the following SQL statement:

SELECT * FROM movies

For more information, see find().

Specify Equality Condition

To specify equality conditions, use <field>:<value> expressions in the query filter document:

{ <field1>: <value1>, ... }

The following example selects all documents from the sample_mflix.movies collection where rated equals "PG-13":

db.movies.find( { rated: "PG-13" } )

This operation uses a query predicate of { rated: "PG-13" }, which corresponds to the following SQL statement:

SELECT * FROM movies WHERE rated = "PG-13"

Specify Conditions Using Query Operators

A query filter document can use the query operators to specify conditions in the following form:

{ <field1>: { <operator1>: <value1> }, ... }

The following example retrieves all documents from the sample_mflix.movies collection where rated equals either "G" or "PG-13":

db.movies.find( { rated: { $in: [ "G", "PG-13" ] } } )

Note

Although you can use the $or operator for this query, use the $in operator instead of $or when performing equality checks on the same field.

The operation uses a query predicate of { rated: { $in: [ "G", "PG-13" ] } }, which corresponds to the following SQL statement:

SELECT * FROM movies WHERE rated in ("G", "PG-13")

For the complete list of MongoDB query operators, see Query Predicates.

Specify AND Conditions

A compound query can specify conditions for more than one field in the collection's documents. Implicitly, a logical AND conjunction connects the clauses of a compound query so that the query selects the documents in the collection that match all the conditions.

The following example retrieves all documents in the sample_mflix.movies collection where rated equals "G" and runtime is less than ($lt) 90:

db.movies.find( { rated: "G", runtime: { $lt: 90 } } )

The operation uses a query predicate of { rated: "G", runtime: { $lt: 90 } }, which corresponds to the following SQL statement:

SELECT * FROM movies WHERE rated = "G" AND runtime < 90

See comparison operators for other MongoDB comparison operators.

Specify OR Conditions

Use the $or operator to specify a compound query that joins each clause with a logical OR conjunction. The query selects documents that match at least one condition.

The following example retrieves all documents in the sample_mflix.movies collection where rated equals "G" or runtime is less than ($lt) 90:

db.movies.find( { $or: [ { rated: "G" }, { runtime: { $lt: 90 } } ] } )

The operation uses a query predicate of { $or: [ { rated: 'G' }, { runtime: { $lt: 90 } } ] }, which corresponds to the following SQL statement:

SELECT * FROM movies WHERE rated = "G" OR runtime < 90

Note

Queries with comparison operators are subject to Type Bracketing in Query Predicates.

Specify AND as well as OR Conditions

In the following example, the compound query document selects all documents in the sample_mflix.movies collection where rated equals "G" and either runtime is less than ($lt) 90 or title starts with the character T:

db.movies.find( {     rated: "G",     $or: [ { runtime: { $lt: 90 } }, { title: /^T/ } ]} )

The operation uses a query predicate of:

{   rated: 'G',   $or: [     { runtime: { $lt: 90 } },     { title: { $regex: '^T' } }   ]}

which corresponds to the following SQL statement:

SELECT * FROM movies WHERE rated = "G"AND ( runtime < 90 OR title LIKE "T%")

Note

MongoDB supports regular expression $regex queries to perform string pattern matches.

Regular expression syntax differs between mongosh and drivers. mongosh uses JavaScript regex literals (for example, { title: /^T/ }). The drivers use the equivalent $regex operator (for example, { title: { $regex: '^T' } }).

Query Documents with MongoDB Atlas

This example uses the sample movies dataset. To load the sample dataset into your MongoDB Atlas deployment, see Load Sample Data.

To project fields for a query 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 the Filter field

Specify the query filter document in the Filter field. A query filter document uses query operators to specify search conditions.

Copy the following query filter document into the Filter search bar:

{ year: 1924 }
4

Click Apply

The query returns all documents in the sample_mflix.movies collection where the year field matches 1924.

Additional Query Tutorials

For more query examples, see:

Behavior

Cursor

The db.collection.find() method returns a cursor to the matching documents.

Concurrent Updates While Using a Cursor

As a cursor returns documents, other operations may run in the background and affect the results, depending on the read concern level. For details, see Read Isolation, Consistency, and Recency.

Read Isolation

For reads to replica sets and replica set shards, read concern lets clients choose an isolation level for their reads. For more information, see Read Concern.

Query Result Format

When you run a find operation with a MongoDB driver or mongosh, MongoDB returns a cursor that manages query results. Query results are not returned as an array of documents.

To learn how to iterate through documents in a cursor, see your driver's documentation. If you are using mongosh, see Iterate a Cursor in mongosh.

Additional Methods and Options

You can also read documents from a collection with:

Note

The db.collection.findOne() method performs the same operation as db.collection.find() with a limit of 1.

Back
Create
Next
Embedded Documents
Earn a Skill Badge

Master "Query Optimization" for free!

Learn more
Select your language
Rate this page

On this page