szehon-ho commented on code in PR #12115:
URL: https://github.com/apache/iceberg/pull/12115#discussion_r1960777677
##########
docs/docs/spark-procedures.md:
##########
@@ -972,4 +972,97 @@ 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`
Review Comment:
Same, use underscore like the other procedure sections.
##########
docs/docs/spark-procedures.md:
##########
@@ -972,4 +972,97 @@ 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.
Review Comment:
The procedure uses underscore, this is the only one that is hyphen.
##########
docs/docs/spark-procedures.md:
##########
@@ -972,4 +972,97 @@ 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 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
| 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 modified 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:
+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`. Optional `start_version` and `end_version`
can be provided to limit the scope of this procedure.
+
+
+#### 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 path of `my_table` from source location in HDFS to
a target location in S3.
Review Comment:
How about:
path => metadata paths, ie
```This example fully rewrites metadata paths of ...```
##########
docs/docs/spark-procedures.md:
##########
@@ -972,4 +972,97 @@ 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 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
| 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 modified 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:
+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`. Optional `start_version` and `end_version`
can be provided to limit the scope of this procedure.
Review Comment:
Optional => Optionally (with a comma).
```Optionally, `start_version` and `end_version` can be provided to limit
the scope of this procedure.```
(I think optional is not gramatically correct)
##########
docs/docs/spark-procedures.md:
##########
@@ -972,4 +972,97 @@ 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 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
| string | The name or path of the chronologically last metadata.json to
rewrite |
Review Comment:
Was there an earlier discussion, why not have 'in table's metadata log' to
match start_version
##########
docs/docs/spark-procedures.md:
##########
@@ -972,4 +972,97 @@ 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 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
| 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 modified 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:
+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`. Optional `start_version` and `end_version`
can be provided to limit the scope of this procedure.
+
+
+#### 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 path 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
table's metadata directory.
Review Comment:
table => the table
##########
docs/docs/spark-procedures.md:
##########
@@ -972,4 +972,97 @@ 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 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
| 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 modified metadata files
|
+
+
+#### Modes of operation
+
+* Full Rewrite:
+A full rewrite will rewrite all reachable metadata files
Review Comment:
Nit: not blocking, but can move to above line? To make it clear to readers,
that it will render as one line
##########
docs/docs/spark-procedures.md:
##########
@@ -972,4 +972,97 @@ 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 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
| 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 modified 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:
+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`. Optional `start_version` and `end_version`
can be provided to limit the scope of this procedure.
+
+
+#### 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 path 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
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 path of `my_table` between metadata
versions `v2.metadata.json` and `v20.metadata.json`,
Review Comment:
Same: path=> metadata paths
--
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
