db.collection.find()¶

db.collection.find(query, projection)¶

The find() method selects documents in a collection and returns a cursor to the selected documents.

The find() method takes the following parameters.

Parameters:

query (document) – Optional. Specifies the selection criteria using query operators. Omit the query parameter or pass an empty document (e.g. {}) to return all documents in the collection.
projection (document) –
Optional. Controls the fields to return, or the projection. The projection argument will resemble the following prototype:
copy
```
{ field1: boolean, field2: boolean ... }
```
The boolean can take the following include or exclude values:
- 1 or true to include. The find() method always includes the _id field even if the field is not explicitly stated to return in the projection parameter.
- 0 or false to exclude.
The projection cannot contain both include and exclude specifications except for the exclusion of the _id field.

Omit the projection parameter to return all the fields in the matching documents.

Returns:

A cursor to the documents that match the query criteria. If the projection argument is specified, the matching documents contain only the projection fields, and the _id field if you do not explicitly exclude the _id field.

Note

In the mongo shell, you can access the returned documents directly without explicitly using the JavaScript cursor handling method. Executing the query directly on the mongo shell prompt automatically iterates the cursor to display up to the first 20 documents. Type it to continue iteration.

Consider the following examples of the find() method:

To select all documents in a collection, call the find() method with no parameters:
copy
```
db.products.find()
```
This operation returns all the documents with all the fields from the collection products. By default, in the mongo shell, the cursor returns the first batch of 20 matching documents. In the mongo shell, iterate through the next batch by typing it. Use the appropriate cursor handling mechanism for your specific language driver.
To select the documents that match a selection criteria, call the find() method with the query criteria:
copy
```
db.products.find( { qty: { $gt: 25 } } )
```
This operation returns all the documents from the collection products where qty is greater than 25, including all fields.
To select the documents that match a selection criteria and return, or project only certain fields into the result set, call the find() method with the query criteria and the projection parameter, as in the following example:
copy
```
db.products.find( { qty: { $gt: 25 } }, { item: 1, qty: 1 } )
```
This operation returns all the documents from the collection products where qty is greater than 25. The documents in the result set only include the _id, item, and qty fields using “inclusion” projection. find() always returns the _id field, even when not explicitly included:
copy
```
{ "_id" : 11, "item" : "pencil", "qty" : 50 }
{ "_id" : ObjectId("50634d86be4617f17bb159cd"), "item" : "bottle", "qty" : 30 }
{ "_id" : ObjectId("50634dbcbe4617f17bb159d0"), "item" : "paper", "qty" : 100 }
```
To select the documents that match a query criteria and exclude a set of fields from the resulting documents, call the find() method with the query criteria and the projection parameter using the exclude syntax:
copy
```
db.products.find( { qty: { $gt: 25 } }, { _id: 0, qty: 0 } )
```
The query will return all the documents from the collection products where qty is greater than 25. The documents in the result set will contain all fields except the _id and qty fields, as in the following:
copy
```
{ "item" : "pencil", "type" : "no.2" }
{ "item" : "bottle", "type" : "blue" }
{ "item" : "paper" }
```

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