From a95f9ee6e231104319c01493cb3ada59d9e782d0 Mon Sep 17 00:00:00 2001
From: jeppe-dos <jeppe.f.sorensen@jppol.dk>
Date: Thu, 9 Jan 2025 19:14:22 +0100
Subject: [PATCH] Change dot notation in add column documentation to tuple
 (#1433)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* Change dot notation in add column documentation to tuple

* Update move and rename column struct in api.md

* Correct rename_column, move_before and delete_column in api.md

* Change exchange to processed by on rename_column in api.md

* Update mkdocs/docs/api.md

Co-authored-by: Kevin Liu <kevinjqliu@users.noreply.github.com>

* Fix rename column in api.md

* Update mkdocs/docs/api.md

* Update mkdocs/docs/api.md

---------

Co-authored-by: Jeppe Finne Sørensen <jeppe.f.sorensen@polhus.rootdom.dk>
Co-authored-by: Kevin Liu <kevinjqliu@users.noreply.github.com>
---
 mkdocs/docs/api.md | 19 +++++++++++++------
 1 file changed, 13 insertions(+), 6 deletions(-)

diff --git a/mkdocs/docs/api.md b/mkdocs/docs/api.md
index 9c48718877..8b106c1034 100644
--- a/mkdocs/docs/api.md
+++ b/mkdocs/docs/api.md
@@ -1072,8 +1072,12 @@ Using `add_column` you can add a column, without having to worry about the field
 with table.update_schema() as update:
     update.add_column("retries", IntegerType(), "Number of retries to place the bid")
     # In a struct
-    update.add_column("details.confirmed_by", StringType(), "Name of the exchange")
+    update.add_column("details", StructType())
+
+with table.update_schema() as update:
+    update.add_column(("details", "confirmed_by"), StringType(), "Name of the exchange")
 ```
+A complex type must exist before columns can be added to it. Fields in complex types are added in a tuple.
 
 ### Rename column
 
@@ -1082,20 +1086,21 @@ Renaming a field in an Iceberg table is simple:
 ```python
 with table.update_schema() as update:
     update.rename_column("retries", "num_retries")
-    # This will rename `confirmed_by` to `exchange`
-    update.rename_column("properties.confirmed_by", "exchange")
+    # This will rename `confirmed_by` to `processed_by` in the `details` struct
+    update.rename_column(("details", "confirmed_by"), "processed_by")
 ```
 
 ### Move column
 
-Move a field inside of struct:
+Move order of fields:
 
 ```python
 with table.update_schema() as update:
     update.move_first("symbol")
+    # This will move `bid` after `ask`
     update.move_after("bid", "ask")
-    # This will move `confirmed_by` before `exchange`
-    update.move_before("details.created_by", "details.exchange")
+    # This will move `confirmed_by` before `exchange` in the `details` struct
+    update.move_before(("details", "confirmed_by"), ("details", "exchange"))
 ```
 
 ### Update column
@@ -1127,6 +1132,8 @@ Delete a field, careful this is a incompatible change (readers/writers might exp
 ```python
 with table.update_schema(allow_incompatible_changes=True) as update:
     update.delete_column("some_field")
+    # In a struct
+    update.delete_column(("details", "confirmed_by"))
 ```
 
 ## Partition evolution