Add tests and examples for server mode and HTTP access in Python bindings

- Introduced new tests for HASH index schema, materialized views, and timeseries SQL.
- Added example 21 demonstrating server mode and HTTP access, covering database creation, schema management, and mixed access patterns.
- Updated documentation to include new examples and tests.
- Improved code formatting for consistency across various Python scripts.

Author: tae898

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

@@ -25,7 +25,7 @@ on:
         description: "Glob pattern(s) for examples to run (space-separated, relative to bindings/python/examples)."
         required: false
         type: string
-        default: "0[1-9]_*.py 1[0-9]_*.py 20_*.py"
+        default: "0[1-9]_*.py 1[0-9]_*.py 2[0-1]_*.py"
       build-version:
         description: "Override package version (PEP 440) for build.sh"
         required: false
@@ -37,10 +37,10 @@ on:
       examples:
         description: "Glob pattern(s) for examples to run (space-separated, relative to bindings/python/examples)."
         required: false
-        default: "0[1-9]_*.py 1[0-9]_*.py 20_*.py"
+        default: "0[1-9]_*.py 1[0-9]_*.py 2[0-1]_*.py"
 
 env:
-  EXAMPLES: ${{ inputs.examples || '0[1-9]_*.py 1[0-9]_*.py 20_*.py' }}
+  EXAMPLES: ${{ inputs.examples || '0[1-9]_*.py 1[0-9]_*.py 2[0-1]_*.py' }}
 
 permissions:
   contents: read
@@ -420,6 +420,12 @@ jobs:
                 timeout_duration=900
                 example_jvm_args=""
                 ;;
+              "21_server_mode_http_access.py")
+                example_args=""
+                example_name="$example (server mode and HTTP access workflow)"
+                timeout_duration=900
+                example_jvm_args=""
+                ;;
               *)
                 example_args=""
                 example_name="$example"

bindings/python/docs/api/async_executor.md

@@ -303,7 +303,7 @@ Schedule asynchronous record deletion.
 ```python
 # Delete old records
 to_delete = list(db.query("sql", "SELECT FROM LogEntry WHERE timestamp < ?",
-                          cutoff_date))
+                            cutoff_date))
 
 async_exec = db.async_executor()
 

bindings/python/docs/api/citation.md

@@ -0,0 +1,46 @@
+# Citation API
+
+The `cite()` helper returns the version-specific DOI URL for released ArcadeDB Embedded Python builds.
+
+## Overview
+
+Use this helper when you want a citable release URL for papers, reports, or reproducibility notes.
+
+The helper is intentionally small:
+
+- released versions return a Zenodo-backed DOI URL
+- unreleased development versions raise `ArcadeDBError`
+- unknown versions also raise `ArcadeDBError`
+
+## Function
+
+### `cite(version=None) -> str`
+
+Return the DOI URL for a released package version.
+
+**Parameters:**
+
+- `version` (`str | None`): Version to cite. If omitted, the installed package version is used.
+
+**Returns:**
+
+- `str`: DOI URL such as `https://doi.org/10.5281/zenodo....`
+
+**Raises:**
+
+- `ArcadeDBError`: If the version is unreleased or missing from the citation map.
+
+**Example:**
+
+```python
+import arcadedb_embedded as arcadedb
+
+doi_url = arcadedb.cite("26.1.1.post3")
+print(doi_url)
+```
+
+## Notes
+
+- This helper only covers released versions present in the package's internal DOI map.
+- Development builds intentionally do not pretend to be citable releases.
+- If a new release is missing here, the release metadata needs to be updated in the Python source.

bindings/python/docs/api/graph_batch.md

@@ -0,0 +1,72 @@
+# GraphBatch API
+
+The `GraphBatch` helper exposes ArcadeDB's high-throughput graph-ingest path from Python.
+
+## Overview
+
+Use `GraphBatch` when you need to load many vertices and edges efficiently.
+
+This is the repository's current recommended bulk graph-ingest path from Python.
+
+You typically create it through `db.graph_batch(...)` rather than constructing the class directly.
+
+## Entry Point
+
+### `db.graph_batch(...) -> GraphBatch`
+
+Create a configured batch helper tied to the current database.
+
+**Common options:**
+
+- `batch_size`: buffered edge batch size before flush
+- `expected_edge_count`: sizing hint for large runs
+- `light_edges`: create property-less light edges when appropriate
+- `commit_every`: commit cadence during batch work
+- `use_wal`: enable WAL for stronger durability
+- `wal_flush`: flush policy such as `no`, `yes_nometadata`, `yes_full`
+- `parallel_flush`: flush deferred work in parallel
+
+**Example:**
+
+```python
+with db.graph_batch(batch_size=1000, expected_edge_count=50000) as batch:
+    alice = batch.create_vertex("Person", name="Alice")
+    bob = batch.create_vertex("Person", name="Bob")
+    batch.new_edge(alice, "Knows", bob, since=2024)
+```
+
+## Common Operations
+
+### `create_vertex(type_name, **properties)`
+
+Create and persist a single vertex.
+
+### `create_vertices(type_name, count_or_properties)`
+
+Create many vertices efficiently and return their RIDs.
+
+### `new_edge(source, edge_type, destination, **properties)`
+
+Buffer an edge for creation during flush/close.
+
+### `flush()`
+
+Force buffered edge work to disk early.
+
+### `close()`
+
+Flush remaining work and finalize the batch.
+
+### Counters
+
+The helper also exposes counters such as:
+
+- `get_total_edges_created()`
+- `get_buffered_edge_count()`
+- `get_deferred_incoming_edge_count()`
+
+## Notes
+
+- Prefer `GraphBatch` over importer-based graph loading for Python-managed bulk ingest.
+- `wal_flush` validation is intentionally strict and raises `ValueError` for invalid modes.
+- See the graph-ingest examples and tests for realistic usage patterns.

