Refactor documentation and examples for clarity and consistency

- Updated vector search recommendations documentation to clarify key parameters and best practices.
- Revised basic example documentation to use relative paths for database creation and improved query examples.
- Enhanced index documentation to remove outdated checks and improve clarity on example usage.
- Adjusted installation and getting started guides to standardize database path usage.
- Updated queries guide to emphasize Gremlin over Cypher for graph queries, including migration guidance.
- Improved graph documentation to recommend Gremlin for edge creation and querying.
- Enhanced Java API coverage documentation to reflect improved coverage metrics.
- Updated simple document store example to utilize the Document API for CRUD operations.
- Improved vector benchmark script to run benchmarks in parallel with limited workers.
- Updated copyright year in documentation files.
- Adjusted core.py to standardize database path usage in examples.
- Updated test README to clarify database creation paths for server mode.

Author: tae898

bindings/python/README.md

@@ -46,7 +46,7 @@ We publish development versions (`X.Y.Z.devN`) for every push to main when `pom.
 import arcadedb_embedded as arcadedb
 
 # Create database (context manager for automatic open and close)
-with arcadedb.create_database("/tmp/mydb") as db:
+with arcadedb.create_database("./mydb") as db:
     # Create schema
     db.command("sql", "CREATE DOCUMENT TYPE Person")
 

bindings/python/docs/api-access-methods.md

@@ -20,7 +20,7 @@ Direct JVM method calls via JPype - **recommended for most Python applications**
 import arcadedb_embedded as arcadedb
 
 # Direct database access - NO server needed
-with arcadedb.create_database("/tmp/mydb") as db:
+with arcadedb.create_database("./mydb") as db:
     # Create schema (auto-transactional)
     db.schema.create_document_type("Person")
     db.schema.create_property("Person", "name", "STRING")
@@ -45,10 +45,11 @@ with arcadedb.create_database("/tmp/mydb") as db:
 import arcadedb_embedded as arcadedb
 
 # Server manages databases (still Java API calls)
-server = arcadedb.create_server("/tmp/server_data", "password123")
+server = arcadedb.create_server("./server_data", "password123")
 server.start()
 
 try:
+    # "mydb" will be created at ./server_data/databases/mydb
     db = server.create_database("mydb")
 
     # Schema operations are auto-transactional
@@ -89,7 +90,7 @@ import requests
 from requests.auth import HTTPBasicAuth
 
 # Start server (using Java API)
-server = arcadedb.create_server("/tmp/server_data", "password123")
+server = arcadedb.create_server("./server_data", "password123")
 server.start()
 
 try:
@@ -152,7 +153,7 @@ import requests
 from requests.auth import HTTPBasicAuth
 
 # Start server
-server = arcadedb.create_server("/tmp/hybrid", "password123")
+server = arcadedb.create_server("./hybrid", "password123")
 server.start()
 
 try:

bindings/python/docs/api/database.md

@@ -29,7 +29,7 @@ Create a new database at the specified path.
 ```python
 import arcadedb_embedded as arcadedb
 
-db = arcadedb.create_database("/tmp/mydb")
+db = arcadedb.create_database("./mydb")
 try:
     # Schema operations are auto-transactional
     db.schema.create_document_type("Person")
@@ -41,7 +41,7 @@ finally:
 !!! tip "Use Context Manager"
     Prefer using `with` statement for automatic cleanup:
     ```python
-    with arcadedb.create_database("/tmp/mydb") as db:
+    with arcadedb.create_database("./mydb") as db:
         # Database automatically closed on exit
         pass
     ```
@@ -71,7 +71,7 @@ Open an existing database.
 **Example:**
 
 ```python
-with arcadedb.open_database("/tmp/mydb") as db:
+with arcadedb.open_database("./mydb") as db:
     result = db.query("sql", "SELECT FROM Person")
     print(f"Found {len(list(result))} records")
 ```
