DOCS-8118: add new namespace options to mongorestore

source/includes/extracts-mongorestore-ns-pattern.yaml

@@ -0,0 +1,64 @@
+ref: _ns-pattern-simple
+content: |
+  {{role}} accepts a *namespace pattern* as its argument. The namespace
+  pattern permits {{role}} to refer to any namespace that matches the
+  specified pattern. {{program}} matches the smallest valid occurence
+  of the namespace pattern.
+
+  Use asterisks (``*``) as wild cards. Escape all literal asterisks
+  and backslashes with a backslash. :ref:`example-basic-wildcard-usage`
+  provides an example of using asterisks as wild cards.
+---
+ref: ns-pattern-simple-include
+inherit:
+  ref: _ns-pattern-simple
+  file: extracts-mongorestore-ns-pattern.yaml
+replacement:
+  role: ":option:`--nsInclude`"
+  program: ":program:`mongorestore`"
+---
+ref: ns-pattern-simple-exclude
+inherit:
+  ref: _ns-pattern-simple
+  file: extracts-mongorestore-ns-pattern.yaml
+replacement:
+  role: ":option:`--nsExclude`"
+  program: ":program:`mongorestore`"
+---
+ref: _ns-pattern-complex
+content: |
+  {{role}} accepts a *namespace pattern* as its argument. The namespace
+  pattern permits {{role}} to refer to any namespace that matches the
+  specified pattern. {{program}} matches the smallest valid occurence
+  of the namespace pattern.
+
+  For simple replacements, use asterisks (``*``) as wild cards.
+  Escape all literal asterisks and backslashes with a backslash.
+  Replacements correspond linearly to matches: each asterisk in
+  ``--nsFrom`` must correspond to an asterisk in ``--nsTo``, and the
+  first asterisk in ``--nsFrom`` matches the first asterisk in ``nsTo``.
+
+  For more complex replacements, use dollar signs to delimit a "wild
+  card" variable to use in the replacement.
+  :ref:`example-complex-wildcard-usage` provides an example of complex
+  replacements with dollar sign-delimited wild cards.
+
+  Unlike replacements with asterisks, replacements with dollar
+  sign-delimited wild cards do **not** need to be linear.
+---  
+ref: ns-pattern-complex-from
+inherit:
+  ref: _ns-pattern-complex
+  file: extracts-mongorestore-ns-pattern.yaml
+replacement:
+  role: ":option:`--nsFrom`"
+  program: ":program:`mongorestore`"
+---
+ref: ns-pattern-complex-to
+inherit:
+  ref: _ns-pattern-complex
+  file: extracts-mongorestore-ns-pattern.yaml
+replacement:
+  role: ":option:`--nsTo`"
+  program: ":program:`mongorestore`"
+...

source/includes/options-mongorestore.yaml

@@ -415,4 +415,92 @@ inherit:
   file: options-shared.yaml
 replacement:
   verb: "insert"
+---
+program: mongorestore
+name: nsExclude
+directive: option
+args: <namespace pattern>
+pre: |
+  .. versionadded:: 3.4
+
+description: |
+  Excludes the specified :term:`namespaces <namespace>` from the
+  restore operation.
+post: |
+  .. include:: /includes/extracts/ns-pattern-simple-exclude.rst
+optional: true
+---
+program: mongorestore
+name: nsInclude
+directive: option
+args: <namespace pattern>
+pre: |
+  .. versionadded:: 3.4
+
+description: |
+  Includes only the specified :term:`namespaces <namespace>` in the
+  restore operation.
+  By enabling you to specify multiple collections to restore,
+  {{role}} offers a superset of the functionality of the
+  :option:`--collection` option.
+optional: true
+post: |
+  .. include:: /includes/extracts/ns-pattern-simple-include.rst
+---
+program: mongorestore
+name: nsFrom
+directive: option
+args: <namespace pattern>
+pre: |
+  .. versionadded:: 3.4
+
+description: |
+  Use with :option:`--nsTo` to rename a :term:`namespace` during the
+  restore operation. {{role}} specifies the collection in the
+  dump file, while :option:`--nsTo` specifies the name that should be
+  used in the restored database.
+optional: true
+post: |
+  .. include:: /includes/extracts/ns-pattern-complex-from.rst
+---
+program: mongorestore
+name: nsTo
+directive: option
+args: <namespace pattern>
+pre: |
+  .. versionadded:: 3.4
+
+description: |
+  Use with :option:`--nsFrom` to rename a :term:`namespace` during the
+  restore operation. {{role}} specifies the new collection
+  name to use in the restored database, while
+  :option:`--nsFrom` specifies the name in the dump file.
+optional: true
+post: |
+  .. include:: /includes/extracts/ns-pattern-complex-to.rst
+---
+program: mongorestore
+name: oplogFile
+directive: option
+args: <path>
+pre: |
+  .. versionadded:: 3.4
+
+description: |
+  Specifies the path to the oplog file containing oplog data for the
+  restore.
+optional: true
+---
+program: mongorestore
+name: dryRun
+directive: option
+args: null
+pre: |
+  .. versionadded:: 3.4
+
+description: |
+  Runs {{program}} without actually importing any data, returning the
+  {{program}} summary information. Use with ``--verbose`` to produce
+  more detailed summary information.  
+optional: true
 ...

