Docs Menu

collection.find()

On this page

  • Definition
  • Usage
  • Example
  • Parameters
  • Return Value
collection.find()

Find all documents in a collection or view that match the provided query predicates and return a handle object that allows you to access them.

To call the collection.find() action from a Function, get a collection handle with database.collection() then call the handle's find() method.

const query = { "reviews.0": { "$exists": true } };
const projection = { "_id": 0 };
return itemsCollection.find(query, projection)
.sort({ name: 1 })
.toArray()
.then(items => {
console.log(`Successfully found ${items.length} documents.`)
items.forEach(console.log)
return items
})
.catch(err => console.error(`Failed to find documents: ${err}`))

The collection.find() action has the following form:

find(query, projection)
Parameter
Description

Query Filter

query: <document>

Optional. A standard MongoDB query document that specifies which documents to find. You can use most query selectors except for evaluation, geospatial, or bitwise selectors.

Specify an empty query filter ({}) or omit this parameter to return the all documents in the collection.

Projection

projection: <document>

Optional. A document that specifies which fields MongoDB should return or withhold in each document that matches the query.

To return all fields in the matching documents, omit this parameter or specify an empty projection document ({}).

To return specific fields and the document's _id, specify the fields in the projection document with a value of 1:

// Includes the field in returned documents
{ <Field Name>: 1 }

To withhold specific fields, specify the fields in the projection document with a value of 0:

// Withholds the field from returned documents
{ <Field Name>: 0 }
Note

You may specify either fields to include or fields to withhold but not both. For example, the following projection is invalid because it simultaneously includes the name field and withholds the address field:

// Invalid
// Can't simultaneously include and withhold
{ "name": 1, "address": 0 }

The exception to this rule is the _id field, which you may withhold from any query:

// Valid
// Can exclude _id while including other fields
{ "_id": 0, "name": 1 }

Client Session

session: <ClientSession>
Optional. A client session that specifies the transaction context in which the operation occurs. To learn more, see Transactions.

The collection.find() action returns a cursor object that points to any documents that match the specified query filters. You can manipulate and access documents in the query result set with the following cursor methods:

Method
Description
cursor.sort(sort)

Sorts documents in the result set according to the sort filter. Sort documents specify one or more fields to sort on. The value of each field indicates whether MongoDB should sort it in ascending (1) or descending (-1) order. For more information, see cursor.sort.

Note

You cannot call this method after retrieving one or more documents using cursor.next() or cursor.toArray().

Example

The following sort document specifies that documents should be sorted first by age from highest to lowest. Once sorted by age, the result set should further be sorted by name in alphabetical order for each distinct age value.

{ age: -1, name: 1 }
cursor.limit(limit)

Specifies the maximum number of documents to include in the query result set. If the result set contains more documents than the specified limit, the cursor will return documents in order up to the limit.

Note

You cannot call this method after retrieving one or more documents using cursor.next() or cursor.toArray().

cursor.skip(amount)

Specifies a number of matching documents to omit from the query result set. MongoDB omits documents from the result set in sort order until it has skipped the specified number. If the query also specifies a limit, skipped documents do not count towards the limit threshold.

Note

You cannot call this method after retrieving one or more documents using cursor.next() or cursor.toArray().

cursor.next()

Iterates the cursor and returns a Promise that resolves to the next document in the cursor. If the cursor is exhausted, the promise resolves to undefined.

Example
collection.find().next()
.then(doc => console.log("next document", doc))
cursor.toArray()

Iterates the cursor to exhaustion and returns a Promise that resolves to an array that contains all of the iterated documents.

Example
collection.find().toArray()
.then(docs => console.log("all documents", docs))

Client Session

session: <ClientSession>
Optional. A client session that specifies the transaction context in which the operation occurs. To learn more, see Transactions.
Note

You cannot return a cursor from a Function. Instead, evaluate the cursor using cursor.next() or cursor.toArray() and return the result.

Give Feedback
© 2021 MongoDB, Inc.

About

  • Careers
  • Legal Notices
  • Privacy Notices
  • Security Information
  • Trust Center
© 2021 MongoDB, Inc.