cursor.maxAwaitTimeMS.txt

.. _cursor-maxAwaitTimeMS:

=======================
cursor.maxAwaitTimeMS()
=======================

.. default-domain:: mongodb

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

Definition
----------

.. method:: cursor.maxAwaitTimeMS(<time limit>)

   .. include:: /includes/fact-mongosh-shell-method.rst

   Specifies the maximum time for the server to wait for new documents
   that match a :ref:`tailable cursor <tailable-cursors-landing-page>`
   query on a :ref:`capped collection <manual-capped-collection>`. For
   more information on iterating a cursor returned by a query, see:
   :ref:`read-operations-cursors`.

   The :method:`~cursor.maxAwaitTimeMS()` method has the following
   prototype form:

   .. code-block:: javascript

      db.collection.find(
         { <query> },
         { <projection> }
      ).tailable( { awaitData: true } ).maxAwaitTimeMS( <milliseconds> )

   The :method:`~cursor.maxAwaitTimeMS()` method has the following
   parameter:

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

      * - ``milliseconds``
        - integer
        - Specifies a maximum wait time for new documents.

.. important::

   This method, :method:`~cursor.maxAwaitTimeMS()`, sets a limit on how
   long a :ref:`tailable cursor <tailable-cursors-landing-page>` waits
   for the next response. :method:`~cursor.maxTimeMS()` sets a limit on
   total processing time.

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

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

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

.. include:: /includes/fact-environments-atlas-support-all.rst

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

Example
--------

Query the :ref:`capped <manual-capped-collection>` ``sales`` collection
to find agent Mary Kay's weekly sales totals:

.. code-block:: javascript
   :emphasize-lines: 4

   db.sales.find( 
      { agent: "Mary Kay" },
      { _id: 0, agent: 1, weeklyTotal: 1  }
   ).tailable( { awaitData: true } ).maxAwaitTimeMS( 1000 )

The highlighted line creates a :ref:`tailable cursor
<tailable-cursors-landing-page>` on the ``sales`` collection. The
:method:`~cursor.maxAwaitTimeMS()` sets a one second maximum wait time
for the next cursor update.