Refactor vector index creation to use SQL LSM_VECTOR

- Updated documentation and examples to reflect the preferred SQL method for creating vector indexes.
- Removed Python object API calls for vector index creation in favor of SQL commands.
- Ensured that SQL index creation builds the vector graph immediately by default.
- Added tests to verify immediate queryability of vector indexes created via SQL.
- Updated test suite to reflect the new implementation, increasing the number of passed tests from 282 to 290.

Author: tae898

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**: 282 Passed | **Platforms**: 4 Supported
+**Status**: ✅ Production Ready | **Tests**: 290 Passed | **Platforms**: 4 Supported
 
 ---
 
@@ -92,7 +92,7 @@ Import: `import arcadedb_embedded as arcadedb`
 
 ## 🧪 Testing
 
-**Status**: 282 passed
+**Status**: 290 passed
 
 ```bash
 # Run all tests

bindings/python/docs/api/database.md

@@ -658,7 +658,14 @@ db.create_vector_index(
 ) -> VectorIndex
 ```
 
-Create a vector index for similarity search (JVector implementation). Existing records are indexed automatically when the index is created. By default, graph preparation is performed immediately (`build_graph_now=True`).
+Create a vector index for similarity search (JVector implementation). Existing records
+are indexed automatically when the index is created. By default, graph preparation is
+performed immediately (`build_graph_now=True`).
+
+For normal application code and documentation examples, prefer SQL `CREATE INDEX ...
+LSM_VECTOR METADATA {...}` because it is cleaner and aligns with the SQL-first workflow.
+Keep `create_vector_index()` for Python-driven setup, tests, or manual control when you
+specifically need that surface.
 
 **Parameters:**
 
@@ -703,7 +710,7 @@ db.command("sql", "CREATE VERTEX TYPE Document")
 db.command("sql", "CREATE PROPERTY Document.embedding ARRAY_OF_FLOATS")
 db.command("sql", "CREATE PROPERTY Document.id STRING")
 
-# Create vector index
+# Secondary/manual option: create vector index from Python
 index = db.create_vector_index("Document", "embedding", dimensions=384)
 
 # Add vectors
@@ -714,17 +721,14 @@ with db.transaction():
         vertex.set("embedding", arcadedb.to_java_float_array(embedding))
         vertex.save()
 
-# Search
+# Preferred query path: SQL search
 query_vector = np.random.rand(384)
-results = index.find_nearest(query_vector, k=5)
-
-# Preferred when you want richer query composition
 qvec_literal = "[" + ", ".join(str(float(x)) for x in query_vector.tolist()) + "]"
 rows = db.query(
     "sql",
     (
         "SELECT id, distance, (1 - distance) AS score "
-        "FROM (SELECT expand(`vector.neighbors`('Document[embedding]', "
+        "FROM (SELECT expand(vectorNeighbors('Document[embedding]', "
         f"{qvec_literal}, 5))) ORDER BY distance"
     ),
 ).to_list()

bindings/python/docs/api/schema.md

@@ -287,8 +287,9 @@ schema.create_index("Article", ["content"], index_type="FULL_TEXT")
 - **beam_width**: Beam width for build/search (default: 100; typical 64-200). Maps to
   JVector `beamWidth`.
 - **dimensions**: Vector size (must match your embeddings).
-- **ef_search**: Query-time exact-search beam width override via `find_nearest(...,
-  ef_search=...)`. Leave unset to use ArcadeDB's default/adaptive behavior.
+- **ef_search**: Query-time exact-search beam width override via SQL
+  `vectorNeighbors(..., k, ef_search)`. Leave unset to use ArcadeDB's default/adaptive
+  behavior.
 
 ## Type Inspection
 

bindings/python/docs/api/transactions.md

@@ -28,7 +28,7 @@ It is important to distinguish between operations that require explicit transact
 | **Data Write** | `db.command("sql", "INSERT...")`, `db.command("sql", "UPDATE...")`, `db.command("sql", "DELETE...")`, `db.command("opencypher", "CREATE ...")` | **Required** (Wrap in `with db.transaction():`) |
 | **Bulk Operations** | `db.command("sql", "IMPORT DATABASE...")`, `db.import_documents(...)`, `db.graph_batch(...)` | **Auto-transactional / auto-managed** (Built-in transaction management) |
 | **Data Read** | `db.query()`, `db.command("sql", "SELECT...")`, `db.lookup_by_rid()` | **Optional** (Can run outside transaction for better performance) |
-| **Vector Operations** | `db.create_vector_index()` | **Auto-transactional** (Do NOT wrap) |
+| **Vector Operations** | `CREATE INDEX ... LSM_VECTOR` | **Auto-transactional** (Do NOT wrap) |
 
 ### Key Distinction: `db.query()` vs `db.command()`
 

bindings/python/docs/api/vector.md