bindings/python/docs/api/schema.md

@@ -470,7 +470,7 @@ if not user_type.get("phoneNumber"):
 
 # Add index to existing type (auto-transactional)
 if not any(idx.get_property_names() == ["email"]
-           for idx in schema.get_type("User").get_indexes()):
+            for idx in schema.get_type("User").get_indexes()):
     schema.create_index("User", ["email"], unique=True)
     print("✅ Added email index")
 ```
@@ -615,7 +615,7 @@ def migrate_schema_v1_to_v2(db):
 
     # Add new index
     if not any(idx.get_property_names() == ["status"]
-               for idx in user_type.get_indexes()):
+                for idx in user_type.get_indexes()):
         db.schema.create_index("User", ["status"])
         print("✅ Added status index")
 

bindings/python/docs/api/transactions.md

@@ -426,13 +426,13 @@ with db.transaction():
 with db.transaction():
     # Debit from Alice
     db.command("sql",
-               "UPDATE Account SET balance = balance - 100 "
-               "WHERE name = 'Alice'")
+                "UPDATE Account SET balance = balance - 100 "
+                "WHERE name = 'Alice'")
 
     # Credit to Bob
     db.command("sql",
-               "UPDATE Account SET balance = balance + 100 "
-               "WHERE name = 'Bob'")
+                "UPDATE Account SET balance = balance + 100 "
+                "WHERE name = 'Bob'")
 
 # Both updates commit together or neither commits
 ```

bindings/python/docs/api/vector.md

@@ -455,11 +455,11 @@ index = db.schema.get_vector_index("Document", "embedding")
 # Sample documents
 documents = [
     {"id": "doc1", "title": "Python Tutorial",
-     "content": "Learn Python programming basics"},
+        "content": "Learn Python programming basics"},
     {"id": "doc2", "title": "Machine Learning Guide",
-     "content": "Introduction to ML algorithms"},
+        "content": "Introduction to ML algorithms"},
     {"id": "doc3", "title": "Database Systems",
-     "content": "Understanding relational databases"},
+        "content": "Understanding relational databases"},
 ]
 
 # Index documents
@@ -536,11 +536,11 @@ index = db.schema.get_vector_index("Product", "features")
 # Add products with feature vectors
 products = [
     {"id": "p1", "name": "Laptop", "category": "Electronics",
-     "price": 999.99, "features": np.random.rand(128)},
+        "price": 999.99, "features": np.random.rand(128)},
     {"id": "p2", "name": "Mouse", "category": "Electronics",
-     "price": 29.99, "features": np.random.rand(128)},
+        "price": 29.99, "features": np.random.rand(128)},
     {"id": "p3", "name": "Desk", "category": "Furniture",
-     "price": 299.99, "features": np.random.rand(128)},
+        "price": 299.99, "features": np.random.rand(128)},
 ]
 
 with db.transaction():

bindings/python/docs/development/architecture.md

