This is an automated email from the ASF dual-hosted git repository.
JingsongLi pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/paimon-rust.git
The following commit(s) were added to refs/heads/main by this push:
new 958912f docs(python): fix README fence and document current
read/write APIs (#457)
958912f is described below
commit 958912fb394484de74ae969fa6e6bb4dcf0ad81d
Author: hechao <[email protected]>
AuthorDate: Tue Jul 7 14:51:29 2026 +0800
docs(python): fix README fence and document current read/write APIs (#457)
---
bindings/python/README.md | 53 ++++++++++++++++++++++++++++++++++++++++++++++-
1 file changed, 52 insertions(+), 1 deletion(-)
diff --git a/bindings/python/README.md b/bindings/python/README.md
index 6e67c8a..6f173a7 100644
--- a/bindings/python/README.md
+++ b/bindings/python/README.md
@@ -56,6 +56,57 @@ ctx.sql("DROP TEMPORARY TABLE paimon.default.my_temp")
For the full SQL reference, see the [SQL Integration
docs](https://paimon.apache.org/docs/master/sql/).
+### Native Read / Write
+
+Beyond SQL, you can use the lower-level read and write APIs directly from
Python.
+Time travel is supported via the `options` dict on `new_read_builder`.
+
+```python
+import pyarrow as pa
+from pypaimon_rust.datafusion import SQLContext, PaimonCatalog
+
+WAREHOUSE = "/tmp/paimon-warehouse"
+
+# --- DDL/DML via DataFusion SQLContext ---
+ctx = SQLContext()
+ctx.register_catalog("paimon", {"warehouse": WAREHOUSE})
+ctx.sql("CREATE SCHEMA paimon.my_db")
+ctx.sql("CREATE TABLE paimon.my_db.users (id INT, name STRING, PRIMARY KEY
(id))")
+ctx.sql("INSERT INTO paimon.my_db.users VALUES (1, 'alice'), (2, 'bob')")
+catalog = PaimonCatalog({"warehouse": WAREHOUSE})
+table = catalog.get_table("my_db.users")
+
+# --- Read data ---
+read_builder = table.new_read_builder().with_projection(["id",
"name"]).with_limit(100)
+scan = read_builder.new_scan()
+plan = scan.plan()
+batches = read_builder.new_read().read(plan.splits())
+
+print(f"\nRead: {batches[0].num_rows} rows")
+print(batches[0])
+
+# --- Write data, from a PyArrow RecordBatch ---
+batch = pa.record_batch(
+ [[3, 4], ["charlie", "diana"]],
+ schema=pa.schema([("id", pa.int32()), ("name", pa.utf8())]),
+)
+write_builder = table.new_write_builder()
+writer = write_builder.new_write()
+writer.write_arrow(batch)
+commit_messages = writer.prepare_commit()
+write_builder.new_commit().commit(commit_messages)
+
+# --- Time travel: read a past version ---
+# Supported options: scan.version, scan.timestamp-millis, scan.snapshot-id, or
scan.tag-name
+read_builder_tt = table.new_read_builder({"scan.snapshot-id": "1"})
+scan_tt = read_builder_tt.new_scan()
+plan_tt = scan_tt.plan()
+batches_tt = read_builder_tt.new_read().read(plan_tt.splits())
+
+print(f"\nRead: {batches_tt[0].num_rows} rows")
+print(batches_tt[0])
+```
+
## Setup
Install [uv](https://docs.astral.sh/uv/getting-started/installation/):
@@ -88,4 +139,4 @@ cd bindings/python
```shell
make test
-```````
+```
