From e44e03eb3a89719f038faef882812573906ace14 Mon Sep 17 00:00:00 2001 From: Andrew Aldridge Date: Mon, 13 Jul 2015 18:38:57 -0400 Subject: [PATCH] DOCS-5834: Update cloneCollection and db.cloneCollection() --- ...iargs-dbcommand-cloneCollection-field.yaml | 5 ++-- ...iargs-method-db.cloneCollection-param.yaml | 12 +++++---- source/includes/extracts-cloneCollection.yaml | 24 ++++++++++++++++++ source/reference/command/cloneCollection.txt | 19 ++++++-------- .../command/cloneCollectionAsCapped.txt | 25 +++++++++++-------- .../reference/method/db.cloneCollection.txt | 9 ++++--- source/release-notes/3.0-compatibility.txt | 9 ++++++- 7 files changed, 68 insertions(+), 35 deletions(-) create mode 100644 source/includes/extracts-cloneCollection.yaml diff --git a/source/includes/apiargs-dbcommand-cloneCollection-field.yaml b/source/includes/apiargs-dbcommand-cloneCollection-field.yaml index 90fe0183cc4..265963445dd 100644 --- a/source/includes/apiargs-dbcommand-cloneCollection-field.yaml +++ b/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 diff --git a/source/includes/apiargs-method-db.cloneCollection-param.yaml b/source/includes/apiargs-method-db.cloneCollection-param.yaml index c466f7b42e8..cd2408e4a8d 100644 --- a/source/includes/apiargs-method-db.cloneCollection-param.yaml +++ b/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 diff --git a/source/includes/extracts-cloneCollection.yaml b/source/includes/extracts-cloneCollection.yaml new file mode 100644 index 00000000000..a50abaa6adc --- /dev/null +++ b/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()` +... diff --git a/source/reference/command/cloneCollection.txt b/source/reference/command/cloneCollection.txt index 9c0df983e17..b3b913ab279 100644 --- a/source/reference/command/cloneCollection.txt +++ b/source/reference/command/cloneCollection.txt @@ -19,27 +19,24 @@ Definition { cloneCollection: "", from: "", 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. diff --git a/source/reference/command/cloneCollectionAsCapped.txt b/source/reference/command/cloneCollectionAsCapped.txt index 67ddc3e65a6..853aa1a5b81 100644 --- a/source/reference/command/cloneCollectionAsCapped.txt +++ b/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 ` 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. diff --git a/source/reference/method/db.cloneCollection.txt b/source/reference/method/db.cloneCollection.txt index 58bac551040..b77e4d217c4 100644 --- a/source/reference/method/db.cloneCollection.txt +++ b/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 diff --git a/source/release-notes/3.0-compatibility.txt b/source/release-notes/3.0-compatibility.txt index 1507d7be8a4..ed7b0d6ace4 100644 --- a/source/release-notes/3.0-compatibility.txt +++ b/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.