[iceberg] branch master updated: Docs: Add `fast_forward` procedure (#8271)

[etudenhoefner]

This is an automated email from the ASF dual-hosted git repository.

etudenhoefner pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/iceberg.git


The following commit(s) were added to refs/heads/master by this push:
     new a7a55b5cbb Docs: Add `fast_forward` procedure (#8271)
a7a55b5cbb is described below

commit a7a55b5cbbacadf4d04c605c95e2e95a0187d8bc
Author: Manu Zhang <owenzhang1...@gmail.com>
AuthorDate: Wed Aug 9 21:20:46 2023 +0800

    Docs: Add `fast_forward` procedure (#8271)
---
 docs/branching-and-tagging.md |  6 +++---
 docs/spark-procedures.md      | 28 ++++++++++++++++++++++++++++
 2 files changed, 31 insertions(+), 3 deletions(-)

diff --git a/docs/branching-and-tagging.md b/docs/branching-and-tagging.md
index dd70d6c45a..b56e8f1066 100644
--- a/docs/branching-and-tagging.md
+++ b/docs/branching-and-tagging.md
@@ -101,13 +101,13 @@ ALTER TABLE db.table CREATE BRANCH `audit-branch` AS OF 
VERSION 3 RETAIN 7 DAYS
 3. Writes are performed on a separate `audit-branch` independent from the main 
table history.
 ```sql
 -- WAP Branch write
-SET spark.wap.branch = 'audit-branch'
+SET spark.wap.branch = audit-branch
 INSERT INTO prod.db.table VALUES (3, 'c')
 ```
 4. A validation workflow can validate (e.g. data quality) the state of 
`audit-branch`.
 5. After validation, the main branch can be `fastForward` to the head of 
`audit-branch` to update the main table state.
-```java
-table.manageSnapshots().fastForward("main", "audit-branch").commit()
+```sql
+CALL catalog_name.system.fast_forward('prod.db.table', 'main', 'audit-branch')
 ```
 6. The branch reference will be removed when `expireSnapshots` is run 1 week 
later.
 
diff --git a/docs/spark-procedures.md b/docs/spark-procedures.md
index df9896fb40..a45bd4cc48 100644
--- a/docs/spark-procedures.md
+++ b/docs/spark-procedures.md
@@ -184,6 +184,34 @@ Cherry-pick snapshot 1 with named args
 CALL catalog_name.system.cherrypick_snapshot(snapshot_id => 1, table => 
'my_table' )
 ```
 
+### `fast_forward`
+
+Fast-forward the current snapshot of one branch to the latest snapshot of 
another.
+
+#### Usage
+
+| Argument Name | Required? | Type | Description |
+|---------------|-----------|------|-------------|
+| `table` | ✔️ | string | Name of the table to update |
+| `branch` | ✔️ | string   | Name of the branch to fast-forward |
+| `to` | ✔️ | string | | Name of the branch to be fast-forwarded to |
+
+#### Output
+
+| Output Name | Type | Description |
+| ------------|------|-------------|
+| `branch_updated` | string | Name of the branch that has been fast-forwarded |
+| `previous_ref` | long | The snapshot ID before applying fast-forward |
+| `updated_ref`  | long | The current snapshot ID after applying fast-forward |
+
+#### Examples
+
+Fast-forward the main branch to the head of `audit-branch`
+```sql
+CALL catalog_name.system.fast_forward('my_table', 'main', 'audit-branch')
+```
+
+
 
 ## Metadata management