Enhance Python bindings for ArcadeDB with performance improvements and new features

- Updated benchmarking results in `results.md` to reflect current performance metrics and improvements.
- Added `get_java_database` method to the `Database` class for internal integrations.
- Refactored the `export_database` function in `exporter.py` to improve parameter naming and error handling.
- Introduced `iter_dicts` method in `ResultSet` for more efficient iteration over results.
- Enhanced `Document` and `Result` classes with caching for property names and improved type conversion handling.
- Improved error handling and type checking in various methods across the codebase.

Author: tae898

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

@@ -136,6 +136,10 @@ with db.transaction():
 Convert the document to a Python dictionary of its properties (metadata like RID/type
 is not included). Use `get_rid()` for the record ID if needed.
 
+**Performance note:** `to_dict()` eagerly converts the full document into Python
+data. For large scans or repeated wrapper access, prefer `get()` when you only need
+specific fields.
+
 ```python
 doc_dict = doc.to_dict()
 print(doc_dict)

bindings/python/docs/api/results.md

@@ -276,6 +276,11 @@ for person in people:
 - Passing data to other libraries
 - Debugging/inspection
 
+**Performance note:** `to_dict()` eagerly converts the current row to Python data.
+That is convenient for small projections and interop, but repeated `to_dict()` calls
+across a large result set will allocate Python objects for every returned property.
+For large scans, prefer iterating and reading only the fields you need with `get()`.
+
 ---
 
 ### `to_json() -> str`
@@ -307,6 +312,10 @@ for result in result_set:
 
 ### Converting to Lists and Dicts
 
+`ResultSet.to_list()` and `Result.to_dict()` are eager materializers. They are the
+right choice when you explicitly want Python-native data, but they are not the
+lowest-overhead path for large result sets.
+
 ```python
 # List of dictionaries (most common)
 result_set = db.query("sql", "SELECT FROM User")
@@ -352,7 +361,13 @@ print(df.head())
 For memory efficiency with large datasets:
 
 ```python
-# Process in batches
+# Stream one row at a time when you only need a few fields
+result_set = db.query("sql", "SELECT name, email FROM LargeTable")
+
+for result in result_set:
+    process_row(result.get("name"), result.get("email"))
+
+# Or process in batches when you do need dict materialization
 result_set = db.query("sql", "SELECT FROM LargeTable")
 
 batch = []

bindings/python/docs/development/troubleshooting.md

@@ -27,7 +27,7 @@ Common issues, solutions, and debugging techniques for ArcadeDB Python bindings.
     (no external Java install is needed):
 
     ```bash
-    uv pip uninstall -y arcadedb-embedded
+    uv pip uninstall arcadedb-embedded
     uv pip install --no-cache-dir arcadedb-embedded
     ```
 

bindings/python/docs/guide/core/queries.md

@@ -372,6 +372,10 @@ records share the same exact-match value, such as `customerId`, `status`, or `co
 
 ### ResultSet Methods
 
+Use `first()` or direct iteration when you want the lowest-overhead path.
+`to_list()` eagerly materializes the full result set into Python dictionaries, so it
+is best reserved for smaller results or explicit interop steps.
+
 ```python
 # first() - get first result
 result = db.query("sql", "SELECT FROM Person ORDER BY name")
@@ -393,6 +397,34 @@ else:
     print("No results found")
 ```
 
+### Performance and Materialization
+
+Use lazy access inside the hot path, and materialize only when you explicitly need
+Python-native containers.
+
+- Use `first()` when you only need one row.
+- Use direct iteration plus `get()` for large scans and request-time processing.
+- Use `to_list()` when you need to keep all rows in Python, hand them to another
+    library, or serialize them as a batch.
+- Use `iter_chunks()` when you need batch processing without loading everything at
+    once.
+- Use wrapper `to_dict()` only when you truly want the full document in Python.
+
+```python
+# Lowest-overhead path for large scans
+result = db.query("sql", "SELECT name, score FROM Item WHERE score > ?", 100)
+for row in result:
+        handle(row.get("name"), row.get("score"))
+
+# Materialize only at the boundary where Python-native data is needed
+result = db.query("sql", "SELECT name, score FROM Item WHERE score > ?", 100)
+payload = result.to_list()
+
+# For wrappers, prefer field access over full dict conversion in large loops
+for doc in db.query("sql", "SELECT FROM Person"):
+        process(doc.get("name"), doc.get("city"))
+```
+
 ## OpenCypher
 
 OpenCypher provides expressive graph pattern matching.

bindings/python/examples/12_vector_search.py

@@ -604,14 +604,13 @@ def _extract_result_id(rec) -> int | None:
             "sql",
             sql,
         ).first()
-        latencies_ms.append((time.perf_counter() - start) * 1000)
-
         neighbors = row.get("res") if row else []
         result_ids: List[int] = []
         for rec in neighbors:
             rid = _extract_result_id(rec)
             if rid is not None:
                 result_ids.append(rid)
