szehon-ho commented on code in PR #12115:
URL: https://github.com/apache/iceberg/pull/12115#discussion_r1938841961
##########
docs/docs/spark-procedures.md:
##########
@@ -972,4 +972,91 @@ 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` assists in moving or copying an Iceberg table from
one location to another.
+
+### `rewrite-table-path`
+
+This procedure writes a new copy of the Iceberg table's metadata files where
every path has had its prefix replaced.
+The newly rewritten metadata files enable moving or coping an Iceberg table to
a new location.
+After copying both metadata and data to the desired location, the replicated
iceberg
+table will appear identical to the source table, including snapshot history,
schema and partition specs.
+
+!!! info
+ This procedure only creates metadata for an existing Iceberg table
modified for a new location. The produced file_list can be used for copying
rewritten metadata and data files to the new location.
Review Comment:
How about:
``` This procedure only prepares metadata for an existing Iceberg table in
preparation for a copy or move to a new location. The copying or moving of
files is outside its scope. ```
Maybe the file_list could be left out as its explained in the output below?
##########
docs/docs/spark-procedures.md:
##########
@@ -972,4 +972,91 @@ 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` assists in moving or copying an Iceberg table from
one location to another.
Review Comment:
nit: assists in => prepares for
``` The `rewrite-table-path` procedure prepares an Iceberg table for move or
copy to another location. ```
##########
docs/docs/spark-procedures.md:
##########
@@ -972,4 +972,91 @@ 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` assists in moving or copying an Iceberg table from
one location to another.
+
+### `rewrite-table-path`
+
+This procedure writes a new copy of the Iceberg table's metadata files where
every path has had its prefix replaced.
Review Comment:
1. Can we drop 'this procedure'? I think its implied, the other ones do not
have it.
2. 'has had' is a mouthful. How about 'every absolute path source prefix is
replaced to the specified target prefix' (going along the javadoc)
3. Misspell 'coping' in next sentence. How about again going with javadoc?
This can be the starting point to fully or incrementally copy an Iceberg
table located under an absolute path under a source prefix to another under the
target prefix.
4. Is there a need to call out explicitly that it retains snapshot history,
schema, partition stats? I would lean towards not having it, as the list could
be big here.
TLDR:
```
Stages a copy of the Iceberg table's metadata files where every absolute
path source prefix is replaced to the specified target. This can be starting
point to fully or incrementally copy an Iceberg table located under an absolute
path under a source prefix to another under the target prefix.
```
##########
docs/docs/spark-procedures.md:
##########
@@ -972,4 +972,91 @@ 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` assists in moving or copying an Iceberg table from
one location to another.
+
+### `rewrite-table-path`
+
+This procedure writes a new copy of the Iceberg table's metadata files where
every path has had its prefix replaced.
+The newly rewritten metadata files enable moving or coping an Iceberg table to
a new location.
+After copying both metadata and data to the desired location, the replicated
iceberg
+table will appear identical to the source table, including snapshot history,
schema and partition specs.
+
+!!! info
+ This procedure only creates metadata for an existing Iceberg table
modified for a new location. The produced file_list can be used for copying
rewritten metadata and data files to the new location.
+ Copying/Moving metadata and data files to the new location 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.
+
+- Incremental Rewrite:
+
+If `start_version` is provided, the procedure will only rewrite metadata files
created between `start_version` and `end_version`. `end_version` defaults to
the latest metadata location of the table.
+
+#### 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 file containing a listing of
comma-separated source and destination paths |
Review Comment:
I feel we did some rounds in the javadoc for the Result, so would take from
that?
```
Path to a file containing a copy plan for all files added to the table
between startVersion and endVersion, comma-separated.
For each file, it will include the source path (either the original path in
the table, or in the staging location if rewritten), and the target path (under
the new prefix).
This allows for copying a functioning version of the table to the target
prefix.
```
--
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: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