@@ -354,7 +354,7 @@ if __name__ == "__main__":
 
     with mp.Pool(processes=4) as pool:
         pool.starmap(process_chunk,
-                     [("./mydb", chunk) for chunk in chunks])
+                        [("./mydb", chunk) for chunk in chunks])
 ```
 
 ## Performance Considerations

bindings/python/docs/development/testing.md

@@ -54,6 +54,42 @@ Comprehensive testing documentation for ArcadeDB Python bindings.
 
     Executable coverage for representative Python snippets in the MkDocs docs tree
 
+-   :material-source-branch: **[GraphBatch Tests](testing/test-graph-batch.md)**
+
+    ---
+
+    Engine-backed bulk graph ingest helper coverage
+
+-   :material-map-marker-radius: **[Geo Predicate SQL Tests](testing/test-geo-predicate-sql.md)**
+
+    ---
+
+    SQL `geo.within` and `geo.intersects` semantics
+
+-   :material-chart-timeline-variant: **[Timeseries SQL Tests](testing/test-timeseries-sql.md)**
+
+    ---
+
+    SQL-first timeseries type creation, range queries, and bucketing
+
+-   :material-table-search: **[Materialized View SQL Tests](testing/test-materialized-view-sql.md)**
+
+    ---
+
+    Materialized view lifecycle, refresh, and metadata coverage
+
+-   :material-map-search: **[Graph Algorithms SQL Tests](testing/test-graph-algorithms-sql.md)**
+
+    ---
+
+    `shortestPath`, `dijkstra`, and `astar` runtime coverage
+
+-   :material-pound-box: **[Hash Index Schema Tests](testing/test-hash-index-schema.md)**
+
+    ---
+
+    HASH index creation, discovery, and drop coverage
+
 -   :material-graph: **[OpenCypher Tests](testing/test-opencypher.md)**
 
     ---
@@ -101,7 +137,7 @@ pytest --cov=arcadedb_embedded --cov-report=html
 | **Server Patterns** | Embedded+HTTP combinations, lock management |
 | **Data Import** | SQL import workflows, type inference, batch commits |
 | **Query Languages** | SQL, OpenCypher |
-| **Advanced Features** | Unicode support, schema introspection, large datasets |
+| **Advanced Features** | Unicode support, schema introspection, geospatial SQL, timeseries SQL, graph algorithms, materialized views, HASH indexes |
 
 ## Key Concepts
 
@@ -158,6 +194,12 @@ tests/
 ├── test_server.py            # Server mode (6 tests)
 ├── test_concurrency.py       # Concurrency (4 tests)
 ├── test_server_patterns.py   # Patterns (4 tests)
+├── test_graph_batch.py       # Bulk graph ingest helper
+├── test_graph_algorithms_sql.py  # shortestPath / dijkstra / astar
+├── test_geo_predicate_sql.py # Geospatial SQL predicates
+├── test_timeseries_sql.py    # Timeseries SQL coverage
+├── test_materialized_view_sql.py # Materialized view lifecycle
+├── test_hash_index_schema.py # HASH index schema API coverage
 ├── test_import_database.py   # Import database tests
 ├── test_docs_examples.py     # Validates runnable docs examples
 ├── test_cypher.py            # OpenCypher (tests)

bindings/python/docs/development/testing/overview.md

@@ -19,6 +19,12 @@ The test suite covers:
 - ✅ **Query languages** - SQL, OpenCypher
 - ✅ **Vector search** - HNSW (JVector) based Vector indexes, similarity search
 - ✅ **Data import** - CSV with batch commits and type inference
+- ✅ **Graph ingest helper** - `GraphBatch` buffering and flush behavior
+- ✅ **Geospatial SQL** - `geo.within`, `geo.intersects`, null/boundary semantics
+- ✅ **Time series SQL** - `CREATE TIMESERIES TYPE`, range queries, bucketing
+- ✅ **Materialized views** - create, refresh, alter, drop lifecycle
+- ✅ **Graph algorithms** - `shortestPath`, `dijkstra`, `astar`
+- ✅ **HASH schema indexes** - create, discover, idempotent drop behavior
 - ✅ **Unicode support** - International characters, emoji
 - ✅ **Schema introspection** - Querying database metadata
 - ✅ **Type conversions** - Python/Java type mapping
@@ -68,14 +74,20 @@ pytest -v -s
 Test counts evolve over time. For the latest per-file counts, run `pytest -v -rs`.
 
 | Test File | Description |
-|-----------|-------------|
+| --------- | ----------- |
 | [`test_core.py`](test-core.md) | Core database operations, CRUD, transactions, queries |
 | [`test_server.py`](test-server.md) | Server mode, HTTP API, configuration |
 | [`test_concurrency.py`](test-concurrency.md) | File locking, thread safety, multi-process behavior |
 | [`test_server_patterns.py`](test-server-patterns.md) | Best practices for embedded + server mode |
 | [`test_import_database.py`](test-importer.md) | SQL `IMPORT DATABASE` scenarios and format coverage |
 | [`test_docs_examples.py`](test-docs-examples.md) | Executes representative Python snippets from the documentation site |
 | [`test_cypher.py`](test-opencypher.md) | OpenCypher query language |
+| [`test_graph_batch.py`](test-graph-batch.md) | Bulk graph-ingest helper coverage |
+| [`test_geo_predicate_sql.py`](test-geo-predicate-sql.md) | Geospatial SQL predicate semantics |
+| [`test_timeseries_sql.py`](test-timeseries-sql.md) | Time-series SQL type creation, range filters, and bucketing |
+| [`test_materialized_view_sql.py`](test-materialized-view-sql.md) | Materialized view lifecycle and refresh behavior |
+| [`test_graph_algorithms_sql.py`](test-graph-algorithms-sql.md) | SQL graph algorithm runtime coverage |
+| [`test_hash_index_schema.py`](test-hash-index-schema.md) | HASH index schema API behavior |
 | [`test_jvm_args.py`](test-jvm-args.md) | JVM args handling |
 | [`test_vector_params_verification.py`](test-vector-params-verification.md) | Vector param validation |
 
@@ -129,12 +141,10 @@ pytest -m "not slow"
 
 When the current bindings test suite passes, you should see a clean all-green summary.
 
-```
+```text
 ======================== 290 passed ========================
 ```
 
-
-
 ## Next Steps
 
 - **New to testing?** Start with [Core Tests](test-core.md)