From 8ef2d1cfa2522c970aa5a5a4e0fa5ecbbc43ac95 Mon Sep 17 00:00:00 2001 From: kay Date: Mon, 28 Jan 2013 15:59:43 -0500 Subject: [PATCH] DOCS-1049 add projection argument in findOne method ref --- .../reference/method/db.collection.find.txt | 10 ++++-- .../method/db.collection.findOne.txt | 32 +++++++++++++++++-- 2 files changed, 38 insertions(+), 4 deletions(-) diff --git a/source/reference/method/db.collection.find.txt b/source/reference/method/db.collection.find.txt index 82a2329e449..38dd6d60e63 100644 --- a/source/reference/method/db.collection.find.txt +++ b/source/reference/method/db.collection.find.txt @@ -42,11 +42,17 @@ db.collection.find() The ``projection`` cannot contain both include and exclude specifications except for the exclusion of the ``_id`` field. + + Omit the ``projection`` parameter to return **all** the fields in + the matching documents. :returns: - A :term:`cursor` to the documents that match - the ``query`` criteria and contain the ``projection`` fields. + A :term:`cursor` to the documents that match the ``query`` + criteria. If the ``projection`` argument is specified, the + matching documents contain only the ``projection`` fields, and + the ``_id`` field if you do not explicitly exclude the ``_id`` + field. .. note:: diff --git a/source/reference/method/db.collection.findOne.txt b/source/reference/method/db.collection.findOne.txt index ea8f6289a8c..77a8420e964 100644 --- a/source/reference/method/db.collection.findOne.txt +++ b/source/reference/method/db.collection.findOne.txt @@ -4,14 +4,42 @@ db.collection.findOne() .. default-domain:: mongodb -.. method:: db.collection.findOne(query) +.. method:: db.collection.findOne(query,projection) :param document query: Optional. A :term:`document` that specifies the :term:`query` using the JSON-like syntax and :doc:`query operators `. + :param document projection: + + Optional. Controls the fields to return, or the + :term:`projection`. The ``projection`` argument will + resemble the following prototype: + + .. code-block:: javascript + + { field1: boolean, field2: boolean ... } + + The ``boolean`` can take the following include or exclude + values: + + - ``1`` or ``true`` to include. The + :method:`~db.collection.findOne()` method always includes + the :term:`_id` field even if the field is not explicitly + stated to return in the :term:`projection` parameter. + + - ``0`` or ``false`` to exclude. + + The ``projection`` cannot contain both include and exclude + specifications except for the exclusion of the ``_id`` field. + + Omit the ``projection`` parameter to return **all** the fields in + the matching documents. :returns: One document that satisfies the query specified as the - argument to this method. + argument to this method. If the ``projection`` argument is + specified, the returned document contains only the + ``projection`` fields, and the ``_id`` field if you do not + explicitly exclude the ``_id`` field. Returns only one document that satisfies the specified query. If multiple documents satisfy the query, this method returns the first