source/reference/program/mongorestore.txt

@@ -129,14 +129,26 @@ Options
 
 .. include:: /includes/option/option-mongorestore-collection.rst
 
+.. include:: /includes/option/option-mongorestore-nsExclude.rst
+
+.. include:: /includes/option/option-mongorestore-nsInclude.rst
+
+.. include:: /includes/option/option-mongorestore-nsFrom.rst
+
+.. include:: /includes/option/option-mongorestore-nsTo.rst
+
 .. include:: /includes/option/option-mongorestore-objcheck.rst
 
 .. include:: /includes/option/option-mongorestore-drop.rst
 
+.. include:: /includes/option/option-mongorestore-dryRun.rst
+
 .. include:: /includes/option/option-mongorestore-oplogReplay.rst
 
 .. include:: /includes/option/option-mongorestore-oplogLimit.rst
 
+.. include:: /includes/option/option-mongorestore-oplogFile.rst
+
 .. include:: /includes/option/option-mongorestore-keepIndexVersion.rst
 
 .. include:: /includes/option/option-mongorestore-noIndexRestore.rst
@@ -177,14 +189,89 @@ Consider the following example:
 
 .. code-block:: sh
 
-   mongorestore --collection people --db accounts dump/accounts/people.bson
+   mongorestore --collection people --db accounts dump/
 
 Here, :program:`mongorestore` reads the database dump in the ``dump/``
 sub-directory of the current directory, and restores *only* the
 documents in the collection named ``people`` from the database named
 ``accounts``. :program:`mongorestore` restores data to the instance
 running on the localhost interface on port ``27017``.
 
+.. versionadded:: 3.4
+
+You may alternatively use :option:`--nsInclude` to specify the
+canonical name of the collection that you wish to restore rather than
+:option:`--collection`. :option:`--nsInclude` enables you to specify
+the :term:`namespace` of one or more collections that you
+wish to include in the restore operation. The following example
+restores the ``people`` collection from the ``accounts`` database
+in the ``dump/`` sub-directory of the current directory:
+
+.. code-block:: sh
+
+   mongorestore --nsInclude accounts.people dump/
+
+.. _example-basic-wildcard-usage:
+
+Restore Collections Using Wild Cards
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. versionadded:: 3.4
+
+:option:`--nsInclude` and :option:`--nsExclude` support specifying
+the :term:`namespaces <namespace>` you wish to include or exclude from a restore operation
+using asterisks as *wild cards*.
+
+The following example restores the documents in the ``dump/``
+sub-directory of the current directory that match the specified
+namespace pattern. The :option:`--nsInclude` statement specifies to
+only restore documents in the ``transactions`` database while
+:option:`--nsExclude` instructs :program:`mongorestore` to exclude
+collections whose names end with ``_dev``. :program:`mongorestore`
+restores data to the :program:`mongod` instance running on the
+localhost interface on port ``27017``.
+
+.. code-block:: sh
+
+   mongorestore --nsInclude 'transactions.*' --nsExclude 'transactions.*_dev' dump/
+
+.. _example-complex-wildcard-usage:
+
+Change Collections' Namespaces during Restore
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. versionadded:: 3.4
+
+MongoDB 3.4 added the :option:`--nsFrom` and :option:`--nsTo` options,
+which enable you to change the namespace of a collection that you are
+restoring. :option:`--nsFrom` and :option:`--nsTo` support using
+asterisks as wild cards *and* support using dollar signs to delimit
+"wild card" variables to use in the replacement.
+
+Consider a database ``data`` that you have exported to a ``dump/``
+directory using :program:`mongodump`. The ``data`` database contains the following
+collections:
+
+- ``sales_customer1``
+- ``sales_customer2``
+- ``sales_customer3``
+- ``users_customer1``
+- ``users_customer2``
+- ``users_customer3``
+
+Using :option:`--nsFrom` and :option:`--nsTo`, you can restore the data
+into different namespaces. The following operation 
+
+- restores the ``sales_<customername>`` collections in the ``data`` database to
+  ``<customerName>`` collections in the ``sales`` database, and
+
+- restores the ``users_<customerName>`` collections to ``<customerName>``
+  collections in the ``users`` database.
+
+.. code-block:: sh
+
+   mongorestore --nsInclude 'data.*' --nsFrom 'data.$prefix$_$customer$' --nsTo '$customer$.$prefix$'
+
 Restore with Access Control
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~