+        latencies_ms.append((time.perf_counter() - start) * 1000)
 
         gt_list = gt_full.get(qid)
         if not gt_list:
@@ -656,16 +655,14 @@ def search_faiss(
         hnsw.efSearch = int(ef_search)
 
     for q_idx, qid in enumerate(qids):
+        start = time.perf_counter()
         qvec = np.ascontiguousarray(
             queries[q_idx : q_idx + 1].astype("float32", copy=True)
         )
         faiss.normalize_L2(qvec)
-
-        start = time.perf_counter()
         _dist, ids = index.search(qvec, int(k))
-        latencies_ms.append((time.perf_counter() - start) * 1000)
-
         result_ids = [int(doc_id) for doc_id in ids[0].tolist() if int(doc_id) >= 0]
+        latencies_ms.append((time.perf_counter() - start) * 1000)
 
         gt_list = gt_full.get(qid)
         if not gt_list:
@@ -732,13 +729,13 @@ def search_lancedb(
             except Exception:
                 pass
         rows = search.to_list()
-        latencies_ms.append((time.perf_counter() - start) * 1000)
 
         result_ids: List[int] = []
         for row in rows:
             rid = row.get("id") if isinstance(row, dict) else None
             if rid is not None:
                 result_ids.append(int(rid))
+        latencies_ms.append((time.perf_counter() - start) * 1000)
 
         gt_list = gt_full.get(qid)
         if not gt_list:
@@ -787,9 +784,8 @@ def search_bruteforce(
         else:
             candidate_idx = np.argpartition(scores, -topk)[-topk:]
             ranked_idx = candidate_idx[np.argsort(scores[candidate_idx])[::-1]]
-        latencies_ms.append((time.perf_counter() - start) * 1000)
-
         result_ids = [int(doc_id) for doc_id in ranked_idx.tolist()]
+        latencies_ms.append((time.perf_counter() - start) * 1000)
 
         gt_list = gt_full.get(qid)
         if not gt_list:
@@ -841,9 +837,8 @@ def search_pgvector(
                 (vector_to_pg_literal(queries[q_idx]), int(k)),
             )
             rows = cur.fetchall()
-            latencies_ms.append((time.perf_counter() - start) * 1000)
-
             result_ids = [int(row[0]) for row in rows]
+            latencies_ms.append((time.perf_counter() - start) * 1000)
             gt_list = gt_full.get(qid)
             if not gt_list:
                 continue
@@ -886,14 +881,13 @@ def search_qdrant(
             with_payload=False,
             with_vectors=False,
         )
-        latencies_ms.append((time.perf_counter() - start) * 1000)
-
         points = getattr(response, "points", response)
         result_ids: List[int] = []
         for point in points:
             point_id = getattr(point, "id", None)
             if point_id is not None:
                 result_ids.append(int(point_id))
+        latencies_ms.append((time.perf_counter() - start) * 1000)
 
         gt_list = gt_full.get(qid)
         if not gt_list:
@@ -1077,10 +1071,10 @@ def is_transient_milvus_search_error(exc: Exception) -> bool:
 
         if rows is None:
             raise RuntimeError("Milvus search returned no result rows")
-        latencies_ms.append((time.perf_counter() - start) * 1000)
 
         hits = rows[0] if rows else []
         result_ids = [int(getattr(hit, "id", -1)) for hit in hits]
+        latencies_ms.append((time.perf_counter() - start) * 1000)
 
         gt_list = gt_full.get(qid)
         if not gt_list:

bindings/python/examples/benchmark_results/summary_10_graph_olap_all_datasets.md

@@ -15,16 +15,16 @@ source "$HELPERS_SH"
 # Large         10,000  32GB    16
 # X-Large       25,000  64GB    32
 
-DATASET="stackoverflow-medium"
-BATCH_SIZE=5000
-MEM_LIMIT="8g"
+DATASET="stackoverflow-large"
+BATCH_SIZE=10000
+MEM_LIMIT="32g"
 THREADS=8
 RUNS=1
 SEED_START=0
 SERVER_FRACTION="0.8"
 MAX_CONNECTIONS=16
 BEAM_WIDTH=100
-QUANTIZATION="INT8"
+QUANTIZATION="NONE"
 STORE_VECTORS_IN_GRAPH=false
 ADD_HIERARCHY=true
 JVM_HEAP_FRACTION="0.80"

bindings/python/examples/scripts/run_11_vector_index_build_matrix.sh

@@ -15,8 +15,8 @@ source "$HELPERS_SH"
 # Large         16GB    16
 # X-Large       32GB    32
 
-DATASET="stackoverflow-large"
-MEM_LIMIT="16g"
+DATASET="stackoverflow-medium"
+MEM_LIMIT="4g"
 THREADS=8
 RUNS=1
 SEED_START=0