Docs: Add rewrite-table-path in spark procedure

docs/docs/spark-procedures.md

@@ -972,4 +972,94 @@ CALL catalog_name.system.compute_table_stats(table => 'my_table', snapshot_id =>
 Collect statistics of the snapshot with id `snap1` of table `my_table` for columns `col1` and `col2`
 ```sql
 CALL catalog_name.system.compute_table_stats(table => 'my_table', snapshot_id => 'snap1', columns => array('col1', 'col2'));
-```
+```
+
+## Table Replication
+
+The `rewrite_table_path` procedure prepares an Iceberg table for copying to another location.
+
+### `rewrite_table_path`
+
+Stages a copy of the Iceberg table's metadata files where every absolute path source prefix is replaced by the specified target prefix.  
+This can be the starting point to fully or incrementally copy an Iceberg table to a new location.
+
+!!! info
+    This procedure only stages rewritten metadata files and prepares a list of files to copy. The actual file copy is not included in this procedure.
+
+
+| Argument Name      | Required? | default                                        | Type   | Description                                                            |
+|--------------------|-----------|------------------------------------------------|--------|------------------------------------------------------------------------|
+| `table`            | ✔️        |                                                | string | Name of the table                                                      |
+| `source_prefix`    | ✔️        |                                                | string | The existing prefix to be replaced                                     |
+| `target_prefix`    | ✔️        |                                                | string | The replacement prefix for `source_prefix`                             |
+| `start_version`    |           | first metadata.json in table's metadata log    | string | The name or path of the chronologically first metadata.json to rewrite |
+| `end_version`      |           | latest metadata.json in table's metadata log   | string | The name or path of the chronologically last metadata.json to rewrite  |
+| `staging_location` |           | new directory under table's metadata directory | string | The output location for newly rewritten metadata files                 |
+
+
+#### Modes of operation
+
+* Full Rewrite: A full rewrite will rewrite all reachable metadata files (this includes metadata.json, manifest lists, manifests, and position delete files), and will return all reachable files in the `file_list_location`. This is the default mode of operation for this procedure.
+
+* Incremental Rewrite: Optionally, `start_version` and `end_version` can be provided to limit the scope to an incremental rewrite. An incremental rewrite will only rewrite metadata files added between `start_version` and `end_version`, and will only return files added in this range in the `file_list_location`.
+
+
+#### Output
+
+| Output Name          | Type   | Description                                                       |
+|----------------------|--------|-------------------------------------------------------------------|
+| `latest_version`     | string | Name of the latest metadata file rewritten by this procedure      |
+| `file_list_location` | string | Path to a CSV file containing a mapping of source to target paths |
+
+##### File List
+The file contains the copy plan for all files added to the table between `start_version` and `end_version`.
+
+For each file, it specifies:
+
+* Source Path: The original file path in the table, or the staging location if the file has been rewritten
+
+* Target Path: The path with the replacement prefix
+
+The following example shows a copy plan for three files:
+
+```csv
+sourcepath/datafile1.parquet,targetpath/datafile1.parquet
+sourcepath/datafile2.parquet,targetpath/datafile2.parquet
+stagingpath/manifest.avro,targetpath/manifest.avro
+```
+
+#### Examples
+
+This example fully rewrites metadata paths of `my_table` from source location in HDFS to a target location in S3.
+It will produce a new set of metadata in the default staging location under the table's metadata directory.
+
+```sql
+CALL catalog_name.system.rewrite_table_path(
+    table => 'db.my_table', 
+    source_prefix => "hdfs://nn:8020/path/to/source_table",
+    target_prefix => "s3a://bucket/prefix/db.db/my_table"
+);
+```
+
+This example incrementally rewrites metadata paths of `my_table` between metadata versions `v2.metadata.json` and `v20.metadata.json`,
+with new metadata files written to an explicit staging location.
+
+```sql
+CALL catalog_name.system.rewrite_table_path(
+    table => 'db.my_table', 
+    source_prefix => "s3a://bucketOne/prefix/db.db/my_table",
+    target_prefix => "s3a://bucketTwo/prefix/db.db/my_table",
+    start_version => "v2.metadata.json",
+    end_version => "v20.metadata.json",
+    staging_location => "s3a://bucketStaging/my_table"  
+);
+```
+
+Once the rewrite completes, third-party tools (
+eg. [Distcp](https://hadoop.apache.org/docs/current/hadoop-distcp/DistCp.html)) can copy the newly created
+metadata files and data files to the target location.
+
+Lastly, the [register_table](#register_table) procedure can be used to register the copied table in the target location with a catalog.
+
+!!! warning
+    Iceberg tables with partition statistics files are not currently supported for path rewrite.