Docs4dev
Docs
mongodb / v3.6 / reference / reference-method-db.collection.find.html

db.collection.find()

On this page

Definition

db.collection. find ( query, projection )

Selects documents in a collection or view and returns a cursor to the selected documents.

Parameter Type Description
query document Optional. Specifies selection filter using query operators. To return all documents in a collection, omit this parameter or pass an empty document ({}).
projection document Optional. Specifies the fields to return in the documents that match the query filter. To return all fields in the matching documents, omit this parameter. For details, see Projection.
Returns: A cursor to the documents that match the query criteria. When the find() method “returns documents,” the method is actually returning a cursor to the documents.

Behavior

Projection

The projection parameter determines which fields are returned in the matching documents. The projection parameter takes a document of the following form:

{ field1: <value>, field2: <value> ... }

The <value> can be any of the following:

Note

For the _id field, you do not have to explicitly specify _id: 1 to return the _id field. The find() method always returns the _id field unless you specify _id: 0 to suppress the field.

A projection cannot contain both include and exclude specifications, except for the exclusion of the _id field. In projections that explicitly include fields, the _id field is the only field that you can explicitly exclude.

Cursor Handling

Executing db.collection.find() in the mongo shell automatically iterates the cursor to display up to the first 20 documents. Type it to continue iteration.

To access the returned documents with a driver, use the appropriate cursor handling mechanism for the driver language .

Read Concern

To specify the read concern for db.collection.find(), use the cursor.readConcern() method.

Type Bracketing

MongoDB treats some data types as equivalent for comparison purposes. For instance, numeric types undergo conversion before comparison. For most data types, however, comparison operators only perform comparisons on documents where the BSON type of the target field matches the type of the query operand. Consider the following collection:

{ "_id": "apples", "qty": 5 }
{ "_id": "bananas", "qty": 7 }
{ "_id": "oranges", "qty": { "in stock": 8, "ordered": 12 } }
{ "_id": "avocados", "qty": "fourteen" }

The following query uses $gt to return documents where the value of qty is greater than 4.

db.collection.find( { qty: { $gt: 4 } } )

The query returns the following documents:

{ "_id": "apples", "qty": 5 }
{ "_id": "bananas", "qty": 7 }

The document with _id equal to "avocados" is not returned because its qty value is of type string while the $gt operand is of type integer.

The document with _id equal to "oranges" is not returned because its qty value is of type object.

Note

To enforce data types in a collection, use Schema Validation.

Session Idle Timeout

Starting in MongoDB 3.6, MongoDB drivers and the mongo shell associate all operations with a server session, with the exception of unacknowledged write operations. For operations not explicitly associated with a session (i.e. using Mongo.startSession()), MongoDB drivers and the mongo shell creates an implicit session and associates it with the operation.

If a session is idle for longer than 30 minutes, the MongoDB server marks that session as expired and may close it at any time. When the MongoDB server closes the session, it also kills any in-progress operations and open cursors associated with the session. This includes cursors configured with noCursorTimeout or a maxTimeMS greater than 30 minutes.

For operations that may be idle for longer than 30 minutes, associate the operation with an explicit session using Session.startSession() and periodically refresh the session using the refreshSessions command. See Session Idle Timeout for more information.

Examples

The examples in this section use documents from the bios collection where the documents generally have the form:

{
    "_id" : <value>,
    "name" : { "first" : <string>, "last" : <string> },       // embedded document
    "birth" : <ISODate>,
    "death" : <ISODate>,
    "contribs" : [ <string>, ... ],                           // Array of Strings
    "awards" : [
        { "award" : <string>, year: <number>, by: <string> }  // Array of embedded documents
        ...
    ]
}

To create and populate the bios collection, see The bios Example Collection.

Find All Documents in a Collection

The find() method with no parameters returns all documents from a collection and returns all fields for the documents. For example, the following operation returns all documents in the bios collection:

db.bios.find()

Find Documents that Match Query Criteria

Query for Equality

  • The following operation returns documents in the bios collection where _id equals 5:

    db.bios.find( { _id: 5 } )

  • The following operation returns documents in the bios collection where the field last in the name embedded document equals "Hopper":

    db.bios.find( { "name.last": "Hopper" } )

    Note

    To access fields in an embedded document, use dot notation ("<embedded document>.<field>").

Query Using Operators

To find documents that match a set of selection criteria, call find() with the <criteria> parameter.

MongoDB provides various query operators to specify the criteria.

  • The following operation uses the $in operator to return documents in the bios collection where _id equals either 5 or ObjectId("507c35dd8fada716c89d0013"):

    db.bios.find(
   { _id: { $in: [ 5, ObjectId("507c35dd8fada716c89d0013") ] } }
)

  • The following operation uses the $gt operator returns all the documents from the bios collection where birth is greater than new Date('1950-01-01'):

    db.bios.find( { birth: { $gt: new Date('1950-01-01') } } )

  • The following operation uses the $regex operator to return documents in the bios collection where name.last field starts with the letter N (or is "LIKE N%")

    db.bios.find(
   { "name.last": { $regex: /^N/ } }
)

For a list of the query operators, see Query Selectors.

Query for Ranges

Combine comparison operators to specify ranges for a field. The following operation returns from the bios