JingsongLi commented on code in PR #1364:
URL: https://github.com/apache/paimon-rust/pull/1364#discussion_r4581788764
##########
docs/src/python-binding.md:
##########
@@ -519,6 +548,106 @@ for stat in table.partition_stats():
print(stat.partition(), stat.record_count(), stat.total_size_bytes())
```
+### Tag Management
+
+`table.list_tags()` only inspects tags. Create, fetch, page, delete, and
rollback
+go through the catalog. The Python binding exposes one API surface for every
+catalog, but support depends on the catalog implementation.
+
+Filesystem Catalog supports creating, fetching, and deleting tags. It does not
+implement `list_tags_paged` or `rollback_to`.
+
+```python
+identifier = ("my_db", "users")
+
+# Pin the latest snapshot, or pass snapshot_id=... for an explicit snapshot.
+catalog.create_tag(identifier, "release-1.0")
+tag = catalog.get_tag(identifier, "release-1.0")
+print(tag.tag_name(), tag.snapshot().id())
+
+catalog.delete_tag(identifier, "release-1.0")
+```
+
+`create_tag(..., time_retained=...)` accepts an optional retention duration on
+both Filesystem Catalog and REST Catalog. `ignore_if_exists=True` ignores a
+duplicate tag name.
+
+REST Catalog also supports paged listing and rollback. These require
+`metastore: rest` and a running Paimon REST Server (see
+[REST Catalog](#rest-catalog) above). Finish every operation that needs the tag
+before deleting it:
+
+```python
+from pypaimon_rust.datafusion import Instant, PaimonCatalog
+
+catalog = PaimonCatalog({
+ "metastore": "rest",
+ "uri": "http://localhost:8080",
+ "warehouse": "my_warehouse",
+})
+identifier = ("my_db", "users")
+
+catalog.create_tag(identifier, "release-1.0", snapshot_id=1)
+names, next_token = catalog.list_tags_paged(identifier, max_results=100)
+
+# Pick one rollback target. Rolling back to an earlier snapshot deletes tags
+# that point at newer snapshots.
+catalog.rollback_to(identifier, Instant.tag("release-1.0"))
+# Or: catalog.rollback_to(identifier, Instant.snapshot(1))
+
+catalog.delete_tag(identifier, "release-1.0")
+```
+
+## Native Search
+
+Tables with vector or full-text indexes can search through the Rust core
without
+materializing candidate rows in Python first:
+
+```python
+# Scalar vector search
+search = (
+ table.new_vector_search_builder()
+ .with_vector_column("embedding")
+ .with_query_vector([1.0, 0.0])
+ .with_limit(10)
+)
+plan = search.new_vector_search_scan().scan()
+result = search.new_vector_search_read().read_plan(plan)
+batches = result.new_read_builder().with_projection(["id"]).read()
+
+# Batch vector search returns one GlobalIndexResult per input query, in order
+batch = (
+ table.new_batch_vector_search_builder()
+ .with_vector_column("embedding")
+ .with_query_vectors([[1.0, 0.0], [0.0, 1.0]])
+ .with_limit(5)
+)
+results = batch.execute()
+
+# Full-text search
+text = (
+ table.new_full_text_search_builder()
+ .with_query("body", "needle")
Review Comment:
[P2] Pass query DSL to the full-text search entry points
with_query(field, query) marks the input as DSL and passes it unchanged to
the full-text engine; it does not wrap plain text as a match query. Following
this example on a nonempty table with a built full-text index raises ValueError
with `json error: expected value at line 1 column 1`. The hybrid example at
line 639 fails in the same way through add_full_text_route. I reproduced both
with the Python extension built from 5852cc65; replacing `"needle"` with
`'{"match":{"query":"needle"}}'` makes both return the expected hits. Use the
serialized match DSL in both snippets and explain the expected query format.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]