diff --git a/config/redirects.yaml b/config/redirects.yaml index 043b092e7b4..ea2b017534e 100644 --- a/config/redirects.yaml +++ b/config/redirects.yaml @@ -1028,6 +1028,20 @@ code: 303 outputs: - 'before-v3.0' --- +from: '/reference/method/cursor.noCursorTimeout' +to: '/reference/method' +type: 'redirect' +code: 303 +outputs: + - 'before-v3.0' +--- +from: '/reference/method/cursor.close' +to: '/reference/method' +type: 'redirect' +code: 303 +outputs: + - 'before-v3.0' +--- from : '/reference/command/geoWalk' to: '/reference/command/nav-geospatial/' type: 'redirect' diff --git a/source/core/cursors.txt b/source/core/cursors.txt index fb6d88c1f1c..25a1e875f09 100644 --- a/source/core/cursors.txt +++ b/source/core/cursors.txt @@ -46,20 +46,19 @@ Closure of Inactive Cursors ~~~~~~~~~~~~~~~~~~~~~~~~~~~ By default, the server will automatically close the cursor after 10 -minutes of inactivity or if client has exhausted the cursor. To -override this behavior, you can specify the ``noTimeout`` flag in your -query using :method:`cursor.addOption()`; however, you should either -close the cursor manually or exhaust the cursor. In the -:program:`mongo` shell, you can set the ``noTimeout`` flag: +minutes of inactivity, or if client has exhausted the cursor. To +override this behavior in the :program:`mongo` shell, you can use +the :method:`cursor.noCursorTimeout()` method: .. code-block:: javascript - var myCursor = db.inventory.find().addOption(DBQuery.Option.noTimeout); + var myCursor = db.inventory.find().noCursorTimeout(); + +After setting the ``noCursorTimeout`` option, you must either close the cursor +manually with :method:`cursor.close()` or by exhausting the cursor's results. See your :doc:`driver ` documentation for -information on setting the ``noTimeout`` flag. For the :program:`mongo` -shell, see :method:`cursor.addOption()` for a complete list of -available cursor flags. +information on setting the ``noCursorTimeout`` option. .. _cursor-isolation: diff --git a/source/includes/ref-toc-method-cursor.yaml b/source/includes/ref-toc-method-cursor.yaml index 9be1c3bddbe..80a13e9e2a0 100644 --- a/source/includes/ref-toc-method-cursor.yaml +++ b/source/includes/ref-toc-method-cursor.yaml @@ -2,6 +2,10 @@ name: ":method:`cursor.batchSize()`" file: /reference/method/cursor.batchSize description: "Controls the number of documents MongoDB will return to the client in a single network message." --- +name: ":method:`cursor.close()`" +file: /reference/method/cursor.close +description: "Close a cursor and free associated server resources." +--- name: ":method:`cursor.comment()`" file: /reference/method/cursor.comment description: "Attaches a comment to the query to allow for traceability in the logs and the system.profile collection." @@ -58,6 +62,10 @@ name: ":method:`cursor.next()`" file: /reference/method/cursor.next description: "Returns the next document in a cursor." --- +name: ":method:`cursor.noCursorTimeout()`" +file: /reference/method/cursor.noCursorTimeout +description: "Instructs the server to avoid closing a cursor automatically after a period of inactivity." +--- name: ":method:`cursor.objsLeftInBatch()`" file: /reference/method/cursor.objsLeftInBatch description: "Returns the number of documents left in the current cursor batch." diff --git a/source/reference/method/cursor.close.txt b/source/reference/method/cursor.close.txt new file mode 100644 index 00000000000..a4cd3a0ee03 --- /dev/null +++ b/source/reference/method/cursor.close.txt @@ -0,0 +1,23 @@ +============== +cursor.close() +============== + +.. default-domain:: mongodb + +Definition +---------- + +.. method:: cursor.close() + + Instructs the server to close a :ref:`cursor ` + and free associated server resources. The server will automatically close + cursors that have no remaining results, as well as cursors that have been + idle for a period of time and lack the :method:`cursor.noCursorTimeout()` + option. + + The :method:`~cursor.close()` method has the following + prototype form: + + .. code-block:: javascript + + db.collection.find().close() diff --git a/source/reference/method/cursor.noCursorTimeout.txt b/source/reference/method/cursor.noCursorTimeout.txt new file mode 100644 index 00000000000..fe8c12c9094 --- /dev/null +++ b/source/reference/method/cursor.noCursorTimeout.txt @@ -0,0 +1,20 @@ +======================== +cursor.noCursorTimeout() +======================== + +.. default-domain:: mongodb + +Definition +---------- + +.. method:: cursor.noCursorTimeout() + + Instructs the server to avoid closing a cursor automatically after a period + of inactivity. + + The :method:`~cursor.noCursorTimeout()` method has the following + prototype form: + + .. code-block:: javascript + + db.collection.find().noCursorTimeout() diff --git a/source/reference/method/db.collection.find.txt b/source/reference/method/db.collection.find.txt index 8ada67f1d56..94132ec9c0d 100644 --- a/source/reference/method/db.collection.find.txt +++ b/source/reference/method/db.collection.find.txt @@ -381,14 +381,17 @@ array: Iterate the Returned Cursor ~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The :method:`~db.collection.find()` method returns a :term:`cursor` to -the results. In the :program:`mongo` shell, if the returned cursor is -not assigned to a variable using the ``var`` keyword, the cursor is -automatically iterated up to 20 times to access up to the first 20 -documents that match the query. You can use the -``DBQuery.shellBatchSize`` to change the number of iterations. See -:ref:`cursor-flags` and :ref:`cursor-behaviors`. To iterate manually, -assign the returned cursor to a variable using the ``var`` keyword. +The :method:`~db.collection.find()` method returns a +:ref:`cursor ` to the results. + +In the :program:`mongo` shell, if the returned cursor is not assigned to a +variable using the ``var`` keyword, the cursor is automatically iterated to +access up to the first 20 documents that match the query. You can set the +``DBQuery.shellBatchSize`` variable to change the number of automatically +iterated documents. + +To manually iterate over the results, assign the returned cursor to a variable +with the ``var`` keyword, as shown in the following sections. With Variable Name `````````````````` diff --git a/source/tutorial/getting-started-with-the-mongo-shell.txt b/source/tutorial/getting-started-with-the-mongo-shell.txt index f95c4049c8c..b37e8be2a31 100644 --- a/source/tutorial/getting-started-with-the-mongo-shell.txt +++ b/source/tutorial/getting-started-with-the-mongo-shell.txt @@ -112,7 +112,7 @@ From the :program:`mongo` shell, you can use the :doc:`shell methods times. You can set the ``DBQuery.shellBatchSize`` attribute to change the - number of iteration from the default value ``20``, as in the + number of documents from the default value of ``20``, as in the following example which sets it to ``10``: .. code-block:: javascript @@ -290,4 +290,4 @@ Exit the Shell To exit the shell, type ``quit()`` or use the ```` shortcut. -.. seealso:: :gettingstarted:`Getting Started Guide ` \ No newline at end of file +.. seealso:: :gettingstarted:`Getting Started Guide `