@@ -97,10 +97,10 @@ Check if a database exists at the given path.
 **Example:**
 
 ```python
-if arcadedb.database_exists("/tmp/mydb"):
-    db = arcadedb.open_database("/tmp/mydb")
+if arcadedb.database_exists("./mydb"):
+    db = arcadedb.open_database("./mydb")
 else:
-    db = arcadedb.create_database("/tmp/mydb")
+    db = arcadedb.create_database("./mydb")
 ```
 
 ---
@@ -490,7 +490,7 @@ Close the database connection.
 **Example:**
 
 ```python
-db = arcadedb.create_database("/tmp/mydb")
+db = arcadedb.create_database("./mydb")
 try:
     # Use database
     pass
@@ -562,7 +562,7 @@ DatabaseFactory(path: str)
 **Example:**
 
 ```python
-factory = arcadedb.DatabaseFactory("/tmp/mydb")
+factory = arcadedb.DatabaseFactory("./mydb")
 if factory.exists():
     db = factory.open()
 else:
@@ -607,7 +607,7 @@ All database objects support context managers:
 
 ```python
 # Database
-with arcadedb.create_database("/tmp/mydb") as db:
+with arcadedb.create_database("./mydb") as db:
     # Automatic cleanup
     pass
 
@@ -681,7 +681,7 @@ All database operations can raise `ArcadeDBError`:
 from arcadedb_embedded import ArcadeDBError
 
 try:
-    with arcadedb.create_database("/tmp/mydb") as db:
+    with arcadedb.create_database("./mydb") as db:
         # Schema operations are auto-transactional
         db.schema.create_document_type("User")
         db.schema.create_property("User", "email", "STRING")
@@ -706,11 +706,11 @@ except ArcadeDBError as e:
 
 ```python
 # ✅ Good - automatic cleanup
-with arcadedb.create_database("/tmp/mydb") as db:
+with arcadedb.create_database("./mydb") as db:
     pass
 
 # ❌ Avoid - manual cleanup
-db = arcadedb.create_database("/tmp/mydb")
+db = arcadedb.create_database("./mydb")
 db.close()
 ```
 
@@ -740,10 +740,10 @@ db.query("sql", f"SELECT FROM Person WHERE name = '{user_input}'")
 ### 4. Check Database Existence
 
 ```python
-if arcadedb.database_exists("/tmp/mydb"):
-    db = arcadedb.open_database("/tmp/mydb")
+if arcadedb.database_exists("./mydb"):
+    db = arcadedb.open_database("./mydb")
 else:
-    db = arcadedb.create_database("/tmp/mydb")
+    db = arcadedb.create_database("./mydb")
 ```
 
 ---

bindings/python/docs/api/importer.md

@@ -72,7 +72,7 @@ stats = arcadedb.import_csv(
 import arcadedb_embedded as arcadedb
 
 with arcadedb.create_database("./restored_db") as db:
-    db.command("sql", "IMPORT DATABASE file:///tmp/export.jsonl.tgz WITH commitEvery = 50000")
+    db.command("sql", "IMPORT DATABASE file:///export.jsonl.tgz WITH commitEvery = 50000")
 ```
 
 For XML imports, use the `Importer` class directly (see below) with `format_type='xml'`.

bindings/python/docs/api/record-wrappers.md

@@ -23,7 +23,7 @@ as the base class for `Vertex` and `Edge`.
 import arcadedb_embedded as arcadedb
 from arcadedb_embedded.graph import Document, Vertex, Edge
 
-with arcadedb.create_database("/tmp/mydb") as db:
+with arcadedb.create_database("./mydb") as db:
     # Schema operations are auto-transactional
     db.schema.create_document_type("Note")
 

bindings/python/docs/development/testing/best-practices.md

@@ -17,6 +17,7 @@ with arcadedb.create_database("./mydb") as db:
 # Also good for servers
 with arcadedb.create_server(root_path="./databases") as server:
     server.start()
+    # "mydb" will be created at ./databases/mydb
     db = server.create_database("mydb")
     # ... work ...
 # Server automatically stopped
@@ -101,6 +102,7 @@ db2 = arcadedb.open_database("./mydb")    # ❌ LockException!
 # Recommended: Start server first
 server = arcadedb.create_server(root_path="./databases")
 server.start()
