@@ -293,6 +293,46 @@ Consider the following examples that illustrate the use of the
293293 { _id: 0, 'name.first': 0, birth: 0 }
294294 )
295295
296+ - The following operation finds all documents in the ``bios``
297+ collection and returns the the ``last`` field in the ``name``
298+ subdocument and the first two elements in the ``contribs`` field:
299+
300+ .. code-block:: javascript
301+
302+ db.bios.find(
303+ { },
304+ {
305+ _id: 0,
306+ 'name.last': 1,
307+ contribs: { $slice: 2 }
308+ }
309+ )
310+
311+ Cursor
312+ ~~~~~~
313+
314+ :method:`find() <db.collection.find()>` returns a *cursor*; however, in
315+ the :program:`mongo` shell, the cursor is automatically iterated up to
316+ 20 times to print the documents referenced by the cursor. To access the
317+ documents, you must explicitly handle the cursor, as in the following
318+ example:
319+
320+ .. code-block:: javascript
321+
322+ var myCursor = db.bios.find( { _id: 1 } );
323+
324+ var myDocument = myCursor.hasNext() ? myCursor.next() : null;
325+
326+ if (myDocument) {
327+ var myName = myDocument.name;
328+
329+ print (tojson(myName));
330+ }
331+
332+ See the :method:`cursor.forEach()`, :method:`cursor.hasNext()`,
333+ :method:`cursor.next()` documentation for more information on cursor
334+ handling.
335+
296336In addition to the ``<query>`` and the ``<projection>`` arguments, the
297337:program:`mongo` shell and the :doc:`drivers </applications/drivers>`
298338provide several cursor methods that you can call on the *cursor*
@@ -437,4 +477,15 @@ because the :method:`findOne() <db.collection.findOne()>` method
437477returns a document rather than a cursor, you cannot apply the cursor
438478methods such as :method:`limit() <cursor.limit()>`, :method:`sort()
439479<cursor.sort()>`, and :method:`skip() <cursor.skip()>` to the result of
440- the :method:`findOne() <db.collection.findOne()>` method.
480+ the :method:`findOne() <db.collection.findOne()>` method. However, you
481+ can access the document directly, as in the following example:
482+
483+ .. code-block:: javascript
484+
485+ var myDocument = db.bios.findOne();
486+
487+ if (myDocument) {
488+ var myName = myDocument.name;
489+
490+ print (tojson(myName));
491+ }
0 commit comments