diff --git a/source/reference/command/configureFailPoint-field.yaml b/source/reference/command/configureFailPoint-field.yaml new file mode 100644 index 00000000000..c11586c89df --- /dev/null +++ b/source/reference/command/configureFailPoint-field.yaml @@ -0,0 +1,26 @@ +object: + name: configureFailPoint + type: dbcommand +field: + optional: false + type: field +name: configureFailPoint +type: string +position: 1 +description: "The name of the failure point." +--- +object: + name: configureFailPoint + type: dbcommand +field: + optional: false + type: field +name: mode +type: field +type: document +position: 2 +description: | + Controls behavior of failure point. Possible values are: ``alwaysOn``, + ``off``, or a document, ``{times: n}``, that specifies the number of + times that MongoDB activates the failure point. +... diff --git a/source/reference/command/configureFailPoint.txt b/source/reference/command/configureFailPoint.txt index e9688aef6eb..79cc4a52eee 100644 --- a/source/reference/command/configureFailPoint.txt +++ b/source/reference/command/configureFailPoint.txt @@ -4,19 +4,29 @@ configureFailPoint .. default-domain:: mongodb +Definition +---------- + .. dbcommand:: configureFailPoint - :dbcommand:`configureFailPoint` is an internal testing command that - configures failure points. + Configures failure points. Issue the :dbcommand:`configureFailPoint` + command against the :term:`admin database`. The command takes the + following form: + + .. code-block:: javascript + + {configureFailPoint: "", mode: } + + The command contains the following fields: + + .. include:: /reference/command/configureFailPoint-field.rst - :param string: Specifies the name of the failure point. +Example +------- - :param string mode: Controls behavior of failure point. Possible - values are: ``alwaysOn`` and ``off``. + .. code-block:: javascript - :param mode: Specify a document ``{times: n}`` - to control the number of times that MongoDB will - activate the failure point. + db.adminCommand( { configureFailPoint: "pingPongPoint", mode: {times: 21} } ) .. |dbcommand| replace:: :dbcommand:`configureFailPoint` .. include:: /includes/note-enabletestcommands.rst diff --git a/source/reference/command/distinct-field.yaml b/source/reference/command/distinct-field.yaml new file mode 100644 index 00000000000..da97ee3d8b1 --- /dev/null +++ b/source/reference/command/distinct-field.yaml @@ -0,0 +1,37 @@ +object: + name: distinct + type: dbcommand +field: + optional: false + type: field +name: collection +type: string +position: 1 +description: | + The name of the collection to query for distinct values. +--- +object: + name: distinct + type: dbcommand +field: + optional: false + type: field +name: field +type: string +position: 2 +description: | + The field for which to return the distinct values. +--- +object: + name: distinct + type: dbcommand +field: + optional: true + type: field +name: query +type: document +position: 3 +description: | + The query to determine the subset of documents from which to retrieve + the distinct values. +... diff --git a/source/reference/command/distinct.txt b/source/reference/command/distinct.txt index cf1af8c89a6..3a50d7f94c6 100644 --- a/source/reference/command/distinct.txt +++ b/source/reference/command/distinct.txt @@ -4,70 +4,59 @@ distinct .. default-domain:: mongodb +Definition +---------- + .. dbcommand:: distinct - The :dbcommand:`distinct` command finds the distinct values for a - specified field across a single collection. The command returns a - document that contains an array of the distinct values as well as - the query plan and status. The command takes the following prototype - form: + Finds the distinct values for a specified field across a single + collection. The command returns a document that contains an array of + the distinct values and that contains a subdocument with query + statistics and the query plan. When possible, the + :dbcommand:`distinct` command uses an index to find documents and + return values. + + The command takes the following form: .. code-block:: javascript - { distinct: collection, key: , query: } + { distinct: "", key: "", query: } + + The command contains the following fields: - The command fields are as follows: - - :field String collection: - - The name of the collection to query for distinct values. + .. include:: /reference/command/distinct-field.rst - :field string field: - - Specifies the field for which to return the distinct values. - - :field document query: - - Optional. Specifies the selection ``query`` to determine the - subset of documents from which to retrieve the distinct - values. +Examples +-------- - Consider the following examples of the :dbcommand:`distinct` command: +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.runCommand ( { distinct: "orders", key: "ord_dt" } ) - db.runCommand ( { distinct: 'orders', key: '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.runCommand ( { distinct: "orders", key: "item.sku" } ) - db.runCommand ( { distinct: 'orders', key: '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.runCommand ( { distinct: "orders", + key: "ord_dt", + query: { price: { $gt: 10 } } + } ) - db.runCommand ( { distinct: 'orders', - key: 'ord_dt', - query: { price: { $gt: 10 } } - } ) +.. note:: - .. note:: - - - MongoDB also provides the shell wrapper method - :method:`db.collection.distinct()` for the - :dbcommand:`distinct` command. Additionally, many MongoDB - :term:`drivers ` also provide a wrapper method. Refer - to the specific driver documentation. - - - When possible, the :dbcommand:`distinct` command will use an - index to find the documents in the query as well as to return - the data. + MongoDB also provides the shell wrapper method + :method:`db.collection.distinct()` for the :dbcommand:`distinct` + command. Additionally, many MongoDB :term:`drivers ` also + provide a wrapper method. Refer to the specific driver documentation. diff --git a/source/reference/command/renameCollection-field.yaml b/source/reference/command/renameCollection-field.yaml new file mode 100644 index 00000000000..f466d5c7d88 --- /dev/null +++ b/source/reference/command/renameCollection-field.yaml @@ -0,0 +1,40 @@ +object: + name: renameCollection + type: dbcommand +field: + optional: false + type: field +name: renameCollection +type: string +position: 1 +description: | + The :term:`namespace` of the collection to rename. The namespace is a + combination of the database name and the name of the collection. +--- +object: + name: renameCollection + type: dbcommand +field: + optional: false + type: field +name: to +type: string +position: 2 +description: | + The new namespace of the collection. If the new namespace specifies a + different database, the :dbcommand:`renameCollection` command copies + the collection to the new database and drops the source collection. +--- +object: + name: renameCollection + type: dbcommand +field: + optional: true + type: field +name: dropTarget +type: boolean +position: 3 +description: | + If ``true``, :program:`mongod` will drop the ``target`` of + :dbcommand:`renameCollection` prior to renaming the collection. +... diff --git a/source/reference/command/renameCollection.txt b/source/reference/command/renameCollection.txt index a10e708d1b8..008f61e0657 100644 --- a/source/reference/command/renameCollection.txt +++ b/source/reference/command/renameCollection.txt @@ -4,38 +4,46 @@ renameCollection .. default-domain:: mongodb +Definition +---------- + .. dbcommand:: renameCollection - The :dbcommand:`renameCollection` command is an administrative - command that changes the name of an existing collection. You - specify collections to :dbcommand:`renameCollection` in the form of - a complete :term:`namespace`, which includes the database name. To - rename a collection, issue the :dbcommand:`renameCollection` - command against the :term:`admin database` in the form: + Changes the name of an existing collection. You specify collections + to :dbcommand:`renameCollection` in the form of a complete + :term:`namespace`, which includes the database name. Issue the + :dbcommand:`renameCollection` command against the :term:`admin + database`. The command takes the following form: .. code-block:: javascript - { renameCollection: , to: [, dropTarget: ] } + { renameCollection: "", to: "", dropTarget: } - The ``dropTarget`` argument is optional. + The command contains the following fields: - If you specify a collection to the ``to`` argument in a different database, the - :dbcommand:`renameCollection` command will copy the collection to the new - database and then drop the source collection. + .. include:: /reference/command/renameCollection-field.rst - :param source-namespace: + You can use :dbcommand:`renameCollection` in production + environments; however: - Specifies the complete namespace of the collection to rename. + - :dbcommand:`renameCollection` will block all database activity + for the duration of the operation. - :param string to: + - :dbcommand:`renameCollection` is incompatible with sharded + collections. - Specifies the new namespace of the collection. + .. warning:: - :param boolean dropTarget: + :dbcommand:`renameCollection` will fail if + `target` is the name of an existing collection + and you do not specify ``dropTarget: true``. + + If the :dbcommand:`renameCollection` operation does not complete + the ``target`` collection and indexes will not be usable and + will require manual intervention to clean up. - Optional. If ``true``, :program:`mongod` will drop the - ``target`` of :dbcommand:`renameCollection` prior to renaming - the collection. +Exceptions +---------- :exception 10026: @@ -51,24 +59,8 @@ renameCollection Raised if the ``target`` namespace is an invalid collection name. - You can use :dbcommand:`renameCollection` in production - environments; however: - - - :dbcommand:`renameCollection` will block all database activity - for the duration of the operation. - - - :dbcommand:`renameCollection` is incompatible with sharded - collections. - - .. warning:: - - :dbcommand:`renameCollection` will fail if - `target` is the name of an existing collection - and you do not specify ``dropTarget: true``. - - If the :dbcommand:`renameCollection` operation does not complete - the ``target`` collection and indexes will not be usable and - will require manual intervention to clean up. +Shell Helper +------------ The shell helper :method:`db.collection.renameCollection()` provides a simpler interface to using this command within a database.