This is an automated email from the ASF dual-hosted git repository.
kevinjqliu pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/iceberg-python.git
The following commit(s) were added to refs/heads/main by this push:
new a02c0bfb docs: Add missing methods for table and namespace
manipulation (#2942)
a02c0bfb is described below
commit a02c0bfb13a231c60ee74fd07718f94e1d07f158
Author: Alex Stephen <[email protected]>
AuthorDate: Tue Jan 27 15:23:41 2026 -0800
docs: Add missing methods for table and namespace manipulation (#2942)
<!--
Thanks for opening a pull request!
-->
<!-- In the case this PR will resolve an issue, please replace
${GITHUB_ISSUE_ID} below with the actual Github issue id. -->
<!-- Closes #${GITHUB_ISSUE_ID} -->
# Rationale for this change
We have some methods for working with tables + namespaces on catalogs
that we haven't properly documented. This documentation is super helpful
for new users to understand what they can use PyIceberg for. It's also
helpful for our LLM...friends? to help understand the project.
## Are these changes tested?
Docs only.
## Are there any user-facing changes?
Docs only.
<!-- In the case of user-facing changes, please add the changelog label.
-->
---
mkdocs/docs/api.md | 54 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 54 insertions(+)
diff --git a/mkdocs/docs/api.md b/mkdocs/docs/api.md
index 1c327319..506547fc 100644
--- a/mkdocs/docs/api.md
+++ b/mkdocs/docs/api.md
@@ -82,6 +82,24 @@ ns = catalog.list_namespaces()
assert ns == [("docs_example",)]
```
+Next, update the namespace properties.
+
+```python
+
+# Load namespace properties
+properties = catalog.load_namespace_properties("docs_example")
+
+# Update namespace properties with additions and removals.
+catalog.update_namespace_properties("docs_example", removals={"remove-meee!"},
updates={"owner": "iceberg"})
+```
+
+Finally, drop the namespace (if you want!)
+
+```python
+# Drop a namespace
+catalog.drop_namespace("docs_example")
+```
+
## Create a table
To create a table from a catalog:
@@ -167,6 +185,17 @@ with
catalog.create_table_transaction(identifier="docs_example.bids", schema=sch
txn.set_properties(test_a="test_aa", test_b="test_b", test_c="test_c")
```
+## Register a table
+
+To register a table using existing metadata:
+
+```python
+catalog.register_table(
+ identifier="docs_example.bids",
+ metadata_location="s3://warehouse/path/to/metadata.json"
+)
+```
+
## Load a table
There are two ways of reading an Iceberg table; through a catalog, and by
pointing at the Iceberg metadata directly. Reading through a catalog is
preferred, and directly pointing at the metadata is read-only.
@@ -216,6 +245,31 @@ catalog.table_exists("docs_example.bids")
Returns `True` if the table already exists.
+## Rename a table
+
+To rename a table:
+
+```python
+catalog.rename_table(
+ from_identifier="docs_example.bids",
+ to_identifier="docs_example.bids_backup"
+)
+```
+
+## Drop a table
+
+To drop a table:
+
+```python
+catalog.drop_table("docs_example.bids")
+```
+
+To drop a table and purge all data and metadata files:
+
+```python
+catalog.purge_table("docs_example.bids")
+```
+
## Write to a table
Reading and writing is being done using [Apache
Arrow](https://arrow.apache.org/). Arrow is an in-memory columnar format for
fast data interchange and in-memory analytics. Let's consider the following
Arrow Table:
