DOCS-5834: Update cloneCollection and db.cloneCollection()

source/includes/apiargs-dbcommand-cloneCollection-field.yaml

@@ -11,8 +11,7 @@ type: string
 ---
 arg_name: field
 description: |
-  Specify a resolvable hostname and optional port number of the remote
-  server where the specified collection resides.
+  The address of the server to clone from.
 interface: dbcommand
 name: from
 operation: cloneCollection
@@ -22,7 +21,7 @@ type: string
 ---
 arg_name: field
 description: |
-  A query that filters the documents in the remote collection that
+  A query that filters the documents in the source collection that
   :dbcommand:`cloneCollection` will copy to the current database.
 interface: dbcommand
 name: query

source/includes/apiargs-method-db.cloneCollection-param.yaml

@@ -1,6 +1,7 @@
 arg_name: param
-description: |
-  Host name of the MongoDB instance that holds the collection to copy.
+source:
+  file: apiargs-dbcommand-cloneCollection-field.yaml
+  ref: from
 interface: method
 name: from
 operation: db.cloneCollection
@@ -13,9 +14,10 @@ description: |
   The collection in the MongoDB instance that you want to copy.
   :method:`db.cloneCollection()` will only copy the collection with this
   name from *database* of the same name as the current database the
-  remote MongoDB instance. If you want to copy a collection from a
-  different database name you must use the :dbcommand:`cloneCollection`
-  directly.
+  remote MongoDB instance.
+
+  If you want to copy a collection from a different database name you must use
+  the :dbcommand:`cloneCollection` directly.
 interface: method
 name: collection
 operation: db.cloneCollection

source/includes/extracts-cloneCollection.yaml

@@ -0,0 +1,24 @@
+ref: _cloneCollection-behavior
+content: |
+   :program:`mongos` does not support {{cloneCollection}}.
+
+   .. versionchanged:: 3.0
+
+      If the given :term:`namespace` already exists in the destination
+      :program:`mongod` instance, {{cloneCollection}} will return an
+      error.
+---
+ref: cloneCollection-behavior-dbcommand
+inherit:
+  file: extracts-cloneCollection.yaml
+  ref: _cloneCollection-behavior
+replacement:
+  cloneCollection: :dbcommand:`cloneCollection`
+---
+ref: cloneCollection-behavior-method
+inherit:
+  file: extracts-cloneCollection.yaml
+  ref: _cloneCollection-behavior
+replacement:
+  cloneCollection: :method:`db.cloneCollection()`
+...

source/reference/command/cloneCollection.txt

@@ -19,27 +19,24 @@ Definition
 
       { cloneCollection: "<namespace>", from: "<hostname>", query: { <query> } }
 
-   .. important:: You cannot clone a collection through a
-      :program:`mongos` but must connect directly to the
-      :program:`mongod` instance.
-
    :dbcommand:`cloneCollection` has the following fields:
 
    .. include:: /includes/apiargs/dbcommand-cloneCollection-field.rst
 
+Behavior
+--------
+
+.. include:: /includes/extracts/cloneCollection-behavior-dbcommand.rst
+
 Example
 -------
 
 .. code-block:: javascript
 
-   { cloneCollection: "users.profiles", from: "mongodb.example.net:27017", query: { active: true } }
+   { cloneCollection: "users.profiles",
+     from: "mongodb.example.net:27017",
+     query: { active: true } }
 
 This operation copies the ``profiles`` collection from the ``users``
 database on the server at ``mongodb.example.net``. The operation only
 copies documents that satisfy the query ``{ active: true }``.
-:dbcommand:`cloneCollection` always copies indexes. The ``query``
-arguments is optional.
-
-If, in the above example, the ``profiles`` collection exists in the
-``users`` database, then MongoDB appends documents from the remote
-collection to the destination collection.

source/reference/command/cloneCollectionAsCapped.txt

@@ -4,6 +4,9 @@ cloneCollectionAsCapped
 
 .. default-domain:: mongodb
 
+Definition
+----------
+
 .. dbcommand:: cloneCollectionAsCapped
 
    The :dbcommand:`cloneCollectionAsCapped` command creates a new
@@ -19,18 +22,18 @@ cloneCollectionAsCapped
 
    The command copies an ``existing collection`` and creates a new
    ``capped collection`` with a maximum size specified by the ``capped
-   size`` in bytes. The name of the new capped collection must be
+   size`` in bytes.
+
+   The name of the new capped collection must be
    distinct and cannot be the same as that of the original existing
-   collection. To replace the original non-capped collection with a
-   capped collection, use the :dbcommand:`convertToCapped` command.
+   collection.
 
-   During the cloning, the :dbcommand:`cloneCollectionAsCapped` command
-   exhibit the following behavior:
+   To replace the original non-capped collection with a
+   capped collection, use the :dbcommand:`convertToCapped` command.
 
-   - MongoDB will transverse the documents in the original collection
-     in :term:`natural order <natural order>` as they're loaded.
+Behavior
+--------
 
-   - If the ``capped size`` specified for the new collection is
-     smaller than the size of the original uncapped collection, then
-     MongoDB will begin overwriting earlier documents in
-     insertion order, which is *first in, first out* (e.g "FIFO").
+If the ``capped size`` is less than the size of the source collection,
+then not all documents in the source collection will exist in the destination
+capped collection.

source/reference/method/db.cloneCollection.txt

@@ -10,12 +10,13 @@ Definition
 .. method:: db.cloneCollection(from, collection, query)
 
    Copies data directly between MongoDB instances. The
-   :method:`db.cloneCollection()` wraps the
+   :method:`db.cloneCollection()` method wraps the
    :dbcommand:`cloneCollection` database command and accepts the
    following arguments:
 
    .. include:: /includes/apiargs/method-db.cloneCollection-param.rst
 
-   :method:`db.cloneCollection()` does not allow you to
-   clone a collection through a :program:`mongos`. You must connect
-   directly to the :program:`mongod` instance.
+Behavior
+--------
+
+.. include:: /includes/extracts/cloneCollection-behavior-method.rst

source/release-notes/3.0-compatibility.txt

@@ -304,7 +304,7 @@ If you are currently using ``auth`` and you have schema version 2 or 3,
 the query returns the ``currentVersion`` of the existing ``authSchema``.
 
 If you do not currently have any users *or* you are using
-``authSchema`` version 1, the query will not return any result. 
+``authSchema`` version 1, the query will not return any result.
 
 If your ``authSchema`` version is less
 than ``3`` or the query does not return any results, see :doc:`/release-notes/2.6-upgrade-authorization` to
@@ -551,3 +551,10 @@ Unix domain socket file permission now defaults to ``0700``. To change
 the permission, MongoDB provides the
 :setting:`net.unixDomainSocket.filePermissions` setting as well as the
 ``--filePermission`` option.
+
+``cloneCollection``
+~~~~~~~~~~~~~~~~~~~
+
+The :dbcommand:`cloneCollection` command and the :method:`db.cloneCollection()`
+method will now return an error if the collection already exists, instead of
+inserting into it.