find.txt

====
find
====

.. default-domain:: mongodb

.. contents:: On this page
   :local:
   :backlinks: none
   :depth: 1
   :class: singlecol

Definition
----------

.. dbcommand:: find

   Executes a query and returns the first batch of results and the
   cursor id, from which the client can construct a cursor.

   .. |method| replace:: :method:`db.collection.find()` or
      :method:`db.collection.findOne()` helper methods
   .. include:: /includes/fact-dbcommand-tip

Compatibility
-------------

This command is available in deployments hosted in the following environments: 

.. include:: /includes/fact-environments-atlas-only.rst

.. include:: /includes/fact-environments-atlas-support-limited-free.rst

.. include:: /includes/fact-environments-onprem-only.rst

Syntax
------

The :dbcommand:`find` command has the following syntax:

.. versionchanged:: 5.0

.. code-block:: javascript

   db.runCommand(
      {
         find: <string>,
         filter: <document>,
         sort: <document>,
         projection: <document>,
         hint: <document or string>,
         skip: <int>,
         limit: <int>,
         batchSize: <int>,
         singleBatch: <bool>,
         comment: <any>,
         maxTimeMS: <int>,
         readConcern: <document>,
         max: <document>,
         min: <document>,
         returnKey: <bool>,
         showRecordId: <bool>,
         tailable: <bool>,
         oplogReplay: <bool>,
         noCursorTimeout: <bool>,
         awaitData: <bool>,
         allowPartialResults: <bool>,
         collation: <document>,
         allowDiskUse : <bool>,
         let: <document> // Added in MongoDB 5.0
      }
   )

.. _find-cmd-fields:

Command Fields
~~~~~~~~~~~~~~

The command accepts the following fields:


.. list-table::
   :header-rows: 1
   :widths: 20 20 80

   * - Field
     - Type
     - Description

   * - ``find``
     - string
     - The name of the collection or :ref:`view <views-landing-page>` to query.

   * - ``filter``
     - document
     - Optional. The query predicate. If unspecified, then all documents in
       the collection will match the predicate.

   * - .. _find-cmd-sort:
   
       :ref:`sort <find-cmd-sort>`
     - document
     - Optional. The sort specification for the ordering of the results.
       
   * - ``projection``
     - document
     - Optional. The :ref:`projection specification <projections>` to
       determine which fields to include in the returned documents.
       
       .. include:: /includes/extracts/views-unsupported-projection-operators.rst
       
   * - ``hint``
     - string or document
     - Optional. Index specification. Specify either the index name as a
       string or the index key pattern. If specified, then the query system
       will only consider plans using the hinted index.
       
       With the following exception, ``hint`` is required if the command 
       includes the ``min`` and/or ``max`` fields; ``hint`` is not required 
       with ``min`` and/or ``max`` if the ``filter`` is an equality condition 
       on the ``_id`` field ``{ _id: <value> }``.
       
   * - ``skip``
     - Positive integer
     - Optional. Number of documents to skip. Defaults to 0.

   * - ``limit``
     - Non-negative integer
     - Optional. The maximum number of documents to return. If unspecified,
       then defaults to no limit. A limit of 0 is equivalent to setting no
       limit.

   * - ``batchSize``
     - non-negative integer
     - Optional. The maximum number of documents within each batch returned in a query result. 
       By default, the ``find`` command has an initial batch size of ``101`` documents and a maximum 
       size of 16 mebibytes (MiB) for each subsequent batch. This option can enforce a smaller
       limit than 16 MiB, but not a larger one. If you set ``batchSize`` to a limit that results 
       in batches larger than 16 MiB, this option has no effect.
