DOC-8351 add execution locality option to restore (#17894)

src/current/v23.1/restore.md

@@ -127,8 +127,9 @@ You can control `RESTORE` behavior using any of the following in the `restore_op
 <span class="version-tag">New in v23.1:</span><a name="skip_missing_udfs"></a>`skip_missing_udfs` | N/A | Must be used when restoring a table with referenced [UDF]({% link {{ page.version.version }}/user-defined-functions.md %}) dependencies. Any column's `DEFAULT` expression using UDFs is dropped. <br><br>Example: `WITH skip_missing_udfs`
 `encryption_passphrase`                                             | Passphrase used to create the [encrypted backup]({% link {{ page.version.version }}/take-and-restore-encrypted-backups.md %}) |  The passphrase used to decrypt the file(s) that were encrypted by the [`BACKUP`]({% link {{ page.version.version }}/take-and-restore-encrypted-backups.md %}) statement.
 <a name="detached"></a>`DETACHED`                                   | N/A                                         |  When `RESTORE` runs with `DETACHED`, the job will execute asynchronously. The job ID is returned after the restore job creation completes. Note that with `DETACHED` specified, further job information and the job completion status will not be returned. For more on the differences between the returned job data, see the [example]({% link {{ page.version.version }}/restore.md %}#restore-a-backup-asynchronously) below. To check on the job status, use the [`SHOW JOBS`]({% link {{ page.version.version }}/show-jobs.md %}) statement. <br><br>To run a restore within a [transaction]({% link {{ page.version.version }}/transactions.md %}), use the `DETACHED` option.
-`debug_pause_on`                                                    | `"error" `                                    |  Use to have a `RESTORE` [job]({% link {{ page.version.version }}/show-jobs.md %}) self pause when it encounters an error. The `RESTORE` job can then be [resumed]({% link {{ page.version.version }}/resume-job.md %}) after the error has been fixed or [canceled]({% link {{ page.version.version }}/cancel-job.md %}) to rollback the job. <br><br>Example: `WITH debug_pause_on='error'`
-<a name="incr-location"></a>`incremental_location` | [`STRING`]({% link {{ page.version.version }}/string.md %}) | Restore an incremental backup from the alternate collection URI the backup was originally taken with. <br><br>See [Restore incremental backups](#restore-a-specific-full-or-incremental-backup) for more detail.
+<a name="execution_locality"></a><span class="version-tag">New in v23.1.12:</span>`EXECUTION LOCALITY`               | Key-value pairs                             | Restricts the execution of the restore to nodes that match the defined [locality filter]({% link {{ page.version.version }}/take-locality-restricted-backups.md %}) requirements. <br><br>Example: `WITH EXECUTION LOCALITY = 'region=us-west-1a,cloud=aws'`
+`debug_pause_on`                                                    | `"error" `                                  |  Use to have a `RESTORE` [job]({% link {{ page.version.version }}/show-jobs.md %}) self pause when it encounters an error. The `RESTORE` job can then be [resumed]({% link {{ page.version.version }}/resume-job.md %}) after the error has been fixed or [canceled]({% link {{ page.version.version }}/cancel-job.md %}) to rollback the job. <br><br>Example: `WITH debug_pause_on='error'`
+<a name="incr-location"></a>`incremental_location` | [`STRING`]({% link {{ page.version.version }}/string.md %}) | Restore an incremental backup from the alternate collection URI the backup was originally taken with. <br><br>Refer to [Restore incremental backups](#restore-the-most-recent-full-or-incremental-backup) for more detail.
 `schema_only` | N/A | Verify that a backup is valid by running `RESTORE ... schema_only`, which will restore the backed-up schema without any user data. Refer to [Backup Validation]({% link {{ page.version.version }}/backup-validation.md %}#validate-a-backup-is-restorable) for detail and an example.
 `verify_backup_table_data` | N/A | Run a `schema_only` restore **and** have the restore read all user data from external storage, verify checksums, and discard the user data before writing it to disk. You must also include the `schema_only` option in the `RESTORE` statement with `verify_backup_table_data`. For more detail, see [Backup Validation]({% link {{ page.version.version }}/backup-validation.md %}#validate-backup-table-data-is-restorable).
 

src/current/v23.1/take-locality-restricted-backups.md

@@ -7,6 +7,8 @@ docs_area: manage
 
 {% include_cached new-in.html version="v23.1" %} The `EXECUTION LOCALITY` option allows you to restrict the nodes that can execute a [backup]({% link {{ page.version.version }}/backup.md %}) job by using a [locality filter]({% link {{ page.version.version }}/cockroach-start.md %}#locality) when you create the backup. This will pin the [coordination of the backup job]({% link {{ page.version.version }}/backup-architecture.md %}#job-creation-phase) and the nodes that [process the row data]({% link {{ page.version.version }}/backup-architecture.md %}#export-phase) to the defined locality filter.
 
+{% include_cached new-in.html version="v23.1.12" %} Pass the `WITH EXECUTION LOCALITY` option for [`RESTORE`]({% link {{ page.version.version }}/restore.md %}) to restrict execution of the job to nodes with matching localities.
+
 Defining an execution locality for a backup job is useful in the following cases:
 
 - When nodes in a cluster operate in different locality tiers, networking rules can restrict nodes from accessing a storage bucket. For an example, refer to [Access backup storage restricted by network rules](#access-backup-storage-restricted-by-network-rules).
@@ -31,11 +33,12 @@ To specify the locality filter for the coordinating node, run `EXECUTION LOCALIT
 BACKUP DATABASE {database} INTO 'external://backup_storage' WITH EXECUTION LOCALITY = 'region={region},cloud={cloud}';
 ~~~
 
-When you run a backup that uses `EXECUTION LOCALITY`, consider the following:
+When you run a backup or restore that uses `EXECUTION LOCALITY`, consider the following:
 
-- The backup job will fail if no nodes match the locality filter.
-- The backup job may take slightly more time to start, because it must select the node that coordinates the backup (the _coordinating node_). Refer to [Job coordination using the `EXECUTION LOCALITY` option]({% link {{ page.version.version }}/backup-architecture.md %}#job-coordination-using-the-execution-locality-option).
-- Even after a backup job has been pinned to a locality filter, it may still read data from another locality if no replicas of the data are available in the locality specified by the backup job's locality filter.
+- `RESTORE` with the `EXECUTION LOCALITY` option is available from v23.1.12.
+- The backup or restore job will fail if no nodes match the locality filter.
+- The backup or restore job may take slightly more time to start, because it must select the node that coordinates the backup or restore (the _coordinating node_). Refer to [Job coordination using the `EXECUTION LOCALITY` option]({% link {{ page.version.version }}/backup-architecture.md %}#job-coordination-using-the-execution-locality-option).
+- Even after a backup or restore job has been pinned to a locality filter, it may still read data from another locality if no replicas of the data are available in the locality specified by the backup job's locality filter.
 - If the job is created on a node that does not match the locality filter, you will receive an error even when the **job creation was successful**. This error indicates that the job execution moved to another node. To avoid this error when creating a manual job (as opposed to a [scheduled job]({% link {{ page.version.version }}/create-schedule-for-backup.md %})), you can use the [`DETACHED`]({% link {{ page.version.version }}/backup.md %}#detached) option with `EXECUTION LOCALITY`. Then, use the [`SHOW JOB WHEN COMPLETE`]({% link {{ page.version.version }}/show-jobs.md %}#show-job-when-complete) statement to determine when the job has finished. For more details, refer to [Job coordination using the `EXECUTION LOCALITY` option]({% link {{ page.version.version }}/backup-architecture.md %}#job-coordination-using-the-execution-locality-option).
 
 ## Examples
@@ -61,7 +64,14 @@ For example, you can pin the execution of the backup job to `us-west-1`:
 BACKUP DATABASE {database} INTO 'external://backup_storage_uswest' WITH EXECUTION LOCALITY = 'region=us-west-1', DETACHED;
 ~~~
 
-Refer to the [`BACKUP`]({% link {{ page.version.version }}/backup.md %}) page for further detail on other parameters and options.
+{% include_cached new-in.html version="v23.1.12" %} To restore the most recent locality-restricted backup:
+
+{% include_cached copy-clipboard.html %}
+~~~ sql
+RESTORE FROM LATEST IN 'external://backup_storage_uswest' WITH EXECUTION LOCALITY = 'region=us-west-1', DETACHED;
+~~~
+
+Refer to the [`BACKUP`]({% link {{ page.version.version }}/backup.md %}) and [`RESTORE`]({% link {{ page.version.version }}/restore.md %}) pages for further detail on other parameters and options.
 
 ### Create a non-primary region for backup jobs
 

src/current/v23.2/restore.md

@@ -127,6 +127,7 @@ You can control `RESTORE` behavior using any of the following in the `restore_op
 <a name="skip_missing_udfs"></a>`skip_missing_udfs` | N/A | Must be used when restoring a table with referenced [UDF]({% link {{ page.version.version }}/user-defined-functions.md %}) dependencies. Any column's `DEFAULT` expression using UDFs is dropped. <br><br>Example: `WITH skip_missing_udfs`
 `encryption_passphrase`                                             | Passphrase used to create the [encrypted backup]({% link {{ page.version.version }}/take-and-restore-encrypted-backups.md %}) |  The passphrase used to decrypt the file(s) that were encrypted by the [`BACKUP`]({% link {{ page.version.version }}/take-and-restore-encrypted-backups.md %}) statement.
 <a name="detached"></a>`DETACHED`                                   | N/A                                         |  When `RESTORE` runs with `DETACHED`, the job will execute asynchronously. The job ID is returned after the restore job creation completes. Note that with `DETACHED` specified, further job information and the job completion status will not be returned. For more on the differences between the returned job data, see the [example]({% link {{ page.version.version }}/restore.md %}#restore-a-backup-asynchronously) below. To check on the job status, use the [`SHOW JOBS`]({% link {{ page.version.version }}/show-jobs.md %}) statement. <br><br>To run a restore within a [transaction]({% link {{ page.version.version }}/transactions.md %}), use the `DETACHED` option.
+<span class="version-tag">New in v23.2:</span><a name="execution_locality"></a>`EXECUTION LOCALITY` | Key-value pairs                             | Restricts the execution of the restore to nodes that match the defined [locality filter]({% link {{ page.version.version }}/take-locality-restricted-backups.md %}) requirements. <br><br>Example: `WITH EXECUTION LOCALITY = 'region=us-west-1a,cloud=aws'`
 `debug_pause_on`                                                    | `"error" `                                    |  Use to have a `RESTORE` [job]({% link {{ page.version.version }}/show-jobs.md %}) self pause when it encounters an error. The `RESTORE` job can then be [resumed]({% link {{ page.version.version }}/resume-job.md %}) after the error has been fixed or [canceled]({% link {{ page.version.version }}/cancel-job.md %}) to rollback the job. <br><br>Example: `WITH debug_pause_on='error'`
 <a name="incr-location"></a>`incremental_location` | [`STRING`]({% link {{ page.version.version }}/string.md %}) | Restore an incremental backup from the alternate collection URI the backup was originally taken with. <br><br>See [Restore incremental backups](#restore-a-specific-full-or-incremental-backup) for more detail.
 `schema_only` | N/A | Verify that a backup is valid by running `RESTORE ... schema_only`, which will restore the backed-up schema without any user data. Refer to [Backup Validation]({% link {{ page.version.version }}/backup-validation.md %}#validate-a-backup-is-restorable) for detail and an example.

src/current/v23.2/take-locality-restricted-backups.md

@@ -7,6 +7,8 @@ docs_area: manage
 
 The `EXECUTION LOCALITY` option allows you to restrict the nodes that can execute a [backup]({% link {{ page.version.version }}/backup.md %}) job by using a [locality filter]({% link {{ page.version.version }}/cockroach-start.md %}#locality) when you create the backup. This will pin the [coordination of the backup job]({% link {{ page.version.version }}/backup-architecture.md %}#job-creation-phase) and the nodes that [process the row data]({% link {{ page.version.version }}/backup-architecture.md %}#export-phase) to the defined locality filter.
 
+{% include_cached new-in.html version="v23.2" %} Pass the `WITH EXECUTION LOCALITY` option for [`RESTORE`]({% link {{ page.version.version }}/restore.md %}) to restrict execution of the job to nodes with matching localities. 
+
 Defining an execution locality for a backup job is useful in the following cases:
 
 - When nodes in a cluster operate in different locality tiers, networking rules can restrict nodes from accessing a storage bucket. For an example, refer to [Access backup storage restricted by network rules](#access-backup-storage-restricted-by-network-rules).
@@ -31,11 +33,11 @@ To specify the locality filter for the coordinating node, run `EXECUTION LOCALIT
 BACKUP DATABASE {database} INTO 'external://backup_storage' WITH EXECUTION LOCALITY = 'region={region},cloud={cloud}';
 ~~~
 
-When you run a backup that uses `EXECUTION LOCALITY`, consider the following:
+When you run a backup or restore that uses `EXECUTION LOCALITY`, consider the following:
 
-- The backup job will fail if no nodes match the locality filter.
-- The backup job may take slightly more time to start, because it must select the node that coordinates the backup (the _coordinating node_). Refer to [Job coordination using the `EXECUTION LOCALITY` option]({% link {{ page.version.version }}/backup-architecture.md %}#job-coordination-using-the-execution-locality-option).
-- Even after a backup job has been pinned to a locality filter, it may still read data from another locality if no replicas of the data are available in the locality specified by the backup job's locality filter.
+- The backup or restore job will fail if no nodes match the locality filter.
+- The backup or restore job may take slightly more time to start, because it must select the node that coordinates the backup or restore (the _coordinating node_). Refer to [Job coordination using the `EXECUTION LOCALITY` option]({% link {{ page.version.version }}/backup-architecture.md %}#job-coordination-using-the-execution-locality-option).
+- Even after a backup or restore job has been pinned to a locality filter, it may still read data from another locality if no replicas of the data are available in the locality specified by the backup job's locality filter.
 - If the job is created on a node that does not match the locality filter, you will receive an error even when the **job creation was successful**. This error indicates that the job execution moved to another node. To avoid this error when creating a manual job (as opposed to a [scheduled job]({% link {{ page.version.version }}/create-schedule-for-backup.md %})), you can use the [`DETACHED`]({% link {{ page.version.version }}/backup.md %}#detached) option with `EXECUTION LOCALITY`. Then, use the [`SHOW JOB WHEN COMPLETE`]({% link {{ page.version.version }}/show-jobs.md %}#show-job-when-complete) statement to determine when the job has finished. For more details, refer to [Job coordination using the `EXECUTION LOCALITY` option]({% link {{ page.version.version }}/backup-architecture.md %}#job-coordination-using-the-execution-locality-option).
 
 ## Examples
@@ -61,7 +63,14 @@ For example, you can pin the execution of the backup job to `us-west-1`:
 BACKUP DATABASE {database} INTO 'external://backup_storage_uswest' WITH EXECUTION LOCALITY = 'region=us-west-1', DETACHED;
 ~~~
 
-Refer to the [`BACKUP`]({% link {{ page.version.version }}/backup.md %}) page for further detail on other parameters and options.
+To restore the most recent locality-restricted backup:
+
+{% include_cached copy-clipboard.html %}
+~~~ sql
+RESTORE FROM LATEST IN 'external://backup_storage_uswest' WITH EXECUTION LOCALITY = 'region=us-west-1', DETACHED;
+~~~
+
+Refer to the [`BACKUP`]({% link {{ page.version.version }}/backup.md %}) and [`RESTORE`]({% link {{ page.version.version }}/restore.md %}) pages for further detail on other parameters and options.
 
 ### Create a non-primary region for backup jobs