Navigation

collection.find()

Definition

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.

Usage

Example

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}`))

Parameters

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 }

Return Value

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.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))

Note

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