Refactor vector index scripts and enhance ArcadeDB integration

- Updated `run_11_vector_index_build_matrix.sh` to use a smaller dataset and reduced resource limits for testing.
- Modified `run_12_vector_search_matrix.sh` to replace overquery factors with ef_search values for improved clarity and consistency.
- Adjusted `summarize_12_vector_search_matrix.sh` to reflect changes in search parameters and updated documentation accordingly.
- Enhanced `arcadedb_embedded/core.py` and `arcadedb_embedded/vector.py` to improve handling of PRODUCT quantization and ef_search parameters.
- Updated tests in `test_vector.py` to validate new ef_search functionality and ensure proper error handling for invalid inputs.
- Increased test coverage by adding scenarios for PRODUCT quantization requirements and ef_search validation.

Author: tae898

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

@@ -367,7 +367,7 @@ jobs:
                   echo ""
                   continue
                 fi
-                example_args="--backend arcadedb_sql --dataset stackoverflow-tiny --db-path $db_path --overquery-factors 1 --k 10 --query-limit 100 --query-runs 1 --query-order fixed --threads 1 --mem-limit 2g --run-label ci12_arcadedb_sql"
+                example_args="--backend arcadedb_sql --dataset stackoverflow-tiny --db-path $db_path --ef-search-values 100 --k 10 --query-limit 100 --query-runs 1 --query-order fixed --threads 1 --mem-limit 2g --run-label ci12_arcadedb_sql"
                 example_name="$example (vector search, arcadedb_sql backend, minimal)"
                 timeout_duration=1200
                 example_jvm_args=""

bindings/python/README.md

@@ -2,7 +2,7 @@
 
 Native Python bindings for ArcadeDB - the multi-model database that supports Graph, Document, Key/Value, Search Engine, Time Series, and Vector models.
 
-**Status**: ✅ Production Ready | **Tests**: 279 Passed Across 27 Test Files | **Platforms**: 4 Supported
+**Status**: ✅ Production Ready | **Tests**: 282 Passed | **Platforms**: 4 Supported
 
 ---
 
@@ -92,7 +92,7 @@ Import: `import arcadedb_embedded as arcadedb`
 
 ## 🧪 Testing
 
