feat(vector-search): update vector query syntax to use parameterized inputs and add tests for parameterized neighbors

Co-authored-by: Copilot <copilot@github.com>

Author: tae898

bindings/python/examples/03_vector_search.py

@@ -257,22 +257,21 @@ def create_mock_embedding(category_seed, doc_seed):
 
     for query_num, cat_num in enumerate(sampled_categories, 1):
         category = f"category_{cat_num}"
+        index_name = "Article[embedding]"
 
         print(f"   🔍 Query {query_num}: Find documents similar to Category {cat_num}")
         print()
 
         query_embedding = create_mock_embedding(category, f"query{query_num}")
-
-        qvec_literal = (
-            "[" + ", ".join(str(float(x)) for x in query_embedding.tolist()) + "]"
-        )
         most_similar = db.query(
             "sql",
             (
                 "SELECT title, category, distance, (1 - distance) AS score "
-                "FROM (SELECT expand(vectorNeighbors('Article[embedding]', "
-                f"{qvec_literal}, 5))) ORDER BY distance"
+                "FROM (SELECT expand(vectorNeighbors(?, ?, ?))) ORDER BY distance"
             ),
+            index_name,
+            query_embedding,
+            5,
         ).to_list()
 
         print("      Top 5 MOST similar documents (smallest distance):")
@@ -288,9 +287,12 @@ def create_mock_embedding(category_seed, doc_seed):
             "sql",
             (
                 "SELECT title, category, distance, (1 - distance) AS score "
-                "FROM (SELECT expand(vectorNeighbors('Article[embedding]', "
-                f"{qvec_literal}, 50))) WHERE category = ? ORDER BY distance LIMIT 5"
+                "FROM (SELECT expand(vectorNeighbors(?, ?, ?))) "
+                "WHERE category = ? ORDER BY distance LIMIT 5"
             ),
+            index_name,
+            query_embedding,
+            50,
             category,
         ).to_list()
 

bindings/python/examples/06_vector_search_recommendations.py

@@ -377,6 +377,7 @@ def vector_based_recommendations(db, model, movie_title, property_suffix="", lim
         Query time in seconds
     """
     embedding_prop = f"embedding{property_suffix}"
+    index_name = f"Movie[{embedding_prop}]"
 
     # Find the movie to get its genres
     movies = list(
@@ -402,18 +403,16 @@ def vector_based_recommendations(db, model, movie_title, property_suffix="", lim
     )
 
     start_time = time.time()
-    qvec_literal = (
-        "[" + ", ".join(str(float(x)) for x in query_embedding.tolist()) + "]"
-    )
     rows = db.query(
         "sql",
         (
             "SELECT title, distance, (1 - distance) AS score "
-            "FROM (SELECT expand(vectorNeighbors('Movie["
-            f"{embedding_prop}]', "
-            f"{qvec_literal}, {int(limit + 5)}))) WHERE title <> ? "
+            "FROM (SELECT expand(vectorNeighbors(?, ?, ?))) WHERE title <> ? "
             "ORDER BY distance LIMIT ?"
         ),
+        index_name,
+        query_embedding,
+        int(limit + 5),
         movie_title,
         limit,
     ).to_list()

bindings/python/examples/12_vector_search.py

@@ -590,19 +590,16 @@ def _extract_result_id(rec) -> int | None:
 
     db = index["db"]
     index_name = index["name"]
-    query_literals = [vector_to_arcadedb_literal(qvec) for qvec in queries]
 
     for q_idx, qid in enumerate(qids):
-        sql = (
-            "SELECT vectorNeighbors("
-            f"'{index_name}', {query_literals[q_idx]}, {int(k)}, {int(ef_search)}"
-            ") as res"
-        )
-
         start = time.perf_counter()
         row = db.query(
             "sql",
-            sql,
+            "SELECT vectorNeighbors(?, ?, ?, ?) as res",
+            index_name,
+            queries[q_idx],
+            int(k),
+            int(ef_search),
         ).first()
         neighbors = row.get("res") if row else []
         result_ids: List[int] = []

bindings/python/src/arcadedb_embedded/vector.py

@@ -10,6 +10,13 @@
 from .exceptions import ArcadeDBError
 
 
+def _quote_identifier(identifier: str) -> str:
+    if not identifier:
+        raise ArcadeDBError("SQL identifier cannot be empty")
+
+    return "`" + identifier.replace("`", "``") + "`"
+
+
 def to_java_float_array(vector):
     """
     Convert a Python array-like object to a Java float array.
@@ -216,6 +223,9 @@ def _lookup_query_vector_by_key(self, key):
         vector_property = self._get_vector_property_name()
         type_name = self._get_type_name()
         id_property = self._get_id_property_name()
+        quoted_vector_property = _quote_identifier(vector_property)
+        quoted_type_name = _quote_identifier(type_name)
+        quoted_id_property = _quote_identifier(id_property)
 
         result = None
         try:
@@ -227,8 +237,8 @@ def _lookup_query_vector_by_key(self, key):
             result = self._database.query(
                 "sql",
                 (
-                    f"SELECT {vector_property} FROM {type_name} "
-                    f"WHERE {id_property} = ? LIMIT 1"
+                    f"SELECT {quoted_vector_property} AS `query_vector` FROM {quoted_type_name} "
+                    f"WHERE {quoted_id_property} = ? LIMIT 1"
                 ),
                 key,
             ).first()
@@ -238,7 +248,7 @@ def _lookup_query_vector_by_key(self, key):
                 f"No record found in type '{type_name}' where {id_property} = {key!r}"
             )
 
-        query_vector = result.get(vector_property)
+        query_vector = result.get("query_vector")
         if query_vector is None:
             raise ArcadeDBError(
                 f"Record found for {id_property} = {key!r} "

bindings/python/tests/test_vector_sql.py

@@ -520,6 +520,32 @@ def test_vector_neighbors(self, test_db):
             # Maybe it expects type name?
             pass
 
+    def test_vector_neighbors_accepts_parameterized_index_and_vector(self, test_db):
+        """SQL vectorNeighbors should accept bound index and vector parameters."""
+        test_db.command("sql", "CREATE VERTEX TYPE ParamItem")
+        test_db.command("sql", "CREATE PROPERTY ParamItem.vec ARRAY_OF_FLOATS")
+
+        test_db.command(
+            "sql",
+            'CREATE INDEX ON `ParamItem` (vec) LSM_VECTOR METADATA {"dimensions": 2}',
+        )
+
+        with test_db.transaction():
+            test_db.command("sql", "INSERT INTO `ParamItem` SET vec = [1.0, 0.0]")
+            test_db.command("sql", "INSERT INTO `ParamItem` SET vec = [0.0, 1.0]")
+
+        row = test_db.query(
+            "sql",
+            "SELECT vectorNeighbors(?, ?, ?) as res",
+            "ParamItem[vec]",
+            arcadedb.to_java_float_array([0.9, 0.1]),
+            1,
+        ).first()
+
+        res = row.get("res") if row else None
+        assert res is not None
+        assert len(res) == 1
+
     def test_vector_delete_and_search_others_sql(self, test_db):
         """Test deleting vertices in a larger dataset using SQL."""
         import random