+# "mydb" will be created at ./databases/mydb
 db = server.create_database("mydb")
 
 # Use embedded access (fast!)
@@ -260,6 +262,7 @@ for i in range(1000):
 # Fast: No HTTP overhead, direct JVM call
 server = arcadedb.create_server(root_path="./databases")
 server.start()
+# "mydb" will be created at ./databases/mydb
 db = server.create_database("mydb")
 
 # This is as fast as standalone embedded!

bindings/python/docs/development/testing/test-concurrency.md

@@ -325,6 +325,7 @@ server = arcadedb.create_server(root_path="./databases")
 server.start()
 
 # Create database through server
+# "mydb" will be created at ./databases/mydb
 db = server.create_database("mydb")
 
 # Now you have TWO ways to access:
@@ -406,6 +407,7 @@ db.close()
 # Process 1: Start server
 server = arcadedb.create_server(root_path="./databases")
 server.start()
+# "mydb" will be created at ./databases/mydb
 db = server.create_database("mydb")
 
 # Process 2+: Use HTTP API

bindings/python/docs/development/testing/test-server-patterns.md

@@ -128,22 +128,25 @@ server.stop()
 
 **Why `close()` is required:**
 
-```
 Your Python process:
-  db = create_database("./temp_db")  🔒 Lock acquired
-  # ... work ...
-  db.close()                         🔓 Lock released
 
-  server.start()
-  server.get_database("mydb")        🔒 Server acquires lock ✅
+```python
+db = create_database("./temp_db")  🔒 Lock acquired
+# ... work ...
+db.close()                         🔓 Lock released
+
+server.start()
+server.get_database("mydb")        🔒 Server acquires lock ✅
+```
 
 Without close():
-  db = create_database("./temp_db")  🔒 Lock acquired
-  # ... work ...
-  # Forgot db.close()!              🔒 Still locked
+```python
+db = create_database("./temp_db")  🔒 Lock acquired
+# ... work ...
+# Forgot db.close()!               🔒 Still locked
 
-  server.start()
-  server.get_database("mydb")        ❌ LockException!
+server.start()
+server.get_database("mydb")        ❌ LockException!
 ```
 
 !!! warning "Common Mistake"

bindings/python/docs/development/testing/test-server.md

@@ -28,6 +28,7 @@ server = arcadedb.create_server(
 server.start()
 
 # Create database
+# "mydb" will be created at ./databases/mydb
 db = server.create_database("mydb")
 
 # Use it

bindings/python/docs/examples/01_simple_document_store.md

@@ -8,17 +8,13 @@ This comprehensive example demonstrates ArcadeDB's document capabilities using a
 
 The example creates a task management system showcasing:
 
-- **Rich Data Types** - STRING, BOOLEAN, INTEGER, FLOAT, DECIMAL, DATE, DATETIME, LIST OF STRING, and Arrays
+- **Rich Data Types** - STRING, BOOLEAN, INTEGER, FLOAT, DECIMAL, DATE, DATETIME, LIST with element types, and Arrays
 - **NULL Handling** - INSERT with NULL, UPDATE to NULL, queries with IS NULL/IS NOT NULL
 - **SQL Operations** - Complete CRUD workflow with ArcadeDB SQL
 - **Built-in Functions** - date() for date literals, uuid() for unique IDs, sysdate() for dynamic timestamps
 - **Record Types** - Understanding Documents vs Vertices vs Edges
 - **Schema Flexibility** - Typed properties for performance with schema-optional flexibility
-- **Type Safety** - LIST OF STRING for validated array data
-
-## Source Code
-
-The complete example is available at: [`examples/01_simple_document_store.py`](https://github.com/humemai/arcadedb-embedded-python/blob/main/bindings/python/examples/01_simple_document_store.py)
+- **Type Safety** - Validated array data with element type specification
 
 ## Key Learning Points
 
@@ -29,15 +25,15 @@ ArcadeDB provides comprehensive data type support with NULL handling:
 ```python
 from datetime import date
 import uuid