-**Status**: 279 passed across 27 test files
+**Status**: 282 passed
 
 ```bash
 # Run all tests

bindings/python/docs/api/database.md

@@ -666,17 +666,25 @@ Create a vector index for similarity search (JVector implementation). Existing r
 - `vector_property` (str): Property storing vector arrays
 - `dimensions` (int): Vector dimensionality
 - `distance_function` (str): `"cosine"`, `"euclidean"`, or `"inner_product"`
-- `max_connections` (int): Max connections per node (default: 16). Maps to `maxConnections` in HNSW (JVector).
-- `beam_width` (int): Beam width for search/construction (default: 100). Maps to `beamWidth` in HNSW (JVector).
-- `quantization` (str | None): `"INT8"` (recommended), `"BINARY"`, `"PRODUCT"` for PQ, or `None` for full precision (default: `"INT8"`).
-    Prefer `"INT8"` for current production usage in these bindings; `"PRODUCT"`/PQ is currently not recommended for production workloads.
+- `max_connections` (int): Max connections per node (default: 16). Maps to
+  `maxConnections` in HNSW (JVector).
+- `beam_width` (int): Beam width for search/construction (default: 100). Maps to
+  `beamWidth` in HNSW (JVector).
+- `quantization` (str | None): `"INT8"` (recommended), `"BINARY"`, `"PRODUCT"` for PQ,
+  or `None` for full precision (default: `"INT8"`). Prefer `"INT8"` for current
+  production usage in these bindings; `"PRODUCT"`/PQ is currently not recommended for
+  production workloads. In current ArcadeDB engine builds, `"PRODUCT"` also requires
+  enough indexed vectors per bucket for PQ training. For tiny corpora, set `pq_clusters`
+  explicitly to a small value or prefer another quantization mode.
 - `location_cache_size` (int | None): Override location cache size (default: `None`, uses engine default).
 - `graph_build_cache_size` (int | None): Override graph build cache size (default: `None`, uses engine default).
 - `mutations_before_rebuild` (int | None): Override rebuild threshold (default: `None`, uses engine default).
 - `store_vectors_in_graph` (bool): Persist vectors inline in graph file (faster reopen/search, larger graph).
 - `add_hierarchy` (bool | None): Force enabling/disabling HNSW hierarchy (default: `True`).
 - `pq_subspaces` (int | None): PQ subspaces (M). Requires `quantization="PRODUCT"`.
-- `pq_clusters` (int | None): PQ clusters per subspace (K). Requires `quantization="PRODUCT"`.
+- `pq_clusters` (int | None): PQ clusters per subspace (K). Requires
+  `quantization="PRODUCT"`. In current ArcadeDB engine builds, this should not exceed
+  the number of indexed vectors available for PQ training in a bucket.
 - `pq_center_globally` (bool | None): PQ global centering flag. Requires `quantization="PRODUCT"`.
 - `pq_training_limit` (int | None): PQ training sample cap. Requires `quantization="PRODUCT"`.
 - `build_graph_now` (bool): If `True` (default), eagerly builds/loads the vector graph immediately after index creation. Set to `False` to defer graph preparation to first query.

bindings/python/docs/api/schema.md

@@ -282,10 +282,13 @@ schema.create_index("Article", ["content"], index_type="FULL_TEXT")
 
 **Vector (JVector) Parameters:**
 
-- **max_connections**: Max connections per node (default: 16; typical 8-32). Maps to JVector `maxConnections`.
-- **beam_width**: Beam width for build/search (default: 100; typical 64-200). Maps to JVector `beamWidth`.
+- **max_connections**: Max connections per node (default: 16; typical 8-32). Maps to
+  JVector `maxConnections`.
+- **beam_width**: Beam width for build/search (default: 100; typical 64-200). Maps to
+  JVector `beamWidth`.
 - **dimensions**: Vector size (must match your embeddings).
-- **overquery_factor**: Search-time candidate multiplier (default: 4; typical 2-8). Higher improves recall with slower search.
+- **ef_search**: Query-time exact-search beam width override via `find_nearest(...,
+  ef_search=...)`. Leave unset to use ArcadeDB's default/adaptive behavior.
 
 ## Type Inspection
 

bindings/python/docs/api/vector.md

@@ -151,11 +151,15 @@ db.create_vector_index(
     - Maps to `beamWidth` in JVector
     - Higher = better recall, slower search
         - Typical range: 50-500
-- `quantization` (str | None): `"INT8"` (recommended), `"BINARY"`, `"PRODUCT"`, or `None` (default: `"INT8"`)
+- `quantization` (str | None): `"INT8"` (recommended), `"BINARY"`, `"PRODUCT"`, or
+  `None` (default: `"INT8"`)
+    - In current ArcadeDB engine builds, `"PRODUCT"` also requires enough indexed
+      vectors per bucket for PQ training. For tiny corpora, set `pq_clusters` explicitly
+      to a small value or prefer `"INT8"`, `"BINARY"`, or `None`.
     - Prefer `"INT8"` for current production usage in these bindings.
     - `"PRODUCT"`/PQ is available but currently not recommended for production workloads.
-- `build_graph_now` (bool): If `True` (default), eagerly prepares the vector graph during index creation.
-    Set to `False` to defer graph preparation until first query.
+- `build_graph_now` (bool): If `True` (default), eagerly prepares the vector graph
+  during index creation. Set to `False` to defer graph preparation until first query.
 
 **Returns:**
 
@@ -192,7 +196,7 @@ print(f"Created vector index: {index}")
 
 ---
 
-### `VectorIndex.find_nearest(query_vector, k=10, overquery_factor=4, allowed_rids=None)`
+### `VectorIndex.find_nearest(query_vector, k=10, ef_search=None, allowed_rids=None)`
 
 Find k-nearest neighbors to the query vector.
 
@@ -207,8 +211,8 @@ to `find_nearest` may perform lazy graph preparation and therefore take longer.
     - NumPy array: `np.array([0.1, 0.2, ...])`
     - Any array-like iterable
 - `k` (int): Number of neighbors to return (default: 10)
-- `overquery_factor` (int): Multiplier for search-time over-querying (implicit efSearch)
-    (default: 4)
+- `ef_search` (int | None): Optional exact-search beam width override. `None` uses
+  ArcadeDB's default/adaptive search behavior.
 - `allowed_rids` (List[str]): Optional list of RID strings (e.g. `["#1:0", "#2:5"]`) to
   restrict search (default: `None`)
 
@@ -514,11 +518,12 @@ db.close()
 - **Medium (16)**: Balanced (default)
 - **Higher (32)**: Better recall, more memory, slower build
 
-**overquery_factor (search size):**
+**ef_search (exact search beam width):**
 
-- **Lower (2)**: Faster search, lower recall
-- **Medium (4)**: Balanced (default)
-- **Higher (8)**: Better recall, slower search
+- **Unset (`None`)**: Use ArcadeDB's default/adaptive behavior
+- **Lower (32)**: Faster search, lower recall
+- **Medium (100)**: Balanced explicit override
+- **Higher (200)**: Better recall, slower search
 
 **beam_width:**
 

bindings/python/docs/development/build-architecture.md

@@ -19,7 +19,7 @@ This document describes the build architecture for creating platform-specific Py
 
 **All supported platforms:**
 
-- ✅ Current suite: 279 passed
+- ✅ Current suite: 282 passed
 - ✅ 31.7M JARs (83 files, identical across platforms)
 - ✅ All native runners (no QEMU emulation)
 - ✅ Reproducible builds (pinned runner versions)

bindings/python/docs/development/ci-setup.md

@@ -102,7 +102,7 @@ All 4 platforms passing the bindings suite and example workflows:
 
 | Platforms | Wheel Size | JRE Size | Tests |
 |-----------|-----------|----------|-------|
-| linux/amd64, linux/arm64, darwin/arm64, windows/amd64 | ~70-75M | ~60M | 279 passed ✅ |
+| linux/amd64, linux/arm64, darwin/arm64, windows/amd64 | ~70-75M | ~60M | 282 passed ✅ |
 
 **All platforms include:**
 

bindings/python/docs/development/testing.md

@@ -3,9 +3,9 @@
 Comprehensive testing documentation for ArcadeDB Python bindings.
 
 !!! success "Test Coverage"
-    **27 test files** in the current bindings suite
+    Current bindings suite
 
-    - **Current package**: 279 passed
+    - **Current package**: 282 passed
     - All ArcadeDB features working (SQL, OpenCypher, Studio)
 
 ## Quick Navigation

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

@@ -5,7 +5,7 @@ The ArcadeDB Python bindings have a comprehensive test suite covering all major
 ## Quick Statistics
 
 !!! success "Test Results"
-    - **Current package**: ✅ 279 passed across 27 test files
+    - **Current package**: ✅ 282 passed
     - Environment-specific skips may vary depending on optional components
 
 ## What's Tested
@@ -130,7 +130,7 @@ pytest -m "not slow"
 When the current bindings test suite passes, you should see a clean all-green summary.
 
 ```
-======================== 279 passed ========================
+======================== 282 passed ========================
 ```
 
 

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

@@ -408,7 +408,8 @@ with arcadedb.create_database("./test_db") as db:
 3. **Set constraints** - Use `set_mandatory()`, `set_not_null()`
 4. **Index frequently queried** - Properties used in WHERE clauses
 5. **Use appropriate types** - Match property types to data
-6. **Configure JVector** - Tune `max_connections`, `beam_width`, `overquery_factor`, `dimensions` for vectors
+6. **Configure JVector** - Tune `max_connections`, `beam_width`, `dimensions`, and
+   optional query-time `ef_search` overrides for vectors
 
 ## See Also