Read Operations Overview¶

On this page

Query Interface
Query Behavior
Query Statements
Projections

Read operations, or queries, retrieve data stored in the database. In MongoDB, queries select documents from a single collection.

Queries specify criteria, or conditions, that identify the documents that MongoDB returns to the clients. A query may include a projection that specifies the fields from the matching documents to return. The projection limits the amount of data that MongoDB returns to the client over the network.

Query Interface¶

For query operations, MongoDB provides a db.collection.find() method. The method accepts both the query criteria and projections and returns a cursor to the matching documents. You can optionally modify the query to impose limits, skips, and sort orders.

The following diagram highlights the components of a MongoDB query operation:

The components of a MongoDB find operation.

The next diagram shows the same query in SQL:

The components of a SQL SELECT statement.

Example

db.users.find( { age: { $gt: 18 } }, { name: 1, address: 1 } ).limit(5)

This query selects the documents in the users collection that match the condition age is greater than 18. To specify the greater than condition, query criteria uses the greater than (i.e. $gt) query selection operator. The query returns at most 5 matching documents (or more precisely, a cursor to those documents). The matching documents will return with only the _id, name and address fields. See Projections for details.

See

SQL to MongoDB Mapping Chart for additional examples of MongoDB queries and the corresponding SQL statements.

Query Behavior¶

MongoDB queries exhibit the following behavior:

All queries in MongoDB address a single collection.
You can modify the query to impose limits, skips, and sort orders.
The order of documents returned by a query is not defined unless you specify a sort().
Operations that modify existing documents (i.e. updates) use the same query syntax as queries to select documents to update.
In aggregation pipeline, the $match pipeline stage provides access to MongoDB queries.

MongoDB provides a db.collection.findOne() method as a special case of find() that returns a single document.

Query Statements¶

Consider the following diagram of the query process that specifies a query criteria and a sort modifier:

The stages of a MongoDB query with a query criteria and a sort modifier.

In the diagram, the query selects documents from the users collection. Using a query selection operator to define the conditions for matching documents, the query selects documents that have age greater than (i.e. $gt) 18. Then the sort() modifier sorts the results by age in ascending order.

For additional examples of queries, see Query Documents.

Projections¶

Queries in MongoDB return all fields in all matching documents by default. To limit the amount of data that MongoDB sends to applications, include a projection in the queries. By projecting results with a subset of fields, applications reduce their network overhead and processing requirements.

Projections, which are the second argument to the find() method, may either specify a list of fields to return or list fields to exclude in the result documents.

Important

Except for excluding the _id field in inclusive projections, you cannot mix exclusive and inclusive projections.

Consider the following diagram of the query process that specifies a query criteria and a projection:

The stages of a MongoDB query with a query criteria and projection. MongoDB only transmits the projected data to the clients.

In the diagram, the query selects from the users collection. The criteria matches the documents that have age equal to 18. Then the projection specifies that only the name field should return in the matching documents.

Projection Examples¶

Exclude One Field From a Result Set¶

db.records.find( { "user_id": { $lt: 42 } }, { "history": 0 } )

This query selects documents in the records collection that match the condition { "user_id": { $lt: 42 } }, and uses the projection { "history": 0 } to exclude the history field from the documents in the result set.

Return Two fields and the `_id` Field¶

db.records.find( { "user_id": { $lt: 42 } }, { "name": 1, "email": 1 } )

This query selects documents in the records collection that match the query { "user_id": { $lt: 42 } } and uses the projection { "name": 1, "email": 1 } to return just the _id field (implicitly included), name field, and the email field in the documents in the result set.

Return Two Fields and Exclude `_id`¶

db.records.find( { "user_id": { $lt: 42} }, { "_id": 0, "name": 1 , "email": 1 } )

This query selects documents in the records collection that match the query { "user_id": { $lt: 42} }, and only returns the name and email fields in the documents in the result set.

See

Limit Fields to Return from a Query for more examples of queries with projection statements.

Projection Behavior¶

MongoDB projections have the following properties:

By default, the _id field is included in the results. To suppress the _id field from the result set, specify _id: 0 in the projection document.
For fields that contain arrays, MongoDB provides the following projection operators: $elemMatch, $slice, and $.
For related projection functionality in the aggregation pipeline , use the $project pipeline stage.

← Read Operations Cursors →

Was this page helpful?

Yes No

Thank you for your feedback!

We're sorry! You can Report a Problem to help us improve this page.