PBM-1427 Documented how to clone collections

modified:   docs/features/selective-backup.md
	modified:   docs/reference/pbm-commands.md
	modified:   docs/usage/restore.md

docs/features/selective-backup.md

@@ -59,6 +59,30 @@ Consider these specifics of selective restore with users and roles:
 * Users and roles must be created in custom databases. For security considerations, users created in `admin`, `config` and `local` databases cannot be a part of a selective restore.
 * If users and roles exist in a database during the restore, they will be overwritten from the backup.
 
+## Restore a collection under a different name
+
+!!! admonition "Version added: [2.8.0](../release-notes/2.8.0.md)"
+
+You can restore a specific collection under a different name alongside the current collection. This is useful when you troubleshoot database issues and need to compare the data in both collections to identify what caused the database to misbehave. When you can see and edit the changes explicitly, you gain insight into your data and have confident control over it. As a result,  your troubleshooting efforts significantly reduce.
+
+To see how it works, imagine the following use case:
+
+You have noticed that your e-commerce app returns incorrect or incomplete results on orders. You remember that everything was working fine yesterday, so it’s likely that recent changes to the database caused the issue. 
+
+To find out, you can now restore the `orders` collection under a different name alongside the current `orders` collection and compare them. 
+
+```{.bash data-prompt="$"}
+$ pbm restore <backup-name> --ns-from=goods.orders --ns-to=goods.orders_prev
+```
+
+The `orders_prev` collection will have the same data and indexes as the `orders` collection, allowing you to see exactly what has changed.
+
+Let’s say you discover that the `status` field now includes an extra `date` field. These changes went unnoticed, and the app’s code was not updated to handle them, leading to incorrect results. Now that you’ve identified the issue you can take necessary actions to fix it.
+
+!!! note
+
+    In version 2.8.0 only non-sharded collections are supported. The support for sharded and timeseries collections is planned for the future releases.
+
 
 [Make a backup](../usage/start-backup.md){ .md-button .md-button }
 [Restore a backup](../usage/restore.md){ .md-button .md-button }

docs/reference/pbm-commands.md

@@ -783,6 +783,8 @@ The command accepts the following flags:
 | `--with-users-and-roles` | Restores users and roles created in custom databases during selective restore. Use this flag with the `--ns` flag. Available starting with version 2.5.0.| 
 | `-c`, `--config`     | The path to the `mongod.conf` file |
 | `--num-parallel-collections`| Sets the number of collections to process in parallel during a specific logical restore. When undefined, `pbm-agent` processes the number of parallel collections defined for the `restore.numParallelCollections` configuration parameter. If that is undefined,  the default number of collections is the half of the number of logical CPUs. Available starting with version 2.7.0.|
+| `--ns-from`="database.collection" |Specifies the name of the collection you want to restore under a new name. It indicates the collection present in the backup that you are targeting for restoration. Available starting with version 2.8.0.|
+| `--ns-to`="database.collection" | Specifies the new name for the collection you are restoring from the original one. Available starting with version 2.8.0.|
 
 ??? "Restore output"
 

docs/usage/restore.md

@@ -290,6 +290,21 @@ To restore a backup, use the [`pbm restore`](../reference/pbm-commands.md#pbm-re
     $ pbm restore <backup_name> --ns <database.*> --with-users-and-roles
     ```
 
+    ### Restore a collection under a different name
+
+    You can restore a specific collection under a different name alongside the current collection. This is useful when you troubleshoot database issues and need to compare the data in both collections to identify the root of the issue.
+
+    Note that in version 2.8.0 you can restore a single collection and this collection must be unsharded. 
+
+    To restore a collection, pass the collection name from the backup for the `--ns-from` flag and the new name for the `--ns-to` flag:
+
+    ```{.bash data-prompt="$"}
+    $ pbm restore <backup_name> --ns-from <database.collection> --ns-to <database.collection_new>
+    ```
+
+    The new collection has the same data and indexes as the source collection. You must provide a unique name for the collection you restore, otherwise the restore fails.
+
+
 === ":simple-databricks: Incremental"
 
     Restore flow from an incremental backup is the same as the restore from a full physical backup: specify the backup name for the `pbm restore` command: