From 853981f1dc77c22d3893fe5e1694ed6c2b5939e2 Mon Sep 17 00:00:00 2001 From: Bob Grabar Date: Mon, 13 May 2013 15:26:54 -0400 Subject: [PATCH] DOCS-1492 generate table output for 2-parameter methods and commands --- source/reference/command/applyOps-param.yaml | 22 +++ source/reference/command/applyOps.txt | 32 ++-- source/reference/command/sleep-param.yaml | 22 +++ source/reference/command/sleep.txt | 23 ++- .../method/Mongo.setReadPref-param.yaml | 27 +++ source/reference/method/Mongo.setReadPref.txt | 100 +++++------ .../method/cursor.readPref-param.yaml | 27 +++ source/reference/method/cursor.readPref.txt | 25 +-- source/reference/method/db.auth-param.yaml | 22 +++ source/reference/method/db.auth.txt | 15 +- .../db.collection.createIndex-param.yaml | 22 +++ .../method/db.collection.createIndex.txt | 18 +- .../method/db.collection.distinct-param.yaml | 22 +++ .../method/db.collection.distinct.txt | 73 ++++---- .../method/db.collection.find-param.yaml | 46 +++++ .../reference/method/db.collection.find.txt | 163 +++++++----------- .../method/db.collection.findOne-param.yaml | 44 +++++ .../method/db.collection.findOne.txt | 43 ++--- .../method/db.collection.insert-param.yaml | 13 ++ .../reference/method/db.collection.insert.txt | 140 +++++++-------- .../method/db.collection.remove-param.yaml | 22 +++ .../reference/method/db.collection.remove.txt | 96 +++++------ .../db.collection.renameCollection-param.yaml | 22 +++ .../method/db.collection.renameCollection.txt | 17 +- source/reference/method/db.eval-param.yaml | 27 +++ source/reference/method/db.eval.txt | 80 ++++----- .../reference/method/db.runCommand-param.yaml | 12 ++ source/reference/method/db.runCommand.txt | 16 +- .../method/db.setProfilingLevel-param.yaml | 25 +++ .../reference/method/db.setProfilingLevel.txt | 26 +-- .../reference/method/rs.reconfig-param.yaml | 22 +++ source/reference/method/rs.reconfig.txt | 65 ++++--- .../method/sh._adminCommand-param.yaml | 22 +++ source/reference/method/sh._adminCommand.txt | 22 +-- .../method/sh.addShardTag-param.yaml | 22 +++ source/reference/method/sh.addShardTag.txt | 35 ++-- .../method/sh.removeShardTag-param.yaml | 22 +++ source/reference/method/sh.removeShardTag.txt | 19 +- source/reference/method/sh.splitAt-param.yaml | 22 +++ source/reference/method/sh.splitAt.txt | 33 ++-- .../reference/method/sh.splitFind-param.yaml | 22 +++ source/reference/method/sh.splitFind.txt | 17 +- .../method/sh.startBalancer-param.yaml | 22 +++ source/reference/method/sh.startBalancer.txt | 18 +- .../method/sh.stopBalancer-param.yaml | 22 +++ source/reference/method/sh.stopBalancer.txt | 20 ++- .../method/sh.waitForBalancerOff-param.yaml | 22 +++ .../method/sh.waitForBalancerOff.txt | 15 +- 48 files changed, 1077 insertions(+), 607 deletions(-) create mode 100644 source/reference/command/applyOps-param.yaml create mode 100644 source/reference/command/sleep-param.yaml create mode 100644 source/reference/method/Mongo.setReadPref-param.yaml create mode 100644 source/reference/method/cursor.readPref-param.yaml create mode 100644 source/reference/method/db.auth-param.yaml create mode 100644 source/reference/method/db.collection.createIndex-param.yaml create mode 100644 source/reference/method/db.collection.distinct-param.yaml create mode 100644 source/reference/method/db.collection.find-param.yaml create mode 100644 source/reference/method/db.collection.findOne-param.yaml create mode 100644 source/reference/method/db.collection.insert-param.yaml create mode 100644 source/reference/method/db.collection.remove-param.yaml create mode 100644 source/reference/method/db.collection.renameCollection-param.yaml create mode 100644 source/reference/method/db.eval-param.yaml create mode 100644 source/reference/method/db.runCommand-param.yaml create mode 100644 source/reference/method/db.setProfilingLevel-param.yaml create mode 100644 source/reference/method/rs.reconfig-param.yaml create mode 100644 source/reference/method/sh._adminCommand-param.yaml create mode 100644 source/reference/method/sh.addShardTag-param.yaml create mode 100644 source/reference/method/sh.removeShardTag-param.yaml create mode 100644 source/reference/method/sh.splitAt-param.yaml create mode 100644 source/reference/method/sh.splitFind-param.yaml create mode 100644 source/reference/method/sh.startBalancer-param.yaml create mode 100644 source/reference/method/sh.stopBalancer-param.yaml create mode 100644 source/reference/method/sh.waitForBalancerOff-param.yaml diff --git a/source/reference/command/applyOps-param.yaml b/source/reference/command/applyOps-param.yaml new file mode 100644 index 00000000000..ce003a84e38 --- /dev/null +++ b/source/reference/command/applyOps-param.yaml @@ -0,0 +1,22 @@ +object: + name: applyOps + type: command +field: + optional: false + type: param +name: operations +type: array +position: 1 +description: "An array of operations to perform." +--- +object: + name: applyOps + type: command +field: + optional: true + type: param +name: preCondition +type: array +position: 2 +description: "Defines one or more conditions that the destination must meet applying the entries from the ```` array. Use ``ns`` to specify a :term:`namespace`, ``q`` to specify a :term:`query` and ``res`` to specify the result that the query should match. You may specify zero, one, or many ``preCondition`` documents." +... diff --git a/source/reference/command/applyOps.txt b/source/reference/command/applyOps.txt index c5134b5660a..a9de8c886c6 100644 --- a/source/reference/command/applyOps.txt +++ b/source/reference/command/applyOps.txt @@ -4,32 +4,29 @@ applyOps .. default-domain:: mongodb -.. dbcommand:: applyOps - - :param array operations: an array of operations to perform. +Definition +---------- - :param array preCondition: Optional. Defines one or more conditions that the destination must meet - applying the entries from the ```` array. - Use ``ns`` to - specify a :term:`namespace`, ``q`` to specify a :term:`query` and - ``res`` to specify the result that the query should match. You may - specify zero, one, or many ``preCondition`` documents. +.. dbcommand:: applyOps - :dbcommand:`applyOps` provides a way to apply entries from an + Provides a way to apply entries from an :term:`oplog` created by :term:`replica set` members and :term:`master` instances in a master/:term:`slave` deployment. :dbcommand:`applyOps` is primarily an internal command - to support sharding functionality, and has the following prototype - form: + to support sharding functionality. + + .. include:: /reference/command/applyOps-param.rst + + :dbcommand:`applyOps` has the following prototype form: .. code-block:: javascript db.runCommand( { applyOps: [ ], preCondition: [ { ns: , q: , res: } ] } ) - :dbcommand:`applyOps` applies oplog entries from the - ```` array, to the :program:`mongod` instance. The - ``preCondition`` array provides the ability to specify conditions - that must be true in order to apply the oplog entry. + :dbcommand:`applyOps` applies oplog entries from the ```` + array, to the :program:`mongod` instance. The ``preCondition`` array + provides the ability to specify conditions that must be true in order + to apply the oplog entry. You can specify as many ``preCondition`` sets as needed. If you specify the ``ns`` option, :dbcommand:`applyOps` will only apply @@ -43,3 +40,6 @@ applyOps .. write-lock .. see: DOCS-133; SERVER-4259 + +.. Example +.. ------- diff --git a/source/reference/command/sleep-param.yaml b/source/reference/command/sleep-param.yaml new file mode 100644 index 00000000000..f8a689d3fde --- /dev/null +++ b/source/reference/command/sleep-param.yaml @@ -0,0 +1,22 @@ +object: + name: sleep + type: command +field: + optional: false + type: param +name: w +type: boolean +position: 1 +description: "If true, obtains a global write lock. Otherwise obtains a read lock." +--- +object: + name: sleep + type: command +field: + optional: false + type: param +name: secs +type: integer +position: 2 +description: "Specifies the number of seconds to sleep." +... diff --git a/source/reference/command/sleep.txt b/source/reference/command/sleep.txt index a0a122a644e..8257c9c46b1 100644 --- a/source/reference/command/sleep.txt +++ b/source/reference/command/sleep.txt @@ -4,15 +4,17 @@ sleep .. default-domain:: mongodb +Definition +---------- + .. dbcommand:: sleep - :dbcommand:`sleep` is an internal command for testing purposes. The - :dbcommand:`sleep` command forces the database to block all operations. It - takes the following options: - - :param boolean w: If true, obtain a global write lock. Otherwise - obtains a read lock. - :param integer secs: Specifies the number of seconds to sleep. + Internal command for testing purposes. The :dbcommand:`sleep` command + forces the database to block all operations. + + .. include:: /reference/command/sleep-param.rst + + The :dbcommand:`sleep` command takes the following prototype form: .. code-block:: javascript @@ -20,8 +22,8 @@ sleep The above command places the :program:`mongod` instance in a "write-lock" state for a specified (i.e. ````) number of - seconds. Without arguments, :dbcommand:`sleep`, causes a "read - lock" for 100 seconds. + seconds. Without arguments, :dbcommand:`sleep`, causes a "read lock" + for 100 seconds. .. warning:: @@ -33,3 +35,6 @@ sleep .. |dbcommand| replace:: :dbcommand:`sleep` .. include:: /includes/note-enabletestcommands.rst + +.. Example +.. ------- diff --git a/source/reference/method/Mongo.setReadPref-param.yaml b/source/reference/method/Mongo.setReadPref-param.yaml new file mode 100644 index 00000000000..576860c90df --- /dev/null +++ b/source/reference/method/Mongo.setReadPref-param.yaml @@ -0,0 +1,27 @@ +object: + name: Mongo.setReadPref() + type: method +field: + optional: false + type: param +name: mode +type: string +position: 1 +description: "One of the following read preference modes: + - :readmode:`primary` + - :readmode:`primaryPreferred` + - :readmode:`secondary` + - :readmode:`secondaryPreferred` + - :readmode:`nearest`" +--- +object: + name: Mongo.setReadPref() + type: method +field: + optional: true + type: param +name: tagSet +type: array +position: 2 +description: "A tag set. See :ref:`tag sets ` for information on using tag sets to provide custom read preference modes." +... diff --git a/source/reference/method/Mongo.setReadPref.txt b/source/reference/method/Mongo.setReadPref.txt index 9e137d3e9d9..1360b7a78a9 100644 --- a/source/reference/method/Mongo.setReadPref.txt +++ b/source/reference/method/Mongo.setReadPref.txt @@ -4,63 +4,55 @@ Mongo.setReadPref() .. default-domain:: mongodb -.. method:: Mongo.setReadPref(, ) +Definition +---------- - :param string mode: Read preference mode. - - :param array tagSet: Optional. A tag set . +.. method:: Mongo.setReadPref(mode, tagSet) Call the :method:`~Mongo.setReadPref()` method on a :method:`Mongo ` connection object to control how the client will route all queries to members of the replica set. - The ``mode`` string should be one of: - - - :readmode:`primary` - - :readmode:`primaryPreferred` - - :readmode:`secondary` - - :readmode:`secondaryPreferred` - - :readmode:`nearest` - - See the :ref:`tag sets ` - documentation for more information on using tag sets to provide - custom read preference modes. - - To set a read preference mode in the :program:`mongo` shell, use - the following operation: - - .. code-block:: javascript - - db.getMongo().setReadPref('primaryPreferred') - - To set a read preference that uses a tag set, specify an array of - tag sets as the second argument to :method:`Mongo.setReadPref()`, - as in the following: - - .. code-block:: javascript - - db.getMongo().setReadPref('primaryPreferred', [ { "dc": "east" } ] ) - - You can specify multiple tag sets, in order of preference, as in - the following: - - .. code-block:: javascript - - db.getMongo().setReadPref('secondaryPreferred', - [ { "dc": "east", "use": "production" }, - { "dc": "east", "use": "reporting" }, - { "dc": "east" }, - {} - ] ) - - If the replica set cannot satisfy the first tag set, the client - will attempt to use the second read preference. Each tag set can - contain zero or more field/value tag pairs, with an "empty" - document acting as a wildcard which matches a replica set member - with any tag set or no tag set. - - .. note:: - - You must call :method:`Mongo.setReadPref()` on the connection - object before retrieving documents using that connection to use - that read preference. + .. include:: /reference/method/Mongo.setReadPref-param.rst + +Examples +-------- + +To set a read preference mode in the :program:`mongo` shell, use the +following operation: + +.. code-block:: javascript + + db.getMongo().setReadPref('primaryPreferred') + +To set a read preference that uses a tag set, specify an array of tag +sets as the second argument to :method:`Mongo.setReadPref()`, as in the +following: + +.. code-block:: javascript + + db.getMongo().setReadPref('primaryPreferred', [ { "dc": "east" } ] ) + +You can specify multiple tag sets, in order of preference, as in the +following: + +.. code-block:: javascript + + db.getMongo().setReadPref('secondaryPreferred', + [ { "dc": "east", "use": "production" }, + { "dc": "east", "use": "reporting" }, + { "dc": "east" }, + {} + ] ) + +If the replica set cannot satisfy the first tag set, the client will +attempt to use the second read preference. Each tag set can contain zero +or more field/value tag pairs, with an "empty" document acting as a +wildcard which matches a replica set member with any tag set or no tag +set. + +.. note:: + + You must call :method:`Mongo.setReadPref()` on the connection object + before retrieving documents using that connection to use that read + preference. diff --git a/source/reference/method/cursor.readPref-param.yaml b/source/reference/method/cursor.readPref-param.yaml new file mode 100644 index 00000000000..8fd0c2539af --- /dev/null +++ b/source/reference/method/cursor.readPref-param.yaml @@ -0,0 +1,27 @@ +object: + name: cursor.readPref() + type: method +field: + optional: false + type: param +name: mode +type: string +position: 1 +description: "The read preference mode. Use one of the following: + - :readmode:`primary` + - :readmode:`primaryPreferred` + - :readmode:`secondary` + - :readmode:`secondaryPreferred` + - :readmode:`nearest`" +--- +object: + name: cursor.readPref() + type: method +field: + optional: true + type: param +name: tagSet +type: array of tag set objects +position: 2 +description: "See the :ref:`tag sets ` documentation for more information on using tag sets to provide custom read preference modes." +... diff --git a/source/reference/method/cursor.readPref.txt b/source/reference/method/cursor.readPref.txt index e34c6ef3abb..b30003317d8 100644 --- a/source/reference/method/cursor.readPref.txt +++ b/source/reference/method/cursor.readPref.txt @@ -4,28 +4,21 @@ cursor.readPref() .. default-domain:: mongodb -.. method:: cursor.readPref() +Definition +---------- - :param string mode: Read preference mode. - :param array tagSet: Optional. Array of tag set objects. +.. method:: cursor.readPref(mode, tagSet) - Append the :method:`readPref() ` to a cursor to - control how the client will route the query will route to members + Append :method:`readPref() ` to a cursor to + control how the client routes the query to members of the replica set. - The ``mode`` string should be one of: - - - :readmode:`primary` - - :readmode:`primaryPreferred` - - :readmode:`secondary` - - :readmode:`secondaryPreferred` - - :readmode:`nearest` - - See the :ref:`tag sets ` - documentation for more information on using tag sets to provide - custom read preference modes. + .. include:: /reference/method/cursor.readPref-param.rst .. note:: You must apply :method:`cursor.readPref()` to the cursor before retrieving any documents from the database. + +.. Example +.. ------- diff --git a/source/reference/method/db.auth-param.yaml b/source/reference/method/db.auth-param.yaml new file mode 100644 index 00000000000..354a355112a --- /dev/null +++ b/source/reference/method/db.auth-param.yaml @@ -0,0 +1,22 @@ +object: + name: db.auth() + type: method +field: + optional: false + type: param +name: username +type: string +position: 1 +description: "Specifies an existing username with access privileges for this database." +--- +object: + name: db.auth() + type: method +field: + optional: false + type: param +name: password +type: string +position: 2 +description: "Specifies the corresponding password." +... diff --git a/source/reference/method/db.auth.txt b/source/reference/method/db.auth.txt index 64bf1ee3dbf..9f849337e7d 100644 --- a/source/reference/method/db.auth.txt +++ b/source/reference/method/db.auth.txt @@ -4,17 +4,22 @@ db.auth() .. default-domain:: mongodb +Definition +---------- + .. method:: db.auth("username", "password") - :param string username: Specifies an existing username with access - privileges for this database. + Allows a user to authenticate to the database from within the + shell. - :param string password: Specifies the corresponding password. + .. include:: /reference/method/db.auth-param.rst - Allows a user to authenticate to the database from within the - shell. Alternatively use :option:`mongo --username` and + Alternatively, you can use :option:`mongo --username` and :option:`--password ` to specify authentication credentials. .. |operation-name| replace:: :method:`db.auth()` .. include:: /includes/note-auth-methods-excluded-from-shell-history.rst + +.. Example +.. ------- diff --git a/source/reference/method/db.collection.createIndex-param.yaml b/source/reference/method/db.collection.createIndex-param.yaml new file mode 100644 index 00000000000..9cf4a0bc409 --- /dev/null +++ b/source/reference/method/db.collection.createIndex-param.yaml @@ -0,0 +1,22 @@ +object: + name: db.collection.createIndex() + type: method +field: + optional: false + type: param +name: keys +type: document +position: 1 +description: "A :term:`document` that contains pairs with the name of the field or fields to index and order of the index. A ``1`` specifies ascending and a ``-1`` specifies descending." +--- +object: + name: db.collection.createIndex() + type: method +field: + optional: true + type: param +name: options +type: document +position: 2 +description: "A document that controls the creation of the index." +... diff --git a/source/reference/method/db.collection.createIndex.txt b/source/reference/method/db.collection.createIndex.txt index 67425eb9574..8945c466c9b 100644 --- a/source/reference/method/db.collection.createIndex.txt +++ b/source/reference/method/db.collection.createIndex.txt @@ -4,21 +4,16 @@ db.collection.createIndex() .. default-domain:: mongodb +Definition +---------- + .. method:: db.collection.createIndex(keys, options) .. deprecated:: 1.8 - :param document keys: A :term:`document` that contains - pairs with the name of the field or - fields to index and order of the index. A - ``1`` specifies ascending and a ``-1`` - specifies descending. - - :param document options: A :term:`document` that controls the creation - of the index. This argument is optional. + Creates indexes on collections. - The :method:`~db.collection.ensureIndex()` method is the preferred - way to create indexes on collections. + .. include:: /reference/method/db.collection.createIndex-param.rst .. seealso:: :doc:`/indexes`, :method:`db.collection.createIndex()`, @@ -28,3 +23,6 @@ db.collection.createIndex() :method:`db.collection.reIndex()`, and :method:`db.collection.totalIndexSize()` +.. Example +.. ------- + diff --git a/source/reference/method/db.collection.distinct-param.yaml b/source/reference/method/db.collection.distinct-param.yaml new file mode 100644 index 00000000000..64a749c8846 --- /dev/null +++ b/source/reference/method/db.collection.distinct-param.yaml @@ -0,0 +1,22 @@ +object: + name: db.collection.distinct() + type: method +field: + optional: false + type: param +name: field +type: string +position: 1 +description: "Specifies the field for which to return the distinct values." +--- +object: + name: db.collection.distinct() + type: method +field: + optional: false + type: param +name: query +type: document +position: 2 +description: "Specifies the selection ``query`` to determine the subset of documents from which to retrieve the distinct values." +... diff --git a/source/reference/method/db.collection.distinct.txt b/source/reference/method/db.collection.distinct.txt index 4a9ba7e5140..9eb6b50bb37 100644 --- a/source/reference/method/db.collection.distinct.txt +++ b/source/reference/method/db.collection.distinct.txt @@ -4,56 +4,51 @@ db.collection.distinct() .. default-domain:: mongodb -.. method:: db.collection.distinct() +Definition +---------- - The :method:`db.collection.distinct()` method finds the distinct +.. method:: db.collection.distinct(field, query) + + Finds the distinct values for a specified field across a single collection and returns - the results in an array. The method accepts the following argument: - - :param string field: - - Specifies the field for which to return the distinct values. - - :param document query: - - Specifies the selection ``query`` to determine the subset of - documents from which to retrieve the distinct values. + the results in an array. + + .. include:: /reference/method/db.collection.distinct-param.rst + + The :method:`db.collection.distinct()` method provides a wrapper + around the :dbcommand:`distinct` command. Results must not be larger + than the maximum :ref:`BSON size `. - .. note:: + When possible to use covered indexes, the + :method:`db.collection.distinct()` method will use an index to find + the documents in the query as well as to return the data. - - The :method:`db.collection.distinct()` method provides a - wrapper around the :dbcommand:`distinct` command. Results must - not be larger than the maximum :ref:`BSON size - `. - - - When possible to use covered indexes, the - :method:`db.collection.distinct()` method will use an index to - find the documents in the query as well as to return the data. +Examples +-------- - Consider the following examples of the - :method:`db.collection.distinct()` method: +The following are examples of the :method:`db.collection.distinct()` +method: - - Return an array of the distinct values of the field ``ord_dt`` - from all documents in the ``orders`` collection: +- Return an array of the distinct values of the field ``ord_dt`` from + all documents in the ``orders`` collection: - .. code-block:: javascript + .. code-block:: javascript - db.orders.distinct( 'ord_dt' ) + db.orders.distinct( 'ord_dt' ) - - Return an array of the distinct values of the field ``sku`` in the - subdocument ``item`` from all documents in the ``orders`` - collection: +- Return an array of the distinct values of the field ``sku`` in the + subdocument ``item`` from all documents in the ``orders`` collection: - .. code-block:: javascript + .. code-block:: javascript - db.orders.distinct( 'item.sku' ) + db.orders.distinct( 'item.sku' ) - - Return an array of the distinct values of the field ``ord_dt`` - from the documents in the ``orders`` collection where the - ``price`` is greater than ``10``: +- Return an array of the distinct values of the field ``ord_dt`` from + the documents in the ``orders`` collection where the ``price`` is + greater than ``10``: - .. code-block:: javascript + .. code-block:: javascript - db.orders.distinct( 'ord_dt', - { price: { $gt: 10 } } - ) + db.orders.distinct( 'ord_dt', + { price: { $gt: 10 } } + ) diff --git a/source/reference/method/db.collection.find-param.yaml b/source/reference/method/db.collection.find-param.yaml new file mode 100644 index 00000000000..89a2314dcff --- /dev/null +++ b/source/reference/method/db.collection.find-param.yaml @@ -0,0 +1,46 @@ +object: + name: db.collection.find() + type: method +field: + optional: true + type: param +name: query +type: document +position: 1 +description: "Specifies the selection criteria using :doc:`query operators `. Omit the ``query`` parameter or pass an empty document (e.g. ``{}``) to return all documents in the collection" +--- +object: + name: db.collection.find() + type: method +field: + optional: true + type: param +name: projection +type: document +position: 2 +description: "Controls the fields to return, or the :term:`projection`. The following is a prototype ``projection`` argument: + + .. code-block:: javascript + + { field1: boolean, field2: boolean ... } + + 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 even if the field is not explicitly + stated to return in the :term:`projection` parameter. + + - ``0`` or ``false`` to exclude. + + The ``projection`` cannot contain both include and exclude + specifications except for the exclusion of the ``_id`` + field. + + Omit the ``projection`` parameter to return **all** the + fields in the matching documents. + + See :doc:`/reference/operator/projection` for a list of + special projection operators." +... diff --git a/source/reference/method/db.collection.find.txt b/source/reference/method/db.collection.find.txt index 3d052a774ca..de6ced12af8 100644 --- a/source/reference/method/db.collection.find.txt +++ b/source/reference/method/db.collection.find.txt @@ -4,50 +4,16 @@ db.collection.find() .. default-domain:: mongodb +Definition +---------- + .. method:: db.collection.find(query,projection) - The :method:`find() ` method selects documents + Selects documents in a collection and returns a :term:`cursor` to the selected documents. - The :method:`find() ` method takes the - following parameters. - - :param document query: - - Optional. Specifies the selection criteria - using :doc:`query operators `. Omit the - ``query`` parameter or pass an empty document (e.g. ``{}``) - to return all documents in the collection. - - :param document projection: - - Optional. Controls the fields to return, or the - :term:`projection`. The ``projection`` argument will - resemble the following prototype: - - .. code-block:: javascript - - { field1: boolean, field2: boolean ... } - - The ``boolean`` can take the following include or exclude - values: - - - ``1`` or ``true`` to include. The :method:`find() - ` method always includes the - :term:`_id` field even if the field is not explicitly - stated to return in the :term:`projection` parameter. - - - ``0`` or ``false`` to exclude. - - The ``projection`` cannot contain both include and exclude - specifications except for the exclusion of the ``_id`` field. - - Omit the ``projection`` parameter to return **all** the fields in - the matching documents. - - See :doc:`/reference/operator/projection` for a list of - special projection operators. + .. include:: /reference/method/db.collection.find-param.rst :returns: @@ -57,87 +23,82 @@ db.collection.find() the ``_id`` field if you do not explicitly exclude the ``_id`` field. - .. note:: - - In the :program:`mongo` shell, you can access the returned - documents directly without explicitly using the JavaScript cursor - handling method. Executing the query directly on the - :program:`mongo` shell prompt automatically iterates the cursor - to display up to the first 20 documents. Type ``it`` to continue - iteration. - - .. examples-begin + In the :program:`mongo` shell, you can access the returned documents + directly without explicitly using the JavaScript cursor handling + method. Executing the query directly on the :program:`mongo` shell + prompt automatically iterates the cursor to display up to the first + 20 documents. Type ``it`` to continue iteration. - Consider the following examples of the :method:`find() - ` method: +Examples +-------- - - To select all documents in a collection, call the - :method:`find() ` method with no parameters: +The following are examples of the :method:`find() +` method: - .. code-block:: javascript +- To select all documents in a collection, call the :method:`find() + ` method with no parameters: - db.products.find() + .. code-block:: javascript - This operation returns all the documents with all the fields from - the collection ``products``. By default, in the :program:`mongo` - shell, the cursor returns the first batch of 20 matching - documents. In the :program:`mongo` shell, iterate through the next - batch by typing ``it``. Use the appropriate cursor - handling mechanism for your specific language driver. + db.products.find() - - To select the documents that match a selection criteria, call the - :method:`find() ` method with the ``query`` - criteria: + This operation returns all the documents with all the fields from the + collection ``products``. By default, in the :program:`mongo` shell, + the cursor returns the first batch of 20 matching documents. In the + :program:`mongo` shell, iterate through the next batch by typing + ``it``. Use the appropriate cursor handling mechanism for your + specific language driver. - .. code-block:: javascript +- To select the documents that match a selection criteria, call the + :method:`find() ` method with the ``query`` + criteria: - db.products.find( { qty: { $gt: 25 } } ) + .. code-block:: javascript - This operation returns all the documents from the collection - ``products`` where ``qty`` is greater than ``25``, including all fields. + db.products.find( { qty: { $gt: 25 } } ) - - To select the documents that match a selection criteria and - return, or *project* only certain fields into the result set, - call the :method:`find() ` method with the - ``query`` criteria and the ``projection`` parameter, as in the - following example: + This operation returns all the documents from the collection + ``products`` where ``qty`` is greater than ``25``, including all + fields. - .. code-block:: javascript +- To select the documents that match a selection criteria and return, or + *project* only certain fields into the result set, call the + :method:`find() ` method with the ``query`` + criteria and the ``projection`` parameter, as in the following + example: - db.products.find( { qty: { $gt: 25 } }, { item: 1, qty: 1 } ) + .. code-block:: javascript - This operation 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 ``_id`` field, even - when not explicitly included: + db.products.find( { qty: { $gt: 25 } }, { item: 1, qty: 1 } ) - .. code-block:: javascript + This operation 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 ``_id`` field, even when not explicitly included: - { "_id" : 11, "item" : "pencil", "qty" : 50 } - { "_id" : ObjectId("50634d86be4617f17bb159cd"), "item" : "bottle", "qty" : 30 } - { "_id" : ObjectId("50634dbcbe4617f17bb159d0"), "item" : "paper", "qty" : 100 } + .. code-block:: javascript - - To select the documents that match a query criteria and exclude a - set of fields from the resulting documents, call the - :method:`find() ` method with the ``query`` - criteria and the ``projection`` parameter using the ``exclude`` - syntax: + { "_id" : 11, "item" : "pencil", "qty" : 50 } + { "_id" : ObjectId("50634d86be4617f17bb159cd"), "item" : "bottle", "qty" : 30 } + { "_id" : ObjectId("50634dbcbe4617f17bb159d0"), "item" : "paper", "qty" : 100 } - .. code-block:: javascript +- To select the documents that match a query criteria and exclude a set + of fields from the resulting documents, call the :method:`find() + ` method with the ``query`` criteria and the + ``projection`` parameter using the ``exclude`` syntax: - db.products.find( { qty: { $gt: 25 } }, { _id: 0, qty: 0 } ) + .. code-block:: javascript - The query will return all the documents from the collection - ``products`` where ``qty`` is greater than ``25``. The documents - in the result set will contain all fields *except* the ``_id`` - and ``qty`` fields, as in the following: + db.products.find( { qty: { $gt: 25 } }, { _id: 0, qty: 0 } ) - .. code-block:: javascript + The query will return all the documents from the collection + ``products`` where ``qty`` is greater than ``25``. The documents in + the result set will contain all fields *except* the ``_id`` and + ``qty`` fields, as in the following: - { "item" : "pencil", "type" : "no.2" } - { "item" : "bottle", "type" : "blue" } - { "item" : "paper" } + .. code-block:: javascript - .. examples-end + { "item" : "pencil", "type" : "no.2" } + { "item" : "bottle", "type" : "blue" } + { "item" : "paper" } diff --git a/source/reference/method/db.collection.findOne-param.yaml b/source/reference/method/db.collection.findOne-param.yaml new file mode 100644 index 00000000000..925043a6c61 --- /dev/null +++ b/source/reference/method/db.collection.findOne-param.yaml @@ -0,0 +1,44 @@ +object: + name: db.collection.findOne() + type: method +field: + optional: true + type: param +name: query +type: document +position: 1 +description: "A :term:`document` that specifies the :term:`query` using the JSON-like syntax and :doc:`query operators `." +--- +object: + name: db.collection.findOne() + type: method +field: + optional: true + type: param +name: projection +type: document +position: 2 +description: "Controls the fields to return. The following is a prototype ``projection`` argument: + + .. code-block:: javascript + + { field1: boolean, field2: boolean ... } + + The ``boolean`` can take the following include or exclude + values: + + - ``1`` or ``true`` to include. The + :method:`~db.collection.findOne()` method always + includes the :term:`_id` field even if the field is not + explicitly stated to return in the :term:`projection` + parameter. + + - ``0`` or ``false`` to exclude. + + The ``projection`` cannot contain both include and exclude + specifications except for the exclusion of the ``_id`` + field. + + Omit the ``projection`` parameter to return **all** the + fields in the matching documents." +... diff --git a/source/reference/method/db.collection.findOne.txt b/source/reference/method/db.collection.findOne.txt index 85af95bcb99..939454e1ee3 100644 --- a/source/reference/method/db.collection.findOne.txt +++ b/source/reference/method/db.collection.findOne.txt @@ -4,36 +4,18 @@ db.collection.findOne() .. default-domain:: mongodb -.. method:: db.collection.findOne(query,projection) - - :param document query: Optional. A :term:`document` that specifies the :term:`query` - using the JSON-like syntax and :doc:`query operators - `. - :param document projection: - - Optional. Controls the fields to return, or the - :term:`projection`. The ``projection`` argument will - resemble the following prototype: - - .. code-block:: javascript +Definition +---------- - { field1: boolean, field2: boolean ... } - - The ``boolean`` can take the following include or exclude - values: - - - ``1`` or ``true`` to include. The - :method:`~db.collection.findOne()` method always includes - the :term:`_id` field even if the field is not explicitly - stated to return in the :term:`projection` parameter. - - - ``0`` or ``false`` to exclude. +.. method:: db.collection.findOne(query,projection) - The ``projection`` cannot contain both include and exclude - specifications except for the exclusion of the ``_id`` field. + Returns one document that satisfies the specified query. If + multiple documents satisfy the query, this method returns the first + document according to the :term:`natural order` which reflects the + order of documents on the disc. In :term:`capped collections + `, natural order is the same as insertion order. - Omit the ``projection`` parameter to return **all** the fields in - the matching documents. + .. include:: /reference/method/db.collection.findOne-param.rst :returns: One document that satisfies the query specified as the argument to this method. If the ``projection`` argument is @@ -41,8 +23,5 @@ db.collection.findOne() ``projection`` fields, and the ``_id`` field if you do not explicitly exclude the ``_id`` field. - Returns only one document that satisfies the specified query. If - multiple documents satisfy the query, this method returns the first - document according to the :term:`natural order` which reflects the - order of documents on the disc. In :term:`capped collections - `, natural order is the same as insertion order. +.. Example +.. ------- diff --git a/source/reference/method/db.collection.insert-param.yaml b/source/reference/method/db.collection.insert-param.yaml new file mode 100644 index 00000000000..2f17e99494a --- /dev/null +++ b/source/reference/method/db.collection.insert-param.yaml @@ -0,0 +1,13 @@ +object: + name: db.collection.insert() + type: method +field: + optional: false + type: param +name: + - document + - array of documents +type: +position: 1 +description: "A document or array of documents to insert into the collection." +... diff --git a/source/reference/method/db.collection.insert.txt b/source/reference/method/db.collection.insert.txt index cdb3e9b231d..d65b178b466 100644 --- a/source/reference/method/db.collection.insert.txt +++ b/source/reference/method/db.collection.insert.txt @@ -4,120 +4,104 @@ db.collection.insert() .. default-domain:: mongodb -.. method:: db.collection.insert(document) +Definition +---------- - The :method:`insert() ` method inserts a - document or documents into a collection. +.. method:: db.collection.insert(document|array) + + Inserts a document or an array of documents into a collection. .. versionchanged:: 2.2 The :method:`insert() ` method can accept an array of documents to perform a bulk insert of the documents into the collection. - Consider the following behaviors of the :method:`insert() - ` method: + .. include:: /reference/method/db.collection.insert-param.rst + + The :method:`insert() ` method has the + following behaviors: - If the collection does not exist, then the :method:`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 the document before inserting. Most drivers - create an ObjectId and insert the ``_id`` field, but the - :program:`mongod` will create and populate the ``_id`` if the - driver or application does not. + - If the document does not specify an :term:`_id` field, then MongoDB + will add the ``_id`` field and assign a unique :term:`ObjectId` for + the document before inserting. Most drivers create an ObjectId and + 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 field. This requires no changes to the data model for the + ` method inserts the document with the new + field. This requires no changes to the data model for the collection or the existing documents. - The :method:`insert() ` method takes one of - the following parameters: - - :param document: - - A document to insert into the collection. - - :param array documents: - - .. versionadded:: 2.2 - - An array of documents to insert into the collection. - - .. examples-begin - - Consider the following examples of the :method:`insert() - ` method: +Examples +-------- - - 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 following: +The following are examples of the :method:`insert() +` method: - .. code-block:: javascript +- 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 + following: - db.products.insert( { item: "card", qty: 15 } ) + .. code-block:: javascript - This operation inserts a new document into the ``products`` - collection with the ``item`` field set to ``card``, the ``qty`` - field set to ``15``, and the ``_id`` field set to a unique - ``ObjectId``: + db.products.insert( { item: "card", qty: 15 } ) - .. code-block:: javascript + This operation inserts a new document into the ``products`` collection + with the ``item`` field set to ``card``, the ``qty`` field set to + ``15``, and the ``_id`` field set to a unique ``ObjectId``: - { "_id" : ObjectId("5063114bd386d8fadbd6b004"), "item" : "card", "qty" : 15 } + .. code-block:: javascript - .. include:: /includes/note-insert-id-field.rst + { "_id" : ObjectId("5063114bd386d8fadbd6b004"), "item" : "card", "qty" : 15 } - - 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: + .. include:: /includes/note-insert-id-field.rst - .. code-block:: javascript +- 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: - db.products.insert( { _id: 10, item: "box", qty: 20 } ) + .. code-block:: javascript - This operation inserts a new document in the ``products`` - collection with the ``_id`` field set to ``10``, the ``item`` - field set to ``box``, the ``qty`` field set to ``20``: + db.products.insert( { _id: 10, item: "box", qty: 20 } ) - .. code-block:: javascript + This operation inserts a new document in the ``products`` collection + with the ``_id`` field set to ``10``, the ``item`` field set to + ``box``, the ``qty`` field set to ``20``: - { "_id" : 10, "item" : "box", "qty" : 20 } + .. code-block:: javascript - .. include:: /includes/note-insert-id-field.rst + { "_id" : 10, "item" : "box", "qty" : 20 } - - To insert multiple documents, pass an array of documents to the - :method:`insert() ` method as in the - following: + .. include:: /includes/note-insert-id-field.rst - .. code-block:: javascript +- To insert multiple documents, pass an array of documents to the + :method:`insert() ` method as in the + following: - db.products.insert( [ { _id: 11, item: "pencil", qty: 50, type: "no.2" }, - { item: "pen", qty: 20 }, - { item: "eraser", qty: 25 } ] ) + .. code-block:: javascript - The operation will insert three documents into the ``products`` - collection: + db.products.insert( [ { _id: 11, item: "pencil", qty: 50, type: "no.2" }, + { item: "pen", qty: 20 }, + { item: "eraser", qty: 25 } ] ) - - A document with the fields ``_id`` set to ``11``, ``item`` - set to ``pencil``, ``qty`` set to ``50``, and the ``type`` set - to ``no.2``. + The operation will insert three documents into the ``products`` + collection: - - A document with the fields ``_id`` set to a unique - ``objectid``, ``item`` set to ``pen``, - and ``qty`` set to ``20``. + - A document with the fields ``_id`` set to ``11``, ``item`` set to + ``pencil``, ``qty`` set to ``50``, and the ``type`` set to ``no.2``. - - A document with the fields ``_id`` set to a unique - ``objectid``, ``item`` set to - ``eraser``, and ``qty`` set to ``25``. + - A document with the fields ``_id`` set to a unique ``objectid``, + ``item`` set to ``pen``, and ``qty`` set to ``20``. - .. code-block:: javascript + - A document with the fields ``_id`` set to a unique ``objectid``, + ``item`` set to ``eraser``, and ``qty`` set to ``25``. - { "_id" : 11, "item" : "pencil", "qty" : 50, "type" : "no.2" } - { "_id" : ObjectId("50631bc0be4617f17bb159ca"), "item" : "pen", "qty" : 20 } - { "_id" : ObjectId("50631bc0be4617f17bb159cb"), "item" : "eraser", "qty" : 25 } + .. code-block:: javascript - .. examples-end + { "_id" : 11, "item" : "pencil", "qty" : 50, "type" : "no.2" } + { "_id" : ObjectId("50631bc0be4617f17bb159ca"), "item" : "pen", "qty" : 20 } + { "_id" : ObjectId("50631bc0be4617f17bb159cb"), "item" : "eraser", "qty" : 25 } diff --git a/source/reference/method/db.collection.remove-param.yaml b/source/reference/method/db.collection.remove-param.yaml new file mode 100644 index 00000000000..e945ecaa25f --- /dev/null +++ b/source/reference/method/db.collection.remove-param.yaml @@ -0,0 +1,22 @@ +object: + name: db.collection.remove() + type: method +field: + optional: true + type: param +name: query +type: document +position: 1 +description: "Specifies the deletion criteria using :doc:`query operators `. Omit the ``query`` parameter or pass an empty document (e.g. ``{}`` ) to delete all :term:`documents ` in the :term:`collection`." +--- +object: + name: db.collection.remove() + type: method +field: + optional: true + type: param +name: justOne +type: boolean +position: 2 +description: "A boolean that limits the deletion to just one document. The default value is ``false``. Set to ``true`` to delete only the first result." +... diff --git a/source/reference/method/db.collection.remove.txt b/source/reference/method/db.collection.remove.txt index 07f697ebed2..11ad0d0f253 100644 --- a/source/reference/method/db.collection.remove.txt +++ b/source/reference/method/db.collection.remove.txt @@ -4,82 +4,68 @@ db.collection.remove() .. default-domain:: mongodb -.. method:: db.collection.remove(query,justOne) - - The :method:`remove ` method - removes documents from a collection. - - The :method:`remove() ` method can take the - following parameters: - - :param document query: +Definition +---------- - Optional. Specifies the deletion criteria using :doc:`query - operators `. Omit the ``query`` - parameter or pass an empty document (e.g. ``{}`` ) to delete - all :term:`documents ` in the :term:`collection`. +.. method:: db.collection.remove(query,justOne) - :param boolean justOne: + Removes documents from a collection. - Optional. A boolean that limits the deletion to just one - document. The default value is ``false``. Set to ``true`` to - delete only the first result. + .. include:: /reference/method/db.collection.remove-param.rst .. note:: .. include:: /includes/fact-remove-capped-collection-restriction.rst - .. examples-begin - - Consider the following examples of the :method:`remove - ` method. +Examples +-------- - - To remove all documents in a collection, call the - :method:`remove ` method with no - parameters: +The following are examples of the :method:`remove +` method. - .. code-block:: javascript +- To remove all documents in a collection, call the :method:`remove + ` method with no parameters: - db.products.remove() + .. code-block:: javascript - This operation will remove all the documents from the collection - ``products``. + db.products.remove() - - To remove the documents that match a deletion criteria, call the - :method:`remove ` method with the - ``query`` criteria: + This operation will remove all the documents from the collection + ``products``. - .. code-block:: javascript +- To remove the documents that match a deletion criteria, call the + :method:`remove ` method with the ``query`` + criteria: - db.products.remove( { qty: { $gt: 20 } } ) + .. code-block:: javascript - This operation removes all the documents from the collection - ``products`` where ``qty`` is greater than ``20``. + db.products.remove( { qty: { $gt: 20 } } ) - - To remove the first document that match a deletion criteria, call the - :method:`remove ` method with the ``query`` - criteria and the ``justOne`` parameter set to ``true`` or ``1``: + This operation removes all the documents from the collection + ``products`` where ``qty`` is greater than ``20``. - .. code-block:: javascript +- To remove the first document that match a deletion criteria, call the + :method:`remove ` method with the ``query`` + criteria and the ``justOne`` parameter set to ``true`` or ``1``: - db.products.remove( { qty: { $gt: 20 } }, true ) + .. code-block:: javascript - This operation removes the first document from the collection - ``products`` where ``qty`` is greater than ``20``. + db.products.remove( { qty: { $gt: 20 } }, true ) - .. examples-end + This operation removes the first document from the collection + ``products`` where ``qty`` is greater than ``20``. - .. note:: +.. note:: - If the ``query`` argument to the :method:`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` isolation operator, effectively isolating the - delete operation and blocking other write operations during the - delete. To isolate the query, include ``$isolated: 1`` in the - ``query`` parameter as in the following example: + If the ``query`` argument to the :method:`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` + isolation operator, effectively isolating the delete operation and + blocking other write operations during the delete. To isolate the + query, include ``$isolated: 1`` in the ``query`` parameter as in the + following example: - .. code-block:: javascript +.. code-block:: javascript - db.products.remove( { qty: { $gt: 20 }, $isolated: 1 } ) + db.products.remove( { qty: { $gt: 20 }, $isolated: 1 } ) diff --git a/source/reference/method/db.collection.renameCollection-param.yaml b/source/reference/method/db.collection.renameCollection-param.yaml new file mode 100644 index 00000000000..2e7c2e9280d --- /dev/null +++ b/source/reference/method/db.collection.renameCollection-param.yaml @@ -0,0 +1,22 @@ +object: + name: db.collection.renameCollection() + type: method +field: + optional: false + type: param +name: target +type: string +position: 1 +description: "Specifies the new name of the collection. Enclose the string in quotes." +--- +object: + name: db.collection.renameCollection() + type: method +field: + optional: true + type: param +name: dropTarget +type: boolean +position: 2 +description: "If ``true``, :program:`mongod` drops the `target` of :dbcommand:`renameCollection` prior to renaming the collection." +... diff --git a/source/reference/method/db.collection.renameCollection.txt b/source/reference/method/db.collection.renameCollection.txt index 6ef2e478005..a06e49a83b7 100644 --- a/source/reference/method/db.collection.renameCollection.txt +++ b/source/reference/method/db.collection.renameCollection.txt @@ -4,19 +4,16 @@ db.collection.renameCollection() .. default-domain:: mongodb -.. method:: db.collection.renameCollection() +Definition +---------- - :method:`db.collection.renameCollection()` provides a helper for +.. method:: db.collection.renameCollection(target, string) + + Provides a helper for the :dbcommand:`renameCollection` :term:`database command` in the :program:`mongo` shell to rename existing collections. - :param string target: Specifies the new name of the - collection. Enclose the string in quotes. - - :param boolean dropTarget: Optional. If ``true``, :program:`mongod` - will drop the `target` of - :dbcommand:`renameCollection` prior to - renaming the collection. + .. include:: /reference/method/db.collection.renameCollection-param.rst Call the :method:`db.collection.renameCollection()` method on a collection object, to rename a collection. Specify the new name of @@ -30,7 +27,7 @@ db.collection.renameCollection() ``record``. If the target name (i.e. ``record``) is the name of an existing collection, then the operation will fail. - Consider the following limitations: + The method has the following limitations: - :method:`db.collection.renameCollection()` cannot move a collection between databases. Use :dbcommand:`renameCollection` diff --git a/source/reference/method/db.eval-param.yaml b/source/reference/method/db.eval-param.yaml new file mode 100644 index 00000000000..8eaf8d952d4 --- /dev/null +++ b/source/reference/method/db.eval-param.yaml @@ -0,0 +1,27 @@ +object: + name: db.eval() + type: method +field: + optional: false + type: param +name: function +type: JavaScript +position: 1 +description: ".. include:: /includes/parameters-eval.rst + :start-after: eval-param-function + :end-before: eval-param-argument" +--- +object: + name: db.eval() + type: method +field: + optional: false + type: param +name: arguments +type: +position: 2 +description: ".. |list| replace:: A list + .. include:: /includes/parameters-eval.rst + :start-after: eval-param-argument + :end-before: eval-param-nolock" +... diff --git a/source/reference/method/db.eval.txt b/source/reference/method/db.eval.txt index e4ac2d940f7..297b866c8ae 100644 --- a/source/reference/method/db.eval.txt +++ b/source/reference/method/db.eval.txt @@ -7,67 +7,59 @@ db.eval() .. default-domain:: mongodb -.. method:: db.eval(function, arguments) +Definition +---------- - The :method:`db.eval()` provides the ability to run JavaScript code - on the MongoDB server. - - .. include:: /includes/fact-eval-helper-method.rst +.. method:: db.eval(function, arguments) - The method accepts the following parameters: + Provides the ability to run JavaScript code on the MongoDB server. - :param JavaScript function: - .. include:: /includes/parameters-eval.rst - :start-after: eval-param-function - :end-before: eval-param-argument + .. include:: /reference/method/db.eval-param.rst - :param arguments: + .. include:: /includes/fact-eval-helper-method.rst - .. |list| replace:: A list - .. include:: /includes/parameters-eval.rst - :start-after: eval-param-argument - :end-before: eval-param-nolock +Examples +-------- - Consider the following example of the :method:`db.eval()` method: +The following is an example of the :method:`db.eval()` method: - .. include:: /includes/examples-eval.rst - :start-after: .. eval-method-example +.. include:: /includes/examples-eval.rst + :start-after: .. eval-method-example - - The ``db`` in the function refers to the current database. +- The ``db`` in the function refers to the current database. - - ``"eliot"`` is the argument passed to the function, and - corresponds to the ``name`` argument. +- ``"eliot"`` is the argument passed to the function, and corresponds to + the ``name`` argument. - - ``5`` is an argument to the function and corresponds to the - ``incAmount`` field. +- ``5`` is an argument to the function and corresponds to the + ``incAmount`` field. - If you want to use the server's interpreter, you must run - :method:`db.eval()`. Otherwise, the :program:`mongo` shell's - JavaScript interpreter evaluates functions entered directly into the - shell. +If you want to use the server's interpreter, you must run +:method:`db.eval()`. Otherwise, the :program:`mongo` shell's JavaScript +interpreter evaluates functions entered directly into the shell. - If an error occurs, :method:`db.eval()` throws an exception. Consider - the following invalid function that uses the variable ``x`` without - declaring it as an argument: +If an error occurs, :method:`db.eval()` throws an exception. Consider +the following invalid function that uses the variable ``x`` without +declaring it as an argument: - .. code-block:: javascript +.. code-block:: javascript - db.eval( function() { return x + x; }, 3 ); + db.eval( function() { return x + x; }, 3 ); - The statement will result in the following exception: +The statement will result in the following exception: - .. code-block:: javascript +.. code-block:: javascript - { - "errmsg" : "exception: JavaScript execution failed: ReferenceError: x is not defined near '{ return x + x; }' ", - "code" : 16722, - "ok" : 0 - } + { + "errmsg" : "exception: JavaScript execution failed: ReferenceError: x is not defined near '{ return x + x; }' ", + "code" : 16722, + "ok" : 0 + } - .. |object| replace:: :method:`db.eval()` - .. |nolockobject| replace:: :dbcommand:`eval` *command* - .. include:: /includes/admonitions-eval.rst +.. |object| replace:: :method:`db.eval()` +.. |nolockobject| replace:: :dbcommand:`eval` *command* +.. include:: /includes/admonitions-eval.rst - .. seealso:: +.. seealso:: - :doc:`/core/server-side-javascript` + :doc:`/core/server-side-javascript` diff --git a/source/reference/method/db.runCommand-param.yaml b/source/reference/method/db.runCommand-param.yaml new file mode 100644 index 00000000000..93a5aa3d7cc --- /dev/null +++ b/source/reference/method/db.runCommand-param.yaml @@ -0,0 +1,12 @@ +object: + name: db.runCommand() + type: method +field: + optional: false + type: param +name: command +type: + - document + - string +position: 1 +description: "Either specifies a :term:`database command` in the form of a :term:`document` or specifies a :doc:`command ` as a string and :method:`db.runCommand()` transforms the string into the form ``{ command: 1 }``. diff --git a/source/reference/method/db.runCommand.txt b/source/reference/method/db.runCommand.txt index 8b03eac53f0..2edef431539 100644 --- a/source/reference/method/db.runCommand.txt +++ b/source/reference/method/db.runCommand.txt @@ -4,17 +4,17 @@ db.runCommand() .. default-domain:: mongodb -.. method:: db.runCommand(command) - - :param document command: Specifies a :term:`database command` in the - form of a :term:`document`. +Definition +---------- - :param string command: When specifying a :doc:`command - ` as a string, - :method:`db.runCommand()` transforms the - command into the form ``{ command: 1 }``. +.. method:: db.runCommand(command) Provides a helper to run specified :doc:`database commands `. This is the preferred method to issue database commands, as it provides a consistent interface between the shell and drivers. + + .. include:: /reference/method/db.runCommand-param.rst + +.. Examples +.. -------- diff --git a/source/reference/method/db.setProfilingLevel-param.yaml b/source/reference/method/db.setProfilingLevel-param.yaml new file mode 100644 index 00000000000..7adcdc40f87 --- /dev/null +++ b/source/reference/method/db.setProfilingLevel-param.yaml @@ -0,0 +1,25 @@ +object: + name: db.setProfilingLevel() + type: method +field: + optional: false + type: param +name: level +type: integer +position: 1 +description: "Specifies a profiling level: + - ``0`` - Off. No profiling. + - ``1`` - On. Only includes slow operations. + - ``2`` - On. Includes all operations." +--- +object: + name: db.setProfilingLevel() + type: method +field: + optional: true + type: param +name: slowms +type: integer +position: 2 +description: "Sets the threshold in milliseconds for the profile to consider a query or operation to be slow." +... diff --git a/source/reference/method/db.setProfilingLevel.txt b/source/reference/method/db.setProfilingLevel.txt index 8952b0f92ee..70fbf5a5e3b 100644 --- a/source/reference/method/db.setProfilingLevel.txt +++ b/source/reference/method/db.setProfilingLevel.txt @@ -4,19 +4,20 @@ db.setProfilingLevel() .. default-domain:: mongodb -.. method:: db.setProfilingLevel(level, [slowms]) +Definition +---------- - :param level: Specifies a profiling level, see list of possible - values below. +.. method:: db.setProfilingLevel(level, slowms) - :param slowms: Optionally modify the threshold for the profile to - consider a query or operation "slow." + Modifies the current :term:`database profiler` level. The database + profiling system allows administrators to capture data about + performance. - Modifies the current :term:`database profiler` level. This allows - administrators to capture data regarding performance. The database - profiling system can impact performance and can allow the server to - write the contents of queries to the log, which might have information - security implications for your deployment. +.. include:: /reference/method/db.setProfilingLevel-param.rst + + The level of profiling can affect performance. It also can allow the + server to write the contents of queries to the log, which might have + information security implications for your deployment. The following profiling levels are available: @@ -28,7 +29,7 @@ db.setProfilingLevel() 2 On. Includes all operations. ========= ================================== - Also configure the :setting:`slowms` option to set the threshold + Configure the :setting:`slowms` option to set the threshold for the profiler to consider a query "slow." Specify this value in milliseconds to override the default. @@ -43,3 +44,6 @@ db.setProfilingLevel() not active. .. include:: /includes/note-disable-profiling-fsynclock.rst + +.. Examples +.. -------- diff --git a/source/reference/method/rs.reconfig-param.yaml b/source/reference/method/rs.reconfig-param.yaml new file mode 100644 index 00000000000..b2f09c32b82 --- /dev/null +++ b/source/reference/method/rs.reconfig-param.yaml @@ -0,0 +1,22 @@ +object: + name: rs.reconfig() + type: method +field: + optional: false + type: param +name: configuration +type: document +position: 1 +description: "A :term:`document` that specifies the configuration of a replica set." +--- +object: + name: rs.reconfig() + type: method +field: + optional: true + type: param +name: force +type: document +position: 2 +description: "Specify ``{ force: true }`` as the force parameter to force the replica set to accept the new configuration even if a majority of the members are not accessible. Use with caution, as this can lead to term:`rollback` situations." +... diff --git a/source/reference/method/rs.reconfig.txt b/source/reference/method/rs.reconfig.txt index f393302cb3a..b5ce592df1e 100644 --- a/source/reference/method/rs.reconfig.txt +++ b/source/reference/method/rs.reconfig.txt @@ -4,25 +4,17 @@ rs.reconfig() .. default-domain:: mongodb -.. method:: rs.reconfig(configuration[, force]) +Definition +---------- - :param configuration: A :term:`document` that specifies - the configuration of a replica set. +.. method:: rs.reconfig(configuration, force) - :param force: Optional. Specify ``{ force: true }`` as the force - parameter to force the replica set to accept the new - configuration even if a majority of the members are - not accessible. Use with caution, as this can lead to - :term:`rollback` situations. + Initializes a new :term:`replica set` configuration. Disconnects the + shell briefly and forces a reconnection as the replica set + renegotiates which node will be :term:`primary`. As a result, the + shell will display an error even if this command succeeds. - Initializes a new :term:`replica set` configuration. This function - will disconnect the shell briefly and forces a reconnection as the - replica set renegotiates which node will be - :term:`primary`. As a result, the shell will display an error even - if this command succeeds. - - :method:`rs.reconfig()` provides a wrapper around the - ":dbcommand:`replSetReconfig`" :term:`database command`. + .. include:: /reference/method/rs.reconfig-param.rst :method:`rs.reconfig()` overwrites the existing replica set configuration. Retrieve the current configuration object with @@ -30,33 +22,38 @@ rs.reconfig() use :method:`rs.reconfig()` to submit the modified configuration object. - To reconfigure a replica set, use the following sequence of - operations: + :method:`rs.reconfig()` provides a wrapper around the + ":dbcommand:`replSetReconfig`" :term:`database command`. + +Examples +-------- + +To reconfigure a replica set, use the following sequence of operations: - .. code-block:: javascript +.. code-block:: javascript - conf = rs.conf() + conf = rs.conf() - // modify conf to change configuration + // modify conf to change configuration - rs.reconfig(conf) + rs.reconfig(conf) - If you want to force the reconfiguration if a majority of the set - isn't connected to the current member, or you're issuing the - command against a secondary, use the following form: +If you want to force the reconfiguration if a majority of the set is not +connected to the current member, or you are issuing the command against a +secondary, use the following form: - .. code-block:: javascript +.. code-block:: javascript - conf = rs.conf() + conf = rs.conf() - // modify conf to change configuration + // modify conf to change configuration - rs.reconfig(conf, { force: true } ) + rs.reconfig(conf, { force: true } ) - .. warning:: +.. warning:: - Forcing a :method:`rs.reconfig()` can lead to :term:`rollback` - situations and other difficult to recover from - situations. Exercise caution when using this option. + Forcing a :method:`rs.reconfig()` can lead to :term:`rollback` + situations and other difficult to recover from situations. Exercise + caution when using this option. - .. seealso:: ":doc:`/reference/replica-configuration`" and ":doc:`/administration/replica-sets`". +.. seealso:: :doc:`/reference/replica-configuration` and :doc:`/administration/replica-sets`. diff --git a/source/reference/method/sh._adminCommand-param.yaml b/source/reference/method/sh._adminCommand-param.yaml new file mode 100644 index 00000000000..c5e5c3bc100 --- /dev/null +++ b/source/reference/method/sh._adminCommand-param.yaml @@ -0,0 +1,22 @@ +object: + name: sh._adminCommand() + type: method +field: + optional: false + type: param +name: command +type: string +position: 1 +description: "A database command to run against the ``admin`` database." +--- +object: + name: sh._adminCommand() + type: method +field: + optional: false + type: param +name: checkMongos +type: boolean +position: 2 +description: "Verifies whether the shell is connected to a :program:`mongos` instance." +... diff --git a/source/reference/method/sh._adminCommand.txt b/source/reference/method/sh._adminCommand.txt index dd366f69e5b..bf11ec62109 100644 --- a/source/reference/method/sh._adminCommand.txt +++ b/source/reference/method/sh._adminCommand.txt @@ -4,15 +4,17 @@ sh._adminCommand() .. default-domain:: mongodb -.. method:: sh._adminCommand(cmd, checkMongos) +Definition +---------- - :param string dbcommand: A database command to run against the ``admin`` - database. +.. method:: sh._adminCommand(command, checkMongos) - :param Boolean checkMongos: Verify whether or not the shell is connected - to a :program:`mongos` instance. - - The :method:`sh._adminCommand` method runs a database command against - the admin database of a :program:`mongos` instance. - -.. seealso:: :method:`db.runCommand()` + Runs a database command against the admin database of a + :program:`mongos` instance. + + .. include:: /reference/method/sh._adminCommand-param.rst + + .. seealso:: :method:`db.runCommand()` + +.. Examples +.. -------- diff --git a/source/reference/method/sh.addShardTag-param.yaml b/source/reference/method/sh.addShardTag-param.yaml new file mode 100644 index 00000000000..8b7c40fc86e --- /dev/null +++ b/source/reference/method/sh.addShardTag-param.yaml @@ -0,0 +1,22 @@ +object: + name: sh.addShardTag() + type: method +field: + optional: false + type: param +name: shard +type: string +position: 1 +description: "Specifies the name of the shard to which to give a specific tag." +--- +object: + name: sh.addShardTag() + type: method +field: + optional: false + type: param +name: tag +type: string +position: 2 +description: "Specifies the name of the tag to add to the shard." +... diff --git a/source/reference/method/sh.addShardTag.txt b/source/reference/method/sh.addShardTag.txt index 205e90892d0..c36c2452b05 100644 --- a/source/reference/method/sh.addShardTag.txt +++ b/source/reference/method/sh.addShardTag.txt @@ -4,37 +4,34 @@ sh.addShardTag() .. default-domain:: mongodb +Definition +---------- + .. method:: sh.addShardTag(shard, tag) .. versionadded:: 2.2 - :param string shard: Specifies the name of the shard that you want to give - a specific tag. - - :param string tag: Specifies the name of the tag that you want to add to - the shard. - - :method:`sh.addShardTag()` associates a shard with a tag or - identifier. - MongoDB uses these identifiers to direct :term:`chunks ` - that fall within a tagged range to specific shards. + Associates a shard with a tag or identifier. MongoDB uses these + identifiers to direct :term:`chunks ` that fall within a + tagged range to specific shards. :method:`sh.addTagRange()` + associates chunk ranges with tag ranges. - :method:`sh.addTagRange()` associates chunk ranges with tag - ranges. + .. include:: /reference/method/sh.addShardTag-param.rst Always issue :method:`sh.addShardTag()` when connected to a :program:`mongos` instance. - .. example:: +Example +------- - The following example adds three tags, ``NYC``, ``LAX``, and - ``NRT``, to three shards: +The following example adds three tags, ``NYC``, ``LAX``, and ``NRT``, to +three shards: - .. code-block:: javascript +.. code-block:: javascript - sh.addShardTag("shard0000", "NYC") - sh.addShardTag("shard0001", "LAX") - sh.addShardTag("shard0002", "NRT") + sh.addShardTag("shard0000", "NYC") + sh.addShardTag("shard0001", "LAX") + sh.addShardTag("shard0002", "NRT") .. seealso:: diff --git a/source/reference/method/sh.removeShardTag-param.yaml b/source/reference/method/sh.removeShardTag-param.yaml new file mode 100644 index 00000000000..97c1797fb6d --- /dev/null +++ b/source/reference/method/sh.removeShardTag-param.yaml @@ -0,0 +1,22 @@ +object: + name: sh.removeShardTag() + type: method +field: + optional: false + type: param +name: shard +type: string +position: 1 +description: "Specifies the name of the shard from which to remove a tag." +--- +object: + name: sh.removeShardTag() + type: method +field: + optional: false + type: param +name: tag +type: string +position: 2 +description: "Specifies the name of the tag to remove from the shard." +... diff --git a/source/reference/method/sh.removeShardTag.txt b/source/reference/method/sh.removeShardTag.txt index a3dd81d3ec1..362d631b5de 100644 --- a/source/reference/method/sh.removeShardTag.txt +++ b/source/reference/method/sh.removeShardTag.txt @@ -4,22 +4,23 @@ sh.removeShardTag() .. default-domain:: mongodb +Definition +---------- + .. method:: sh.removeShardTag(shard, tag) .. versionadded:: 2.2 - :param string shard: Specifies the name of the shard that you want - to remove a tag from. - - :param string tag: Specifies the name of the tag that you want to remove - from the shard. + Removes the association between a tag and a shard. Always issue + :method:`sh.removeShardTag()` when connected to a :program:`mongos` + instance. - Removes the association between a tag and a shard. - - Always issue :method:`sh.removeShardTag()` when connected to a - :program:`mongos` instance. + .. include:: /reference/method/sh.removeShardTag-param.rst .. seealso:: :method:`sh.addShardTag()`, :method:`sh.addTagRange()` + +.. Examples +.. -------- diff --git a/source/reference/method/sh.splitAt-param.yaml b/source/reference/method/sh.splitAt-param.yaml new file mode 100644 index 00000000000..6d1fa55c080 --- /dev/null +++ b/source/reference/method/sh.splitAt-param.yaml @@ -0,0 +1,22 @@ +object: + name: sh.splitAt() + type: method +field: + optional: false + type: param +name: namespace +type: string +position: 1 +description: "Specify the namespace (i.e. ``.``) of the sharded collection that contains the chunk to split." +--- +object: + name: sh.splitAt() + type: method +field: + optional: false + type: param +name: query +type: document +position: 2 +description: "Specify a query to identify a document in a specific chunk. Typically specify the :term:`shard key` for a document as the query." +... diff --git a/source/reference/method/sh.splitAt.txt b/source/reference/method/sh.splitAt.txt index bd0ebd44503..05714095fd5 100644 --- a/source/reference/method/sh.splitAt.txt +++ b/source/reference/method/sh.splitAt.txt @@ -4,27 +4,26 @@ sh.splitAt() .. default-domain:: mongodb +Definition +---------- + .. method:: sh.splitAt(namespace, query) - :param string namespace: Specify the namespace - (i.e. "``.``") of - the sharded collection that contains the - chunk to split. + Splits the chunk containing the document specified by the query as if + that document were at the "middle" of the collection, even if the + specified document is not the actual median of the collection. - :param document query: Specify a query to identify a document in a - specific chunk. Typically specify the - :term:`shard key` for a document as the - query. + .. include:: /reference/method/sh.splitAt-param.rst - Splits the chunk containing the document specified by the ``query`` - as if that document were at the "middle" of the collection, even if - the specified document is not the actual median of the - collection. Use this command to manually split chunks unevenly. Use - the ":method:`sh.splitFind()`" function to split a chunk at the - actual median. + Use this command to manually split chunks unevenly. Use the + ":method:`sh.splitFind()`" function to split a chunk at the actual + median. In most circumstances, you should leave chunk splitting to the - automated processes within MongoDB. However, when initially - deploying a :term:`sharded cluster` it is necessary to perform some - measure of :term:`pre-splitting` using manual methods including + automated processes within MongoDB. However, when initially deploying + a :term:`sharded cluster` it is necessary to perform some measure of + :term:`pre-splitting` using manual methods including :method:`sh.splitAt()`. + +.. Examples +.. -------- diff --git a/source/reference/method/sh.splitFind-param.yaml b/source/reference/method/sh.splitFind-param.yaml new file mode 100644 index 00000000000..e80a34045fb --- /dev/null +++ b/source/reference/method/sh.splitFind-param.yaml @@ -0,0 +1,22 @@ +object: + name: sh.splitFind() + type: method +field: + optional: false + type: param +name: namespace +type: string +position: 1 +description: "Specify the namespace (i.e. ``.``) of the sharded collection that contains the chunk to split." +--- +object: + name: sh.splitFind() + type: method +field: + optional: false + type: param +name: query +type: document +position: 2 +description: "Specify a query to identify a document in a specific chunk. Typically specify the :term:`shard key` for a document as the query." +... diff --git a/source/reference/method/sh.splitFind.txt b/source/reference/method/sh.splitFind.txt index 39b98ce1dd7..7630f46c9a9 100644 --- a/source/reference/method/sh.splitFind.txt +++ b/source/reference/method/sh.splitFind.txt @@ -4,16 +4,10 @@ sh.splitFind() .. default-domain:: mongodb -.. method:: sh.splitFind(namespace, query) - - :param string namespace: Specify the namespace - (i.e. "``.``") of - the sharded collection that contains the - chunk to split. +Definition +---------- - :param query: Specify a query to identify a document in a specific - chunk. Typically specify the :term:`shard key` for a - document as the query. +.. method:: sh.splitFind(namespace, query) Splits the chunk containing the document specified by the ``query`` at its median point, creating two roughly equal chunks. Use @@ -24,3 +18,8 @@ sh.splitFind() :term:`sharded cluster` it is necessary to perform some measure of :term:`pre-splitting` using manual methods including :method:`sh.splitFind()`. + + .. include:: /reference/method/sh.splitFind-param.rst + +.. Examples +.. -------- diff --git a/source/reference/method/sh.startBalancer-param.yaml b/source/reference/method/sh.startBalancer-param.yaml new file mode 100644 index 00000000000..dc28c3e0f49 --- /dev/null +++ b/source/reference/method/sh.startBalancer-param.yaml @@ -0,0 +1,22 @@ +object: + name: sh.startBalancer() + type: method +field: + optional: false + type: param +name: timeout +type: integer +position: 1 +description: "Milliseconds to wait." +--- +object: + name: sh.startBalancer() + type: method +field: + optional: false + type: param +name: interval +type: integer +position: 2 +description: "Milliseconds to sleep each cycle of waiting." +... diff --git a/source/reference/method/sh.startBalancer.txt b/source/reference/method/sh.startBalancer.txt index 27c81a87aa6..154ee0e1663 100644 --- a/source/reference/method/sh.startBalancer.txt +++ b/source/reference/method/sh.startBalancer.txt @@ -4,14 +4,15 @@ sh.startBalancer() .. default-domain:: mongodb +Definition +---------- + .. method:: sh.startBalancer(timeout, interval) - - :param integer timeout: Milliseconds to wait. - - :param integer interval: Milliseconds to sleep each cycle of waiting. - - The :method:`sh.startBalancer()` enables the balancer in a sharded - cluster and waits for balancing to initiate. + + Enables the balancer in a sharded cluster and waits for balancing to + initiate. + + .. include:: /reference/method/sh.startBalancer-param.rst .. seealso:: @@ -24,3 +25,6 @@ sh.startBalancer() - :method:`sh.stopBalancer()` - :method:`sh.waitForBalancer()` - :method:`sh.waitForBalancerOff()` + +.. Examples +.. -------- diff --git a/source/reference/method/sh.stopBalancer-param.yaml b/source/reference/method/sh.stopBalancer-param.yaml new file mode 100644 index 00000000000..5fcda7f32a0 --- /dev/null +++ b/source/reference/method/sh.stopBalancer-param.yaml @@ -0,0 +1,22 @@ +object: + name: sh.stopBalancer() + type: method +field: + optional: false + type: param +name: timeout +type: integer +position: 1 +description: "Milliseconds to wait." +--- +object: + name: sh.stopBalancer() + type: method +field: + optional: false + type: param +name: interval +type: integer +position: 2 +description: "Milliseconds to sleep each cycle of waiting." +... diff --git a/source/reference/method/sh.stopBalancer.txt b/source/reference/method/sh.stopBalancer.txt index 86f395a8c91..4e9664b6f13 100644 --- a/source/reference/method/sh.stopBalancer.txt +++ b/source/reference/method/sh.stopBalancer.txt @@ -4,15 +4,16 @@ sh.stopBalancer() .. default-domain:: mongodb +Definition +---------- + .. method:: sh.stopBalancer(timeout, interval) - - :param integer timeout: Milliseconds to wait. - - :param integer interval: Milliseconds to sleep each cycle of waiting. - - The :method:`sh.stopBalancer()` disables the balancer in a sharded - cluster and waits for balancing to complete. - + + Disables the balancer in a sharded cluster and waits for balancing to + complete. + + .. include:: /reference/method/sh.stopBalancer-param.rst + .. seealso:: - :method:`sh.enableBalancing()` @@ -24,3 +25,6 @@ sh.stopBalancer() - :method:`sh.startBalancer()` - :method:`sh.waitForBalancer()` - :method:`sh.waitForBalancerOff()` + +.. Examples +.. -------- diff --git a/source/reference/method/sh.waitForBalancerOff-param.yaml b/source/reference/method/sh.waitForBalancerOff-param.yaml new file mode 100644 index 00000000000..2459250d54c --- /dev/null +++ b/source/reference/method/sh.waitForBalancerOff-param.yaml @@ -0,0 +1,22 @@ +object: + name: sh.waitForBalancerOff() + type: method +field: + optional: false + type: param +name: timeout +type: integer +position: 1 +description: "Milliseconds to wait." +--- +object: + name: sh.waitForBalancerOff() + type: method +field: + optional: false + type: param +name: interval +type: integer +position: 2 +description: "Milliseconds to sleep." +... diff --git a/source/reference/method/sh.waitForBalancerOff.txt b/source/reference/method/sh.waitForBalancerOff.txt index 6f878017cbb..5b3679ee9ab 100644 --- a/source/reference/method/sh.waitForBalancerOff.txt +++ b/source/reference/method/sh.waitForBalancerOff.txt @@ -4,14 +4,14 @@ sh.waitForBalancerOff() .. default-domain:: mongodb -.. method:: sh.waitForBalancerOff() +Definition +---------- - :param integer timeout: Milliseconds to wait. - - :param integer interval: Milliseconds to sleep. +.. method:: sh.waitForBalancerOff(timeout, interval) - :method:`sh.waitForBalancerOff()` is an internal method that waits - until the balancer is not running. + Internal method that waits until the balancer is not running. + + .. include:: /reference/method/sh.waitForBalancerOff-param.rst .. seealso:: @@ -24,3 +24,6 @@ sh.waitForBalancerOff() - :method:`sh.startBalancer()` - :method:`sh.stopBalancer()` - :method:`sh.waitForBalancer()` + +.. Examples +.. --------