From 13eae4d4253d63be6f51fbeed1f7a048c6a94c05 Mon Sep 17 00:00:00 2001 From: Zack Brown Date: Wed, 7 Aug 2013 17:34:03 -0400 Subject: [PATCH 1/2] DOCS-1455: Add Section to Describe dynamic TTL collections --- .../note-ttl-collection-background-timing.rst | 21 +- source/tutorial/expire-data.txt | 186 ++++++++++++------ 2 files changed, 143 insertions(+), 64 deletions(-) diff --git a/source/includes/note-ttl-collection-background-timing.rst b/source/includes/note-ttl-collection-background-timing.rst index 8fa78e96a66..12aeb7844e4 100644 --- a/source/includes/note-ttl-collection-background-timing.rst +++ b/source/includes/note-ttl-collection-background-timing.rst @@ -1,12 +1,15 @@ -.. note:: +.. warning:: - TTL indexes expire data by removing documents in a background task - that runs *every 60 seconds*. As a result, the TTL index provides no - guarantees that expired documents will not exist in the - collection. Consider that: + The TTL index does not guarantee that expired data will be deleted + immediately. There may be a delay between the time a document expires + and the time it is deleted from the database. - - Documents may remain in a collection *after* they expire and before - the background process runs. + The background task that removes expired documents runs *every 60 + seconds*. As a result, documents may remain in a collection *after* + they expire but *before* the background task runs. + + The duration of the removal operation depends on the workload of + your :program:`mongod` instance. Therefore, expired data may exist + for some time *beyond* the 60 second period between runs of the + background task. - - The duration of the removal operations depend on the workload of - your :program:`mongod` instance. diff --git a/source/tutorial/expire-data.txt b/source/tutorial/expire-data.txt index cecd4834d6b..5f96e3d5c62 100644 --- a/source/tutorial/expire-data.txt +++ b/source/tutorial/expire-data.txt @@ -6,38 +6,34 @@ Expire Data from Collections by Setting TTL .. default-domain:: mongodb +.. contents:: + :backlinks: none + :local: + .. versionadded:: 2.2 This document provides an introduction to MongoDB's "*time to live*" -or ":term:`TTL`" collection feature. Implemented as a special index -type, TTL collections make it possible to store data in MongoDB and -have the :program:`mongod` automatically remove data after a specified -period of time. This is ideal for some types of information like -machine generated event data, logs, and session information that only -need to persist in a database for a limited period of time. - -Background ----------- - -Collections expire by way of a special index of a field with date -values in conjunction with a background thread in :program:`mongod` -that regularly removes expired :term:`documents ` from the -collection. You can use this feature to expire data from -:term:`replica sets ` and :term:`sharded clusters -`. - -Use the ``expireAfterSeconds`` option to the :method:`ensureIndex -` method in conjunction with a TTL value -in seconds to create an expiring collection. Collections with an index -that expires data set the :collflag:`usePowerOf2Sizes` collection -flag. As a result, MongoDB must allocate more disk space relative to -data size. This approach helps mitigate the possibility of storage -fragmentation caused by frequent delete operations and leads to more -predictable storage use patterns. - -.. important:: All collections with an index using the - ``expireAfterSeconds`` option have :collflag:`usePowerOf2Sizes` - enabled. Users cannot modify this setting. +or ":term:`TTL`" collection feature. TTL collections make it possible +to store data in MongoDB and have the :program:`mongod` automatically +remove data after a specified number of seconds, or when a particular +clock time is reached. + +Data expiration is useful for some types of information like machine +generated event data, logs, and session information that only need to +persist for a limited period of time. + +Enable TTL for a Collection +--------------------------- + +TTL collections are implemented as a special index type that contains +date values. TTL relies on a background thread in :program:`mongod` that +reads the date values and regularly removes expired :term:`documents +` from the collection. + +To enable TTL for a collection, use the +:method:`~db.collection.ensureIndex()` method to create a TTL index, +as shown in the examples below. TTL is enabled as soon as the index +finishes building. .. note:: @@ -46,47 +42,127 @@ predictable storage use patterns. :method:`db.currentOp()` or in the data collected by the :ref:`database profiler `. -Constraints ------------ +.. note:: -Consider the following limitations: + When enabling TTL on :term:`replica sets `, the + TTL background thread runs *only* on :term:`primary` members. + :term:`Secondary` members replicate deletion operations + from the primary. -- the indexed field must be a date :term:`BSON type `. If - the field does not have a date type, the data will not expire. +.. include:: /includes/note-ttl-collection-background-timing.rst -- documents that omit the indexed field will never expire. +With the exception of the background thread, A TTL index optimizes +queries in the same way normal indexes do. For this reason, there are +two different approaches to expiring documents, corresponding to two +different use-cases for querying the indexed TTL field. -- you cannot create this index on the ``_id`` field, or a field that - already has an index. +In one case, expiration occurs after a certain number of seconds, which +supports querying the creation-time of documents. In the other case, +expiration occurs when a certain clock time is reached, which supports +querying the expected expiration-time of documents. -- the TTL index may not be compound (may not have multiple fields). +Both of these approaches to TTL are described below: -- if the field holds an array, and there are multiple date-typed - data in the index, the document will expire when the *lowest* - (i.e. earliest) matches the expiration threshold. +Expire after a Certain Number of Seconds +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- you cannot use a TTL index on a capped collection, because MongoDB - cannot remove documents from a capped collection. +To expire documents after a certain number of seconds, give the date +field a value corresponding to the current time (i.e. when the document +was created), and give the ``expireAfterSeconds`` option a TTL value in +seconds. For example, if the current date and time is ``July 22, 2013: +13:00:00``, consider a document such as the following: -.. include:: /includes/note-ttl-collection-background-timing.rst +.. code-block:: javascript -Enabling a TTL for a Collection -------------------------------- + db.log.events.insert( { + "status": new Date('July 22, 2013: 13:00:00'), + "logEvent": 2, + "logMessage": "Success!", + } ) -To set a TTL on the collection "``log.events``" for one hour use the -following command at the :program:`mongo` shell: +The ``status`` field *must* hold a BSON date object or an array of BSON +date objects. To set a TTL of one hour on this collection, use the following command +at the :program:`mongo` shell: .. code-block:: javascript db.log.events.ensureIndex( { "status": 1 }, { expireAfterSeconds: 3600 } ) -The ``status`` field *must* hold date/time information. MongoDB will -automatically delete documents from this collection once the value of -``status`` is one or more hours old. +MongoDB will automatically delete documents from this +collection when at least one of the values of ``status`` is a time older +than the number of seconds specified in ``expireAfterSeconds``. + +Notice that the value of ``status`` can be queried for the creation-time +of a document. Querying ``status`` is not part of the TTL feature, but +the fact that the TTL index exists makes such queries highly efficient. +Now consider a value of ``status`` other than the creation-time of the +document: + +Expire at a Certain Clock Time +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To expire documents at a certain clock time, give the date field a +value corresponding to the time a document should expire, and give the +``expireAfterSeconds`` option a TTL value of ``0``. For example, if the +current date and time is ``July 22, 2013: 13:00:00`` as above, consider +a document such as the following: + +.. code-block:: javascript + + db.log.events.insert( { + "status": new Date('July 22, 2013: 14:00:00'), + "logEvent": 2, + "logMessage": "Success!", + } ) -Replication +As above, the ``status`` field *must* hold a BSON date object or an +array of BSON date objects. Notice that the ``status`` field has a date +that is one hour in the future. That is the desired expiration time. To +set a TTL that will expire this document at that time, use the following +command at the :program:`mongo` shell: + +.. code-block:: javascript + + db.log.events.ensureIndex( { "status": 1 }, { expireAfterSeconds: 0 } ) + +Because ``expireAfterSeconds`` is ``0``, MongoDB will automatically +delete documents from this collection when at least one of the the +values of ``status`` is equal to the current time, or is in the past. + +Notice that in the current case, the value of ``status`` can be queried +for the expiration-time of a document. Again, this is not a feature +of TTL, but the existence of the TTL index makes such a query highly +efficient. + +Constraints ----------- -The TTL background thread *only* runs on :term:`primary` members of -:term:`replica sets `. :term:`Secondaries ` -members will replicate deletion operations from the primaries. +- The ``_id`` field cannot be used as a TTL index. + +- TTL cannot be enabled on a field that already has an index. + +- A document will not expire if the indexed field does not exist. + +- A document will not expire if the indexed field is not a date + :term:`BSON type ` or an array of date :term:`BSON types + `. + +- The TTL index may not be compound (may not have multiple fields). + +- If the TTL field holds an array, and there are multiple date-typed + data in the index, the document will expire when the *lowest* (i.e. + earliest) date matches the expiration threshold. + +- TTL cannot be enabled on a capped collection, because MongoDB cannot + remove documents from a capped collection. + +.. important:: + + All collections with an index using the ``expireAfterSeconds`` option + have :collflag:`usePowerOf2Sizes` enabled. Users cannot modify this + setting. As a result of enabling :collflag:`usePowerOf2Sizes`, + MongoDB must allocate more disk space relative to data size. This + approach helps mitigate the possibility of storage fragmentation + caused by frequent delete operations and leads to more predictable + storage use patterns. + From 96700045fe20e5bf4e17671abe8ad041e15267bc Mon Sep 17 00:00:00 2001 From: Zack Brown Date: Wed, 7 Aug 2013 17:34:54 -0400 Subject: [PATCH 2/2] changing reference formating --- source/core/capped-collections.txt | 49 +++++----- source/core/document.txt | 52 ++++++----- source/core/geohaystack.txt | 4 +- source/core/indexes.txt | 22 ++--- source/core/read-operations.txt | 89 +++++++++---------- source/core/read-preference.txt | 11 ++- source/core/write-operations.txt | 22 ++--- source/faq/developers.txt | 38 ++++---- source/faq/indexes.txt | 32 +++---- source/faq/storage.txt | 22 ++--- ...t-remove-capped-collection-restriction.rst | 2 +- .../table-lock-behavior-per-operation.yaml | 8 +- .../table-sql-to-mongo-delete-examples.yaml | 4 +- .../table-sql-to-mongo-insert-examples.yaml | 4 +- .../table-sql-to-mongo-schema-examples.yaml | 23 ++--- .../table-sql-to-mongo-select-examples.yaml | 52 +++++------ .../table-sql-to-mongo-update-examples.yaml | 6 +- source/reference/command/findAndModify.txt | 4 +- source/reference/database-profiler.txt | 6 +- source/reference/glossary.txt | 4 +- .../method/Mongo.getReadPrefMode.txt | 4 +- .../method/Mongo.getReadPrefTagSet.txt | 4 +- source/reference/method/Mongo.setSlaveOk.txt | 4 +- source/reference/method/cursor.explain.txt | 31 +++---- source/reference/method/cursor.limit.txt | 10 +-- source/reference/method/cursor.max.txt | 11 ++- source/reference/method/cursor.min.txt | 9 +- source/reference/method/cursor.readPref.txt | 4 +- source/reference/method/cursor.snapshot.txt | 15 ++-- source/reference/method/cursor.sort.txt | 15 ++-- .../method/db.collection.ensureIndex.txt | 10 +-- .../reference/method/db.collection.find.txt | 9 +- .../method/db.collection.getIndexStats.txt | 4 +- .../reference/method/db.collection.insert.txt | 19 ++-- .../reference/method/db.collection.remove.txt | 13 ++- .../reference/method/db.collection.update.txt | 7 +- source/reference/mongo-shell.txt | 34 +++---- source/reference/object-id.txt | 11 ++- source/reference/operator/all.txt | 3 +- source/reference/operator/and.txt | 5 +- source/reference/operator/exists.txt | 2 +- source/reference/operator/explain.txt | 18 ++-- source/reference/operator/gt.txt | 5 +- source/reference/operator/gte.txt | 5 +- source/reference/operator/in.txt | 5 +- source/reference/operator/lt.txt | 5 +- source/reference/operator/lte.txt | 5 +- source/reference/operator/max.txt | 10 +-- source/reference/operator/min.txt | 10 +-- source/reference/operator/mod.txt | 3 +- source/reference/operator/ne.txt | 5 +- source/reference/operator/nin.txt | 5 +- source/reference/operator/nor.txt | 3 +- source/reference/operator/not.txt | 3 +- source/reference/operator/or.txt | 12 +-- source/reference/operator/positional.txt | 4 +- source/reference/operator/type.txt | 3 +- source/reference/projection/elemMatch.txt | 4 +- source/reference/system-collections.txt | 4 +- source/release-notes/2.2.txt | 33 ++++--- .../password-hashing-insecurity.txt | 2 +- source/tutorial/access-mongo-shell-help.txt | 16 ++-- source/tutorial/aggregation-examples.txt | 28 +++--- source/tutorial/create-a-unique-index.txt | 4 +- .../create-an-auto-incrementing-field.txt | 8 +- source/tutorial/create-an-index.txt | 4 +- ...ce-unique-keys-for-sharded-collections.txt | 2 +- .../evaluate-operation-performance.txt | 6 +- .../getting-started-with-the-mongo-shell.txt | 6 +- source/tutorial/getting-started.txt | 15 ++-- .../manage-chunks-in-sharded-cluster.txt | 12 +-- source/tutorial/manage-mongodb-processes.txt | 4 +- source/tutorial/measure-index-use.txt | 9 +- ...rformance-with-indexes-and-projections.txt | 8 +- source/tutorial/perform-two-phase-commits.txt | 37 ++++---- source/use-cases/storing-log-data.txt | 8 +- 76 files changed, 465 insertions(+), 524 deletions(-) diff --git a/source/core/capped-collections.txt b/source/core/capped-collections.txt index 19ecdd26ee9..c063201d7cd 100644 --- a/source/core/capped-collections.txt +++ b/source/core/capped-collections.txt @@ -11,7 +11,7 @@ collections work in a way similar to circular buffers: once a collection fills its allocated space, it makes room for new documents by overwriting the oldest documents in the collection. -See :method:`db.createCollection()` or :dbcommand:`createCollection` +See :method:`~db.createCollection()` or :dbcommand:`createCollection` for more information on creating capped collections. Capped collections have the following behaviors: @@ -60,8 +60,8 @@ Recommendations and Restrictions - You cannot delete documents from a capped collection. To remove all records from a capped collection, use the 'emptycapped' command. To - remove the collection entirely, use the :method:`drop() - ` method. + remove the collection entirely, use the :method:`~db.collection.drop()` + method. - You cannot shard a capped collection. @@ -74,13 +74,12 @@ Recommendations and Restrictions .. warning:: If you have a capped collection in a :term:`replica set` outside - of the ``local`` database, before 2.2, you should create a unique - index on ``_id``. Ensure uniqueness using the ``unique: true`` - option to the :method:`ensureIndex() - ` method or by using an - :term:`ObjectId` for the ``_id`` field. Alternately, you can use - the ``autoIndexId`` option to :dbcommand:`create` when creating - the capped collection, as in the + of the ``local`` database, before 2.2, you should create a + unique index on ``_id``. Ensure uniqueness using the ``unique: + true`` option to the :method:`~db.collection.ensureIndex()` + method or by using an :term:`ObjectId` for the ``_id`` field. + Alternately, you can use the ``autoIndexId`` option to + :dbcommand:`create` when creating the capped collection, as in the :ref:`capped-collections-options` procedure. - Use natural ordering to retrieve the most recently inserted elements @@ -94,12 +93,12 @@ Create a Capped Collection ~~~~~~~~~~~~~~~~~~~~~~~~~~ You must create capped collections explicitly using the -:method:`createCollection() ` method, which is -a helper in the :program:`mongo` shell for the :dbcommand:`create` -command. When creating a capped collection you must specify the -maximum size of the collection in bytes, which MongoDB will pre-allocate -for the collection. The size of the capped collection includes a -small amount of space for internal overhead. +:method:`~db.createCollection()` method, which is a helper in the +:program:`mongo` shell for the :dbcommand:`create` command. When +creating a capped collection you must specify the maximum size of the +collection in bytes, which MongoDB will pre-allocate for the collection. +The size of the capped collection includes a small amount of space for +internal overhead. .. code-block:: javascript @@ -117,21 +116,21 @@ collection using the ``max`` field as in the following document: documents if a collection reaches the maximum size limit before it reaches the maximum document count. -.. see:: :method:`db.createCollection()` and :dbcommand:`create`. +.. see:: :method:`~db.createCollection()` and :dbcommand:`create`. .. _capped-collections-options: Query a Capped Collection ~~~~~~~~~~~~~~~~~~~~~~~~~ -If you perform a :method:`find() ` on a capped -collection with no ordering specified, MongoDB guarantees that the -ordering of results is the same as the insertion order. +If you perform a :method:`~db.collection.find()` on a capped collection +with no ordering specified, MongoDB guarantees that the ordering of +results is the same as the insertion order. -To retrieve documents in reverse insertion order, issue :method:`find() -` along with the :method:`sort() ` -method with the :operator:`$natural` parameter set to ``-1``, as shown in the -following example: +To retrieve documents in reverse insertion order, issue +:method:`~db.collection.find()` along with the :method:`~cursor.sort()` +method with the :operator:`$natural` parameter set to ``-1``, as shown +in the following example: .. code-block:: javascript @@ -140,7 +139,7 @@ following example: Check if a Collection is Capped ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Use the :method:`db.collection.isCapped()` method to determine if a +Use the :method:`~db.collection.isCapped()` method to determine if a collection is capped, as follows: .. code-block:: javascript diff --git a/source/core/document.txt b/source/core/document.txt index edad04f172f..dd9816d668c 100644 --- a/source/core/document.txt +++ b/source/core/document.txt @@ -24,11 +24,11 @@ MongoDB contexts: - arguments to several MongoDB methods and operators, including: - - :ref:`sort order ` for the :method:`sort() - ` method. + - :ref:`sort order ` for the + :method:`~cursor.sort()` method. - :ref:`index specification ` for the - :method:`hint() ` method. + :method:`~cursor.hint()` method. - the output of a number of MongoDB commands and operations, including: @@ -264,11 +264,11 @@ select for read, update, and delete operations. You can use :doc:`query operator ` expressions to specify additional conditions. -When passed as an argument to methods such as the :method:`find() -` method, the :method:`remove() -` method, or the :method:`update() -` method, the query document selects documents -for MongoDB to return, remove, or update, as in the following: +When passed as an argument to methods such as +the :method:`~db.collection.find()` method, the +:method:`~db.collection.remove()` method, or the +:method:`~db.collection.update()` method, the query document selects +documents for MongoDB to return, remove, or update, as in the following: .. code-block:: javascript @@ -295,11 +295,10 @@ for MongoDB to return, remove, or update, as in the following: Update Specification Documents ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Update documents specify the data modifications to perform during -an :method:`update() ` operation to modify -existing records in a collection. You can use :ref:`update operators -` to specify the exact actions to perform on the -document fields. +Update documents specify the data modifications to perform during an +:method:`~db.collection.update()` operation to modify existing records +in a collection. You can use :ref:`update operators ` +to specify the exact actions to perform on the document fields. Consider the update document example: @@ -313,8 +312,8 @@ Consider the update document example: } } -When passed as an argument to the :method:`update() -` method, the update actions document: +When passed as an argument to the :method:`~db.collection.update()` +method, the update actions document: - Modifies the field ``name`` whose value is another document. Specifically, the :operator:`$set` operator updates the ``middle`` @@ -383,9 +382,8 @@ subdocument: { _id: 1, 'name.last': 1 } -When passed as an argument to the :method:`ensureIndex() -` method, the index documents specifies -the index to create: +When passed as an argument to the :method:`~db.collection.ensureIndex()` +method, the index documents specifies the index to create: .. code-block:: javascript @@ -402,9 +400,9 @@ Sort Order Specification Documents Sort order documents specify the order of documents that a :method:`query() ` returns. Pass sort order -specification documents as an argument to the :method:`sort() -` method. See the :method:`sort() ` page -for more information on sorting. +specification documents as an argument to the :method:`~cursor.sort()` +method. See the :method:`~cursor.sort()` page for more information on +sorting. The sort order documents contain field and value pairs, in the following form: @@ -425,9 +423,9 @@ by the ``first`` field also ascending: { 'name.last': 1, 'name.first': 1 } -When passed as an argument to the :method:`sort() ` +When passed as an argument to the :method:`~cursor.sort()` method, the sort order document sorts the results of the -:method:`find() ` method: +:method:`~db.collection.find()` method: .. code-block:: javascript @@ -464,10 +462,10 @@ most international characters in BSON strings with ease. :operator:`$regex` queries support UTF-8 in the regex string. .. [#sort-string-internationalization] Given strings using UTF-8 - character sets, using :method:`sort() ` on strings - will be reasonably correct; however, because internally - :method:`sort() ` uses the C++ ``strcmp`` api, the - sort order may handle some characters incorrectly. + character sets, using :method:`~cursor.sort()` on strings will be + reasonably correct; however, because internally :method:`~cursor.sort()` + uses the C++ ``strcmp`` api, the sort order may handle some characters + incorrectly. .. _document-bson-type-timestamp: diff --git a/source/core/geohaystack.txt b/source/core/geohaystack.txt index 7773a6de8ea..07dcc784284 100644 --- a/source/core/geohaystack.txt +++ b/source/core/geohaystack.txt @@ -119,5 +119,5 @@ point, the command would resemble: ` are not currently supported by haystack indexes. - The :method:`find() ` method and - :dbcommand:`geoNear` command cannot access the haystack index. + The :method:`~db.collection.find()` method and :dbcommand:`geoNear` + command cannot access the haystack index. diff --git a/source/core/indexes.txt b/source/core/indexes.txt index ea3702547c7..1cd55995ece 100644 --- a/source/core/indexes.txt +++ b/source/core/indexes.txt @@ -44,7 +44,7 @@ MongoDB indexes have the following core features: selects the index empirically by occasionally running alternate query plans and by selecting the plan with the best response time for each query type. You can override - the query optimizer using the :method:`cursor.hint()` method. + the query optimizer using the :method:`~cursor.hint()` method. - An index "covers" a query if: @@ -118,7 +118,7 @@ suitable for use as the value of an ``_id`` field. auto-generated :term:`ObjectId`. .. [#unique-index-report] Although the index on ``_id`` *is* unique, - the :method:`getIndexes() ` method will + the :method:`~db.collection.getIndexes()` method will *not* print ``unique: true`` in the :program:`mongo` shell. .. [#capped-collections] Before version 2.2 capped collections did not @@ -149,8 +149,8 @@ and user-facing queries. Doing so requires MongoDB to scan the fewest number of documents possible. In the :program:`mongo` shell, you can create an index by calling the -:method:`ensureIndex() ` method. -Arguments to :method:`ensureIndex() ` +:method:`~db.collection.ensureIndex()` method. +Arguments to :method:`~db.collection.ensureIndex()` resemble the following: .. code-block:: javascript @@ -605,8 +605,8 @@ default name. The resulting index is named: ``inventory``. -To view the name of an index, use the :method:`getIndexes() -` method. +To view the name of an index, use the +:method:`~db.collection.getIndexes()` method. .. index:: index; options .. _index-creation-operations: @@ -616,7 +616,7 @@ Index Creation Options ---------------------- You specify index creation options in the second argument in -:method:`ensureIndex() `. +:method:`~db.collection.ensureIndex()`. The options :ref:`sparse `, :ref:`unique `, and :ref:`TTL ` affect the @@ -679,10 +679,10 @@ construction: larger than the available RAM, then the incremental process can take *much* longer than the foreground build. -- If your application includes :method:`ensureIndex() - ` operations, and an index *doesn't* - exist for other operational concerns, building the index can have a - severe impact on the performance of the database. +- If your application includes :method:`~db.collection.ensureIndex()` + operations, and an index *doesn't* exist for other operational concerns, + building the index can have a severe impact on the performance of the + database. Make sure that your application checks for the indexes at start up using the :method:`~db.collection.getIndexes()` method diff --git a/source/core/read-operations.txt b/source/core/read-operations.txt index 41cd67eeb1a..a62cd7fa65b 100644 --- a/source/core/read-operations.txt +++ b/source/core/read-operations.txt @@ -30,11 +30,10 @@ factors affect the efficiency of reads. Queries in MongoDB ------------------ -In the :program:`mongo` shell, the :method:`find() -` and :method:`findOne() -` methods perform read operations. The -:method:`find() ` method has the following -syntax: [#formal-query-structure]_ +In the :program:`mongo` shell, the :method:`~db.collection.find()` and +:method:`~db.collection.findOne()` methods perform read operations. +The :method:`~db.collection.find()` method has the following syntax: +[#formal-query-structure]_ .. code-block:: javascript @@ -52,10 +51,9 @@ syntax: [#formal-query-structure]_ :doc:`query operators ` to describe query parameters. - The ```` argument of the :method:`find() - ` method holds this query document. A read - operation without a query document will return all documents in the - collection. + The ```` argument of the :method:`~db.collection.find()` method + holds this query document. A read operation without a query document + will return all documents in the collection. - The ```` argument describes the result set in the form of a document. Projections specify or limit the fields to return. @@ -65,9 +63,9 @@ syntax: [#formal-query-structure]_ larger, or when your application only needs a subset of available fields. -- The order of documents returned by a query is not defined and is not - necessarily consistent unless you specify a sort (:method:`sort() - `). +- The order of documents returned by a query is not defined + and is not necessarily consistent unless you specify a sort + (:method:`~cursor.sort()`). For example, the following operation on the ``inventory`` collection selects all documents where the ``type`` field equals ``'food'`` and @@ -79,9 +77,9 @@ limits the response to the ``item`` and ``qty``, and ``_id`` field: 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 +The :method:`~db.collection.findOne()` method is similar to +the :method:`~db.collection.find()` method except the +:method:`~db.collection.findOne()` method returns a single document from a collection rather than a cursor. The method has the syntax: @@ -93,7 +91,7 @@ For additional documentation and examples of the main MongoDB read operators, refer to the :doc:`/core/read` page of the :doc:`/crud` section. -.. [#formal-query-structure] :method:`db.collection.find()` is a +.. [#formal-query-structure] :method:`~db.collection.find()` is a wrapper for the more formal query structure with the :operator:`$query` operator. @@ -108,9 +106,9 @@ queries. See the preceding section for more information on :ref:`queries in MongoDB `. The following examples demonstrate the key properties of the query -document in MongoDB queries, using the :method:`find() -` method from the :program:`mongo` shell, and a -collection of documents named ``inventory``: +document in MongoDB queries, using the :method:`~db.collection.find()` +method from the :program:`mongo` shell, and a collection of documents +named ``inventory``: - An empty query document (``{}``) selects all documents in the collection: @@ -119,10 +117,9 @@ collection of documents named ``inventory``: db.inventory.find( {} ) - Not specifying a query document to the :method:`find() - ` is equivalent to specifying an empty query - document. Therefore the following operation is equivalent to the - previous operation: + Not specifying a query document to the :method:`~db.collection.find()` + is equivalent to specifying an empty query document. Therefore the + following operation is equivalent to the previous operation: .. code-block:: javascript @@ -358,7 +355,7 @@ all matching documents. Restricting the fields to return can minimize network transit costs and the costs of deserializing documents in the application layer. -The second argument to the :method:`find() ` +The second argument to the :method:`~db.collection.find()` method is a projection, and it takes the form of a :term:`document` with a list of fields for inclusion or exclusion from the result set. You can either specify the fields to include (e.g. ``{ field: 1 }``) or specify the @@ -372,12 +369,11 @@ exclusion of the ``_id`` field (i.e. ``{ _id: 0 }``). You cannot combine inclusion and exclusion semantics in a single projection with the *exception* of the ``_id`` field. -Consider the following projection specifications in :method:`find() -` operations: +Consider the following projection specifications in +:method:`~db.collection.find()` operations: -- If you specify no projection, the :method:`find() - ` method returns all fields of all documents - that match the query. +- If you specify no projection, the :method:`~db.collection.find()` + method returns all fields of all documents that match the query. .. code-block:: javascript @@ -387,9 +383,9 @@ Consider the following projection specifications in :method:`find() collection where the value of the ``type`` field is ``'food'``. - A projection can explicitly include several fields. In the following - operation, :method:`find() ` method returns - all documents that match the query as well as ``item`` and ``qty`` - fields. The results also include the ``_id`` field: + operation, :method:`~db.collection.find()` method returns all documents + that match the query as well as ``item`` and ``qty`` fields. The results + also include the ``_id`` field: .. code-block:: javascript @@ -437,7 +433,7 @@ index can: support and optimize specific queries, sort operations, and allow for more efficient storage utilization. For more information about indexes in MongoDB see: :doc:`/indexes` and :doc:`/core/indexes`. -You can create indexes using the :method:`db.collection.ensureIndex()` method +You can create indexes using the :method:`~db.collection.ensureIndex()` method in the :program:`mongo` shell, as in the following prototype operation: @@ -670,8 +666,8 @@ queries with the same query pattern: db.inventory.find( { type: 'utensil' } ) To manually compare the performance of a query using more than one -index, you can use the :method:`hint() ` and -:method:`explain() ` methods in conjunction, as in +index, you can use the :method:`~cursor.hint()` and +:method:`~cursor.explain()` methods in conjunction, as in the following prototype: .. code-block:: javascript @@ -687,13 +683,12 @@ use of the different indexes: db.inventory.find( { type: 'food' } ).hint( { type: 1, name: 1 }).explain() This returns the statistics regarding the execution of the query. For -more information on the output of :method:`explain() -`, see :doc:`/reference/method/cursor.explain`. +more information on the output of :method:`~cursor.explain()`, see :doc:`/reference/method/cursor.explain`. .. note:: - If you run :method:`explain() ` without including - :method:`hint() `, the query optimizer reevaluates + If you run :method:`~cursor.explain()` without including + :method:`~cursor.hint()`, the query optimizer reevaluates the query and runs against multiple indexes before returning the query statistics. @@ -734,7 +729,7 @@ indexes at all. Consider the following situations: Cursors ------- -The :method:`find() ` method returns a +The :method:`~db.collection.find()` method returns a :term:`cursor` to the results; however, in the :program:`mongo` shell, if the returned cursor is not assigned to a variable, then the cursor is automatically iterated up to 20 times [#set-shell-batch-size]_ to print @@ -745,7 +740,7 @@ example: db.inventory.find( { type: 'food' } ); -When you assign the :method:`find() ` to a +When you assign the :method:`~db.collection.find()` to a variable: - you can call the cursor variable in the shell to iterate up to 20 @@ -758,7 +753,7 @@ variable: myCursor -- you can use the cursor method :method:`next() ` to +- you can use the cursor method :method:`~cursor.next()` to access the documents, as in the following example: .. code-block:: javascript @@ -781,7 +776,7 @@ variable: printjson(myItem); } -- you can use the cursor method :method:`forEach() ` +- you can use the cursor method :method:`~cursor.forEach()` to iterate the cursor and access the documents, as in the following example: @@ -879,7 +874,7 @@ Consider the following behaviors related to cursors: `. - As you iterate through the cursor and reach the end of the returned - batch, if there are more results, :method:`cursor.next()` will + batch, if there are more results, :method:`~cursor.next()` will perform a :data:`getmore operation ` to retrieve the next batch. @@ -967,7 +962,7 @@ series of steps by a sequence of :ref:`pipeline operators ` that manipulate and transform the documents until they're output at the end. The aggregation framework is accessible via the :dbcommand:`aggregate` -command or the :method:`db.collection.aggregate()` helper in the +command or the :method:`~db.collection.aggregate()` helper in the :program:`mongo` shell. For more information on the aggregation framework see @@ -978,9 +973,9 @@ operations for more basic data aggregation operations: - :dbcommand:`count` (:method:`~cursor.count()`) -- :dbcommand:`distinct` (:method:`db.collection.distinct()`) +- :dbcommand:`distinct` (:method:`~db.collection.distinct()`) -- :dbcommand:`group` (:method:`db.collection.group()`) +- :dbcommand:`group` (:method:`~db.collection.group()`) - :dbcommand:`mapReduce`. (Also consider :method:`~db.collection.mapReduce()` and diff --git a/source/core/read-preference.txt b/source/core/read-preference.txt index 553f918c438..dc5c68934ff 100644 --- a/source/core/read-preference.txt +++ b/source/core/read-preference.txt @@ -43,7 +43,7 @@ MongoDB :term:`drivers ` allow client applications to configure a :term:`read preference` on a per-connection, per-collection, or per-operation basis. For more information about secondary read operations in the :program:`mongo` shell, see the -:method:`~readPref()` method. For more information about a driver's +:method:`~cursor.readPref()` method. For more information about a driver's read preference configuration, see the appropriate :ref:`driver` API documentation. @@ -93,9 +93,8 @@ Read preference modes are also available to clients connecting to a connecting to the :term:`replica set` that provides each :term:`shard` in the cluster. -In the :program:`mongo` shell, the -:method:`readPref() ` cursor method -provides access to read preferences. +In the :program:`mongo` shell, the :method:`~cursor.readPref()` cursor +method provides access to read preferences. .. warning:: @@ -225,8 +224,8 @@ behavior `. See also the members evenly regardless of ping time, set secondaryAcceptableLatencyMS very high. -.. The :method:`readPreference() ` reference - above will error until DOCS-364 is complete. +.. The :method:`~cursor.readPref()` reference above will error until + DOCS-364 is complete. .. [#capacity-planning] If your set has more than one secondary, and you use the :readmode:`secondary` read preference mode, consider diff --git a/source/core/write-operations.txt b/source/core/write-operations.txt index c45957da938..db92761fdb6 100644 --- a/source/core/write-operations.txt +++ b/source/core/write-operations.txt @@ -34,11 +34,11 @@ database, see the following pages: For information on specific methods used to perform write operations in the :program:`mongo` shell, see the following: -- :method:`db.collection.insert()` -- :method:`db.collection.update()` -- :method:`db.collection.save()` -- :method:`db.collection.findAndModify()` -- :method:`db.collection.remove()` +- :method:`~db.collection.insert()` +- :method:`~db.collection.update()` +- :method:`~db.collection.save()` +- :method:`~db.collection.findAndModify()` +- :method:`~db.collection.remove()` For information on how to perform write operations from within an application, see the :doc:`/applications/drivers` documentation or the @@ -71,13 +71,13 @@ data into a MongoDB database. These *bulk inserts* have some special considerations that are different from other write operations. -The :method:`insert() ` method, when passed an -array of documents, will perform a bulk insert, and inserts each -document atomically. :doc:`Drivers ` -provide their own interface for this kind of operation. +The :method:`~db.collection.insert()` method, when passed an array +of documents, will perform a bulk insert, and inserts each document +atomically. :doc:`Drivers ` provide their own +interface for this kind of operation. .. versionadded:: 2.2 - :method:`insert() ` in the :program:`mongo` + :method:`~db.collection.insert()` in the :program:`mongo` shell gained support for bulk inserts in version 2.2. Bulk insert can significantly increase performance by amortizing @@ -207,7 +207,7 @@ and moves. but does not eliminate, document movements. To check the current :data:`~collStats.paddingFactor` on a collection, you can -run the :method:`db.collection.stats()` operation in the +run the :method:`~db.collection.stats()` operation in the :program:`mongo` shell, as in the following example: .. code-block:: javascript diff --git a/source/faq/developers.txt b/source/faq/developers.txt index 88515088ea9..e72204a19d5 100644 --- a/source/faq/developers.txt +++ b/source/faq/developers.txt @@ -73,7 +73,7 @@ If you remove a document, does MongoDB remove it from disk? Yes. -When you use :method:`db.collection.remove()`, the object will no longer +When you use :method:`~db.collection.remove()`, the object will no longer exist in MongoDB's on-disk data storage. When does MongoDB write updates to disk? @@ -307,7 +307,7 @@ All of the following MongoDB operations permit you to run arbitrary JavaScript expressions directly on the server: - :operator:`$where` -- :method:`db.eval()` +- :method:`~db.eval()` - :dbcommand:`mapReduce` - :dbcommand:`group` @@ -326,7 +326,7 @@ JavaScript code to the :operator:`$where` field. scope document, you can avoid evaluating them on the database server. -- If you need to use :method:`db.eval()` with user supplied values, you can +- If you need to use :method:`~db.eval()` with user supplied values, you can either use a ``CodeWScope`` or you can supply extra arguments to your function. For instance: @@ -373,7 +373,7 @@ the same time, ``my_object`` might be ``{ $where : "things" MongoDB client drivers, if properly implemented, check for reserved characters in keys on inserts. -- **Update**. The :method:`db.collection.update()` operation permits ``$`` operators +- **Update**. The :method:`~db.collection.update()` operation permits ``$`` operators in the update argument but does not support the :operator:`$where` operator. Still, some users may be able to inject operators that can manipulate a single @@ -549,7 +549,7 @@ exceptions: If your collection name includes special characters, such as the underscore character, then to access the collection use the -:method:`db.getCollection()` method or a :api:`similar method for your +:method:`~db.getCollection()` method or a :api:`similar method for your driver <>`. .. example:: To create a collection ``_foo`` and insert the @@ -573,33 +573,31 @@ How do I isolate cursors from intervening write operations? MongoDB cursors can return the same document more than once in some situations. [#duplicate-document-in-result-set]_ You can use the -:method:`snapshot() ` method on a cursor to isolate +:method:`~cursor.snapshot()` method on a cursor to isolate the operation for a very specific case. -:method:`snapshot() ` traverses the -index on the ``_id`` field and guarantees that the query will return -each document (with respect to the value of the ``_id`` field) no more -than once. [#id-is-immutable]_ +:method:`~cursor.snapshot()` traverses the index on the ``_id`` field +and guarantees that the query will return each document (with respect to +the value of the ``_id`` field) no more than once. [#id-is-immutable]_ -The :method:`snapshot() ` does not guarantee that -the data returned by the query will reflect a single moment in time -*nor* does it provide isolation from insert or delete operations. +The :method:`~cursor.snapshot()` does not guarantee that the data +returned by the query will reflect a single moment in time *nor* does it +provide isolation from insert or delete operations. .. warning:: - - You **cannot** use :method:`snapshot() ` with + - You **cannot** use :method:`~cursor.snapshot()` with :term:`sharded collections `. - - You **cannot** use :method:`snapshot() ` with - :method:`sort() ` or :method:`hint() - ` cursor methods. + - You **cannot** use :method:`~cursor.snapshot()` with + :method:`~cursor.sort()` or :method:`~cursor.hint()` cursor methods. As an alternative, if your collection has a field or fields that are never modified, you can use a *unique* index on this field or these -fields to achieve a similar result as the :method:`snapshot() -`. Query with :method:`hint() ` to -explicitly force the query to use that index. +fields to achieve a similar result as the :method:`~cursor.snapshot()`. +Query with :method:`~cursor.hint()` to explicitly force the query to use +that index. .. [#duplicate-document-in-result-set] As a cursor returns documents other operations may interleave with the query: if some of these diff --git a/source/faq/indexes.txt b/source/faq/indexes.txt index c2b85da03fa..0dcf5708351 100644 --- a/source/faq/indexes.txt +++ b/source/faq/indexes.txt @@ -22,24 +22,24 @@ No. You only need to create an index once for a single collection. After initial creation, MongoDB automatically updates the index as data changes. -While running :method:`ensureIndex() ` is -usually ok, if an index doesn't exist because of ongoing administrative -work, a call to :method:`ensureIndex() ` -may disrupt database availability. Running :method:`ensureIndex() -` can render a replica set inaccessible as -the index creation is happening. See :ref:`index-building-replica-sets`. +While running :method:`~db.collection.ensureIndex()` is usually ok, +if an index doesn't exist because of ongoing administrative work, a +call to :method:`~db.collection.ensureIndex()` may disrupt database +availability. Running :method:`~db.collection.ensureIndex()` can render +a replica set inaccessible as the index creation is happening. See +:ref:`index-building-replica-sets`. How do you know what indexes exist in a collection? --------------------------------------------------- To list a collection's indexes, use the -:method:`db.collection.getIndexes()` method or a similar -:api:`method for your driver <>`. +:method:`~db.collection.getIndexes()` method or a similar :api:`method +for your driver <>`. How do you determine the size of an index? ------------------------------------------ -To check the sizes of the indexes on a collection, use :method:`db.collection.stats()`. +To check the sizes of the indexes on a collection, use :method:`~db.collection.stats()`. .. todo:: FAQ How do I determine if an index fits into RAM? @@ -59,9 +59,9 @@ details, see :ref:`indexing-right-handed`. How do you know what index a query used? ---------------------------------------- -To inspect how MongoDB processes a query, use the :method:`explain() -` method in the :program:`mongo` shell, or in your -application driver. +To inspect how MongoDB processes a query, use the +:method:`~cursor.explain()` method in the :program:`mongo` shell, or in +your application driver. How do you determine what fields to index? ------------------------------------------ @@ -108,7 +108,7 @@ do one of the following: - Wait for the index to finish building. -- Kill the current operation (see :method:`db.killOp()`). The partial +- Kill the current operation (see :method:`~db.killOp()`). The partial index will be deleted. .. _faq-index-min-max: @@ -116,9 +116,9 @@ do one of the following: Can I use index keys to constrain query matches? ------------------------------------------------ -You can use the :method:`min() ` and :method:`max() -` methods to constrain the results of the cursor returned -from :method:`find() ` by using index keys. +You can use the :method:`~cursor.min()` and :method:`~cursor.max()` +methods to constrain the results of the cursor returned from +:method:`~db.collection.find()` by using index keys. Using ``$ne`` and ``$nin`` in a query is slow. Why? --------------------------------------------------- diff --git a/source/faq/storage.txt b/source/faq/storage.txt index 3b334191fb8..1cd0b389fe5 100644 --- a/source/faq/storage.txt +++ b/source/faq/storage.txt @@ -79,10 +79,10 @@ cache. In production, MongoDB will rarely encounter soft page faults. What tools can I use to investigate storage use in MongoDB? ----------------------------------------------------------- -The :method:`db.stats()` method in the :program:`mongo` shell, +The :method:`~db.stats()` method in the :program:`mongo` shell, returns the current state of the "active" database. The :doc:`dbStats command ` document describes -the fields in the :method:`db.stats()` output. +the fields in the :method:`~db.stats()` output. .. _faq-working-set: @@ -195,9 +195,9 @@ How can I check the size of a collection? ----------------------------------------- To view the size of a collection and other information, use the -:method:`stats() ` method from the -:program:`mongo` shell. The following example issues :method:`stats() -` for the ``orders`` collection: +:method:`~db.collection.stats()` method from the :program:`mongo` shell. +The following example issues :method:`~db.collection.stats()` for the +``orders`` collection: .. code-block:: javascript @@ -205,10 +205,10 @@ To view the size of a collection and other information, use the To view specific measures of size, use these methods: -- :method:`db.collection.dataSize()`: data size for the collection. -- :method:`db.collection.storageSize()`: allocation size, including unused space. -- :method:`db.collection.totalSize()`: the data size plus the index size. -- :method:`db.collection.totalIndexSize()`: the index size. +- :method:`~db.collection.dataSize()`: data size for the collection. +- :method:`~db.collection.storageSize()`: allocation size, including unused space. +- :method:`~db.collection.totalSize()`: the data size plus the index size. +- :method:`~db.collection.totalIndexSize()`: the index size. Also, the following scripts print the statistics for each database and collection: @@ -227,7 +227,7 @@ How can I check the size of indexes? To view the size of the data allocated for an index, use one of the following procedures in the :program:`mongo` shell: -- Use the :method:`stats() ` method using the +- Use the :method:`~db.collection.stats()` method using the index namespace. To retrieve a list of namespaces, issue the following command: @@ -236,7 +236,7 @@ following procedures in the :program:`mongo` shell: db.system.namespaces.find() - Check the value of :data:`~collStats.indexSizes` in the output of the - :method:`db.collection.stats()` command. + :method:`~db.collection.stats()` command. .. example:: Issue the following command to retrieve index namespaces: diff --git a/source/includes/fact-remove-capped-collection-restriction.rst b/source/includes/fact-remove-capped-collection-restriction.rst index 012c17eb62d..3c643f62188 100644 --- a/source/includes/fact-remove-capped-collection-restriction.rst +++ b/source/includes/fact-remove-capped-collection-restriction.rst @@ -1,2 +1,2 @@ -You cannot use the :method:`remove() ` method +You cannot use the :method:`~db.collection.remove()` method with a :term:`capped collection`. diff --git a/source/includes/table-lock-behavior-per-operation.yaml b/source/includes/table-lock-behavior-per-operation.yaml index afda836b5d3..3867597fffe 100644 --- a/source/includes/table-lock-behavior-per-operation.yaml +++ b/source/includes/table-lock-behavior-per-operation.yaml @@ -38,15 +38,15 @@ op7: Create an index lock7: | Building an index in the foreground, which is the default, locks the database for extended periods of time. -op8: :method:`db.eval()` +op8: :method:`~db.eval()` lock8: | - Write lock. :method:`db.eval()` blocks all other JavaScript + Write lock. :method:`~db.eval()` blocks all other JavaScript processes. op9: :dbcommand:`eval` lock9: | Write lock. If used with the ``nolock`` lock option, the :dbcommand:`eval` option does not take a write lock and cannot write data to the database. -op10: :method:`aggregate() ` +op10: :method:`~db.collection.aggregate()` lock10: Read lock -... \ No newline at end of file +... diff --git a/source/includes/table-sql-to-mongo-delete-examples.yaml b/source/includes/table-sql-to-mongo-delete-examples.yaml index 72364df9ee7..74a1da7d5fc 100644 --- a/source/includes/table-sql-to-mongo-delete-examples.yaml +++ b/source/includes/table-sql-to-mongo-delete-examples.yaml @@ -24,7 +24,7 @@ mongo1: | db.users.remove( { status: "D" } ) ref1: | - See :method:`remove() ` + See :method:`~db.collection.remove()` for more information. sql2: | .. code-block:: sql @@ -35,4 +35,4 @@ mongo2: | :emphasize-lines: 1 db.users.remove( ) -... \ No newline at end of file +... diff --git a/source/includes/table-sql-to-mongo-insert-examples.yaml b/source/includes/table-sql-to-mongo-insert-examples.yaml index 2dd3e7fd870..4160546578e 100644 --- a/source/includes/table-sql-to-mongo-insert-examples.yaml +++ b/source/includes/table-sql-to-mongo-insert-examples.yaml @@ -31,5 +31,5 @@ mongo1: | status: "A" } ) ref1: | - See :method:`insert() ` for more information. -... \ No newline at end of file + See :method:`~db.collection.insert()` for more information. +... diff --git a/source/includes/table-sql-to-mongo-schema-examples.yaml b/source/includes/table-sql-to-mongo-schema-examples.yaml index 5c08ecdce6a..0939078d387 100644 --- a/source/includes/table-sql-to-mongo-schema-examples.yaml +++ b/source/includes/table-sql-to-mongo-schema-examples.yaml @@ -29,8 +29,7 @@ sql1: | PRIMARY KEY (id) ) mongo1: | - Implicitly created on first :method:`insert - ` operation. The primary key ``_id`` + Implicitly created on first :method:`~db.collection.insert()` operation. The primary key ``_id`` is automatically added if ``_id`` field is not specified. .. code-block:: javascript @@ -50,8 +49,8 @@ mongo1: | db.createCollection("users") ref1: | See - :method:`insert() ` and - :method:`createCollection() ` + :method:`~db.collection.insert()` and + :method:`~db.createCollection()` for more information. sql2: | .. code-block:: sql @@ -63,8 +62,7 @@ mongo2: | documents; i.e. there is no structural alteration at the collection level. - However, at the document level, :method:`update() - ` operations can add fields to existing + However, at the document level, :method:`~db.collection.update()` operations can add fields to existing documents using the :operator:`$set` operator. .. code-block:: javascript @@ -76,8 +74,7 @@ mongo2: | { multi: true } ) ref2: | - See the :doc:`/core/data-modeling`, :method:`update() - `, and :operator:`$set` for more + See the :doc:`/core/data-modeling`, :method:`~db.collection.update()`, and :operator:`$set` for more information on changing the structure of documents in a collection. sql3: | @@ -90,8 +87,7 @@ mongo3: | documents; i.e. there is no structural alteration at the collection level. - However, at the document level, :method:`update() - ` operations can remove fields from + However, at the document level, :method:`~db.collection.update()` operations can remove fields from documents using the :operator:`$unset` operator. .. code-block:: javascript @@ -103,8 +99,7 @@ mongo3: | { multi: true } ) ref3: | - See :doc:`/core/data-modeling`, :method:`update() - `, and :operator:`$unset` for more + See :doc:`/core/data-modeling`, :method:`~db.collection.update()`, and :operator:`$unset` for more information on changing the structure of documents in a collection. sql4: | @@ -118,7 +113,7 @@ mongo4: | db.users.ensureIndex( { user_id: 1 } ) ref4: | - See :method:`ensureIndex() ` + See :method:`~db.collection.ensureIndex()` and :doc:`indexes ` for more information. sql5: | .. code-block:: sql @@ -141,6 +136,6 @@ mongo6: | db.users.drop() ref6: | - See :method:`drop() ` for + See :method:`~db.collection.drop()` for more information. ... diff --git a/source/includes/table-sql-to-mongo-select-examples.yaml b/source/includes/table-sql-to-mongo-select-examples.yaml index c8d44ac2500..c931b68cd67 100644 --- a/source/includes/table-sql-to-mongo-select-examples.yaml +++ b/source/includes/table-sql-to-mongo-select-examples.yaml @@ -44,7 +44,7 @@ mongo1: | db.users.find() ref1: | - See :method:`find() ` + See :method:`~db.collection.find()` for more information. sql2: | .. code-block:: sql @@ -113,7 +113,7 @@ mongo6: | { status: { $ne: "A" } } ) ref6: | - See :method:`find() ` + See :method:`~db.collection.find()` and :operator:`$ne` for more information. sql7: | .. code-block:: sql @@ -131,7 +131,7 @@ mongo7: | age: 50 } ) ref7: | - See :method:`find() ` + See :method:`~db.collection.find()` and :operator:`$and` for more information. sql8: | .. code-block:: sql @@ -149,7 +149,7 @@ mongo8: | { age: 50 } ] } ) ref8: | - See :method:`find() ` + See :method:`~db.collection.find()` and :operator:`$or` for more information. sql9: | .. code-block:: sql @@ -165,7 +165,7 @@ mongo9: | { age: { $gt: 25 } } ) ref9: | - See :method:`find() ` + See :method:`~db.collection.find()` and :operator:`$gt` for more information. sql10: | .. code-block:: sql @@ -181,7 +181,7 @@ mongo10: | { age: { $lt: 25 } } ) ref10: | - See :method:`find() ` + See :method:`~db.collection.find()` and :operator:`$lt` for more information. sql11: | .. code-block:: sql @@ -198,7 +198,7 @@ mongo11: | { age: { $gt: 25, $lte: 50 } } ) ref11: | - See :method:`find() `, + See :method:`~db.collection.find()`, :operator:`$gt`, and :operator:`$lte` for more information. sql12: | @@ -215,7 +215,7 @@ mongo12: | { user_id: /bc/ } ) ref12: | - See :method:`find() ` + See :method:`~db.collection.find()` and :operator:`$regex` for more information. sql13: | @@ -244,8 +244,8 @@ mongo14: | db.users.find( { status: "A" } ).sort( { user_id: 1 } ) ref14: | - See :method:`find() ` - and :method:`sort() ` + See :method:`~db.collection.find()` + and :method:`~cursor.sort()` for more information. sql15: | .. code-block:: sql @@ -277,8 +277,8 @@ mongo16: | db.users.find().count() ref16: | - See :method:`find() ` - and :method:`count() ` for + See :method:`~db.collection.find()` + and :method:`~cursor.count()` for more information. sql17: | .. code-block:: sql @@ -298,8 +298,8 @@ mongo17: | db.users.find( { user_id: { $exists: true } } ).count() ref17: | - See :method:`find() `, - :method:`count() `, and + See :method:`~db.collection.find()`, + :method:`~cursor.count()`, and :operator:`$exists` for more information. sql18: | .. code-block:: sql @@ -320,8 +320,8 @@ mongo18: | db.users.find( { age: { $gt: 30 } } ).count() ref18: | - See :method:`find() `, - :method:`count() `, and + See :method:`~db.collection.find()`, + :method:`~cursor.count()`, and :operator:`$gt` for more information. sql19: | .. code-block:: sql @@ -334,8 +334,8 @@ mongo19: | db.users.distinct( "status" ) ref19: | - See :method:`find() ` - and :method:`distinct() ` + See :method:`~db.collection.find()` + and :method:`~db.collection.distinct()` for more information. sql20: | .. code-block:: sql @@ -356,9 +356,9 @@ mongo20: | db.users.find().limit(1) ref20: | - See :method:`find() `, - :method:`findOne() `, - and :method:`limit() ` + See :method:`~db.collection.find()`, + :method:`~db.collection.findOne()`, + and :method:`~cursor.limit()` for more information. sql21: | .. code-block:: sql @@ -373,9 +373,9 @@ mongo21: | db.users.find().limit(5).skip(10) ref21: | - See :method:`find() `, - :method:`limit() `, and - :method:`skip() ` for + See :method:`~db.collection.find()`, + :method:`~cursor.limit()`, and + :method:`~cursor.skip()` for more information. sql22: | .. code-block:: sql @@ -389,7 +389,7 @@ mongo22: | db.users.find( { status: "A" } ).explain() ref22: | - See :method:`find() ` - and :method:`explain() ` + See :method:`~db.collection.find()` + and :method:`~cursor.explain()` for more information. ... diff --git a/source/includes/table-sql-to-mongo-update-examples.yaml b/source/includes/table-sql-to-mongo-update-examples.yaml index 602d37b0e25..6dd58d4f009 100644 --- a/source/includes/table-sql-to-mongo-update-examples.yaml +++ b/source/includes/table-sql-to-mongo-update-examples.yaml @@ -30,7 +30,7 @@ mongo1: | { multi: true } ) ref1: | - See :method:`update() `, + See :method:`~db.collection.update()`, :operator:`$gt`, and :operator:`$set` for more information. sql2: | @@ -50,7 +50,7 @@ mongo2: | { multi: true } ) ref2: | - See :method:`update() `, + See :method:`~db.collection.update()`, :operator:`$inc`, and :operator:`$set` for more information. -... \ No newline at end of file +... diff --git a/source/reference/command/findAndModify.txt b/source/reference/command/findAndModify.txt index de24ee5a3a1..5da6589d87a 100644 --- a/source/reference/command/findAndModify.txt +++ b/source/reference/command/findAndModify.txt @@ -43,7 +43,7 @@ findAndModify Optional. Specifies the selection criteria for the modification. The ``query`` field employs the same :ref:`query selectors ` as used in the - :method:`db.collection.find()` method. Although the query may + :method:`~db.collection.find()` method. Although the query may match multiple documents, :dbcommand:`findAndModify` will only select one document to modify. @@ -417,4 +417,4 @@ findAndModify This command obtains a write lock on the affected database and will block other operations until it has completed; however, typically the write lock is short lived and equivalent to other - similar :method:`update() ` operations. + similar :method:`~db.collection.update()` operations. diff --git a/source/reference/database-profiler.txt b/source/reference/database-profiler.txt index e563df3f497..46dd3f177cd 100644 --- a/source/reference/database-profiler.txt +++ b/source/reference/database-profiler.txt @@ -133,14 +133,14 @@ operation. If the :data:`~system.profile.ntoreturn` value is ``0``, the command did not specify a number of documents to return, as would be the case with a simple - :method:`find() ` command with no limit + :method:`~db.collection.find()` command with no limit specified. .. data:: system.profile.ntoskip .. versionadded:: 2.2 - The number of documents the :method:`skip() ` method + The number of documents the :method:`~cursor.skip()` method specified to skip. .. data:: system.profile.nscanned @@ -246,7 +246,7 @@ operation. The IP address or hostname of the client connection where the operation originates. - For some operations, such as :method:`db.eval()`, the client is + For some operations, such as :method:`~db.eval()`, the client is ``0.0.0.0:0`` instead of an actual client. .. data:: system.profile.user diff --git a/source/reference/glossary.txt b/source/reference/glossary.txt index f4f47f68063..87530cc2ce1 100644 --- a/source/reference/glossary.txt +++ b/source/reference/glossary.txt @@ -502,7 +502,7 @@ Glossary padding The extra space allocated to document on the disk to prevent moving a document when it grows as the result of - :method:`update() ` + :method:`~db.collection.update()` operations. See :ref:`write-operations-padding-factor`. padding factor @@ -836,7 +836,7 @@ Glossary An operation that will either update the first document matched by a query or insert a new document if none matches. The new document will have the fields implied by the operation. You perform upserts - with the :method:`update ` operation. See + with the :method:`~db.collection.update()` operation. See :ref:`upsert-parameter`. virtual memory diff --git a/source/reference/method/Mongo.getReadPrefMode.txt b/source/reference/method/Mongo.getReadPrefMode.txt index 5a6b30c0a42..cef59b119e1 100644 --- a/source/reference/method/Mongo.getReadPrefMode.txt +++ b/source/reference/method/Mongo.getReadPrefMode.txt @@ -35,5 +35,5 @@ Mongo.getReadPrefMode() - :readmode:`nearest` .. seealso:: :doc:`/core/read-preference`, - :method:`cursor.readPref()`, :method:`Mongo.setReadPref()`, and - :method:`Mongo.getReadPrefTagSet()`. + :method:`~cursor.readPref()`, :method:`~Mongo.setReadPref()`, and + :method:`~Mongo.getReadPrefTagSet()`. diff --git a/source/reference/method/Mongo.getReadPrefTagSet.txt b/source/reference/method/Mongo.getReadPrefTagSet.txt index fe5dee33070..76cef7779eb 100644 --- a/source/reference/method/Mongo.getReadPrefTagSet.txt +++ b/source/reference/method/Mongo.getReadPrefTagSet.txt @@ -26,5 +26,5 @@ Mongo.getReadPrefTagSet() printjson(db.getMongo().getReadPrefTagSet()); .. seealso:: :doc:`/core/read-preference`, - :method:`cursor.readPref()`, :method:`Mongo.setReadPref()`, and - :method:`Mongo.getReadPrefTagSet()`. + :method:`~cursor.readPref()`, :method:`~Mongo.setReadPref()`, and + :method:`~Mongo.getReadPrefTagSet()`. diff --git a/source/reference/method/Mongo.setSlaveOk.txt b/source/reference/method/Mongo.setSlaveOk.txt index d1cbf418ad2..3ea14c87c5e 100644 --- a/source/reference/method/Mongo.setSlaveOk.txt +++ b/source/reference/method/Mongo.setSlaveOk.txt @@ -17,8 +17,8 @@ mongo.setSlaveOk() Indicates that ":term:`eventually consistent `" read operations are acceptable for the current application. This function provides the same functionality as - :method:`rs.slaveOk()`. + :method:`~rs.slaveOk()`. - See the :method:`readPref() ` method for more + See the :method:`~cursor.readPref()` method for more fine-grained control over :doc:`read preference ` in the :program:`mongo` shell. diff --git a/source/reference/method/cursor.explain.txt b/source/reference/method/cursor.explain.txt index 409ce5fb900..931ff860876 100644 --- a/source/reference/method/cursor.explain.txt +++ b/source/reference/method/cursor.explain.txt @@ -31,42 +31,41 @@ Definition The :method:`~cursor.explain()` method runs the actual query to determine the result. Although there are some differences between - running the query with :method:`explain ` and + running the query with :method:`~cursor.explain()` and running without, generally, the performance will be similar between - the two. So, if the query is slow, the :method:`explain - ` operation is also slow. + the two. So, if the query is slow, the :method:`~cursor.explain()` operation is also slow. - Additionally, the :method:`explain ` operation reevaluates a set - of candidate query plans, which may cause the :method:`explain ` + Additionally, the :method:`~cursor.explain()` operation reevaluates a set + of candidate query plans, which may cause the :method:`~cursor.explain()` operation to perform differently than a normal query. As a result, these operations generally provide an accurate account of *how* MongoDB would perform the query, but do not reflect the length of these queries. To determine the performance of a particular index, you can use - :method:`hint() ` and in conjunction with - :method:`explain() `, as in the following example: + :method:`~cursor.hint()` and in conjunction with + :method:`~cursor.explain()`, as in the following example: .. code-block:: javascript db.products.find().hint( { type: 1 } ).explain() - When you run :method:`explain ` with - :method:`hint() `, the query optimizer does not + When you run :method:`~cursor.explain()` with + :method:`~cursor.hint()`, the query optimizer does not reevaluate the query plans. .. note:: - In some situations, the :method:`explain() ` + In some situations, the :method:`~cursor.explain()` operation may differ from the actual query plan used by MongoDB in a normal query. - The :method:`explain() ` operation evaluates + The :method:`~cursor.explain()` operation evaluates the set of query plans and reports on the winning plan for the query. In normal operations the query optimizer caches winning query plans and uses them for similar related queries in the future. As a result MongoDB may sometimes select query plans from the cache that are different from the plan displayed using - :method:`explain `. + :method:`~cursor.explain()`. .. seealso:: @@ -129,7 +128,7 @@ Explain on ``$or`` Queries Queries with :operator:`$or` operator execute each clause of the :operator:`$or` expression in parallel and can use separate indexes on the individual clauses. If the query uses indexes on any or all of the -query's clause, :method:`explain() ` contains +query's clause, :method:`~cursor.explain()` contains :ref:`output ` for each clause as well as the cumulative data for the entire query: @@ -342,8 +341,7 @@ sharded*. For queries on sharded collections, see :data:`~explain.allPlans` is an array that holds the list of plans the query optimizer runs in order to select the index for the query. - Displays only when the ```` parameter to :method:`explain() - ` is ``true`` or ``1``. + Displays only when the ```` parameter to :method:`~cursor.explain()` is ``true`` or ``1``. .. data:: explain.oldPlan @@ -351,8 +349,7 @@ sharded*. For queries on sharded collections, see :data:`~explain.oldPlan` is a document value that contains the previous plan selected by the query optimizer for the query. Displays only when - the ```` parameter to :method:`explain() - ` is ``true`` or ``1``. + the ```` parameter to :method:`~cursor.explain()` is ``true`` or ``1``. .. data:: explain.server diff --git a/source/reference/method/cursor.limit.txt b/source/reference/method/cursor.limit.txt index 2f0671eaaf2..d33ce305266 100644 --- a/source/reference/method/cursor.limit.txt +++ b/source/reference/method/cursor.limit.txt @@ -6,17 +6,17 @@ cursor.limit() .. method:: cursor.limit() - Use the :method:`cursor.limit()` method on a cursor to specify the maximum - number of documents the cursor will return. :method:`cursor.limit()` is + Use the :method:`~cursor.limit()` method on a cursor to specify the maximum + number of documents the cursor will return. :method:`~cursor.limit()` is analogous to the ``LIMIT`` statement in a SQL database. .. note:: - You must apply :method:`cursor.limit()` to the cursor before + You must apply :method:`~cursor.limit()` to the cursor before retrieving any documents from the database. - Use :method:`cursor.limit()` to maximize performance and prevent + Use :method:`~cursor.limit()` to maximize performance and prevent MongoDB from returning more results than required for processing. - A :method:`cursor.limit()` value of 0 (e.g. ":method:`.limit(0) `") + A :method:`~cursor.limit()` value of 0 (e.g. ":method:`.limit(0) `") is equivalent to setting no limit. diff --git a/source/reference/method/cursor.max.txt b/source/reference/method/cursor.max.txt index f4632d85be9..5bbd0d75783 100644 --- a/source/reference/method/cursor.max.txt +++ b/source/reference/method/cursor.max.txt @@ -39,7 +39,7 @@ Definition Behavior -------- -- Because :method:`max() ` requires an index on a field, +- Because :method:`~cursor.max()` requires an index on a field, and forces the query to use this index, you may prefer the :operator:`$lt` operator for the query if possible. Consider the following example: @@ -89,7 +89,7 @@ The collection has the following indexes: { "price" : 1 } - Using the ordering of ``{ item: 1, type: 1 }`` index, - :method:`max() ` limits the query to the documents + :method:`~cursor.max()` limits the query to the documents that are below the bound of ``item`` equal to ``apple`` and ``type`` equal to ``jonagold``: @@ -106,14 +106,13 @@ The collection has the following indexes: { "_id" : 1, "item" : "apple", "type" : "honey crisp", "price" : 1.99 } If the query did not explicitly specify the index with the - :method:`hint() ` method, it is ambiguous as to + :method:`~cursor.hint()` method, it is ambiguous as to whether :program:`mongod` would select the ``{ item: 1, type: 1 }`` index ordering or the ``{ item: 1, type: -1 }`` index ordering. -- Using the ordering of the index ``{ price: 1 }``, :method:`max() - ` limits the query to the documents that are below +- Using the ordering of the index ``{ price: 1 }``, :method:`~cursor.max()` limits the query to the documents that are below the index key bound of ``price`` equal to ``1.99`` and - :method:`min() ` limits the query to the documents + :method:`~cursor.min()` limits the query to the documents that are at or above the index key bound of ``price`` equal to ``1.39``: diff --git a/source/reference/method/cursor.min.txt b/source/reference/method/cursor.min.txt index 1d7c634abfc..a234511be33 100644 --- a/source/reference/method/cursor.min.txt +++ b/source/reference/method/cursor.min.txt @@ -57,7 +57,7 @@ Behaviors - If you use :method:`~cursor.min()` with :method:`~cursor.max()` to specify a range, the index bounds specified in - :method:`~cursor.min()` and :method:`!cursor.max()` must both refer + :method:`~cursor.min()` and :method:`~cursor.max()` must both refer to the keys of the same index. Example @@ -110,14 +110,13 @@ The collection has the following indexes: { "_id" : 8, "item" : "orange", "type" : "valencia", "price" : 0.99 } If the query did not explicitly specify the index with the - :method:`hint() ` method, it is ambiguous as to + :method:`~cursor.hint()` method, it is ambiguous as to whether :program:`mongod` would select the ``{ item: 1, type: 1 }`` index ordering or the ``{ item: 1, type: -1 }`` index ordering. -- Using the ordering of the index ``{ price: 1 }``, :method:`min() - ` limits the query to the documents that are at or +- Using the ordering of the index ``{ price: 1 }``, :method:`~cursor.min()` limits the query to the documents that are at or above the index key bound of ``price`` equal to ``1.39`` and - :method:`max() ` limits the query to the documents + :method:`~cursor.max()` limits the query to the documents that are below the index key bound of ``price`` equal to ``1.99``: .. code-block:: javascript diff --git a/source/reference/method/cursor.readPref.txt b/source/reference/method/cursor.readPref.txt index d5b8bd3e635..655c8979d86 100644 --- a/source/reference/method/cursor.readPref.txt +++ b/source/reference/method/cursor.readPref.txt @@ -9,7 +9,7 @@ Definition .. method:: cursor.readPref(mode, tagSet) - Append :method:`readPref() ` to a cursor to + Append :method:`~cursor.readPref()` to a cursor to control how the client routes the query to members of the replica set. @@ -17,5 +17,5 @@ Definition .. note:: - You must apply :method:`cursor.readPref()` to the cursor before retrieving + You must apply :method:`~cursor.readPref()` to the cursor before retrieving any documents from the database. diff --git a/source/reference/method/cursor.snapshot.txt b/source/reference/method/cursor.snapshot.txt index 7ca002327e0..2ffad09e3e7 100644 --- a/source/reference/method/cursor.snapshot.txt +++ b/source/reference/method/cursor.snapshot.txt @@ -6,26 +6,25 @@ cursor.snapshot() .. method:: cursor.snapshot() - Append the :method:`cursor.snapshot()` method to a cursor to toggle + Append the :method:`~cursor.snapshot()` method to a cursor to toggle the "snapshot" mode. This ensures that the query will not return a document multiple times, even if intervening write operations result in a move of the document due to the growth in document size. .. warning:: - - You must apply :method:`cursor.snapshot()` to the cursor before + - You must apply :method:`~cursor.snapshot()` to the cursor before retrieving any documents from the database. - - You can only use :method:`snapshot() ` with + - You can only use :method:`~cursor.snapshot()` with **unsharded** collections. - The :method:`snapshot() ` does not guarantee + The :method:`~cursor.snapshot()` does not guarantee isolation from insertion or deletions. - The :method:`cursor.snapshot()` traverses the index on the ``_id`` - field. As such, :method:`snapshot() ` **cannot** - be used with :method:`sort() ` or :method:`hint() - `. + The :method:`~cursor.snapshot()` traverses the index on the ``_id`` + field. As such, :method:`~cursor.snapshot()` **cannot** + be used with :method:`~cursor.sort()` or :method:`~cursor.hint()`. diff --git a/source/reference/method/cursor.sort.txt b/source/reference/method/cursor.sort.txt index ccbabe2c970..7fe1be3d6f8 100644 --- a/source/reference/method/cursor.sort.txt +++ b/source/reference/method/cursor.sort.txt @@ -11,18 +11,17 @@ Definition Controls the order that the query returns matching documents. For each field in the sort document, if the field's corresponding value - is positive, then :method:`sort() ` returns query + is positive, then :method:`~cursor.sort()` returns query results in ascending order for that attribute. If the field's - corresponding value is negative, then :method:`sort() - ` returns query results in descending order. + corresponding value is negative, then :method:`~cursor.sort()` returns query results in descending order. - The :method:`sort() ` method has the following parameter: + The :method:`~cursor.sort()` method has the following parameter: .. include:: /reference/method/cursor.sort-param.rst .. note:: - You must apply :method:`cursor.limit()` to the cursor before + You must apply :method:`~cursor.limit()` to the cursor before retrieving any documents from the database. .. todo: verify "must," seems a bit strong. @@ -45,9 +44,9 @@ Limit Results ------------- Unless you have an index for the specified key pattern, use -:method:`cursor.sort()` in conjunction with :method:`cursor.limit()` to avoid +:method:`~cursor.sort()` in conjunction with :method:`~cursor.limit()` to avoid requiring MongoDB to perform a large, in-memory -sort. :method:`cursor.limit()` increases the speed and reduces the amount +sort. :method:`~cursor.limit()` increases the speed and reduces the amount of memory required to return this query by way of an optimized algorithm. @@ -56,7 +55,7 @@ algorithm. The sort function requires that the entire sort be able to complete within 32 megabytes. When the sort option consumes more than 32 megabytes, MongoDB will return an error. Use - :method:`cursor.limit()`, or create an index on the field that you're + :method:`~cursor.limit()`, or create an index on the field that you're sorting to avoid this error. Return Natural Order diff --git a/source/reference/method/db.collection.ensureIndex.txt b/source/reference/method/db.collection.ensureIndex.txt index d60fdfc449d..ebb92c05667 100644 --- a/source/reference/method/db.collection.ensureIndex.txt +++ b/source/reference/method/db.collection.ensureIndex.txt @@ -12,13 +12,13 @@ Definition Creates an index on the specified field if the index does not already exist. - The :method:`db.collection.ensureIndex()` method has the following fields: + The :method:`~db.collection.ensureIndex()` method has the following fields: .. include:: /reference/method/db.collection.ensureIndex-param.rst .. warning:: Index names, including their full namespace (i.e. ``database.collection``) cannot be longer than 128 - characters. See the :method:`db.collection.getIndexes()` field + characters. See the :method:`~db.collection.getIndexes()` field :data:`~system.indexes.name` for the names of existing indexes. The ``options`` document has one or more of the following fields: @@ -39,7 +39,7 @@ The following example creates an ascending index on the field db.collection.ensureIndex( { orderDate: 1 } ) If the ``keys`` document specifies more than one field, then -:method:`db.collection.ensureIndex()` creates a :term:`compound +:method:`~db.collection.ensureIndex()` creates a :term:`compound index`. Create an Index on a Multiple Fields @@ -59,7 +59,7 @@ component. .. note:: The order of an index is important for supporting - :method:`cursor.sort()` operations using the index. + :method:`~cursor.sort()` operations using the index. .. seealso:: @@ -87,7 +87,7 @@ described here. :method:`~db.collection.ensureIndex()` will *not* rebuild the existing index with the new options. -- If you call multiple :method:`ensureIndex() ` +- If you call multiple :method:`~db.collection.ensureIndex()` methods with the same index specification at the same time, only the first operation will succeed, all other operations will have no effect. diff --git a/source/reference/method/db.collection.find.txt b/source/reference/method/db.collection.find.txt index f34d597f561..aad2aadcab7 100644 --- a/source/reference/method/db.collection.find.txt +++ b/source/reference/method/db.collection.find.txt @@ -35,7 +35,7 @@ Examples Select All Documents in a Collection ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Call the :method:`find() ` method with no +Call the :method:`~db.collection.find()` method with no parameters: .. code-block:: javascript @@ -51,7 +51,7 @@ mechanism for your specific language driver. Select Documents that Match a Selection Criteria ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Call the :method:`find() ` method with a ``criteria``: +Call the :method:`~db.collection.find()` method with a ``criteria``: .. code-block:: javascript @@ -69,8 +69,7 @@ Prototype Projection Document The ``boolean`` can take the following include or exclude values: -- ``1`` or ``true`` to include. The :method:`find() - ` method always includes the :term:`_id` field +- ``1`` or ``true`` to include. The :method:`~db.collection.find()` method always includes the :term:`_id` field even if the field is not explicitly stated to return in the :term:`projection` parameter. @@ -92,7 +91,7 @@ and returns, or *projects*, only certain fields into the result set: This returns all the documents from the collection ``products`` where ``qty`` is greater than ``25``. The documents in the result set only include the ``_id``, ``item``, and ``qty`` fields using "inclusion" -projection. :method:`find() ` always returns the +projection. :method:`~db.collection.find()` always returns the ``_id`` field, even when not explicitly included: .. code-block:: javascript diff --git a/source/reference/method/db.collection.getIndexStats.txt b/source/reference/method/db.collection.getIndexStats.txt index d0108d4b317..a3127f7d60b 100644 --- a/source/reference/method/db.collection.getIndexStats.txt +++ b/source/reference/method/db.collection.getIndexStats.txt @@ -13,7 +13,7 @@ Definition index's B-tree data structure. The information summarizes the output returned by the :dbcommand:`indexStats` command and :method:`~db.collection.indexStats()` method. The - :method:`getIndexStats ` method + :method:`~db.collection.getIndexStats()` method displays the information on the screen and does not return an object. The :method:`~db.collection.getIndexStats()` method has the @@ -31,7 +31,7 @@ Definition ` option. To view :ref:`index names ` for a collection, use the - :method:`getIndexes() ` method. + :method:`~db.collection.getIndexes()` method. .. warning:: Do not use :method:`~db.collection.getIndexStats()` or :dbcommand:`indexStats` with production deployments. diff --git a/source/reference/method/db.collection.insert.txt b/source/reference/method/db.collection.insert.txt index d65b178b466..e32eb718b94 100644 --- a/source/reference/method/db.collection.insert.txt +++ b/source/reference/method/db.collection.insert.txt @@ -12,17 +12,16 @@ Definition Inserts a document or an array of documents into a collection. .. versionchanged:: 2.2 - The :method:`insert() ` method can accept + The :method:`~db.collection.insert()` method can accept an array of documents to perform a bulk insert of the documents into the collection. .. include:: /reference/method/db.collection.insert-param.rst - The :method:`insert() ` method has the + The :method:`~db.collection.insert()` method has the following behaviors: - - If the collection does not exist, then the :method:`insert() - ` method will create the collection. + - If the collection does not exist, then the :method:`~db.collection.insert()` method will create the collection. - If the document does not specify an :term:`_id` field, then MongoDB will add the ``_id`` field and assign a unique :term:`ObjectId` for @@ -30,20 +29,18 @@ Definition insert the ``_id`` field, but the :program:`mongod` will create and populate the ``_id`` if the driver or application does not. - - If the document specifies a new field, then the :method:`insert() - ` method inserts the document with the new + - If the document specifies a new field, then the :method:`~db.collection.insert()` method inserts the document with the new field. This requires no changes to the data model for the collection or the existing documents. Examples -------- -The following are examples of the :method:`insert() -` method: +The following are examples of the :method:`~db.collection.insert()` method: - To insert a single document and have MongoDB generate the unique ``_id``, omit the ``_id`` field in the document and pass the document - to the :method:`insert() ` method as in the + to the :method:`~db.collection.insert()` method as in the following: .. code-block:: javascript @@ -62,7 +59,7 @@ The following are examples of the :method:`insert() - To insert a single document, with a custom ``_id`` field, include the ``_id`` field set to a unique identifier and pass the document to the - :method:`insert() ` method as follows: + :method:`~db.collection.insert()` method as follows: .. code-block:: javascript @@ -79,7 +76,7 @@ The following are examples of the :method:`insert() .. include:: /includes/note-insert-id-field.rst - To insert multiple documents, pass an array of documents to the - :method:`insert() ` method as in the + :method:`~db.collection.insert()` method as in the following: .. code-block:: javascript diff --git a/source/reference/method/db.collection.remove.txt b/source/reference/method/db.collection.remove.txt index 11ad0d0f253..7a7928b1fa2 100644 --- a/source/reference/method/db.collection.remove.txt +++ b/source/reference/method/db.collection.remove.txt @@ -19,11 +19,9 @@ Definition Examples -------- -The following are examples of the :method:`remove -` method. +The following are examples of the :method:`~db.collection.remove()` method. -- To remove all documents in a collection, call the :method:`remove - ` method with no parameters: +- To remove all documents in a collection, call the :method:`~db.collection.remove()` method with no parameters: .. code-block:: javascript @@ -33,7 +31,7 @@ The following are examples of the :method:`remove ``products``. - To remove the documents that match a deletion criteria, call the - :method:`remove ` method with the ``query`` + :method:`~db.collection.remove()` method with the ``query`` criteria: .. code-block:: javascript @@ -44,7 +42,7 @@ The following are examples of the :method:`remove ``products`` where ``qty`` is greater than ``20``. - To remove the first document that match a deletion criteria, call the - :method:`remove ` method with the ``query`` + :method:`~db.collection.remove()` method with the ``query`` criteria and the ``justOne`` parameter set to ``true`` or ``1``: .. code-block:: javascript @@ -56,8 +54,7 @@ The following are examples of the :method:`remove .. note:: - If the ``query`` argument to the :method:`remove() - ` method matches multiple documents in the + If the ``query`` argument to the :method:`~db.collection.remove()` method matches multiple documents in the collection, the delete operation may interleave with other write operations to that collection. For an unsharded collection, you have the option to override this behavior with the :operator:`$isolated` diff --git a/source/reference/method/db.collection.update.txt b/source/reference/method/db.collection.update.txt index b190764c85d..878f3f7a748 100644 --- a/source/reference/method/db.collection.update.txt +++ b/source/reference/method/db.collection.update.txt @@ -33,7 +33,7 @@ Definition db.collection.update(query, update, , ) Although the update operation may apply mostly to updating the values - of the fields, :method:`update() ` can also + of the fields, :method:`~db.collection.update()` can also modify the name of the ``field`` in a document using the :operator:`$rename` operator. @@ -123,8 +123,7 @@ Replace All Fields in a Document ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ To replace all the fields in a document with the document as -specified in the ``update`` parameter, call the :method:`update() -` method with an ``update`` parameter +specified in the ``update`` parameter, call the :method:`~db.collection.update()` method with an ``update`` parameter that consists of *only* ``key: value`` expressions, as in the following: .. code-block:: javascript @@ -140,7 +139,7 @@ except the :term:`_id` field. Update Multiple Documents ~~~~~~~~~~~~~~~~~~~~~~~~~ -Call the :method:`update() ` method and specify +Call the :method:`~db.collection.update()` method and specify the ``multi`` option, as in the following: .. code-block:: javascript diff --git a/source/reference/mongo-shell.txt b/source/reference/mongo-shell.txt index 49b9e0dc1ab..654cdb45640 100644 --- a/source/reference/mongo-shell.txt +++ b/source/reference/mongo-shell.txt @@ -119,7 +119,7 @@ The following table displays some common JavaScript operations: * - **JavaScript Database Operations** - **Description** - * - :method:`db.auth()` + * - :method:`~db.auth()` - If running in secure mode, authenticate the user. @@ -139,7 +139,7 @@ The following table displays some common JavaScript operations: coll.find(); - * - :method:`db.collection.find()` + * - :method:`~db.collection.find()` - Find all documents in the collection and returns a cursor. @@ -149,39 +149,39 @@ The following table displays some common JavaScript operations: See :ref:`read-operations-cursors` for additional information on cursor handling in the :program:`mongo` shell. - * - :method:`db.collection.insert()` + * - :method:`~db.collection.insert()` - Insert a new document into the collection. - * - :method:`db.collection.update()` + * - :method:`~db.collection.update()` - Update an existing document in the collection. See :doc:`/core/update` for more information. - * - :method:`db.collection.save()` + * - :method:`~db.collection.save()` - Insert either a new document or update an existing document in the collection. See :doc:`/core/update` for more information. - * - :method:`db.collection.remove()` + * - :method:`~db.collection.remove()` - Delete documents from the collection. See :doc:`/core/delete` for more information. - * - :method:`db.collection.drop()` + * - :method:`~db.collection.drop()` - Drops or removes completely the collection. - * - :method:`db.collection.ensureIndex()` + * - :method:`~db.collection.ensureIndex()` - Create a new index on the collection if the index does not exist; otherwise, the operation has no effect. - * - :method:`db.getSiblingDB()` or ``db.getSisterDB()`` + * - :method:`~db.getSiblingDB()` or ``db.getSisterDB()`` - Return a reference to another database using this same connection without explicitly switching the current database. @@ -317,10 +317,10 @@ Queries ------- In the :program:`mongo` shell, perform read operations using the -:method:`db.collection.find()` and :method:`db.collection.findOne()` +:method:`~db.collection.find()` and :method:`~db.collection.findOne()` methods. -The :method:`db.collection.find()` method returns a cursor object +The :method:`~db.collection.find()` method returns a cursor object which the :program:`mongo` shell iterates to print documents on screen. By default, :program:`mongo` prints the first 20. The :program:`mongo` shell will prompt the user to "``Type it``" to continue @@ -404,7 +404,7 @@ The following table provides some common read operations in the - Skip ```` results. - * - :method:`db.collection.count()` + * - :method:`~db.collection.count()` - Returns total number of documents in the collection. @@ -451,10 +451,10 @@ methods. These methods are: * - **Error Checking Methods** - **Description** - * - :method:`db.getLastError()` + * - :method:`~db.getLastError()` - Returns error message from the last operation. - * - :method:`db.getLastErrorObj()` + * - :method:`~db.getLastErrorObj()` - Returns the error document from the last operation. .. _mongo-dba-helpers: @@ -489,7 +489,7 @@ administration: - Rename collection from ``fromColl`` to ````. - * - :method:`db.repairDatabase()` + * - :method:`~db.repairDatabase()` - Repair and compact the current database. This operation can be very slow on large databases. @@ -498,11 +498,11 @@ administration: - Add user to current database. - * - :method:`db.getCollectionNames()` + * - :method:`~db.getCollectionNames()` - Get the list of all collections in the current database. - * - :method:`db.dropDatabase()` + * - :method:`~db.dropDatabase()` - Drops the current database. diff --git a/source/reference/object-id.txt b/source/reference/object-id.txt index ec43b54b710..c07ec61c9ec 100644 --- a/source/reference/object-id.txt +++ b/source/reference/object-id.txt @@ -28,8 +28,7 @@ Using ObjectIds for the ``_id`` field provides the following additional benefits: - in the :program:`mongo` shell, you can access the creation time of - the ``ObjectId``, using the :method:`getTimestamp() - ` method. + the ``ObjectId``, using the :method:`~ObjectId.getTimestamp()` method. - sorting on an ``_id`` field that stores ``ObjectId`` values is roughly equivalent to sorting by creation time. @@ -69,16 +68,16 @@ and methods: returned string literal has the format "``ObjectId(...)``". .. versionchanged:: 2.2 - In previous versions :method:`ObjectId.toString()` returns the + In previous versions :method:`~ObjectId.toString()` returns the value of the ObjectId as a hexadecimal string. -- :method:`valueOf() ` +- :method:`~ObjectId.valueOf()` Returns the value of the ``ObjectId()`` object as a hexadecimal string. The returned string is the ``str`` attribute. .. versionchanged:: 2.2 - In previous versions :method:`ObjectId.valueOf()` returns the + In previous versions :method:`~ObjectId.valueOf()` returns the ``ObjectId()`` object. Examples @@ -114,7 +113,7 @@ Consider the following uses ``ObjectId()`` class in the ObjectId("507f191e810c19729de860ea") - To return the timestamp of an ``ObjectId()`` object, use the - :method:`getTimestamp() ` method as follows: + :method:`~ObjectId.getTimestamp()` method as follows: .. code-block:: javascript diff --git a/source/reference/operator/all.txt b/source/reference/operator/all.txt index 622d7e5cb0f..e084def86ab 100644 --- a/source/reference/operator/all.txt +++ b/source/reference/operator/all.txt @@ -61,5 +61,4 @@ $all first element in the array is not very selective. .. seealso:: - :method:`find() `, :method:`update() - `, and :operator:`$set`. + :method:`~db.collection.find()`, :method:`~db.collection.update()`, and :operator:`$set`. diff --git a/source/reference/operator/and.txt b/source/reference/operator/and.txt index 27438c008c9..2b0ad90085a 100644 --- a/source/reference/operator/and.txt +++ b/source/reference/operator/and.txt @@ -53,7 +53,7 @@ $and db.inventory.update( { price: { $ne: 1.99, $exists: true } } , { $set: { qty: 15 } } ) - Both :method:`update() ` operations will set + Both :method:`~db.collection.update()` operations will set the value of the ``qty`` field in documents where: - the ``price`` field value does not equal ``1.99`` **and** @@ -61,7 +61,6 @@ $and .. seealso:: - :method:`find() `, :method:`update() - `, :operator:`$ne`, :operator:`$exists`, + :method:`~db.collection.find()`, :method:`~db.collection.update()`, :operator:`$ne`, :operator:`$exists`, :operator:`$set`. diff --git a/source/reference/operator/exists.txt b/source/reference/operator/exists.txt index c8cb775bec3..1b28e31659a 100644 --- a/source/reference/operator/exists.txt +++ b/source/reference/operator/exists.txt @@ -29,7 +29,7 @@ $exists .. seealso:: - - :method:`find() ` + - :method:`~db.collection.find()` - :operator:`$nin` diff --git a/source/reference/operator/explain.txt b/source/reference/operator/explain.txt index 36cdcadb59f..0700701c243 100644 --- a/source/reference/operator/explain.txt +++ b/source/reference/operator/explain.txt @@ -24,7 +24,7 @@ $explain db.collection.find( { $query: {}, $explain: 1 } ) You also can specify :operator:`$explain` through the - :method:`explain() ` method in the :program:`mongo` + :method:`~cursor.explain()` method in the :program:`mongo` shell: .. code-block:: javascript @@ -45,34 +45,34 @@ $explain these queries. To determine the performance of a particular index, you can use - :method:`hint() ` and in conjunction with - :method:`explain() `, as in the following example: + :method:`~cursor.hint()` and in conjunction with + :method:`~cursor.explain()`, as in the following example: .. code-block:: javascript db.products.find().hint( { type: 1 } ).explain() - When you run :method:`explain() ` with - :method:`hint() `, the query optimizer does not + When you run :method:`~cursor.explain()` with + :method:`~cursor.hint()`, the query optimizer does not reevaluate the query plans. .. note:: - In some situations, the :method:`explain() ` + In some situations, the :method:`~cursor.explain()` operation may differ from the actual query plan used by MongoDB in a normal query. - The :method:`explain() ` operation evaluates + The :method:`~cursor.explain()` operation evaluates the set of query plans and reports on the winning plan for the query. In normal operations the query optimizer caches winning query plans and uses them for similar related queries in the future. As a result MongoDB may sometimes select query plans from the cache that are different from the plan displayed using - :method:`explain() `. + :method:`~cursor.explain()`. .. seealso:: - - :method:`cursor.explain()` + - :method:`~cursor.explain()` - :doc:`/applications/optimization` page for information regarding optimization strategies. diff --git a/source/reference/operator/gt.txt b/source/reference/operator/gt.txt index a5da3f704e4..83bef93fd5a 100644 --- a/source/reference/operator/gt.txt +++ b/source/reference/operator/gt.txt @@ -27,12 +27,11 @@ $gt db.inventory.update( { "carrier.fee": { $gt: 2 } }, { $set: { price: 9.99 } } ) - This :method:`update() ` operation will set + This :method:`~db.collection.update()` operation will set the value of the ``price`` field in the documents that contain the embedded document ``carrier`` whose ``fee`` field value is greater than ``2``. .. seealso:: - :method:`find() `, :method:`update() - `, :operator:`$set`. + :method:`~db.collection.find()`, :method:`~db.collection.update()`, :operator:`$set`. diff --git a/source/reference/operator/gte.txt b/source/reference/operator/gte.txt index 6dbf51be74e..2b87c7c09b5 100644 --- a/source/reference/operator/gte.txt +++ b/source/reference/operator/gte.txt @@ -28,12 +28,11 @@ $gte db.inventory.update( { "carrier.fee": { $gte: 2 } }, { $set: { price: 9.99 } } ) - This :method:`update() ` operation will set + This :method:`~db.collection.update()` operation will set the value of the ``price`` field that contain the embedded document ``carrier`` whose ``fee`` field value is greater than or equal to ``2``. .. seealso:: - :method:`find() `, :method:`update() - `, :operator:`$set`. + :method:`~db.collection.find()`, :method:`~db.collection.update()`, :operator:`$set`. diff --git a/source/reference/operator/in.txt b/source/reference/operator/in.txt index 1a608b3bc41..cc7fd277b40 100644 --- a/source/reference/operator/in.txt +++ b/source/reference/operator/in.txt @@ -39,7 +39,7 @@ $in { $set: { sale:true } } ) - This :method:`update() ` operation will set + This :method:`~db.collection.update()` operation will set the ``sale`` field value in the ``inventory`` collection where the ``tags`` field holds an array with at least one element matching an element in the array ``["appliances", "school"]``. @@ -50,5 +50,4 @@ $in .. seealso:: - :method:`find() `, :method:`update() - `, :operator:`$or`, :operator:`$set`. + :method:`~db.collection.find()`, :method:`~db.collection.update()`, :operator:`$or`, :operator:`$set`. diff --git a/source/reference/operator/lt.txt b/source/reference/operator/lt.txt index e9a4366e9d2..54aad292c13 100644 --- a/source/reference/operator/lt.txt +++ b/source/reference/operator/lt.txt @@ -27,12 +27,11 @@ $lt db.inventory.update( { "carrier.fee": { $lt: 20 } }, { $set: { price: 9.99 } } ) - This :method:`update() ` operation will set + This :method:`~db.collection.update()` operation will set the ``price`` field value in the documents that contain the embedded document ``carrier`` whose ``fee`` field value is less than ``20``. .. seealso:: - :method:`find() `, :method:`update() - `, :operator:`$set`. + :method:`~db.collection.find()`, :method:`~db.collection.update()`, :operator:`$set`. diff --git a/source/reference/operator/lte.txt b/source/reference/operator/lte.txt index 37439662e06..1ef929437ea 100644 --- a/source/reference/operator/lte.txt +++ b/source/reference/operator/lte.txt @@ -28,12 +28,11 @@ $lte db.inventory.update( { "carrier.fee": { $lte: 5 } }, { $set: { price: 9.99 } } ) - This :method:`update() ` operation will set + This :method:`~db.collection.update()` operation will set the ``price`` field value in the documents that contain the embedded document ``carrier`` whose ``fee`` field value is less than or equal to ``5``. .. seealso:: - :method:`find() `, :method:`update() - `, :operator:`$set`. + :method:`~db.collection.find()`, :method:`~db.collection.update()`, :operator:`$set`. diff --git a/source/reference/operator/max.txt b/source/reference/operator/max.txt index 3d5bf1c0fa9..e0b1915e46f 100644 --- a/source/reference/operator/max.txt +++ b/source/reference/operator/max.txt @@ -8,8 +8,8 @@ $max Specify a :operator:`$max` value to specify the *exclusive* upper bound for a specific index in order to constrain the results of - :method:`find() `. The :program:`mongo` shell - provides the :method:`cursor.max()` wrapper method: + :method:`~db.collection.find()`. The :program:`mongo` shell + provides the :method:`~cursor.max()` wrapper method: .. code-block:: javascript @@ -36,7 +36,7 @@ $max field ``age`` is less than ``100`` using the index ``{ age: 1 }``. You can explicitly specify the corresponding index with - :method:`cursor.hint()`. Otherwise, MongoDB selects the index using + :method:`~cursor.hint()`. Otherwise, MongoDB selects the index using the fields in the ``indexBounds``; however, if multiple indexes exist on same fields with different sort orders, the selection of the index may be ambiguous. @@ -49,7 +49,7 @@ $max { age: 1, type: -1 } { age: 1, type: 1 } - Without explicitly using :method:`cursor.hint()`, MongoDB may + Without explicitly using :method:`~cursor.hint()`, MongoDB may select either index for the following operation: .. code-block:: javascript @@ -66,7 +66,7 @@ $max .. note:: - Because :method:`cursor.max()` requires an index on a field, and + Because :method:`~cursor.max()` requires an index on a field, and forces the query to use this index, you may prefer the :operator:`$lt` operator for the query if possible. Consider the following example: diff --git a/source/reference/operator/min.txt b/source/reference/operator/min.txt index 527f6268ac1..e6b172f54d2 100644 --- a/source/reference/operator/min.txt +++ b/source/reference/operator/min.txt @@ -8,8 +8,8 @@ $min Specify a :operator:`$min` value to specify the *inclusive* lower bound for a specific index in order to constrain the results of - :method:`find() `. The :program:`mongo` shell - provides the :method:`cursor.min()` wrapper method: + :method:`~db.collection.find()`. The :program:`mongo` shell + provides the :method:`~cursor.min()` wrapper method: .. code-block:: javascript @@ -36,7 +36,7 @@ $min ``age`` is at least ``20`` using the index ``{ age: 1 }``. You can explicitly specify the corresponding index with - :method:`cursor.hint()`. Otherwise, MongoDB selects the index using + :method:`~cursor.hint()`. Otherwise, MongoDB selects the index using the fields in the ``indexBounds``; however, if multiple indexes exist on same fields with different sort orders, the selection of the index may be ambiguous. @@ -49,7 +49,7 @@ $min { age: 1, type: -1 } { age: 1, type: 1 } - Without explicitly using :method:`cursor.hint()`, it is unclear + Without explicitly using :method:`~cursor.hint()`, it is unclear which index the following operation will select: .. code-block:: javascript @@ -66,7 +66,7 @@ $min .. note:: - Because :method:`cursor.min()` requires an index on a field, and + Because :method:`~cursor.min()` requires an index on a field, and forces the query to use this index, you may prefer the :operator:`$gte` operator for the query if possible. Consider the following example: diff --git a/source/reference/operator/mod.txt b/source/reference/operator/mod.txt index bfbc5e5d646..c91145bdeb7 100644 --- a/source/reference/operator/mod.txt +++ b/source/reference/operator/mod.txt @@ -38,5 +38,4 @@ $mod .. seealso:: - :method:`find() `, :method:`update() - `, :operator:`$set`. + :method:`~db.collection.find()`, :method:`~db.collection.update()`, :operator:`$set`. diff --git a/source/reference/operator/ne.txt b/source/reference/operator/ne.txt index 97ad557bb24..f34f892f40e 100644 --- a/source/reference/operator/ne.txt +++ b/source/reference/operator/ne.txt @@ -29,7 +29,7 @@ $ne db.inventory.update( { "carrier.state": { $ne: "NY" } }, { $set: { qty: 20 } } ) - This :method:`update() ` operation will set + This :method:`~db.collection.update()` operation will set the ``qty`` field value in the documents that contains the embedded document ``carrier`` whose ``state`` field value does not equal "NY", or where the ``state`` field or the ``carrier`` embedded document @@ -37,5 +37,4 @@ $ne .. seealso:: - :method:`find() `, :method:`update() - `, :operator:`$set`. + :method:`~db.collection.find()`, :method:`~db.collection.update()`, :operator:`$set`. diff --git a/source/reference/operator/nin.txt b/source/reference/operator/nin.txt index 638dac58916..2300e48daaf 100644 --- a/source/reference/operator/nin.txt +++ b/source/reference/operator/nin.txt @@ -35,7 +35,7 @@ $nin db.inventory.update( { tags: { $nin: [ "appliances", "school" ] } }, { $set: { sale: false } } ) - This :method:`update() ` operation will set + This :method:`~db.collection.update()` operation will set the ``sale`` field value in the ``inventory`` collection where the ``tags`` field holds an array with **no** elements matching an element in the array ``["appliances", "school"]`` or where a @@ -43,5 +43,4 @@ $nin .. seealso:: - :method:`find() `, :method:`update() - `, :operator:`$set`. \ No newline at end of file + :method:`~db.collection.find()`, :method:`~db.collection.update()`, :operator:`$set`. diff --git a/source/reference/operator/nor.txt b/source/reference/operator/nor.txt index 61e4c2f4265..240dcecdcf6 100644 --- a/source/reference/operator/nor.txt +++ b/source/reference/operator/nor.txt @@ -65,5 +65,4 @@ $nor .. seealso:: - :method:`find() `, :method:`update() - `, :operator:`$set`, :operator:`$exists`. + :method:`~db.collection.find()`, :method:`~db.collection.update()`, :operator:`$set`, :operator:`$exists`. diff --git a/source/reference/operator/not.txt b/source/reference/operator/not.txt index 402cb4726b2..db6cde976ac 100644 --- a/source/reference/operator/not.txt +++ b/source/reference/operator/not.txt @@ -68,7 +68,6 @@ $not .. seealso:: - :method:`find() `, :method:`update() - `, :operator:`$set`, :operator:`$gt`, + :method:`~db.collection.find()`, :method:`~db.collection.update()`, :operator:`$set`, :operator:`$gt`, :operator:`$regex`, :api:`PyMongo `, :term:`driver`. diff --git a/source/reference/operator/or.txt b/source/reference/operator/or.txt index 51b0fd6356b..905014a6cbc 100644 --- a/source/reference/operator/or.txt +++ b/source/reference/operator/or.txt @@ -38,7 +38,7 @@ $or db.inventory.update( { $or: [ { price:10.99 }, { "carrier.state": "NY"} ] }, { $set: { sale: true } } ) - This :method:`update() ` operation will set + This :method:`~db.collection.update()` operation will set the value of the ``sale`` field in the documents in the ``inventory`` collection where: @@ -82,9 +82,9 @@ $or than a compound index. - Also, when using the :operator:`$or` operator with the - :method:`sort() ` method in a query, the query will + :method:`~cursor.sort()` method in a query, the query will **not** use the indexes on the :operator:`$or` fields. Consider the following - query which adds a :method:`sort() ` method to the above query: + query which adds a :method:`~cursor.sort()` method to the above query: .. code-block:: javascript @@ -96,6 +96,6 @@ $or - You cannot use the :operator:`$or` with ``2d`` :doc:`geospatial queries `. - .. seealso:: :method:`find() `, - :method:`update() `, :operator:`$set`, - :operator:`$and`, :method:`sort() `. + .. seealso:: :method:`~db.collection.find()`, + :method:`~db.collection.update()`, :operator:`$set`, + :operator:`$and`, :method:`~cursor.sort()`. diff --git a/source/reference/operator/positional.txt b/source/reference/operator/positional.txt index f9df37ed316..5fe480b8228 100644 --- a/source/reference/operator/positional.txt +++ b/source/reference/operator/positional.txt @@ -14,7 +14,7 @@ array element from a read operation, see the :projection:`$` projection operator. - When used with the :method:`update() ` + When used with the :method:`~db.collection.update()` method, - the positional :operator:`$` operator acts as a placeholder for @@ -86,5 +86,5 @@ .. seealso:: - :method:`update() `, :operator:`$set` and + :method:`~db.collection.update()`, :operator:`$set` and :operator:`$unset` diff --git a/source/reference/operator/type.txt b/source/reference/operator/type.txt index f50e2e09346..aa112962c02 100644 --- a/source/reference/operator/type.txt +++ b/source/reference/operator/type.txt @@ -119,6 +119,5 @@ $type .. seealso:: - :method:`find() `, :method:`insert() - `, :operator:`$where`, :term:`BSON`, + :method:`~db.collection.find()`, :method:`~db.collection.insert()`, :operator:`$where`, :term:`BSON`, :term:`shard key`, :term:`sharded cluster` . diff --git a/source/reference/projection/elemMatch.txt b/source/reference/projection/elemMatch.txt index fefb4e615f5..766a89521a6 100644 --- a/source/reference/projection/elemMatch.txt +++ b/source/reference/projection/elemMatch.txt @@ -68,7 +68,7 @@ $elemMatch (projection) .. example:: - The following :method:`find() ` operation + The following :method:`~db.collection.find()` operation queries for all documents where the value of the ``zipcode`` field is ``63109``. The :projection:`$elemMatch` projection returns only the **first** matching element of the ``students`` @@ -103,7 +103,7 @@ $elemMatch (projection) .. example:: - The following :method:`find() ` operation + The following :method:`~db.collection.find()` operation queries for all documents where the value of the ``zipcode`` field is ``63109``. The projection includes the **first** matching element of the ``students`` array where the ``school`` diff --git a/source/reference/system-collections.txt b/source/reference/system-collections.txt index 4139b72c774..583f0aaf080 100644 --- a/source/reference/system-collections.txt +++ b/source/reference/system-collections.txt @@ -37,8 +37,8 @@ System collections include these collections stored directly in the database: The :data:`.system.indexes` collection lists all the indexes in the database. Add and remove data from this collection - via the :method:`ensureIndex() ` and - :method:`dropIndex() ` + via the :method:`~db.collection.ensureIndex()` and + :method:`~db.collection.dropIndex()` .. data:: .system.profile diff --git a/source/release-notes/2.2.txt b/source/release-notes/2.2.txt index 69bd39b3323..444a83dc2a7 100644 --- a/source/release-notes/2.2.txt +++ b/source/release-notes/2.2.txt @@ -88,18 +88,18 @@ procedure: with the 2.2 binary. After upgrading a :program:`mongod` instance, wait for the member to recover to ``SECONDARY`` state before upgrading the next instance. - To check the member's state, issue :method:`rs.status()` in the + To check the member's state, issue :method:`~rs.status()` in the :program:`mongo` shell. -#. Use the :program:`mongo` shell method :method:`rs.stepDown()` to +#. Use the :program:`mongo` shell method :method:`~rs.stepDown()` to step down the :term:`primary` to allow the normal :ref:`failover - ` procedure. :method:`rs.stepDown()` + ` procedure. :method:`~rs.stepDown()` expedites the failover procedure and is preferable to shutting down the primary directly. Once the primary has stepped down and another member has assumed ``PRIMARY`` state, as observed in the output of - :method:`rs.status()`, shut down the previous primary and replace + :method:`~rs.status()`, shut down the previous primary and replace :program:`mongod` binary with the 2.2 binary and start the new process. @@ -150,7 +150,7 @@ Aggregation Framework The aggregation framework makes it possible to do aggregation operations without needing to use :term:`map-reduce`. The :dbcommand:`aggregate` command exposes the aggregation framework, and the -:method:`db.collection.aggregate()` helper in the :program:`mongo` shell +:method:`~db.collection.aggregate()` helper in the :program:`mongo` shell provides an interface to these operations. Consider the following resources for background on the aggregation framework and its use: @@ -187,7 +187,7 @@ To reflect these changes, MongoDB now provides changed and improved reporting for concurrency and use, see :ref:`locks` and :ref:`server-status-record-stats` in :doc:`server status ` and see -:method:`db.currentOp()`, +:method:`~db.currentOp()`, :doc:`mongotop `, and :doc:`mongostat `. @@ -220,9 +220,9 @@ or "``reporting``") the application uses to service requests. See the documentation for the following helpers in the :program:`mongo` shell that support tagged sharding configuration: -- :method:`sh.addShardTag()` -- :method:`sh.addTagRange()` -- :method:`sh.removeShardTag()` +- :method:`~sh.addShardTag()` +- :method:`~sh.addTagRange()` +- :method:`~sh.removeShardTag()` Also, see :doc:`/core/tag-aware-sharding` and :doc:`/tutorial/administer-shard-tags`. @@ -239,7 +239,7 @@ support for a full range of :ref:`read preference modes to the replica sets for each shard in a :term:`sharded cluster`. Additional read preference support now exists in the :program:`mongo` -shell using the :method:`readPref() ` cursor method. +shell using the :method:`~cursor.readPref()` cursor method. .. including tagging @@ -298,7 +298,7 @@ See: :issue:`SERVER-6961` for more information. ``ObjectId().toString()`` Returns String Literal ``ObjectId("...")`` ```````````````````````````````````````````````````````````````````` -In version 2.2, the :method:`ObjectId.toString()` method returns the +In version 2.2, the :method:`~ObjectId.toString()` method returns the string representation of the :ref:`ObjectId() ` object and has the format ``ObjectId("...")``. @@ -323,12 +323,11 @@ hexadecimal string value in both versions. ``ObjectId().valueOf()`` Returns hexadecimal string ``````````````````````````````````````````````````` -In version 2.2, the :method:`ObjectId.valueOf()` method returns the +In version 2.2, the :method:`~ObjectId.valueOf()` method returns the value of the :ref:`ObjectId() ` object as a lowercase hexadecimal string. -Consider the following example that calls the :method:`valueOf() -` method on the +Consider the following example that calls the :method:`~ObjectId.valueOf()` method on the ``ObjectId("507c7f79bcf86cd7994f6c0e")`` object: .. code-block:: javascript @@ -573,7 +572,7 @@ consistency of the user interface for the :program:`mongo` shell: Helper to load Server-Side Functions ```````````````````````````````````` -The :method:`db.loadServerScripts()` loads the contents of the current +The :method:`~db.loadServerScripts()` loads the contents of the current database's ``system.js`` collection into the current :program:`mongo` shell session. See :issue:`SERVER-1651` for more information. @@ -581,7 +580,7 @@ Support for Bulk Inserts ```````````````````````` If you pass an array of :term:`documents ` to the -:method:`insert() ` method, the :program:`mongo` +:method:`~db.collection.insert()` method, the :program:`mongo` shell will now perform a bulk insert operation. See :issue:`SERVER-3819` and :issue:`SERVER-2395` for more information. @@ -671,7 +670,7 @@ Replica Set Members can Sync from Specific Members .. the following has been copied to source/administration/replica-sets.txt The new :dbcommand:`replSetSyncFrom` command and new -:method:`rs.syncFrom()` helper in the :program:`mongo` shell make it +:method:`~rs.syncFrom()` helper in the :program:`mongo` shell make it possible for you to manually configure from which member of the set a replica will poll :term:`oplog` entries. Use these commands to override the default selection logic if needed. Always exercise diff --git a/source/release-notes/password-hashing-insecurity.txt b/source/release-notes/password-hashing-insecurity.txt index 16f87285700..a6f3a9fc159 100644 --- a/source/release-notes/password-hashing-insecurity.txt +++ b/source/release-notes/password-hashing-insecurity.txt @@ -55,7 +55,7 @@ for each database. use admin db.auth("alice", "pass") - Consider the output of :method:`find() ` on + Consider the output of :method:`~db.collection.find()` on the ``system.users`` collection: .. code-block:: javascript diff --git a/source/tutorial/access-mongo-shell-help.txt b/source/tutorial/access-mongo-shell-help.txt index bc071e902df..041c85c004b 100644 --- a/source/tutorial/access-mongo-shell-help.txt +++ b/source/tutorial/access-mongo-shell-help.txt @@ -55,7 +55,7 @@ Database Help ``show databases`` is now an alias for ``show dbs`` - To see the list of help for methods you can use on the ``db`` - object, call the :method:`db.help()` method: + object, call the :method:`~db.help()` method: .. code-block:: javascript @@ -64,7 +64,7 @@ Database Help - To see the implementation of a method in the shell, type the ``db.`` without the parenthesis (``()``), as in the following example which will return the implementation of the method - :method:`db.addUser()`: + :method:`~db.addUser()`: .. code-block:: javascript @@ -96,7 +96,7 @@ Collection Help - To see the collection method implementation, type the ``db..`` name without the parenthesis (``()``), as in the following example which will return the implementation of - the :method:`save() ` method: + the :method:`~db.collection.save()` method: .. code-block:: javascript @@ -108,11 +108,11 @@ Cursor Help ----------- When you perform :ref:`read operations ` with -the :method:`find() ` method in the +the :method:`~db.collection.find()` method in the :program:`mongo` shell, you can use various cursor methods to modify -the :method:`find() ` behavior and various +the :method:`~db.collection.find()` behavior and various JavaScript methods to handle the cursor returned from the -:method:`find() ` method. +:method:`~db.collection.find()` method. - To list the available modifier and cursor handling methods, use the ``db.collection.find().help()`` command: @@ -135,10 +135,10 @@ JavaScript methods to handle the cursor returned from the Some useful methods for handling cursors are: -- :method:`hasNext() ` which checks whether the +- :method:`~cursor.hasNext()` which checks whether the cursor has more documents to return. -- :method:`next() ` which returns the next document and +- :method:`~cursor.next()` which returns the next document and advances the cursor position forward by one. - :method:`forEach(\) ` which iterates the diff --git a/source/tutorial/aggregation-examples.txt b/source/tutorial/aggregation-examples.txt index 9847b870cbd..de6132c5c8a 100644 --- a/source/tutorial/aggregation-examples.txt +++ b/source/tutorial/aggregation-examples.txt @@ -60,9 +60,8 @@ In these documents: - The ``loc`` field holds the location as a latitude longitude pair. -All of the following examples use the :method:`aggregate() -` helper in the :program:`mongo` -shell. :method:`aggregate() ` provides a +All of the following examples use the :method:`~db.collection.aggregate()` helper in the :program:`mongo` +shell. :method:`~db.collection.aggregate()` provides a wrapper around the :dbcommand:`aggregate` database command. See the documentation for your :doc:`driver ` for a more idiomatic interface for data aggregation operations. @@ -80,10 +79,8 @@ the following aggregation operation: totalPop : { $sum : "$pop" } } }, { $match : {totalPop : { $gte : 10*1000*1000 } } } ) -Aggregations operations using the :method:`aggregate() -` helper, process all documents on the -``zipcodes`` collection. :method:`aggregate() -` connects a number of :ref:`pipeline +Aggregations operations using the :method:`~db.collection.aggregate()` helper, process all documents on the +``zipcodes`` collection. :method:`~db.collection.aggregate()` connects a number of :ref:`pipeline ` operators, which define the aggregation process. @@ -140,10 +137,8 @@ following aggregation operation: { _id : "$_id.state", avgCityPop : { $avg : "$pop" } } } ) -Aggregations operations using the :method:`aggregate() -` helper, process all documents on the -``zipcodes`` collection. :method:`aggregate() -` a number of :ref:`pipeline +Aggregations operations using the :method:`~db.collection.aggregate()` helper, process all documents on the +``zipcodes`` collection. :method:`~db.collection.aggregate()` a number of :ref:`pipeline ` operators that define the aggregation process. @@ -213,10 +208,8 @@ state, use the following aggregation operation: biggestCity: { name: "$biggestCity", pop: "$biggestPop" }, smallestCity: { name: "$smallestCity", pop: "$smallestPop" } } } ) -Aggregations operations using the :method:`aggregate() -` helper, process all documents on the -``zipcodes`` collection. :method:`aggregate() -` a number of :ref:`pipeline +Aggregations operations using the :method:`~db.collection.aggregate()` helper, process all documents on the +``zipcodes`` collection. :method:`~db.collection.aggregate()` a number of :ref:`pipeline ` operators that define the aggregation process. @@ -357,7 +350,7 @@ and stores these data in documents that resemble the following: } For basic query and projection operations, standard queries with the - :method:`find() ` method are preferable. This + :method:`~db.collection.find()` method are preferable. This operation appears as an hypothetical example only. .. end-redaction @@ -502,8 +495,7 @@ the following operations: - Creates two new fields: ``month_joined`` and ``name``. - - Suppresses the ``id`` from the results. The :method:`aggregate() - ` method includes the ``_id``, unless + - Suppresses the ``id`` from the results. The :method:`~db.collection.aggregate()` method includes the ``_id``, unless explicitly suppressed. - The :expression:`$month` operator converts the values of the diff --git a/source/tutorial/create-a-unique-index.txt b/source/tutorial/create-a-unique-index.txt index be8435e1b88..ab5de517dd4 100644 --- a/source/tutorial/create-a-unique-index.txt +++ b/source/tutorial/create-a-unique-index.txt @@ -72,7 +72,7 @@ index on a collection with duplicate values in the field you are indexing you can use the ``dropDups`` option. This will force MongoDB to create a *unique* index by deleting documents with duplicate values when building the index. Consider the following prototype invocation -of :method:`db.collection.ensureIndex()`: +of :method:`~db.collection.ensureIndex()`: .. code-block:: javascript @@ -86,6 +86,6 @@ See the full documentation of :ref:`duplicate dropping Specifying ``{ dropDups: true }`` may delete data from your database. Use with extreme caution. -Refer to the :method:`ensureIndex() ` +Refer to the :method:`~db.collection.ensureIndex()` documentation for additional index creation options. diff --git a/source/tutorial/create-an-auto-incrementing-field.txt b/source/tutorial/create-an-auto-incrementing-field.txt index 5501409676f..356fe131f25 100644 --- a/source/tutorial/create-an-auto-incrementing-field.txt +++ b/source/tutorial/create-an-auto-incrementing-field.txt @@ -67,7 +67,7 @@ contains the last value of the sequence. } #. Use this ``getNextSequence()`` function during - :method:`insert() `. + :method:`~db.collection.insert()`. .. code-block:: javascript @@ -85,7 +85,7 @@ contains the last value of the sequence. } ) - You can verify the results with :method:`find() `: + You can verify the results with :method:`~db.collection.find()`: .. code-block:: javascript @@ -165,7 +165,7 @@ is successful. #. Create a function named ``insertDocument`` that performs the "insert if not present" loop. The function wraps the - :method:`insert() ` method and takes a + :method:`~db.collection.insert()` method and takes a ``doc`` and a ``targetCollection`` arguments. .. code-block:: javascript @@ -237,7 +237,7 @@ is successful. myCollection ) - You can verify the results with :method:`find() `: + You can verify the results with :method:`~db.collection.find()`: .. code-block:: javascript diff --git a/source/tutorial/create-an-index.txt b/source/tutorial/create-an-index.txt index d7a4f92a7cd..6c2cb2e0e9a 100644 --- a/source/tutorial/create-an-index.txt +++ b/source/tutorial/create-an-index.txt @@ -22,7 +22,7 @@ compound indexes. Build a Foreground Index on a Single Field ------------------------------------------ -To create an index, use :method:`db.collection.ensureIndex()` or a similar +To create an index, use :method:`~db.collection.ensureIndex()` or a similar :api:`method from your driver <>`. For example the following creates an index on the ``phone-number`` field of the ``people`` collection: @@ -31,7 +31,7 @@ of the ``people`` collection: db.people.ensureIndex( { "phone-number": 1 } ) -:method:`ensureIndex() ` only creates an +:method:`~db.collection.ensureIndex()` only creates an index if an index of the same specification does not already exist. All indexes support and optimize the performance for queries that select diff --git a/source/tutorial/enforce-unique-keys-for-sharded-collections.txt b/source/tutorial/enforce-unique-keys-for-sharded-collections.txt index 7cb26d036ca..4fb5b59eab2 100644 --- a/source/tutorial/enforce-unique-keys-for-sharded-collections.txt +++ b/source/tutorial/enforce-unique-keys-for-sharded-collections.txt @@ -174,7 +174,7 @@ this operation succeeds, the ``email`` field is unique, and you may continue by inserting the actual document into the ``information`` collection. -.. see:: The full documentation of: :method:`db.collection.ensureIndex()` +.. see:: The full documentation of: :method:`~db.collection.ensureIndex()` and :dbcommand:`shardCollection`. Considerations diff --git a/source/tutorial/evaluate-operation-performance.txt b/source/tutorial/evaluate-operation-performance.txt index 791cfe71017..2e7433d2481 100644 --- a/source/tutorial/evaluate-operation-performance.txt +++ b/source/tutorial/evaluate-operation-performance.txt @@ -24,18 +24,18 @@ For more information, see :ref:`database-profiling`. Use ``db.currentOp()`` to Evaluate ``mongod`` Operations -------------------------------------------------------- -The :method:`db.currentOp()` method reports on current operations +The :method:`~db.currentOp()` method reports on current operations running on a :program:`mongod` instance. Use ``$explain`` to Evaluate Query Performance ---------------------------------------------- -The :method:`explain() ` method returns statistics +The :method:`~cursor.explain()` method returns statistics on a query, and reports the index MongoDB selected to fulfill the query, as well as information about the internal operation of the query. -.. example:: To use :method:`explain() ` on a query +.. example:: To use :method:`~cursor.explain()` on a query for documents matching the expression ``{ a: 1 }``, in the collection named ``records``, use an operation that resembles the following in the :program:`mongo` shell: diff --git a/source/tutorial/getting-started-with-the-mongo-shell.txt b/source/tutorial/getting-started-with-the-mongo-shell.txt index eea90cb950c..fd3f374e2e5 100644 --- a/source/tutorial/getting-started-with-the-mongo-shell.txt +++ b/source/tutorial/getting-started-with-the-mongo-shell.txt @@ -94,9 +94,9 @@ From the :program:`mongo` shell, you can use the :doc:`shell methods db.getCollection("3test").find() -- The :method:`find() ` method is the JavaScript +- The :method:`~db.collection.find()` method is the JavaScript method to retrieve documents from ````. The - :method:`find() ` method returns a + :method:`~db.collection.find()` method returns a :term:`cursor` to the results; however, in the :program:`mongo` shell, if the returned cursor is not assigned to a variable, then the cursor is automatically iterated up to 20 times to print up to the @@ -136,7 +136,7 @@ Print ----- The :program:`mongo` shell automatically prints the results of the -:method:`find() ` method if the returned cursor +:method:`~db.collection.find()` method if the returned cursor is not assigned to a variable. To format the result, you can add the ``.pretty()`` to the operation, as in the following: diff --git a/source/tutorial/getting-started.txt b/source/tutorial/getting-started.txt index 038d16403d1..19092d8a556 100644 --- a/source/tutorial/getting-started.txt +++ b/source/tutorial/getting-started.txt @@ -167,7 +167,7 @@ into the collection. #. Confirm that the documents exist in the ``testData`` collection by issuing a query on the collection using the - :method:`find() ` method: + :method:`~db.collection.find()` method: .. code-block:: javascript @@ -310,12 +310,12 @@ for a full account of queries in MongoDB. In this procedure, you query for specific documents in the ``testData`` :term:`collection` by passing a "query document" as a parameter to the -:method:`find() ` method. A query document +:method:`~db.collection.find()` method. A query document specifies the criteria the query must match to return a document. In the :program:`mongo` shell, query for all documents where the ``x`` field has a value of ``18`` by passing the ``{ x : 18 }`` query document -as a parameter to the :method:`find() ` method: +as a parameter to the :method:`~db.collection.find()` method: .. code-block:: javascript @@ -330,10 +330,9 @@ MongoDB returns one document that fits this criteria: Return a Single Document from a Collection ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -With the :method:`db.collection.findOne()` method you can return a -single *document* from a MongoDB collection. The :method:`findOne() -` method takes the same parameters as -:method:`find() `, but returns a document rather +With the :method:`~db.collection.findOne()` method you can return a +single *document* from a MongoDB collection. The :method:`~db.collection.findOne()` method takes the same parameters as +:method:`~db.collection.find()`, but returns a document rather than a cursor. To retrieve one document from the ``testData`` collection, issue the @@ -354,7 +353,7 @@ limiting the amount of data your application must receive over the network. To specify the maximum number of documents in the result set, call the -:method:`limit() ` method on a cursor, as in the +:method:`~cursor.limit()` method on a cursor, as in the following command: .. code-block:: javascript diff --git a/source/tutorial/manage-chunks-in-sharded-cluster.txt b/source/tutorial/manage-chunks-in-sharded-cluster.txt index ea5a8c67ae3..b56ea3a0fe8 100644 --- a/source/tutorial/manage-chunks-in-sharded-cluster.txt +++ b/source/tutorial/manage-chunks-in-sharded-cluster.txt @@ -46,12 +46,12 @@ You may want to split chunks manually if: .. include:: /includes/warning-splitting-chunks.rst -Use :method:`sh.status()` to determine the current chunks ranges across +Use :method:`~sh.status()` to determine the current chunks ranges across the cluster. To split chunks manually, use the :dbcommand:`split` command with operators: ``middle`` and ``find``. The equivalent shell helpers are -:method:`sh.splitAt()` or :method:`sh.splitFind()`. +:method:`~sh.splitAt()` or :method:`~sh.splitFind()`. .. example:: @@ -63,16 +63,16 @@ operators: ``middle`` and ``find``. The equivalent shell helpers are sh.splitFind( "records.people", { "zipcode": 63109 } ) -:method:`sh.splitFind()` will split the chunk that contains the +:method:`~sh.splitFind()` will split the chunk that contains the *first* document returned that matches this query into two equally sized chunks. You must specify the full namespace (i.e. "``.``") of the sharded collection to -:method:`sh.splitFind()`. The query in :method:`sh.splitFind()` need +:method:`~sh.splitFind()`. The query in :method:`~sh.splitFind()` need not contain the shard key, though it almost always makes sense to query for the shard key in this case, and including the shard key will expedite the operation. -Use :method:`sh.splitAt()` to split a chunk in two using the queried +Use :method:`~sh.splitAt()` to split a chunk in two using the queried document as the partition point: .. code-block:: javascript @@ -193,7 +193,7 @@ to modify the chunk size, use the following procedure: use config -#. Issue the following :method:`save() ` +#. Issue the following :method:`~db.collection.save()` operation: .. code-block:: javascript diff --git a/source/tutorial/manage-mongodb-processes.txt b/source/tutorial/manage-mongodb-processes.txt index c6f7f53f494..fc96066a243 100644 --- a/source/tutorial/manage-mongodb-processes.txt +++ b/source/tutorial/manage-mongodb-processes.txt @@ -129,7 +129,7 @@ foreground, issue the :method:`~db.shutdownServer()` helper in the use admin db.shutdownServer() -You may only use :method:`db.shutdownServer()` when connected to the +You may only use :method:`~db.shutdownServer()` when connected to the :program:`mongod` when authenticated to the ``admin`` database or on systems without authentication connected via the localhost interface. @@ -183,7 +183,7 @@ set to ``5``: db.adminCommand({shutdown : 1, timeoutSecs : 5}) Alternately you can use the ``timeoutSecs`` argument with the -:method:`shutdownServer() ` method: +:method:`~db.shutdownServer()` method: .. code-block:: javascript diff --git a/source/tutorial/measure-index-use.txt b/source/tutorial/measure-index-use.txt index d389d0589f2..d5ca71d673a 100644 --- a/source/tutorial/measure-index-use.txt +++ b/source/tutorial/measure-index-use.txt @@ -26,7 +26,7 @@ Operations Return Query Plan with ``explain()`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Append the :method:`explain() ` method to any cursor +Append the :method:`~cursor.explain()` method to any cursor (e.g. query) to return a document with statistics about the query process, including the index used, the number of documents scanned, and the time the query takes to process in milliseconds. @@ -34,7 +34,7 @@ and the time the query takes to process in milliseconds. Control Index Use with ``hint()`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Append the :method:`hint() ` to any cursor (e.g. +Append the :method:`~cursor.hint()` to any cursor (e.g. query) with the index as the argument to *force* MongoDB to use a specific index to fulfill the query. Consider the following example: @@ -43,10 +43,9 @@ example: db.people.find( { name: "John Doe", zipcode: { $gt: 63000 } } } ).hint( { zipcode: 1 } ) -You can use :method:`hint() ` and :method:`explain() -` in conjunction with each other to compare the +You can use :method:`~cursor.hint()` and :method:`~cursor.explain()` in conjunction with each other to compare the effectiveness of a specific index. Specify the ``$natural`` operator -to the :method:`hint() ` method to prevent MongoDB from +to the :method:`~cursor.hint()` method to prevent MongoDB from using *any* index: .. code-block:: javascript diff --git a/source/tutorial/optimize-query-performance-with-indexes-and-projections.txt b/source/tutorial/optimize-query-performance-with-indexes-and-projections.txt index e44144e4e3d..8e15ea2e23d 100644 --- a/source/tutorial/optimize-query-performance-with-indexes-and-projections.txt +++ b/source/tutorial/optimize-query-performance-with-indexes-and-projections.txt @@ -56,7 +56,7 @@ Limit the Number of Query Results to Reduce Network Demand MongoDB :term:`cursors ` return results in groups of multiple documents. If you know the number of results you want, you can reduce -the demand on network resources by issuing the :method:`cursor.limit()` +the demand on network resources by issuing the :method:`~cursor.limit()` method. This is typically used in conjunction with sort operations. For example, @@ -67,7 +67,7 @@ collection, you would issue the following command: db.posts.find().sort( { timestamp : -1 } ).limit(10) -For more information on limiting results, see :method:`cursor.limit()` +For more information on limiting results, see :method:`~cursor.limit()` Use Projections to Return Only Necessary Data --------------------------------------------- @@ -92,8 +92,8 @@ Use ``$hint`` to Select a Particular Index In most cases the :ref:`query optimizer ` selects the optimal index for a specific operation; however, you can force MongoDB to use a specific -index using the :method:`hint() ` method. Use -:method:`hint() ` to support performance testing, or on +index using the :method:`~cursor.hint()` method. Use +:method:`~cursor.hint()` to support performance testing, or on some queries where you must select a field or field included in several indexes. diff --git a/source/tutorial/perform-two-phase-commits.txt b/source/tutorial/perform-two-phase-commits.txt index 281e6777ce5..db118ed17fa 100644 --- a/source/tutorial/perform-two-phase-commits.txt +++ b/source/tutorial/perform-two-phase-commits.txt @@ -86,8 +86,7 @@ following command: db.accounts.save({name: "A", balance: 1000, pendingTransactions: []}) db.accounts.save({name: "B", balance: 1000, pendingTransactions: []}) -To verify that these operations succeeded, use :method:`find() -`: +To verify that these operations succeeded, use :method:`~db.collection.find()`: .. code-block:: javascript @@ -121,8 +120,7 @@ transaction. db.transactions.save({source: "A", destination: "B", value: 100, state: "initial"}) -To verify that these operations succeeded, use :method:`find() -`: +To verify that these operations succeeded, use :method:`~db.collection.find()`: .. code-block:: javascript @@ -143,7 +141,7 @@ Before modifying either records in the ``accounts`` collection, set the transaction state to ``pending`` from ``initial``. Set the local variable ``t`` in your shell session, to the transaction -document using :method:`findOne() `: +document using :method:`~db.collection.findOne()`: .. code-block:: javascript @@ -162,7 +160,7 @@ of ``t``, you will see the following output: "state" : "initial" } -Use :method:`update() ` to change the value of +Use :method:`~db.collection.update()` to change the value of ``state`` to ``pending``: .. code-block:: javascript @@ -170,7 +168,7 @@ Use :method:`update() ` to change the value of db.transactions.update({_id: t._id}, {$set: {state: "pending"}}) db.transactions.find() -The :method:`find() ` operation will return the +The :method:`~db.collection.find()` operation will return the contents of the ``transactions`` collection, which should resemble the following: @@ -184,9 +182,9 @@ Apply Transaction to Both Accounts `````````````````````````````````` Continue by applying the transaction to both accounts. The -:method:`update() ` query will prevent you from +:method:`~db.collection.update()` query will prevent you from applying the transaction *if* the transaction is *not* already -pending. Use the following :method:`update() ` +pending. Use the following :method:`~db.collection.update()` operation: .. code-block:: javascript @@ -195,7 +193,7 @@ operation: db.accounts.update({name: t.destination, pendingTransactions: {$ne: t._id}}, {$inc: {balance: t.value}, $push: {pendingTransactions: t._id}}) db.accounts.find() -The :method:`find() ` operation will return the +The :method:`~db.collection.find()` operation will return the contents of the ``accounts`` collection, which should now resemble the following: @@ -209,7 +207,7 @@ following: Set Transaction State to Committed `````````````````````````````````` -Use the following :method:`update() ` operation +Use the following :method:`~db.collection.update()` operation to set the transaction's state to ``committed``: .. code-block:: javascript @@ -217,7 +215,7 @@ to set the transaction's state to ``committed``: db.transactions.update({_id: t._id}, {$set: {state: "committed"}}) db.transactions.find() -The :method:`find() ` operation will return the +The :method:`~db.collection.find()` operation will return the contents of the ``transactions`` collection, which should now resemble the following: @@ -230,7 +228,7 @@ the following: Remove Pending Transaction `````````````````````````` -Use the following :method:`update() ` operation +Use the following :method:`~db.collection.update()` operation to set remove the pending transaction from the :term:`documents ` in the ``accounts`` collection: @@ -240,7 +238,7 @@ to set remove the pending transaction from the :term:`documents db.accounts.update({name: t.destination}, {$pull: {pendingTransactions: t._id}}) db.accounts.find() -The :method:`find() ` operation will return the +The :method:`~db.collection.find()` operation will return the contents of the ``accounts`` collection, which should now resemble the following: @@ -262,7 +260,7 @@ Complete the transaction by setting the ``state`` of the transaction db.transactions.update({_id: t._id}, {$set: {state: "done"}}) db.transactions.find() -The :method:`find() ` operation will return the +The :method:`~db.collection.find()` operation will return the contents of the ``transactions`` collection, which should now resemble the following: @@ -341,7 +339,7 @@ Set Transaction State to Canceling ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Begin by setting the transaction's state to ``canceling`` using the -following :method:`update() ` operation: +following :method:`~db.collection.update()` operation: .. code-block:: javascript @@ -361,7 +359,7 @@ operation from both accounts: db.accounts.update({name: t.destination, pendingTransactions: t._id}, {$inc: {balance: -t.value}, $pull: {pendingTransactions: t._id}}) db.accounts.find() -The :method:`find() ` operation will return the +The :method:`~db.collection.find()` operation will return the contents of the ``accounts`` collection, which should resemble the following: @@ -375,8 +373,7 @@ following: Set Transaction State to Canceled ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Finally, use the following :method:`update() -` operation to set the transaction's state to +Finally, use the following :method:`~db.collection.update()` operation to set the transaction's state to ``canceled``: **Step 3:** set the transaction's state to "canceled": @@ -482,7 +479,7 @@ pending debits. Then: removing the transaction from the ``pending`` field., all in one update. Because all of the changes in the above two operations occur within a -single :method:`update() ` operation, these +single :method:`~db.collection.update()` operation, these changes are all atomic. Additionally, for most important transactions, ensure that: diff --git a/source/use-cases/storing-log-data.txt b/source/use-cases/storing-log-data.txt index 6dbadb12518..2aa1645ba2a 100644 --- a/source/use-cases/storing-log-data.txt +++ b/source/use-cases/storing-log-data.txt @@ -328,7 +328,7 @@ wider distribution in values, you may need to re investigate your indexing support. In most cases, however, this index is entirely sufficient. -.. seealso:: The :method:`db.collection.ensureIndex()` JavaScript method +.. seealso:: The :method:`~db.collection.ensureIndex()` JavaScript method and the :py:meth:`db.events.ensure_index() ` method in :api:`PyMongo `. @@ -366,7 +366,7 @@ a result, if you query primarily on recent data, MongoDB will be able to maintain a large index, quickly fulfill queries, and avoid using much system memory. -.. seealso:: The :method:`db.events.ensureIndex() ` JavaScript method +.. seealso:: The :method:`~db.events.ensureIndex() ` JavaScript method and the :py:meth:`db.events.ensure_index() ` method in :api:`PyMongo `. @@ -472,7 +472,7 @@ build more useful queries. depending on your other queries, it may make more sense to use the ``{ time: 1, host: 1 }`` index depending on usage profile. -.. seealso:: The :method:`db.events.ensureIndex() +.. seealso:: The :method:`~db.events.ensureIndex() ` JavaScript method and the :py:meth:`db.events.ensure_index() ` method in :api:`PyMongo `. @@ -529,7 +529,7 @@ a pipeline that: #. Uses the :pipeline:`$match` to limit the documents that the aggregation framework must process. :pipeline:`$match` is - similar to a :method:`find() ` query. + similar to a :method:`~db.collection.find()` query. This operation selects all documents where the value of the ``time`` field represents a date that is on or after