-import arcadedb
+import arcadedb_embedded as arcadedb
 
 with arcadedb.create_database("./task_db") as db:
     # Schema operations are auto-transactional (no wrapper needed)
     db.schema.create_document_type("Task")
     db.schema.create_property("Task", "title", "STRING")
     db.schema.create_property("Task", "priority", "STRING")
     db.schema.create_property("Task", "completed", "BOOLEAN")
-    db.schema.create_property("Task", "tags", "LIST OF STRING")  # Type-safe arrays
+    db.schema.create_property("Task", "tags", "LIST", of_type="STRING")
     db.schema.create_property("Task", "created_date", "DATE")
     db.schema.create_property("Task", "due_datetime", "DATETIME")
     db.schema.create_property("Task", "estimated_hours", "FLOAT")
@@ -68,7 +64,7 @@ Learn about built-in functions and NULL handling:
 ```python
 from datetime import datetime
 import uuid
-import arcadedb
+import arcadedb_embedded as arcadedb
 
 with arcadedb.open_database("./task_db") as db:
     # Insert with Python-native types (UUID, datetime handled by converter)
@@ -82,8 +78,15 @@ with arcadedb.open_database("./task_db") as db:
         task.save()
 
     # Query for NULL values (reads don't need transaction)
-    result = db.query("sql", "SELECT FROM Task WHERE due_datetime IS NULL")
-    result = db.query("sql", "SELECT FROM Task WHERE cost IS NULL")
+    print("Tasks with NULL due_datetime:")
+    result = db.query("sql", "SELECT title, due_datetime, cost FROM Task WHERE due_datetime IS NULL")
+    for record in result:
+        print(f"  Title: {record.get('title')}, Due: {record.get('due_datetime')}, Cost: {record.get('cost')}")
+
+    print("\nTasks with NULL cost:")
+    result = db.query("sql", "SELECT title, due_datetime, cost FROM Task WHERE cost IS NULL")
+    for record in result:
+        print(f"  Title: {record.get('title')}, Due: {record.get('due_datetime')}, Cost: {record.get('cost')}")
 
     # UPDATE via API (fetch + mutate in transaction)
     with db.transaction():
@@ -107,7 +110,7 @@ Understanding when to use different record types:
 The example demonstrates:
 
 - **NULL Values** - Optional fields with IS NULL/IS NOT NULL queries
-- **Type-Safe Arrays** - LIST OF STRING for validated collections
+- **Type-Safe Arrays** - LIST with of_type parameter for validated collections
 - **DECIMAL Handling** - Java BigDecimal conversion via float(str(value))
 - **DATETIME Literals** - String literals automatically parsed to DATETIME type
 - **Schema-Optional Flexibility** - Define properties for performance, add ad-hoc fields when needed
@@ -134,7 +137,7 @@ After running, examine the created files:
 
 ```text
 my_test_databases/task_db/
-├── configuration.json     # Database configuration
+├── configuration.json    # Database configuration
 ├── schema.json           # Type definitions with LIST OF STRING
 ├── Task_*.bucket         # Data storage files with tasks
 ├── dictionary.*.dict     # String compression dictionary
@@ -154,8 +157,10 @@ After mastering this example:
 **Q: How does ArcadeDB handle NULL values?**
 A: All ArcadeDB types support NULL by default. You can INSERT NULL, UPDATE to NULL, and query with IS NULL/IS NOT NULL operators.
 
-**Q: What's the difference between LIST and LIST OF STRING?**
-A: LIST is a generic untyped list. LIST OF STRING provides type validation ensuring all elements are strings, giving better performance and data integrity.
+**Q: How do I create a LIST with STRING elements?**
+A: In Python API: `db.schema.create_property("Task", "tags", "LIST", of_type="STRING")`.
+In SQL: `CREATE PROPERTY Task.tags LIST OF STRING`. Both create a type-safe list of
+strings.
 
 **Q: Why use typed properties?**
 A: They provide better performance, validation, and enable advanced features like indexes. But ArcadeDB is schema-optional - you can still add properties dynamically.