szehon-ho commented on code in PR #12115:
URL: https://github.com/apache/iceberg/pull/12115#discussion_r1957073109
##########
docs/docs/spark-procedures.md:
##########
@@ -972,4 +972,101 @@ 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'));
-```
\ No newline at end of file
+```
+
+## 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 part of 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 to the chronologically first metadata.json to
rewrite |
+| `end_version` | | latest metadata.json
| string | The name or path to the chronologically last metadata.json to
rewrite |
+| `staging_location` | | new directory under table's metadata
directory | string | The output location for newly modified metadata files
|
+
+
+#### Modes of operation:
+
+- Full Rewrite:
+
+By default, the procedure operates in full rewrite mode, rewriting all
reachable metadata files
Review Comment:
Noticed that the two sentences dont match in tense.
Also reading this through in order again, I think its better to mention
file_list_location as copy plan is not known yet.
How about
`By default, the procedure operates in full rewrite mode. It will rewrite
all reachable metadata files... and will return all reachable files in the
file_list_location.`
`The `start_version` and/or `end_version` arguments may be provided to limit
the scope of the procedure.
It 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.`
##########
docs/docs/spark-procedures.md:
##########
@@ -972,4 +972,101 @@ 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'));
-```
\ No newline at end of file
+```
+
+## 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 part of 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 to the chronologically first metadata.json to
rewrite |
+| `end_version` | | latest metadata.json
| string | The name or path to the chronologically last metadata.json to
rewrite |
+| `staging_location` | | new directory under table's metadata
directory | string | The output location for newly modified metadata files
|
+
+
+#### Modes of operation:
+
+- Full Rewrite:
+
+By default, the procedure operates in full rewrite mode, rewriting all
reachable metadata files
+(this includes metadata.json, manifest lists, manifests, and position delete
files), and returning all reachable files in the result copy plan.
+
+- Incremental Rewrite:
+
+The `start_version` and/or `end_version` arguments may be provided to limit
the scope of rewrite.
+Only metadata files added between `start_version` and `end_version` will be
rewritten, and only files added in this range are returned in the copy plan.
+
+#### 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 Copy Plan
+The file contains the copy plan for all files added to the table between
`startVersion` and `endVersion`:
Review Comment:
Sorry I meant, colon after specifies in line 1022, not here.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscr...@iceberg.apache.org
For queries about this service, please contact Infrastructure at:
us...@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscr...@iceberg.apache.org
For additional commands, e-mail: issues-h...@iceberg.apache.org