@@ -106,14 +106,42 @@ print(type(py_list))  # <class 'list'>
 
 Wrapper for ArcadeDB's vector index, providing similarity search capabilities.
 
-Creation and configuration fit well in the Python object API. For search, prefer SQL
-or Cypher when you need filtering, projection, self-exclusion, or custom score
-shaping. The Python search methods below are convenience helpers for simple
-embedded-mode workflows.
+For creation, prefer SQL `CREATE INDEX ... LSM_VECTOR METADATA {...}`. For search,
+prefer SQL or Cypher when you need filtering, projection, self-exclusion, or custom
+score shaping. The Python methods below are convenience helpers for simple
+embedded-mode workflows and for advanced/manual control. They are not the primary
+application-facing workflow this documentation recommends.
+
+For SQL snippets in this documentation, use `vectorNeighbors(...)` by default. The
+engine also exposes an equivalent dotted canonical function name, but the alias is more
+ergonomic in SQL because it does not require backticks.
+
+### Preferred Creation: SQL
+
+Use SQL as the default creation surface:
+
+```python
+db.command(
+    "sql",
+    """
+    CREATE INDEX ON Document (embedding)
+    LSM_VECTOR
+    METADATA {
+        "dimensions": 384,
+        "similarity": "COSINE"
+    }
+    """
+)
+```
+
+SQL builds the vector graph immediately by default. Add `"buildGraphNow": false` only
+if you intentionally want lazy preparation.
 
 ### Creation via Database
 
-Vector indexes are created using the `Database.create_vector_index()` method:
+`Database.create_vector_index()` still exists, but it should be treated as a secondary,
+Python-driven helper for manual setup, tests, and API completeness rather than the
+primary documented workflow.
 
 **Signature:**
 
