From 40f80d2357a54ecc6879debeee958b10f1d6c8d8 Mon Sep 17 00:00:00 2001
From: xiaohongbo <xiaohongbo.xhb@alibaba-inc.com>
Date: Wed, 28 Jan 2026 17:42:36 +0800
Subject: [PATCH] [python/doc] add alterTable in pypaimon doc

---
 docs/content/pypaimon/python-api.md | 28 ++++++++++++++++++++++++++++
 1 file changed, 28 insertions(+)

diff --git a/docs/content/pypaimon/python-api.md b/docs/content/pypaimon/python-api.md
index 04c724812633..5516adf7fb06 100644
--- a/docs/content/pypaimon/python-api.md
+++ b/docs/content/pypaimon/python-api.md
@@ -153,6 +153,34 @@ catalog.create_table(
 table = catalog.get_table('database_name.table_name')
 ```
 
+## Alter Table
+
+Alter a table with a list of schema changes. Use `SchemaChange` from `pypaimon.schema.schema_change` and types from `pypaimon.schema.data_types` (e.g. `AtomicType`).
+
+```python
+from pypaimon.schema.schema_change import SchemaChange
+from pypaimon.schema.data_types import AtomicType
+
+# Add column(s)
+catalog.alter_table(
+    'database_name.table_name',
+    [
+        SchemaChange.add_column('new_col', AtomicType('STRING')),
+        SchemaChange.add_column('score', AtomicType('DOUBLE'), comment='optional'),
+    ],
+    ignore_if_not_exists=False
+)
+
+# Drop column
+catalog.alter_table(
+    'database_name.table_name',
+    [SchemaChange.drop_column('col_name')],
+    ignore_if_not_exists=False
+)
+```
+
+Other supported changes: `SchemaChange.rename_column`, `update_column_type`, `update_column_comment`, `set_option`, `remove_option`, `update_comment`.
+
 ## Batch Write
 
 Paimon table write is Two-Phase Commit, you can write many times, but once committed, no more data can be written.