`
       A batchSize of 0 means that the cursor will be established, but no documents 
       will be returned in the first batch.
       
       Unlike the previous wire protocol version, a batchSize of 1 for
       the :dbcommand:`find` command does not close the cursor.

   * - .. _find-single-batch:
       
       ``singleBatch``
     - boolean
     - Optional. Determines whether to close the cursor after the first
       batch. Defaults to false.
       
   * - ``comment``
     - any
     - .. include:: /includes/extracts/comment-content.rst
       
       .. |comment-include-command| replace:: ``find``

       .. include:: /includes/comment-option-getMore-inheritance.rst

   * - ``maxTimeMS``
     - non-negative integer
     - Optional.

       .. include:: /includes/maxTimeMS-description.rst
       
       .. include:: /includes/extracts/maxTimeMS-readConcern.rst
       
   * - ``readConcern``
     - document
     - Optional. Specifies the :term:`read concern`.
       
       .. include:: /includes/fact-readConcern-syntax.rst
       
       .. include:: /includes/fact-readConcern-option-description.rst
       
       The :dbcommand:`getMore` command uses the ``readConcern`` level
       specified in the originating ``find`` command.
       
   * - ``max``
     - document
     - Optional. The *exclusive* upper bound for a specific index. See
       :method:`cursor.max()` for details.
       
       To use the ``max`` field, the command must also use ``hint`` unless the 
       specified ``filter`` is an equality condition on the ``_id`` field 
       ``{ _id: <value> }``.
       
   * - ``min``
     - document
     - Optional. The *inclusive* lower bound for a specific index. See
       :method:`cursor.min()` for details.
       
       To use the ``min`` field, the command must also use ``hint`` unless the
       specified ``filter`` is an equality condition on the ``_id`` field 
       ``{ _id: <value> }``.
       
   * - ``returnKey``
     - boolean
     - Optional. If true, returns only the index keys in the resulting documents.
       Default value is false. If returnKey is true and the :dbcommand:`find`
       command does not use an index, the returned documents will be empty.

   * - ``showRecordId``
     - boolean
     - Optional. Determines whether to return the record identifier for each document.
       If true, adds a field $recordId to the returned documents.
       
   * - ``tailable``
     - boolean
     - Optional. Returns a :term:`tailable cursor` for a capped collections.

   * - ``awaitData``
     - boolean
     - Optional. Use in conjunction with the tailable option to block a
       :dbcommand:`getMore` command on the cursor temporarily at the end
       of data rather than returning no data. After a timeout period,
       :dbcommand:`find` returns as normal.

   * - ``noCursorTimeout``
     - boolean
     - Optional. Prevents the server from timing out non-session idle cursors 
       after an inactivity period of 30 minutes. Ignored for cursors that are 
       part of a session. For more information, refer to 
       :ref:`Session Idle Timeout <session-idle-timeout>`.

       
   * - :ref:`allowPartialResults <cmd-find-allowPartialResults>`
     - boolean
     - .. _cmd-find-allowPartialResults:
     
       Optional. For queries against a sharded collection, allows the
       command (or subsequent :dbcommand:`getMore` commands) to return
       partial results, rather than an error, if one or more queried
       shards are unavailable.

       .. include:: /includes/find-getmore-partialresults.rst

   * - ``collation``
     - document
     - Optional. 
       
       .. include:: /includes/extracts/collation-option.rst

   * - .. _find-cmd-allowDiskUse: 
   
       :ref:`allowDiskUse <find-cmd-allowDiskUse>`
     
     - boolean
     - Optional. 

       .. include:: /includes/fact-allowDiskUse-option-6.0.rst

       ``allowDiskUse`` has no effect if MongoDB can satisfy the
       specified :ref:`sort <find-cmd-sort>` using an index, *or* if the
       blocking sort requires less than 100 megabytes of memory.

       For more complete documentation on ``allowDiskUse``, 
       see :method:`cursor.allowDiskUse()`.

       For more information on memory restrictions for large blocking
       sorts, see :ref:`sort-index-use`.

   * - :ref:`let <find-let-syntax>`
     - document
     - .. _find-let-syntax:
     
       Optional.
     
       .. include:: /includes/let-variables-syntax.rst

       .. include:: /includes/let-variables-syntax-note.rst

       For a complete example using ``let`` and variables, see
       :ref:`find-let-example`.

       .. versionadded:: 5.0

.. _cmd-find-output:

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:

.. code-block:: javascript

   {
      "cursor" : {
         "firstBatch" : [
            {
               "_id" : ObjectId("5e8e2ca217b5324fa9847435"),
               "zipcode" : "20001",
               "x" : 1
            },
            {
               "_id" : ObjectId("5e8e2ca517b5324fa9847436"),
               "zipcode" : "30001",
               "x" : 1
            }
         ],
         "partialResultsReturned" : true, 
         "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")
         }
      }
   }

.. list-table::
   :widths: 20 80
   :header-rows: 1
   
   * - Field
     - Description

   * - ``cursor``
     
     - Contains the cursor information, including the
       cursor ``id`` and the ``firstBatch`` of documents.

       If the operation against a sharded collection returns partial results 
       due to the unavailability of the queried shard(s), the ``cursor`` 
       document includes a ``partialResultsReturned`` field. To return partial 
       results, rather than error, due to the unavailability of the queried
       shard(s), the :dbcommand:`find` command must run with
       :ref:`allowPartialResults <cmd-find-allowPartialResults>` set to
       ``true``. See :ref:`allowPartialResults
       <cmd-find-allowPartialResults>`.

       If the queried shards are initially available for the
       :dbcommand:`find` command but one or more shards become
       unavailable in subsequent :dbcommand:`getMore` commands, only
       the :dbcommand:`getMore` commands run when a queried shard or
       shards are unavailable include the ``partialResultsReturned``
       flag in the output.
       
   * - ``"ok"``
   
     - Indicates whether the command has succeeded (``1``) or failed
       (``0``).

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

- ``$clusterTime``
  
- ``operationTime``

See :ref:`db.runCommand() Results <command-response>` for details.

Behavior
--------

``$regex`` Find Queries No Longer Ignore Invalid Regex
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. include:: /includes/fact-5.1-regex-find-functionality.rst

Sessions
~~~~~~~~

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

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

.. _session-idle-timeout:

Session Idle Timeout
````````````````````

.. include:: /includes/extracts/sessions-cursor-timeout.rst

For operations that return a cursor, if the cursor may be idle for
longer than 30 minutes, issue the operation within an explicit session
using :method:`Mongo.startSession()` and periodically refresh the
session using the :dbcommand:`refreshSessions` command. See
:limit:`Session Idle Timeout` for more information.

Transactions
~~~~~~~~~~~~

.. include:: /includes/extracts/transactions-supported-operation.rst

.. include:: /includes/extracts/transactions-operations-getMore.rst

.. include:: /includes/extracts/transactions-usage.rst

.. |operation| replace:: :dbcommand:`find`

Client Disconnection
~~~~~~~~~~~~~~~~~~~~~

.. include:: /includes/extracts/4.2-changes-disconnect.rst

Stable API
~~~~~~~~~~

When using :ref:`Stable API <stable-api>` V1, the following
:dbcommand:`find` command fields are not supported:

- ``awaitData``
- ``max``
- ``min``
- ``noCursorTimeout``
- ``oplogReplay``
- ``returnKey``
- ``showRecordId``
- ``tailable``

Index Filters and Collations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. include:: /includes/index-filters-and-collations.rst

Find Cursor Behavior on Views
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. include:: /includes/fact-7.3-singlebatch-cursor.rst

Query Settings
~~~~~~~~~~~~~~

.. include:: /includes/persistent-query-settings-info-for-queries.rst

Examples
--------

Specify a Sort and Limit
~~~~~~~~~~~~~~~~~~~~~~~~

The following command runs the :dbcommand:`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.

.. code-block:: javascript

   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 :readconcern:`"local"`,
use the ``readConcern`` option.

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

.. code-block:: javascript

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

.. include:: /includes/fact-readConcern-most-recent-data-in-node.rst

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

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

.. code-block:: javascript

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

For more information on available read concerns, see
:ref:`read-concern`.

Specify Collation
~~~~~~~~~~~~~~~~~

.. include:: /includes/extracts/collation-versionadded.rst

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

.. code-block:: javascript

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

:binary:`~bin.mongosh` provides the :method:`cursor.collation()` to
specify :ref:`collation <collation>` for a
:method:`db.collection.find()` operation.

.. _find-let-example:

Use Variables in ``let``
~~~~~~~~~~~~~~~~~~~~~~~~

.. |let-option| replace:: :ref:`let <find-let-syntax>`

.. include:: /includes/let-example-introduction.rst

.. include:: /includes/let-example-find-flavors.rst

.. code-block:: javascript

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