@@ -177,8 +205,6 @@ db.create_vector_index(
 
 ```python
 import arcadedb_embedded as arcadedb
-from arcadedb_embedded import to_java_float_array
-import numpy as np
 
 # Create database and schema
 db = arcadedb.create_database("./vector_db")
@@ -189,7 +215,7 @@ db.command("sql", "CREATE PROPERTY Document.text STRING")
 db.command("sql", "CREATE PROPERTY Document.embedding ARRAY_OF_FLOATS")
 db.command("sql", "CREATE INDEX ON Document (id) UNIQUE")
 
-# Create vector index
+# Secondary option: create vector index from Python
 index = db.create_vector_index(
     vertex_type="Document",
     vector_property="embedding",
@@ -209,9 +235,14 @@ print(f"Created vector index: {index}")
 
 Find k-nearest neighbors to the query vector.
 
+Treat this as a helper/manual API. For normal application queries, prefer SQL
+`vectorNeighbors` so search composes naturally with filtering, projection, and record
+exclusion.
+
 **Note:** With default settings (`build_graph_now=True` in `create_vector_index`), graph
-preparation runs during index creation. If you set `build_graph_now=False`, the first call
-to `find_nearest` may perform lazy graph preparation and therefore take longer.
+preparation runs during index creation. In the preferred SQL path, this eager behavior is
+also the default. If you explicitly disable eager preparation, the first call to
+`find_nearest` may perform lazy graph preparation and therefore take longer.
 
 **Parameters:**
 
@@ -264,7 +295,7 @@ rows = db.query(
     "sql",
     (
         "SELECT id, distance, (1 - distance) AS score "
-        "FROM (SELECT expand(`vector.neighbors`('Document[embedding]', "
+        "FROM (SELECT expand(vectorNeighbors('Document[embedding]', "
         f"{qvec_literal}, 10))) WHERE id <> ? ORDER BY distance LIMIT 5"
     ),
     "doc-42",
@@ -292,6 +323,9 @@ Find nearest neighbors by reusing the vector stored on an existing record.
 This is the Python wrapper for the common "search from an existing record" workflow,
 using the index's configured `id_property` to look up the source vector first.
 
+Treat this as a convenience helper. If you need the recommended query surface, use SQL
+or Cypher instead.
+
 **Parameters:**
 
 - `key`: Value of the configured ID property
@@ -350,14 +384,20 @@ print(meta["dimensions"], meta["similarity_function"], meta["id_property"])
 
 Force an immediate rebuild/preparation of the vector graph.
 
+This is a maintenance API, not part of the normal SQL-first creation workflow.
+
 Use this when you want to control when rebuild cost is paid, for example:
 
 - after bulk inserts,
 - after bulk deletes/removals,
 - before opening traffic after large vector mutations.
 
-This is especially useful if you created the index with `build_graph_now=False` and want
-to avoid rebuild work on the first query.
+This is especially useful if you created the index with `build_graph_now=False` or with
+SQL metadata `"buildGraphNow": false` and want to avoid rebuild work on the first query.
+
+When you create an `LSM_VECTOR` index through SQL, ArcadeDB now builds the graph
+immediately by default. Use `build_graph_now()` only for explicit maintenance or when
+you intentionally deferred graph preparation.
 
 **Returns:**
 
@@ -395,16 +435,23 @@ db.command("sql", "CREATE PROPERTY Document.content STRING")
 db.command("sql", "CREATE PROPERTY Document.embedding ARRAY_OF_FLOATS")
 db.command("sql", "CREATE INDEX ON Document (id) UNIQUE")
 
-# Create vector index (384 dimensions for all-MiniLM-L6-v2)
-index = db.create_vector_index(
-    vertex_type="Document",
-    vector_property="embedding",
-    dimensions=384,
-    distance_function="cosine",
-    max_connections=16,
-    beam_width=100  # Default beam width
+# Preferred: create vector index in SQL
+db.command(
+    "sql",
+    """
+    CREATE INDEX ON Document (embedding)
+    LSM_VECTOR
+    METADATA {
+        "dimensions": 384,
+        "similarity": "COSINE",
+        "maxConnections": 16,
+        "beamWidth": 100
+    }
+    """
 )
 
+index = db.schema.get_vector_index("Document", "embedding")
+
 # Sample documents
 documents = [
     {"id": "doc1", "title": "Python Tutorial",
@@ -471,13 +518,21 @@ db.command("sql", "CREATE PROPERTY Product.price DECIMAL")
 db.command("sql", "CREATE PROPERTY Product.features ARRAY_OF_FLOATS")
 db.command("sql", "CREATE INDEX ON Product (category) NOTUNIQUE")
 
-# Create vector index
-index = db.create_vector_index(
-    vertex_type="Product",
-    vector_property="features",
-    dimensions=128
+# Create vector index in SQL
+db.command(
+    "sql",
+    """
+    CREATE INDEX ON Product (features)
+    LSM_VECTOR
+    METADATA {
+        "dimensions": 128,
+        "similarity": "COSINE"
+    }
+    """
 )
 
+index = db.schema.get_vector_index("Product", "features")
+
 # Add products with feature vectors
 products = [
     {"id": "p1", "name": "Laptop", "category": "Electronics",
@@ -552,16 +607,23 @@ db.command("sql", "CREATE PROPERTY Image.filename STRING")
 db.command("sql", "CREATE PROPERTY Image.path STRING")
 db.command("sql", "CREATE PROPERTY Image.embedding ARRAY_OF_FLOATS")
 
-# Create index
-index = db.create_vector_index(
-    vertex_type="Image",
-    vector_property="embedding",
-    dimensions=512,
-    distance_function="cosine",
-    max_connections=24,  # Higher for image search
-    beam_width=200
+# Create index in SQL
+db.command(
+    "sql",
+    """
+    CREATE INDEX ON Image (embedding)
+    LSM_VECTOR
+    METADATA {
+        "dimensions": 512,
+        "similarity": "COSINE",
+        "maxConnections": 24,
+        "beamWidth": 200
+    }
+    """
 )
 
+index = db.schema.get_vector_index("Image", "embedding")
+
 # Index images
 image_files = ["img1.jpg", "img2.jpg", "img3.jpg"]
 
@@ -662,7 +724,10 @@ import numpy as np
 
 try:
     # Dimension mismatch
-    index = db.create_vector_index("Doc", "emb", dimensions=384)
+    db.command(
+        "sql",
+        'CREATE INDEX ON Doc (emb) LSM_VECTOR METADATA {"dimensions": 384}',
+    )
 
     v = db.new_vertex("Doc")
     v.set("emb", to_java_float_array(np.random.rand(512)))  # Wrong size!

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: 282 passed
+- ✅ Current suite: 290 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 | 282 passed ✅ |
+| linux/amd64, linux/arm64, darwin/arm64, windows/amd64 | ~70-75M | ~60M | 290 passed ✅ |
 
 **All platforms include:**
 

bindings/python/docs/development/contributing.md

@@ -620,10 +620,10 @@ mkdocs build
 git add src/ tests/ docs/
 
 # Commit with clear message
-git commit -m "Add vector search distance function parameter
+git commit -m "Refine vector search docs and tests
 
-- Added distance_function parameter to create_vector_index()
-- Supports cosine, euclidean, and inner_product
+- Clarified SQL-first vector index workflow
+- Updated vector docs and tests
 - Added tests for all distance functions
 - Updated API documentation
 

bindings/python/docs/development/testing.md

@@ -5,7 +5,7 @@ Comprehensive testing documentation for ArcadeDB Python bindings.
 !!! success "Test Coverage"
     Current bindings suite
 
-    - **Current package**: 282 passed
+    - **Current package**: 290 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**: ✅ 282 passed
+    - **Current package**: ✅ 290 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.
 
 ```
-======================== 282 passed ========================
+======================== 290 passed ========================
 ```