feat: support named parameters in SQL queries and enhance type conversion

Author: tae898

bindings/python/docs/api/database.md

@@ -143,7 +143,7 @@ Execute a query and return results. Queries are read-only and don't require a tr
 
 - `language` (str): Query language - `"sql"`, `"opencypher"`, `"mongo"`, `"graphql"`
 - `command` (str): Query string
-- `*args`: Optional parameters to bind to the query
+- `*args`: Optional positional parameters, or one mapping for named parameters
 
 **Returns:**
 
@@ -164,6 +164,13 @@ for record in result:
 # Parameterized query
 result = db.query("sql", "SELECT FROM Person WHERE age > ?", 25)
 
+# Named parameters
+result = db.query(
+    "sql",
+    "SELECT FROM Person WHERE age IN :ages ORDER BY age",
+    {"ages": [25, 30, 35]},
+)
+
 # OpenCypher query
 result = db.query("opencypher", """
     MATCH (p:Person)-[:Knows]->(friend)
@@ -195,7 +202,7 @@ Execute a command (write operation). Commands modify data and **require a transa
 
 - `language` (str): Command language (usually `"sql"` or `"opencypher"`)
 - `command` (str): Command string
-- `*args`: Optional parameters
+- `*args`: Optional positional parameters, or one mapping for named parameters
 
 **Returns:**
 
@@ -223,7 +230,11 @@ db.command(
 # Data operations must be in a transaction
 with db.transaction():
     db.command("sql", "INSERT INTO Person SET name = ?, age = ?", "Alice", 30)
-    db.command("sql", "UPDATE Person SET age = 31 WHERE name = 'Alice'")
+    db.command(
+        "sql",
+        "UPDATE Person SET age = :age WHERE name = :name",
+        {"age": 31, "name": "Alice"},
+    )
     db.command("sql", "DELETE FROM Person WHERE name = 'Alice'")
 ```
 

bindings/python/docs/api/type_conversion.md

@@ -302,6 +302,12 @@ results = db.query(
     25, datetime(2024, 1, 1)  # Python types converted to Java
 )
 
+results = db.query(
+    "sql",
+    "SELECT FROM User WHERE age IN :ages",
+    {"ages": [25, 30, 35]}  # dict/list converted to Java Map/List
+)
+
 # Reading results (automatically converted back to Python)
 for result in results:
     name = result.get("name")         # str

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

@@ -137,11 +137,19 @@ result = db.query(
     {"name": "Alice", "min_age": 25}
 )
 
+# Named collection parameter
+result = db.query(
+    "sql",
+    "SELECT FROM Person WHERE age IN :ages ORDER BY age",
+    {"ages": [25, 30, 35]}
+)
+
 # Positional parameters
 result = db.query(
     "sql",
     "SELECT FROM Person WHERE name = ? AND age > ?",
-    ["Alice", 25]
+    "Alice",
+    25,
 )
 ```
 

bindings/python/src/arcadedb_embedded/core.py

@@ -4,8 +4,9 @@
 Database and DatabaseFactory classes for embedded database access.
 """
 
+from collections.abc import Mapping
 from os import PathLike
-from typing import Any, List, Mapping, Optional
+from typing import Any, List, Optional
 
 from .exceptions import ArcadeDBError
 from .graph import Document, Edge, Vertex
@@ -14,6 +15,7 @@
 from .importer import import_documents as run_document_import
 from .jvm import start_jvm
 from .results import ResultSet
+from .type_conversion import convert_python_to_java
 from .transactions import TransactionContext
 from .vector import to_java_float_array
 
@@ -50,6 +52,8 @@ def _convert_args(args):
         for arg in args:
             if np is not None and isinstance(arg, np.ndarray):
                 converted_args.append(to_java_float_array(arg))
+            elif isinstance(arg, Mapping):
+                converted_args.append(convert_python_to_java(arg))
             else:
                 converted_args.append(arg)
 

bindings/python/tests/test_hash_index_schema.py

@@ -82,3 +82,29 @@ def test_hash_index_schema_get_or_create_and_force_drop(temp_db_path):
 
         schema.drop_index(index_name, force=True)
         assert not schema.exists_index(index_name)
+
+
+def test_indexed_in_named_list_parameter_returns_rows(temp_db_path):
+    """Indexed SQL IN parameters should expand Python list values in named args."""
+    with arcadedb.create_database(temp_db_path) as db:
+        schema = db.schema
+        schema.create_document_type("IssueItem")
+        schema.create_property("IssueItem", "code", arcadedb.PropertyType.INTEGER)
+        schema.create_index(
+            "IssueItem", ["code"], index_type=arcadedb.IndexType.LSM_TREE
+        )
+
+        with db.transaction():
+            db.command("sql", "INSERT INTO IssueItem SET code = 1, name = 'one'")
+            db.command("sql", "INSERT INTO IssueItem SET code = 2, name = 'two'")
+            db.command("sql", "INSERT INTO IssueItem SET code = 3, name = 'three'")
+
+        rows = list(
+            db.query(
+                "sql",
+                "SELECT code FROM IssueItem WHERE code IN :codes ORDER BY code",
+                {"codes": [1, 2, 3]},
+            )
+        )
+
+        assert [row.get("code") for row in rows] == [1, 2, 3]