feat: Add example 18 for geo predicates with WKT points and polygons, update workflows and documentation

Author: tae898

.github/workflows/test-python-examples.yml

@@ -402,6 +402,12 @@ jobs:
                 timeout_duration=900
                 example_jvm_args=""
                 ;;
+              "18_geo_predicates_wkt.py")
+                example_args=""
+                example_name="$example (geo predicates with WKT points and polygons)"
+                timeout_duration=900
+                example_jvm_args=""
+                ;;
               "19_hash_index_exact_match.py")
                 example_args=""
                 example_name="$example (hash index exact-match workflow)"

bindings/python/docs/examples/18_geo_predicates_wkt.md

@@ -0,0 +1,55 @@
+# 18 - Geo Predicates With WKT Points And Polygons
+
+[View source code]({{ config.repo_url }}/blob/{{ config.extra.version_tag }}/bindings/python/examples/18_geo_predicates_wkt.py){ .md-button }
+
+This example demonstrates the current SQL-first geospatial surface in the Python
+bindings. It deliberately uses WKT stored in `STRING` properties and exercises the same
+`geo.*` predicates already covered by the Java engine tests:
+
+- creating a `GEOSPATIAL` index on point coordinates
+- storing depots as WKT `POINT` values
+- storing service areas as WKT `POLYGON` values
+- running direct `geo.within(...)` and `geo.intersects(...)` sanity checks
+- querying indexed point records with polygon filters
+- querying stored polygon records for overlap
+- reopening the database to verify persisted geospatial index metadata
+- dropping the index and rerunning the same filter to show full-scan fallback
+
+## Run
+
+From `bindings/python/examples`:
+
+```bash
+python3 18_geo_predicates_wkt.py
+```
+
+With a custom database path:
+
+```bash
+python3 18_geo_predicates_wkt.py --db-path ./my_test_databases/geo_demo
+```
+
+## Notes
+
+- The example stays SQL-first on purpose. There is no separate Python geometry object
+  API.
+- Geospatial values are stored as WKT strings and interpreted in queries via `geo.*`.
+- `GEOSPATIAL` indexes are for spatial predicates, not uniqueness constraints.
+- The example includes both the indexed path and the post-`DROP INDEX` fallback path so
+  the script shows that the index changes performance characteristics, not result
+  correctness.
+- If the packaged runtime does not include geospatial SQL functions or `GEOSPATIAL`
+  index support, the script prints a short explanation and exits.
+
+## Why This Example Exists
+
+The Java engine already has focused geospatial coverage for:
+
+- `CREATE INDEX ... GEOSPATIAL`
+- indexed `geo.within(...)` queries over stored WKT points
+- indexed `geo.intersects(...)` queries
+- fallback evaluation when the index is absent
+- persistence across reopen
+
+This Python example mirrors those behaviors with the public bindings API so the examples
+set includes a dedicated geospatial workflow without introducing a new Python-side DSL.

bindings/python/docs/examples/index.md

@@ -64,6 +64,9 @@ Four-way graph-ingest comparison. Repository guidance from these experiments is
 **[17 - Time Series End-to-End](17_timeseries_end_to_end.md)**
 SQL-first time-series workflow covering type creation, tagged inserts, range queries, and hourly bucket aggregation.
 
+**[18 - Geo Predicates With WKT Points And Polygons](18_geo_predicates_wkt.md)**
+SQL-first geospatial workflow covering WKT storage, GEOSPATIAL indexes, indexed `within` / `intersects`, polygon overlap queries, and fallback after dropping the index.
+
 **[19 - Hash Index Exact-Match Lookup Workflow](19_hash_index_exact_match.md)**
 SQL-first HASH index workflow covering unique and non-unique exact-match lookups, schema inspection, and duplicate-key rejection.
 
@@ -90,7 +93,8 @@ python 01_simple_document_store.py
 10. **Hybrid Queries** (13) - Combined SQL, graph, and vector workflow
 11. **Lifecycle And Ingest Benchmarks** (14/15/16) - Embedded lifecycle timing and ingest comparisons
 12. **Time Series SQL Workflow** (17) - Tagged samples, range queries, and bucket aggregation from Python
-13. **Hash Index Workflow** (19) - Exact-match HASH indexes, missing-key behavior, and duplicate protection
+13. **Geo Predicate Workflow** (18) - WKT points and polygons, indexed spatial filters, and fallback semantics
+14. **Hash Index Workflow** (19) - Exact-match HASH indexes, missing-key behavior, and duplicate protection
 
 ---