db.collection.find()¶

On this page

Definition
Behavior
Examples

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:

copy

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

The <value> can be any of the following:

1 or true to include the field in the return documents.
0 or false to exclude the field.
Expression using a Projection Operators.

find() operations on views do not support the following projection operators:
- $
- $elemMatch
- $slice
- $meta

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:

copy

{ "_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.

copy

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

The query returns the following documents:

copy

{ "_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 Document Validation.

Examples¶

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

copy

{
    "_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:

copy

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:
copy
```
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":
copy
```
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"):
copy
```
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'):
copy
```
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%")
copy
```
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 collection documents where birth is between new Date('1940-01-01') and new Date('1960-01-01') (exclusive):

copy

db.bios.find( { birth: { $gt: new Date('1940-01-01'), $lt: new Date('1960-01-01') } } )

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

Query for Multiple Conditions¶

The following operation returns all the documents from the bios collection where birth field is greater than new Date('1950-01-01') and death field does not exists:

copy

db.bios.find( {
   birth: { $gt: new Date('1920-01-01') },
   death: { $exists: false }
} )

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

Query Embedded Documents¶

The following examples query the name embedded field in the bios collection.

Query Exact Matches on Embedded Documents¶

The following operation returns documents in the bios collection where the embedded document name is exactly { first: "Yukihiro", last: "Matsumoto" }, including the order:

copy

db.bios.find(
    { name: { first: "Yukihiro", last: "Matsumoto" } }
)

The name field must match the embedded document exactly. The query does not match documents with the following name fields:

copy

{
   first: "Yukihiro",
   aka: "Matz",
   last: "Matsumoto"
}

{
   last: "Matsumoto",
   first: "Yukihiro"
}

Query Fields of an Embedded Document¶

The following operation returns documents in the bios collection where the embedded document name contains a field first with the value "Yukihiro" and a field last with the value "Matsumoto". The query uses dot notation to access fields in an embedded document:

copy

db.bios.find(
   {
     "name.first": "Yukihiro",
     "name.last": "Matsumoto"
   }
)

The query matches the document where the name field contains an embedded document with the field first with the value "Yukihiro" and a field last with the value "Matsumoto". For instance, the query would match documents with name fields that held either of the following values:

copy

{
  first: "Yukihiro",
  aka: "Matz",
  last: "Matsumoto"
}

{
  last: "Matsumoto",
  first: "Yukihiro"
}

For more information and examples, see also Query on Embedded/Nested Documents.

Query Arrays¶

Query for an Array Element¶

The following examples query the contribs array in the bios collection.

The following operation returns documents in the bios collection where the array field contribs contains the element "UNIX":
copy
```
db.bios.find( { contribs: "UNIX" } )
```
The following operation returns documents in the bios collection where the array field contribs contains the element "ALGOL" or "Lisp":
copy
```
db.bios.find( { contribs: { $in: [ "ALGOL", "Lisp" ]} } )
```
The following operation use the $all query operator to return documents in the bios collection where the array field contribs contains both the elements "ALGOL" and "Lisp":
copy
```
db.bios.find( { contribs: { $all: [ "ALGOL", "Lisp" ] } } )
```
For more examples, see $all. See also $elemMatch.
The following operation uses the $size operator to return documents in the bios collection where the array size of contribs is 4:
copy
```
db.bios.find( { contribs: { $size: 4 } } )
```

For more information and examples of querying an array, see:

For a list of array specific query operators, see Array.

Query an Array of Documents¶

The following examples query the awards array in the bios collection.

The following operation returns documents in the bios collection where the awards array contains an element with award field equals "Turing:
copy
```
db.bios.find(
   { "awards.award": "Turing Award" }
)
```
The following operation returns documents in the bios collection where the awards array contains at least one element with both the award field equals "Turing Award" and the year field greater than 1980:
copy
```
db.bios.find(
   { awards: { $elemMatch: { award: "Turing Award", year: { $gt: 1980 } } } }
)
```
Use the $elemMatch operator to specify multiple criteria on an array element.

For more information and examples of querying an array, see:

For a list of array specific query operators, see Array.

Projections¶

The projection parameter specifies which fields to return. The parameter contains either include or exclude specifications, not both, unless the exclude is for the _id field.

Note

Unless the _id field is explicitly excluded in the projection document _id: 0, the _id field is returned.

Specify the Fields to Return¶

The following operation finds all documents in the bios collection and returns only the name field, contribs field and _id field:

copy

db.bios.find( { }, { name: 1, contribs: 1 } )

Note

Unless the _id field is explicitly excluded in the projection document _id: 0, the _id field is returned.

Explicitly Excluded Fields¶

The following operation queries the bios collection and returns all fields except the first field in the name embedded document and the birth field:

copy

db.bios.find(
   { contribs: 'OOP' },
   { 'name.first': 0, birth: 0 }
)

Explicitly Exclude the `_id` Field¶

Note

Unless the _id field is explicitly excluded in the projection document _id: 0, the _id field is returned.

The following operation finds documents in the bios collection and returns only the name field and the contribs field:

copy

db.bios.find(
   { },
   { name: 1, contribs: 1, _id: 0 }
)

On Arrays and Embedded Documents¶

The following operation queries the bios collection and returns the last field in the name embedded document and the first two elements in the contribs array:

copy

db.bios.find(
   { },
   {
     _id: 0,
     'name.last': 1,
     contribs: { $slice: 2 }
   }
)

Iterate the Returned Cursor¶

The find() method returns a cursor to the results.

In the mongo shell, if the returned cursor is not assigned to a variable using the var keyword, the cursor is automatically iterated to access up to the first 20 documents that match the query. You can set the DBQuery.shellBatchSize variable to change the number of automatically iterated documents.

To manually iterate over the results, assign the returned cursor to a variable with the var keyword, as shown in the following sections.

With Variable Name¶

The following example uses the variable myCursor to iterate over the cursor and print the matching documents:

copy

var myCursor = db.bios.find( );

myCursor

With `next()` Method¶

The following example uses the cursor method next() to access the documents:

copy

var myCursor = db.bios.find( );

var myDocument = myCursor.hasNext() ? myCursor.next() : null;

if (myDocument) {
    var myName = myDocument.name;
    print (tojson(myName));
}

To print, you can also use the printjson() method instead of print(tojson()):

copy

if (myDocument) {
   var myName = myDocument.name;
   printjson(myName);
}

With `forEach()` Method¶

The following example uses the cursor method forEach() to iterate the cursor and access the documents:

copy

var myCursor = db.bios.find( );

myCursor.forEach(printjson);

Modify the Cursor Behavior¶

The mongo shell and the drivers provide several cursor methods that call on the cursor returned by the find() method to modify its behavior.

Order Documents in the Result Set¶

The sort() method orders the documents in the result set. The following operation returns documents in the bios collection sorted in ascending order by the name field:

copy

db.bios.find().sort( { name: 1 } )

sort() corresponds to the ORDER BY statement in SQL.

Limit the Number of Documents to Return¶

The limit() method limits the number of documents in the result set. The following operation returns at most 5 documents in the bios collection:

copy

db.bios.find().limit( 5 )

limit() corresponds to the LIMIT statement in SQL.

Set the Starting Point of the Result Set¶

The skip() method controls the starting point of the results set. The following operation skips the first 5 documents in the bios collection and returns all remaining documents:

copy

db.bios.find().skip( 5 )

Specify Collation¶

Collation allows users to specify language-specific rules for string comparison, such as rules for lettercase and accent marks.

The collation() method specifies the collation for the db.collection.find() operation.

copy

db.bios.find( { "name.last": "hopper" } ).collation( { locale: "en_US", strength: 1 } )

Combine Cursor Methods¶

The following statements chain cursor methods limit() and sort():

copy

db.bios.find().sort( { name: 1 } ).limit( 5 )
db.bios.find().limit( 5 ).sort( { name: 1 } )

The two statements are equivalent; i.e. the order in which you chain the limit() and the sort() methods is not significant. Both statements return the first five documents, as determined by the ascending sort order on ‘name’.

← db.collection.explain() db.collection.findAndModify() →

db.collection.find()¶

Definition¶

Behavior¶

Projection¶

Cursor Handling¶

Read Concern¶

Type Bracketing¶

Examples¶

Find All Documents in a Collection¶

Find Documents that Match Query Criteria¶

Query for Equality¶

Query Using Operators¶

Query for Ranges¶

Query for Multiple Conditions¶

Query Embedded Documents¶

Query Exact Matches on Embedded Documents¶

Query Fields of an Embedded Document¶

Query Arrays¶

Query for an Array Element¶

Query an Array of Documents¶

Projections¶

Specify the Fields to Return¶

Explicitly Excluded Fields¶

Explicitly Exclude the _id Field¶

On Arrays and Embedded Documents¶

Iterate the Returned Cursor¶

With Variable Name¶

With next() Method¶

With forEach() Method¶

Modify the Cursor Behavior¶

Order Documents in the Result Set¶

Limit the Number of Documents to Return¶

Set the Starting Point of the Result Set¶

Specify Collation¶

Combine Cursor Methods¶

Explicitly Exclude the `_id` Field¶

With `next()` Method¶

With `forEach()` Method¶