szehon-ho commented on code in PR #12115:
URL: https://github.com/apache/iceberg/pull/12115#discussion_r1945624171
##########
docs/docs/spark-procedures.md:
##########
@@ -976,18 +976,18 @@ CALL catalog_name.system.compute_table_stats(table =>
'my_table', snapshot_id =>
## Table Replication
-The `rewrite-table-path` assists in moving or copying an Iceberg table from
one location to another.
+The `rewrite-table-path` procedure prepares an Iceberg table for moving or
copying to another.
Review Comment:
Nit: add location at the end of the sentence
##########
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 moving or
copying to another.
+
+### `rewrite-table-path`
+
+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 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.
+
+!!! info
+ This procedure only prepares metadata for an existing Iceberg table in
preparation for a copy or move to a 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.
Review Comment:
is it the `location of the chronologically last metadata.json`? Not
metadata location (which could be a folder)
##########
docs/docs/spark-procedures.md:
##########
@@ -976,18 +976,18 @@ CALL catalog_name.system.compute_table_stats(table =>
'my_table', snapshot_id =>
## Table Replication
-The `rewrite-table-path` assists in moving or copying an Iceberg table from
one location to another.
+The `rewrite-table-path` procedure prepares an Iceberg table for moving or
copying 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.
+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 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.
!!! 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.
+ This procedure only prepares metadata for an existing Iceberg table in
preparation for a copy or move to a new location.
Copying/Moving metadata and data files to the new location is not part of
this procedure.
+
Review Comment:
Revert newline
##########
docs/docs/spark-procedures.md:
##########
@@ -976,18 +976,18 @@ CALL catalog_name.system.compute_table_stats(table =>
'my_table', snapshot_id =>
## Table Replication
-The `rewrite-table-path` assists in moving or copying an Iceberg table from
one location to another.
+The `rewrite-table-path` procedure prepares an Iceberg table for moving or
copying 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.
+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 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.
!!! 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.
+ This procedure only prepares metadata for an existing Iceberg table in
preparation for a copy or move to a new location.
Review Comment:
prepares and in preparation are redundant. How about `This procedure only
prepares metadata for an existing Iceberg table for a copy or move to a new
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 moving or
copying to another.
+
+### `rewrite-table-path`
+
+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 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.
+
+!!! info
+ This procedure only prepares metadata for an existing Iceberg table in
preparation for a copy or move to a 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. |
Review Comment:
we should standardize (put period or not). Lets go with the majority in the
file (no period)
##########
docs/docs/spark-procedures.md:
##########
@@ -976,18 +976,18 @@ CALL catalog_name.system.compute_table_stats(table =>
'my_table', snapshot_id =>
## Table Replication
-The `rewrite-table-path` assists in moving or copying an Iceberg table from
one location to another.
+The `rewrite-table-path` procedure prepares an Iceberg table for moving or
copying 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.
+Stages a copy of the Iceberg table's metadata files where every absolute path
source prefix is replaced to the specified target.
Review Comment:
Nit: `replaced to` is probably not correct, should be `replaced by`. Also,
add `prefix` at the end?
##########
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 moving or
copying to another.
+
+### `rewrite-table-path`
+
+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 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.
+
+!!! info
+ This procedure only prepares metadata for an existing Iceberg table in
preparation for a copy or move to a 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 |
+
+##### File List Copy Plan
+The file list contains the copy plan for all files added to the table between
`startVersion` and `endVersion`.
+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
+
+Full rewrite of a table's path from source location in HDFS to a target
location in S3 bucket of table `my_table`.
+This produces a new set of metadata using the s3a prefix in the default
staging location under table's metadata directory
Review Comment:
Nit: period at end of sentence.
##########
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 moving or
copying to another.
+
+### `rewrite-table-path`
+
+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 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.
+
+!!! info
+ This procedure only prepares metadata for an existing Iceberg table in
preparation for a copy or move to a 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 |
+
+##### File List Copy Plan
+The file list contains the copy plan for all files added to the table between
`startVersion` and `endVersion`.
+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
+
+Full rewrite of a table's path from source location in HDFS to a target
location in S3 bucket of table `my_table`.
+This produces a new set of metadata using the s3a prefix in the default
staging location under 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"
+);
+```
+
+Incremental rewrite of a table's path from a source location to a target
location between metadata versions
Review Comment:
Let's put periods after all of these for consistency? (as you have period
in the previous example)
--
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
