find

Command Fields

The command accepts the following fields:

{ find: "data",
  oplogReplay: true,
  filter: { ts: { $gte: new Timestamp(1514764800, 0) } } }

collation: {
   locale: <string>,
   caseLevel: <boolean>,
   caseFirst: <string>,
   strength: <int>,
   numericOrdering: <boolean>,
   alternate: <string>,
   maxVariable: <string>,
   backwards: <boolean>
}

{ <variable_name_1>: <expression_1>,
  ...,
  <variable_name_n>: <expression_n> }

Output

The command returns a document that contains the cursor information, including the cursor ID and the first batch of documents. For example, the following document is returned when run against a sharded collection:

{
   "cursor" : {
      "firstBatch" : [
         {
            "_id" : ObjectId("5e8e2ca217b5324fa9847435"),
            "zipcode" : "20001",
            "x" : 1
         },
         {
            "_id" : ObjectId("5e8e2ca517b5324fa9847436"),
            "zipcode" : "30001",
            "x" : 1
         }
      ],
      "partialResultsReturned" : true, // Starting in version 4.4
      "id" : NumberLong("668860441858272439"),
      "ns" : "test.contacts"
   },
   "ok" : 1,
   "operationTime" : Timestamp(1586380205, 1),
   "$clusterTime" : {
      "clusterTime" : Timestamp(1586380225, 2),
      "signature" : {
         "hash" : BinData(0,"aI/jWsUVUSkMw8id+A+AVVTQh9Y="),
         "keyId" : NumberLong("6813364731999420435")
      }
   }
}

In addition to the aforementioned find-specific fields, the db.runCommand() includes the following information for replica sets and sharded clusters:

• $clusterTime

• operationTime

See db.runCommand() Results for details.

$regex Find Queries No Longer Ignore Invalid Regex

Starting in MongoDB 5.1, invalid $regex options options are no longer ignored. This change makes $regex options more consistent with the use of $regex in the aggregate command and projection queries.

Sessions

For cursors created inside a session, you cannot call getMore outside the session.

Similarly, for cursors created outside of a session, you cannot call getMore inside a session.

Transactions

find can be used inside multi-document transactions.

• For cursors created outside of a transaction, you cannot call getMore inside the transaction.

• For cursors created in a transaction, you cannot call getMore outside the transaction.

Client Disconnection

Starting in MongoDB 4.2, if the client that issued find disconnects before the operation completes, MongoDB marks find for termination using killOp.

Stable API

When using Stable API V1, the following find command fields are not supported:

• awaitData

• max

• min

• noCursorTimeout

• oplogReplay

• returnKey

• showRecordId

• tailable

Index Filters and Collations

Starting in MongoDB 6.0, an index filter uses the collation previously set using the planCacheSetFilter command.

Specify a Sort and Limit

The following command runs the find command filtering on the rating field and the cuisine field. The command includes a projection to only return the following fields in the matching documents: _id, name, rating, and address fields.

The command sorts the documents in the result set by the name field and limits the result set to 5 documents.

db.runCommand(
   {
     find: "restaurants",
     filter: { rating: { $gte: 9 }, cuisine: "italian" },
     projection: { name: 1, rating: 1, address: 1 },
     sort: { name: 1 },
     limit: 5
   }
)

Override Default Read Concern

To override the default read concern level of "local", use the readConcern option.

The following operation on a replica set specifies a read concern of "majority" to read the most recent copy of the data confirmed as having been written to a majority of the nodes.

db.runCommand(
   {
     find: "restaurants",
     filter: { rating: { $lt: 5 } },
     readConcern: { level: "majority" }
   }
)

Regardless of the read concern level, the most recent data on a node may not reflect the most recent version of the data in the system.

The getMore command uses the readConcern level specified in the originating find command.

A readConcern can be specified for the mongosh method db.collection.find() using the cursor.readConcern() method:

db.restaurants.find( { rating: { $lt: 5 } } ).readConcern("majority")

For more information on available read concerns, see Read Concern.

Specify Collation

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

The following operation runs the find command with the collation specified:

db.runCommand(
   {
     find: "myColl",
     filter: { category: "cafe", status: "a" },
     sort: { category: 1 },
     collation: { locale: "fr", strength: 1 }
   }
)

mongosh provides the cursor.collation() to specify collation for a db.collection.find() operation.

Use Variables in let

To define variables that you can access elsewhere in the command, use the let option.

Create a collection cakeFlavors:

db.cakeFlavors.insertMany( [
   { _id: 1, flavor: "chocolate" },
   { _id: 2, flavor: "strawberry" },
   { _id: 3, flavor: "cherry" }
] )

The following example defines a targetFlavor variable in let and uses the variable to retrieve the chocolate cake flavor:

db.cakeFlavors.runCommand( {
   find: db.cakeFlavors.getName(),
   filter: { $expr: { $eq: [ "$flavor", "$$targetFlavor" ] } },
   let : { targetFlavor: "chocolate" }
} )