From 6d58fc58208a376c8a4455d6ce84c5043965828b Mon Sep 17 00:00:00 2001 From: kay Date: Mon, 22 Oct 2012 12:33:24 -0400 Subject: [PATCH] DOCS-617 crud draft edits --- draft/applications/create.txt | 68 +-- draft/applications/read.txt | 77 +++- draft/applications/update.txt | 2 +- draft/core/documents.txt | 35 +- draft/core/read-operations.txt | 387 ++++++++++++------ .../reference/method/db.collection.find.txt | 4 +- 6 files changed, 393 insertions(+), 180 deletions(-) diff --git a/draft/applications/create.txt b/draft/applications/create.txt index 00d2e950748..03e5ff7d508 100644 --- a/draft/applications/create.txt +++ b/draft/applications/create.txt @@ -51,7 +51,7 @@ following syntax: The :method:`insert() ` method is analogous to the ``SQL INSERT``. -Consider the following examples that illustrate the usage of the +Consider the following examples that illustrate the use of the :method:`insert() ` method: - If the collection does not exist, then the :method:`insert() @@ -90,8 +90,12 @@ Consider the following examples that illustrate the usage of the .. code-block:: javascript - > db.csbios.find() - + db.csbios.find() + + This will return the document from the ``csbios`` collection: + + .. code-block:: javascript + { "_id" : 1, "name" : { "first" : "John", "last" :"Backus" }, @@ -143,12 +147,17 @@ Consider the following examples that illustrate the usage of the } ) - You can verify the addition of the ``_id`` field to the inserted - document by the querying the ``csbios`` collection: + You can verify the inserted document by the querying the ``csbios`` + collection: .. code-block:: javascript - > db.csbios.find( { name: { first: 'John', last: 'McCarthy' } } ) + db.csbios.find( { name: { first: 'John', last: 'McCarthy' } } ) + + The returned document contains an ``_id`` field with the generated + ``ObjectId`` value: + + .. code-block:: javascript { "_id" : ObjectId("507c294cbcf86cd7994f6c0a"), @@ -169,7 +178,6 @@ Consider the following examples that illustrate the usage of the ] } - - If the argument to the :method:`insert() ` method is an array of documents, then the :method:`insert() ` method performs a bulk insert into a @@ -265,7 +273,7 @@ An ``upsert`` has the following syntax: , { upsert: true } ) -Consider the following examples that illustrate the usage of the +Consider the following examples that illustrate the use of the ``upsert`` to perform create operations: - If the ``update`` argument contains only ``field:value`` pairs and no @@ -352,14 +360,18 @@ Consider the following examples that illustrate the usage of the { upsert: true } ) - You can verify that the inserted document contains the ``_id`` and - the ``name`` fields from the ``query`` argument as well as the fields - and values from the ``update`` argument by querying the - ``csbios`` collection: + You can verify the inserted document by querying the ``csbios`` + collection: .. code-block:: javascript - > db.csbios.find( { _id: 7 } ) + db.csbios.find( { _id: 7 } ) + + The returned document contains the ``_id`` and the ``name`` fields + from the ``query`` argument as well as the fields and values from the + ``update`` argument: + + .. code-block:: javascript { "_id" : 7, @@ -416,12 +428,17 @@ Consider the following examples that illustrate the usage of the { upsert: true } ) - You can verify the addition of the ``_id`` field to the inserted - document by the querying the ``csbios`` collection: + You can verify the inserted document by the querying the ``csbios`` + collection: .. code-block:: javascript - > db.csbios.find( { name: { first: 'Bjarne', last: 'Stroustrup' } } ) + db.csbios.find( { name: { first: 'Bjarne', last: 'Stroustrup' } } ) + + The returned document contains an ``_id`` field with the generated + ``ObjectId`` value: + + .. code-block:: javascript { "_id" : ObjectId("507c35dd8fada716c89d0013"), @@ -457,7 +474,7 @@ following syntax: db.collection.save( ) -Consider the following examples that illustrate the usage of the +Consider the following examples that illustrate the use of the :method:`insert() ` method for create operations: @@ -489,7 +506,12 @@ operations: .. code-block:: javascript - > db.csbios.find( { name: { first: 'Guido', last: 'van Rossum'} } ) + db.csbios.find( { name: { first: 'Guido', last: 'van Rossum'} } ) + + The returned document contains an ``_id`` field with the generated + ``ObjectId`` value: + + .. code-block:: javascript { "_id" : ObjectId("507c387cbcf86cd7994f6c0b"), @@ -503,7 +525,7 @@ operations: { "award" : "NLUUG Award", "year" : "2003", "by" : "NLUUG" } - ] + ] } - If the ``document`` contains an ``_id`` field but has a value not @@ -516,18 +538,16 @@ operations: .. code-block:: javascript - db.csbios.save( - { + db.csbios.save( + { _id: 10, name: { first: 'Yukihiro', aka: 'Matz', last: 'Matsumoto'}, birth: new Date('Apr 14, 1965'), contribs: [ 'Ruby' ], - awards: [ + awards: [ { award: 'Award for the Advancement of Free Software', year: '2011', by: 'Free Software Foundation' } ] } ) - - \ No newline at end of file diff --git a/draft/applications/read.txt b/draft/applications/read.txt index 0d95c9ce20b..3150113b43e 100644 --- a/draft/applications/read.txt +++ b/draft/applications/read.txt @@ -5,7 +5,7 @@ Read .. default-domain:: mongodb Read operation selects documents from a :term:`collection`. MongoDB -provides the following methods to perform create operations: +provides the following methods to perform read operations: - :ref:`find ` @@ -30,13 +30,43 @@ syntax: db.collection.find( , ) The :method:`find() ` method is analogous to the -``SQL SELECT`` with the ``query`` argument analogous to the ``WHERE`` -statement and the ``projection`` argument analogous to the selected -fields to return. +``SQL SELECT`` with: -Consider the following examples that illustrate the usage of the +- The ``query`` argument analogous to the ``WHERE`` statement. + +- The ``projection`` argument analogous to the selected fields to + return. + +Consider the following examples that illustrate the use of the :method:`find() ` method: +The examples refer to a collection named ``csbios`` that contains +documents with the following prototype: + +.. code-block:: javascript + + { + "_id" : 1, + "name" : { "first" : "John", "last" :"Backus" }, + "birth" : ISODate("1924-12-03T05:00:00Z"), + "death" : ISODate("2007-03-17T04:00:00Z"), + "contribs" : [ "Fortran", "ALGOL", "Backus-Naur Form", "FP" ], + "awards" : [ + { "award" : "W.W. McDowellAward", + "year" : "1967", + "by" : "IEEE Computer Society" }, + { "award" : "National Medal of Science", + "year" : "1975", + "by" : "National Science Foundation" }, + { "award" : "Turing Award", + "year" : "1977", + "by" : "ACM" }, + { "award" : "Draper Prize", + "year" : "1993", + "by" : "National Academy of Engineering" } + ] + } + .. note:: In the :program:`mongo` shell, you can format the output by adding @@ -83,9 +113,13 @@ Consider the following examples that illustrate the usage of the db.csbios.find( { 'name.first': 'Yukihiro', 'name.last': 'Matsumoto' } ) - The query matches the document with ``name`` field equal to ``{ - first: 'Yukihiro', aka: 'Matz', last: 'Matsumoto'}``. - + The query matches the document where the ``name`` field contains a + field ``first`` with the value ``Yukihiro`` and a field ``last`` + with the value ``Matsumoto``. For instance, the query would match both: + + - ``name: { first: 'Yukihiro', aka: 'Matz', last: 'Matsumoto'}`` + - ``name: { last: 'Matsumoto', first: 'Yukihiro'}``. + - The following operation returns all documents in the ``csbios`` collection where the subdocument ``name`` is *exactly* ``{ first: 'Yukihiro', last: 'Matsumoto' }``, including the order of the @@ -95,10 +129,12 @@ Consider the following examples that illustrate the usage of the db.csbios.find( { name: { first: 'Yukihiro', last: 'Matsumoto' } } ) - The query does *not* match the document with ``name`` field equal - to ``{ first: 'Yukihiro', aka: 'Matz', last: 'Matsumoto'}`` nor - does it match a document with the ``name`` field equal to ``{ last: - 'Matsumoto' , first: 'Yukihiro' }``. + The query *only* matches the document where the ``name`` field is + *exactly* ``{ first: 'Yukihiro', last: 'Matsumoto' }``. For + instance, the query would **not** match either: + + - ``name: { first: 'Yukihiro', aka: 'Matz', last: 'Matsumoto'}`` + - ``name: { last: 'Matsumoto' , first: 'Yukihiro' }``. - The following operation returns all documents in the ``csbios`` collection where either the field ``first`` in the subdocument @@ -111,7 +147,6 @@ Consider the following examples that illustrate the usage of the { birth: { $lt: new Date('01/01/1945') } } ] } ) - - The following operation returns all documents in the ``csbios`` collection where the field ``first`` in the subdocument ``name`` starts with the letter ``K`` **and** the array field ``contribs`` @@ -147,6 +182,19 @@ Consider the following examples that illustrate the usage of the db.csbios.find( { }, { name: 1, contribs: 1 } ) + - The following operation finds all documents in the ``csbios`` + collection and returns only the ``name`` field and the ``contribs`` + field: + + .. code-block:: javascript + + db.csbios.find( { }, { name: 1, contribs: 1, _id: 0 } ) + + .. note:: + + The ``projection`` argument cannot contain both include and + exclude specifications *except* for the exclusion of the ``_id``. + - The following operation finds the documents in the ``csbios`` collection where the ``contribs`` field contains the element ``OOP`` and returns all fields *except* the ``_id`` field, the @@ -184,7 +232,6 @@ provides the cursor methods that work with the :method:`find() db.csbios.find().limit( 5 ) - .. _crud-read-findOne: FindOne @@ -206,7 +253,7 @@ the :method:`find() ` method except the :method:`findOne() ` method returns the single document rather than a cursor. -Consider the following examples that illustrate the usage of the +Consider the following examples that illustrate the use of the :method:`findOne() ` method: - If there is no ``query`` argument, the :method:`findOne() diff --git a/draft/applications/update.txt b/draft/applications/update.txt index 4d9954ce9c5..0a2cf664433 100644 --- a/draft/applications/update.txt +++ b/draft/applications/update.txt @@ -42,7 +42,7 @@ the ``SQL UPDATE`` with the ``query`` argument analogous to the ` method provides additional flexibility and control in use. -Consider the following examples that illustrate the usage of the +Consider the following examples that illustrate the use of the :method:`update() ` method: - If the ``update`` argument contains only :ref:`update operators diff --git a/draft/core/documents.txt b/draft/core/documents.txt index 1872bbacb94..0b4ac1157f2 100644 --- a/draft/core/documents.txt +++ b/draft/core/documents.txt @@ -4,13 +4,15 @@ Documents .. default-domain:: mongodb -Documents in MongoDB refer to the data structure of the records stored -in :term:`collections `, the query criteria, the update actions, and -other arguments to MongoDB methods and operators. +The document structure in MongoDB refer to the data structure of the +records stored in :term:`collections `, the query criteria, +the update actions, and other arguments to MongoDB methods and +operators. -Documents in MongoDB are :term:`BSON` objects with support for the full -range of :term:`BSON types`; however, conceptually, documents may be -viewed as :term:`JSON` objects with the following structure: +The document structure in MongoDB are :term:`BSON` objects with support +for the full range of :term:`BSON types`; however, conceptually, +documents may be viewed as :term:`JSON` objects with the following +structure: .. code-block:: javascript @@ -69,7 +71,7 @@ Consider the following examples of MongoDB documents: { _id: { $gt: 3 } } - The following document specifies the query criteria where ``_id`` - is equal to ``1`` and the ``name`` field equals the document ``{ + is equal to ``1`` **and** the ``name`` field equals the document ``{ first: 'John', last: 'Backus' }``: .. code-block:: javascript @@ -112,19 +114,26 @@ Consider the following examples of MongoDB documents: - The following document specifies the sort order: .. code-block:: javascript - + { 'name.last': 1 } When passed as an argument to the :method:`sort() ` - method, the document specifies the sort order: + method, the document specifies the sort order of the results: .. code-block:: javascript - + db.csbios.find().sort( { 'name.last': 1 } ) - When passed as an argument to the :method:`ensureIndex() ` - method, the document specifies the index to create: +- The following document specifies the index to create: + + .. code-block:: javascript + + { id:1, 'name.last': 1 } + + When passed as an argument to the :method:`ensureIndex() + ` method, the document specifies the + multi-key index to create on the fields ``_id`` and ``name.last``: .. code-block:: javascript - db.csbios.ensureIndex( { 'name.last': 1 } ) + db.csbios.ensureIndex( { id:1, 'name.last': 1 } ) diff --git a/draft/core/read-operations.txt b/draft/core/read-operations.txt index 18cac1eb39e..701b9caa85a 100644 --- a/draft/core/read-operations.txt +++ b/draft/core/read-operations.txt @@ -4,77 +4,281 @@ Read Operations .. default-domain:: mongodb -Read operations determine how MongoDB returns collection data when you -issue a query. This document describes how MongoDB performs read -operations and how different factors affect the efficiency of reads. +Read operations retrieve data from collections. The data returned is in +the form of a :term:`document`. + +This section of the manual describes how MongoDB performs read +operations and how different factors affect the efficiency of the read +operations. .. index:: read operation; query .. index:: query; read operations -.. _read-operations-query-operators: -Query Operations ----------------- +.. _read-operations-operation: -Queries are the primary read operations in MongoDB. +Read Operators +-------------- -.. _read-operations-query-syntax: +MongoDB provides the :method:`find() ` method and +the :method:`findOne() ` method to perform +read operations. -Query Syntax -~~~~~~~~~~~~ +The :method:`find() ` method is the primary +method to select data from a collection. The method has the syntax: + +.. code-block:: javascript + + db.collection.find( , ) + +- The ``query`` argument specifies the select criteria that limits the + documents returned. + +- The ``projection`` argument specifies the fields to return. + +Both the ``query`` argument and the ``projection`` +argument are in the form of a ``document`` structure. + +For example, the following operation selects from the ``products`` +collection where field ``type`` equals ``food`` and the field ``price`` +is less than ``9.95`` and returns the fields ``item`` and ``qty``: + +.. code-block:: javascript + + db.inventory.find( { type: 'food', price: { $lt: 9.95 } }, + { item: 1, qty: 1 } ) + +The :method:`findOne() ` method is similar to +the :method:`find() ` method except the +:method:`findOne() ` method returns a single +document from a collection rather than a cursor. The method has the +syntax: + +.. code-block:: javascript + + db.collection.findOne( , ) + +For additional documentation and examples of the main MongoDB read +operators, refer to the :doc:`/applications/read` page of the +:doc:`/crud` section. + +.. _read-operations-query-argument: + +Query Argument +~~~~~~~~~~~~~~ + +The ``query`` argument determines which records to return. + +Consider the ``query`` arguments in the following :method:`find() +` method calls: + +- No ``query`` argument or an empty ``query`` argument (``{}``) returns + all documents in a collection: + + .. code-block:: javascript + + db.inventory.find() + db.inventory.find( {} ) + +- A ``query`` argument specifies the criteria where the field + ``type`` equals either ``food`` or ``snacks``: + + .. code-block:: javascript + + db.inventory.find( { type: { $in: [ 'food', 'snacks' ] } } ) + +- Compound ``query`` argument specifies the criteria where the field + ``type`` equals ``food`` **and** the field ``price`` is less than + ``9.95``: + + .. code-block:: javascript + + db.inventory.find( { type: 'food', price: { $lt: 9.95 } } ) + +- Compound ``query`` argument specifies the criteria where the field + ``qty`` is greater than ``100`` **or** the field ``price`` is less + than ``9.95``: + + .. code-block:: javascript + + db.inventory.find( { $or: [ { qty: { $gt: 100 } }, + { price: { $lt: 9.95 } } ] + } ) + +- Compound ``query`` argument specifies the criteria where the field + ``type`` equals ``food`` the field **and** either the field ``qty`` + is greater than ``100`` **or** the field ``price`` is less than + ``9.95``: + + .. code-block:: javascript + + db.inventory.find( { type: 'food', $or: [ { qty: { $gt: 100 } }, + { price: { $lt: 9.95 } } ] + } ) + +- A ``query`` argument specifies the criteria where the array field + ``tags`` contains the element ``fruit``: + + .. code-block:: javascript + + db.inventory.find( { tags: "fruit" } ) + +MongoDB provides numerous query selector operators such as the +:operator:`$lt` operator and the :operator:`$or` operator. Refer to the +:doc:`/reference/operators` for the complete list of the ``query`` +operators. + +.. _read-operations-projection: + +Projection Argument +~~~~~~~~~~~~~~~~~~~ + +The ``projection`` argument specifies the fields to return for the +matching documents. By narrowing the fields to return, projections can +minimize network and deserialization costs. In the ``projection`` +argument, you can either specify the fields to include (``field:1``) or +specify the fields to exclude (``field:0``). The ``_id`` field is +implicitly included in the ``projection`` argument. + +Consider the ``projection`` arguments in the following :method:`find() +` method calls: + +- No ``projection`` argument specifies that the :method:`find() + ` method return all fields in the documents + that have the ``type`` field equal to ``food``. + + .. code-block:: javascript + + db.inventory.find( { type: 'food' } ) + +- The ``projection`` argument specifies that the :method:`find() + ` method return the ``item`` field, the ``qty`` + field, and by default, the ``_id`` field in the documents that have + the ``type`` field equal to ``food``. + + .. code-block:: javascript + + db.inventory.find( { type: 'food' }, { item: 1, qty: 1 } ) + +- The ``projection`` argument specifies that the :method:`find() + ` method return the ``item`` field and the + ``qty`` field only in the documents that have the ``type`` field + equal to ``food``. -For a list of query operators, see :doc:`/reference/operators`. + .. code-block:: javascript -.. TODO link to the yet-to-be created query operations doc + db.inventory.find( { type: 'food' }, { item: 1, qty: 1, _id:0 } ) + + .. note:: + + The ``projection`` argument cannot contain both include and + exclude specifications *except* for the exclusion of the ``_id``. + +- The ``projection`` argument specifies that the :method:`find() + ` method return all fields except the ``type`` + field in the documents that have the ``type`` field equal to ``food``. + + .. code-block:: javascript + + db.inventory.find( { type: 'food' }, { type:0 } ) + +MongoDB also provides the following projection operators specific to +arrays. Refer to the operator documentation: + +- :projection:`$elemMatch` + +- :projection:`$slice` .. _read-operations-indexing: Indexes -~~~~~~~ +------- Indexes improve the efficiency of read operations by optimizing queries, pre-sorting query results, and making it possible to store fewer documents in memory. -The most selective indexes return the fastest results. The most -selective index possible for a given query is an index for which all the -documents that match the query criteria also match the entire query. +The syntax to create an index on a collection is: + +.. code-block:: javascript + + db.collection.ensureIndex( { field1: order1, field2: order2, ... } ) -.. example:: +- The ``field`` specifies the field to index. - Given a collection with the following indexes, data, and query: +- The ``order`` specifies ascending ( ``1`` ) or descending ( ``-1`` ). - Indexes: +Refer to the :method:`ensureIndex() ` method +documentation for additional options available for the method. - .. code-block:: javascript +Consider the performance of the following read operation that does not +use an index: - { x : 1 } , { y : 1 } +.. code-block:: javascript - Data: + db.inventory.find( { type: 'food' } ).explain() - .. code-block:: javascript +The results from the :method:`explain() ` method +shows that the execution of the :method:`find() ` +method would involve scanning ``4000006`` documents to return ``5`` +objects: - { x : 1 , y : 2 } - { x : 2 , y : 1 } - { x : 3 , y : 0 } - { x : 4 , y : 0 } +.. code-block:: javascript - Query: + { + "cursor" : "BasicCursor", + "isMultiKey" : false, + "n" : 5, + "nscannedObjects" : 4000006, + "nscanned" : 4000006, + "nscannedObjectsAllPlans" : 4000006, + "nscannedAllPlans" : 4000006, + "scanAndOrder" : false, + "indexOnly" : false, + "nYields" : 2, + "nChunkSkips" : 0, + "millis" : 1591, + "indexBounds" : { }, + "server" : "My-Machine.local:27017" + } + +To improve the performance of the query, create an index on the +``type`` field: - .. code-block:: javascript +.. code-block:: javascript - db.foo.find( { x : { $gte : 1 } , y : { $gte : 1} } ) + db.inventory.ensureIndex( { type: 1 } ) - The ``{ y : 1 }`` index is more selective because all the documents - that match the query's ``y`` key value also match the entire query. - Conversely, not all the documents that match the query's ``x`` key - value also match the entire query. +Compare the performance of the previous read operation, but now +executed with the newly created index: -.. seealso:: +.. code-block:: javascript + + db.inventory.find( { type: 'food' } ).explain() - - The :doc:`/indexes` documentation, in particular :doc:`/applications/indexes` - - :doc:`/reference/operators` - - :method:`find() ` - - :method:`findOne() ` +The results show a substantial improvement in the performance of the +operation. The execution of the :method:`find() ` +method would involve scanning ``5`` documents to return ``5`` objects: + +.. code-block:: javascript + + { + "cursor" : "BtreeCursor type_1", + "isMultiKey" : false, + "n" : 5, + "nscannedObjects" : 5, + "nscanned" : 5, + "nscannedObjectsAllPlans" : 5, + "nscannedAllPlans" : 5, + "scanAndOrder" : false, + "indexOnly" : false, + "nYields" : 0, + "nChunkSkips" : 0, + "millis" : 0, + "indexBounds" : { "type" : [ + [ "food", + "food" ] + ] }, + "server" : "My-Machine.local:27017" } .. index:: query optimizer .. _read-operations-query-optimization: @@ -83,25 +287,20 @@ Query Optimization ~~~~~~~~~~~~~~~~~~ The MongoDB query optimizer matches a query to the index that produces -the fastest results. The optimizer then uses the query plan each time +the fastest results. The optimizer then uses this query plan each time the query runs. If a collection changes significantly, the optimizer creates a new query plan. -Query plans take advantage of MongoDB's indexing features. You should -always write indexes that use the same fields and that sort in the same -order as do your queries. For more information, see -:doc:`/applications/indexes`. - MongoDB creates a query plan as follows: -1. The query optimizer runs the query against several indexes at once in +1. The query optimizer runs the query against several indexes in parallel. -#. The optimizer records matches in a single common buffer, as though - the results all come from the same index. +#. The optimizer records the matches in a single common buffer, as + though the results all come from the same index. #. If an index returns a result already returned by another index, the - optimizer recognizes the duplication and skips the duplicate match. + optimizer skips the duplicate match. #. The optimizer determines a "winning" index when either of the following occur: @@ -111,24 +310,23 @@ MongoDB creates a query plan as follows: querying. - The optimizer reaches 101 results. At this point, the optimizer - chooses the plan that has provided the most results *first* and - continues reading only from that plan. Note that another index - might have provided all those results as duplicates but because the - "winning" index provided the full result set first, it is more - efficient. + chooses the index that has provided the most results *first* and + continues reading only from that index. #. The "winning" index becomes the index specified in the query plan. -To evaluate the optimizer's choice of query plan, run the query with the -:method:`explain() ` method and :method:`hint() -` methods appended. Instead of returning query results, -this returns statistics about how the query runs. For example: +To evaluate the optimizer's choice of query plan, run the query with +the :method:`explain() ` method and the +:method:`hint() ` method appended. Instead of returning +query results, this returns statistics about how the query runs. For +example: .. code-block:: javascript - db.people.find( { name:"John"} ).explain().hint() + db.inventory.find( { type: 'food' } ).explain().hint() -For details on the output, see :method:`explain() `. +For details on the output, see the :method:`explain() +` method documentation. .. note:: @@ -137,9 +335,8 @@ For details on the output, see :method:`explain() `. the query and runs against multiple indexes before returning the query statistics. -Because your collections will likely change over time, the query -optimizer deletes a query plan and re-evaluates the indexes when any -of the following occur: +As collections change over time, the query optimizer deletes a query +plan and re-evaluates the indexes when any of the following occur: - The number of writes to the collection reaches 1,000. @@ -154,67 +351,7 @@ indexes at once during re-evaluation, and the order in which results appear depends on the order of the indexes in the parallel query operation. -.. _read-operations-projection: - -Projection -~~~~~~~~~~ - -A projection specifies which field values to return for matching -documents. If you run a query *without* a projection, the query returns -all fields and values for matching documents. By narrowing the fields to -display, projections can minimize network and deserialization costs. - -You specify a projection in the second document in a query: - -.. code-block:: javascript - - db.foo.find( { } , { } ) - -.. example:: - - Given the following small collection name ``foo``: - - .. code-block:: javascript - - { "_id" : 100 , x : 1 , y : 15 , z : 20 } - { "_id" : 101 , x : 2 , y : 16 , z : 21 } - { "_id" : 102 , x : 2 , y : 17 , z : 22 } - { "_id" : 103 , x : 3 , y : 18 , z : 23 } - - To search for all documents where ``x`` is ``2`` but return only the - ``z`` field, issue this query: - - .. code-block:: javascript - - db.foo.find( { x : 2 } , { z : 1 } ) - - The query returns this result set: - - .. code-block:: javascript - - { "_id" : 101, "z" : 21 } - { "_id" : 102, "z" : 22 } - - By default, the results include the ``_id`` field. To return ``z`` - *without* returning ``_id``, include ``_id : 0`` in the projection: - - .. code-block:: javascript - - db.foo.find( { x : 2 } , { z : 1 , _id : 0 } ) - - The query returns this result set: - - .. code-block:: javascript - - { "z" : 21 } - { "z" : 22 } - -MongoDB also provides the following projection operators specific to -arrays. For documentation on each operator, click the operator name: - -- :projection:`$elemMatch` - -- :projection:`$slice` +For more information, refer to :doc:`/applications/indexes`. .. _read-operations-aggregation: @@ -263,7 +400,7 @@ Operators that cannot use indexes include the following: - :operator:`$ne` -.. TODO Regular expressions queries also do not use an index. +.. TODO Regular expressions queries also do not use an index except when used with anchors. .. TODO :method:`cursor.skip()` can cause paginating large numbers of docs Architecture diff --git a/source/reference/method/db.collection.find.txt b/source/reference/method/db.collection.find.txt index 37282f6df1b..82a2329e449 100644 --- a/source/reference/method/db.collection.find.txt +++ b/source/reference/method/db.collection.find.txt @@ -40,8 +40,8 @@ db.collection.find() - ``0`` or ``false`` to exclude. - You cannot mix include and exclude fields in projection - specifications. + The ``projection`` cannot contain both include and exclude + specifications except for the exclusion of the ``_id`` field. :returns: