DOCS-675 incorporate scott's first round of feedback

Author: kay-kim

source/applications/read.txt

@@ -330,9 +330,9 @@ Cursor
 The :method:`find() <db.collection.find()>` method returns a
 :term:`cursor`; however, in the :program:`mongo` shell, if the result
 of the :method:`find() <db.collection.find()>` is not assigned to a
-variable, then the cursor is automatically iterated up to 20 times to
-print the documents referenced by the cursor, as in the following
-example:
+variable, then the cursor is automatically iterated up to 20 times
+[#setShellBatchSize]_ to print the documents referenced by the cursor,
+as in the following example:
 
 .. code-block:: javascript
 
@@ -342,20 +342,55 @@ This operation will iterate the cursor up to 20 times and print the
 first 20 documents referenced by the cursor.
 
 If the result of the :method:`find() <db.collection.find()>` is
-assigned to a variable, you can use the cursor method :method:`next()
-<cursor.next()>` to access the documents, as in the following example:
+assigned to a variable:
 
-.. code-block:: javascript
+- you can type the name of the cursor variable to iterate up to 20
+  times [#setShellBatchSize]_ and print the documents referenced by the
+  cursor, as in the following example:
 
-   var myCursor = db.bios.find( { _id: 1 } );
+  .. code-block:: javascript
 
-   var myDocument = myCursor.hasNext() ? myCursor.next() : null;
+     var myCursor = db.bios.find( { _id: 1 } );
 
-   if (myDocument) {
-      var myName = myDocument.name;
+     myCursor
 
-      print (tojson(myName));
-   }
+- you can use the cursor method :method:`next() <cursor.next()>` to
+  access the documents, as in the following example:
+
+  .. code-block:: javascript
+
+     var myCursor = db.bios.find( { _id: 1 } );
+
+     var myDocument = myCursor.hasNext() ? myCursor.next() : null;
+
+     if (myDocument) {
+
+        var myName = myDocument.name;
+
+        print (tojson(myName));
+     }
+
+  To print, you can also use the ``printjson()`` method instead of
+  ``print(tojson())``:
+
+  .. code-block:: javascript
+
+     if (myDocument) { 
+
+         var myName = myDocument.name;
+
+         printjson(myName);
+     }
+
+- you can use the cursor method :method:`forEach() <cursor.forEach()>`
+  to iterate the cursor and access the documents, as in the following
+  example:
+
+  .. code-block:: javascript
+
+     var myCursor = db.bios.find( { _id: 1 } );
+
+     myCursor.forEach(printjson);
 
 For more information on cursor handling, see:
 
@@ -369,6 +404,13 @@ For more information on cursor handling, see:
 
 - :ref:`JavaScript cursor methods<js-query-cursor-methods>`
 
+.. [#setShellBatchSize] You can use the ``DBQuery.shellBatchSize`` to
+   change the number of iteration from the default value ``20``, as in the
+   following example which sets the number to ``10`` :
+
+   .. code-block:: javascript
+
+      DBQuery.shellBatchSize = 10
 
 Modify Cursor Behavior
 ``````````````````````
@@ -419,7 +461,8 @@ its behavior, such as:
 
 You may chain these cursor methods; however, the :method:`limit()
 <cursor.limit()>` method is always applied after the :method:`sort()
-<cursor.sort()>` even if you chain the methods in the reverse order:
+<cursor.sort()>` even if you chain the methods in the reverse
+order [#dbquery-server]_:
 
   .. code-block:: javascript
 
@@ -430,6 +473,17 @@ See :ref:`JavaScript cursor methods <js-query-cursor-methods>` and your
 information on cursor methods. See :ref:`read-operations-cursors` for
 more information regarding cursors.
 
+.. [#dbquery-server] The server treats the query with the sort as a
+   single object:
+
+   .. code-block:: javascript
+
+      db.bios.find( { $query: {}, $orderby: { name: 1 } } ).limit( 5 )
+
+   For other cursor modifiers that are treated with the query as a
+   single object, see the :doc:`meta query operators
+   </reference/meta-query-operators>`.
+
 .. _crud-read-findOne:
 .. _crud-read-find-one:
 

source/core/read-operations.txt

@@ -664,9 +664,9 @@ Cursors
 The :method:`find() <db.collection.find()>` method returns a
 :term:`cursor`; however, in the :program:`mongo` shell, if the result
 of the :method:`find() <db.collection.find()>` is not assigned to a
-variable, then the cursor is automatically iterated up to 20 times to
-print the documents referenced by the cursor, as in the following
-example:
+variable, then the cursor is automatically iterated up to 20 times
+[#setShellBatchSize]_ to print the documents referenced by the cursor,
+as in the following example:
 
 .. code-block:: javascript
 
@@ -676,56 +676,102 @@ This operation will iterate the cursor up to 20 times and print the
 first 20 documents referenced by the cursor.
 
 If the result of the :method:`find() <db.collection.find()>` is
-assigned to a variable, you can use the cursor method :method:`next()
-<cursor.next()>` to access the documents, as in the following example:
+assigned to a variable:
 
-.. code-block:: javascript
+- you can type the name of the cursor variable to iterate up to 20
+  times [#setShellBatchSize]_ and print the documents referenced by the
+  cursor, as in the following example:
+
+  .. code-block:: javascript
 
-   var myCursor =  db.inventory.find( { type: 'food' } );
+     var myCursor = db.inventory.find( { type: 'food' } );
 
-   var myDocument = myCursor.hasNext() ? myCursor.next() : null;
+     myCursor
 
-   if (myDocument) {
-      var myItem = myDocument.item;
+- you can use the cursor method :method:`next() <cursor.next()>` to
+  access the documents, as in the following example:
 
-      print (tojson(myItem));
-   }
+  .. code-block:: javascript
+
+     var myCursor = db.inventory.find( { type: 'food' } );
+
+     var myDocument = myCursor.hasNext() ? myCursor.next() : null;
+
+     if (myDocument) {
+
+         var myItem = myDocument.item;
+
+         print(tojson(myItem));
+     }
+
+  To print, you can also use the ``printjson()`` method instead of
+  ``print(tojson())``:
+
+  .. code-block:: javascript
+
+     if (myDocument) { 
+
+         var myItem = myDocument.item;
+
+         printjson(myItem);
+     }
+
+- you can use the cursor method :method:`forEach() <cursor.forEach()>`
+  to iterate the cursor and access the documents, as in the following
+  example:
+
+  .. code-block:: javascript
+
+     var myCursor =  db.inventory.find( { type: 'food' } );
+
+     myCursor.forEach(printjson);
 
 See :ref:`JavaScript cursor methods <js-query-cursor-methods>` and your
 :doc:`driver </applications/drivers>` documentation for more
 information on cursor methods.
 
-Array Mode
-~~~~~~~~~~
+.. [#setShellBatchSize] You can use the ``DBQuery.shellBatchSize`` to
+   change the number of iteration from the default value ``20``, as in the
+   following example which sets the number to ``10``:
+
+   .. code-block:: javascript
+
+      DBQuery.shellBatchSize = 10
+
+Iterator Index
+~~~~~~~~~~~~~~
 
 Additionally, with some of the :doc:`drivers </applications/drivers>`,
-you can use the cursor in "array mode" and access the documents with an
-index (i.e. ``cursor[index]``), as in the following example:
+you can iterate with an index (i.e. ``cursor[index]``) and return the
+document at the index position, as in the following example:
 
 .. code-block:: javascript
 
    var myCursor = db.inventory.find( { type: 'food' } );
 
-   for (var idx = 0; idx < myCursor.length(); idx++ ){
-       myDoc = myCursor[idx];
-       print (tojson(myDoc));
-   }
+   myDoc = myCursor[3];
 
-The "array mode" loads into RAM the documents up to the highest
-specified index and should not be used for queries which may return
-very large number of data that may exceed memory.
+Accessing the document with an index iterates the cursor and loads into
+RAM the documents up to the index and should not be used for queries
+which may return very large number of data that may exceed memory.
 
-You can also convert the cursor explicitly to an array, as in the following:
+In the :program:`mongo` shell, you can use the ``toArray()`` method to
+iterate the cursor and return the documents in an array, as in the
+following:
 
 .. code-block:: javascript
 
    var myCursor = db.inventory.find( { type: 'food' } );
    var documentArray = myCursor.toArray();
 
-The ``toArray()`` method loads into RAM all documents returned by the cursor.
+The ``toArray()`` method loads into RAM all documents returned by the
+cursor.
 
 .. TODO link to toArray() method once the page has been added
 
+Cursor Considerations
+~~~~~~~~~~~~~~~~~~~~~
+
 Consider the following behaviors related to cursors:
 
 - By default, the server will automatically close the cursor after 10
@@ -758,9 +804,9 @@ Consider the following behaviors related to cursors:
   - Batch size cannot exceed the :ref:`maximum BSON document size
     <limit-bson-document-size>`.
 
-  - As you iterate through the cursor and reach the end of that batch,
-    if there are more results, :method:`cursor.next()` will perform a
-    :data:`getmore operation <op>` to retrieve the next batch.
+  - As you iterate through the cursor and reach the end of the returned
+    batch, if there are more results, :method:`cursor.next()` will
+    perform a :data:`getmore operation <op>` to retrieve the next batch.
 
     To see how many documents remain in the batch as you iterate the
     cursor, you can use the :method:`cursor.objsLeftInBatch()` method,