- Reference >
- JavaScript Methods >
- db.collection.find()
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:The
boolean
can take the following include or exclude values:1
ortrue
to include. Thefind()
method always includes the _id field even if the field is not explicitly stated to return in the projection parameter.0
orfalse
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 theprojection
argument is specified, the matching documents contain only theprojection
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 themongo
shell prompt automatically iterates the cursor to display up to the first 20 documents. Typeit
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:This operation returns all the documents with all the fields from the collection
products
. By default, in themongo
shell, the cursor returns the first batch of 20 matching documents. In themongo
shell, iterate through the next batch by typingit
. 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 thequery
criteria:This operation returns all the documents from the collection
products
whereqty
is greater than25
, 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 thequery
criteria and theprojection
parameter, as in the following example:This operation returns all the documents from the collection
products
whereqty
is greater than25
. The documents in the result set only include the_id
,item
, andqty
fields using “inclusion” projection.find()
always returns the_id
field, even when not explicitly included:To select the documents that match a query criteria and exclude a set of fields from the resulting documents, call the
find()
method with thequery
criteria and theprojection
parameter using theexclude
syntax:The query will return all the documents from the collection
products
whereqty
is greater than25
. The documents in the result set will contain all fields except the_id
andqty
fields, as in the following:
- query (document) – Optional. Specifies the selection criteria
using query operators. Omit the