feat: enhance SQL identifier handling and validation in Python bindings

Author: tae898

bindings/python/examples/16_import_database_vs_transactional_graph_ingest.py

@@ -56,6 +56,7 @@
 """
 
 import argparse
+import re
 import shutil
 import time
 from pathlib import Path
@@ -66,6 +67,17 @@
 ColumnDef = Tuple[str, str]
 
 NUMERIC_COLUMN_TYPES = {"INTEGER", "LONG"}
+SAFE_IDENTIFIER_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
+
+
+def _validated_identifier(identifier: str) -> str:
+    if not SAFE_IDENTIFIER_RE.fullmatch(identifier):
+        raise ValueError(f"Unsafe SQL identifier: {identifier!r}")
+    return identifier
+
+
+def _quote_identifier(identifier: str) -> str:
+    return f"`{_validated_identifier(identifier)}`"
 
 
 def result_int(row, *keys: str) -> int:
@@ -131,9 +143,10 @@ def edge_endpoints(edge_id: int, vertex_count: int) -> Tuple[int, int]:
 
 
 def build_rid_lookup_for_vertex_type(db, vertex_type: str) -> Dict[int, str]:
+    safe_vertex_type = _quote_identifier(vertex_type)
     rows = db.query(
         "sql",
-        f"SELECT Id, @rid as rid FROM {vertex_type}",
+        f"SELECT Id, @rid as rid FROM {safe_vertex_type}",  # nosec B608 - validated identifier
     ).to_list()
     rid_lookup: Dict[int, str] = {}
     for row in rows:
@@ -167,11 +180,11 @@ def query_one_or_none(result_set):
 def collect_vertex_sample(
     db, vertex_type: str, vertex_id: int, props: List[ColumnDef]
 ) -> dict:
+    safe_vertex_type = _quote_identifier(vertex_type)
     row = query_one_or_none(
         db.query(
             "sql",
-            # vertex_type is a constant from this script; vertex_id is bound as parameter.
-            f"SELECT FROM {vertex_type} WHERE Id = ?",
+            f"SELECT FROM {safe_vertex_type} WHERE Id = ?",  # nosec B608 - validated identifier
             vertex_id,
         )
     )
@@ -230,6 +243,7 @@ def collect_graph_signature(
         str(db_path),
         jvm_kwargs={"heap_size": heap_size} if heap_size else None,
     ) as db:
+        safe_vertex_type = _quote_identifier(vertex_type)
         vertex_int_props = [
             name for name, kind in vertex_props if kind in NUMERIC_COLUMN_TYPES
         ]
@@ -242,7 +256,10 @@ def collect_graph_signature(
             "sum(Id) AS sum_id",
             "min(Id) AS min_id",
             "max(Id) AS max_id",
-        ] + [f"sum({name}) AS sum_{name}" for name in vertex_int_props]
+        ] + [
+            f"sum({_quote_identifier(name)}) AS sum_{_validated_identifier(name)}"
+            for name in vertex_int_props
+        ]
 
         edge_match_aggregate_fields = [
             "count(r) AS count",
@@ -254,8 +271,7 @@ def collect_graph_signature(
         vertex_aggregate = query_one_or_none(
             db.query(
                 "sql",
-                # vertex_aggregate_fields and vertex_type are script-local constants.
-                f"SELECT {', '.join(vertex_aggregate_fields)} FROM {vertex_type}",
+                f"SELECT {', '.join(vertex_aggregate_fields)} FROM {safe_vertex_type}",  # nosec B608 - validated identifier
             )
         )
         edge_aggregate = query_one_or_none(

bindings/python/examples/20_graph_algorithms_route_planning.py

@@ -29,11 +29,21 @@
 from __future__ import annotations
 
 import argparse
+import re
 import shutil
 from pathlib import Path
 
 import arcadedb_embedded as arcadedb
 
+SAFE_IDENTIFIER_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
+
+
+def _quote_identifier(identifier: str) -> str:
+    if not SAFE_IDENTIFIER_RE.fullmatch(identifier):
+        raise ValueError(f"Unsafe SQL identifier: {identifier!r}")
+    return f"`{identifier}`"
+
+
 CITIES = [
     {"code": "ALPHA", "name": "Alpha Hub", "lat": 0.0, "lon": 0.0},
     {"code": "BRAVO", "name": "Bravo Junction", "lat": 1.0, "lon": 0.0},
@@ -284,8 +294,7 @@ def insert_seed_data(db) -> None:
         for route in ROUTES:
             db.command(
                 "sql",
-                # route['edge_type'] is a constant from the demo schema.
-                f"CREATE EDGE {route['edge_type']} "
+                f"CREATE EDGE {_quote_identifier(route['edge_type'])} "  # nosec B608 - validated identifier
                 "FROM (SELECT FROM City WHERE code = ? LIMIT 1) "
                 "TO (SELECT FROM City WHERE code = ? LIMIT 1) "
                 "SET distance = ?, duration = ?, risk = ?, lane = ?",
@@ -758,7 +767,7 @@ def run_reopen_phase(db_path: Path) -> None:
         route_count = sum(
             reopened_db.query(
                 "sql",
-                f"SELECT count(*) AS count FROM {edge_type}",
+                f"SELECT count(*) AS count FROM {_quote_identifier(edge_type)}",  # nosec B608 - validated identifier
             )
             .first()
             .get("count")

bindings/python/examples/22_graph_analytical_view_sql.py

@@ -36,6 +36,7 @@
 from __future__ import annotations
 
 import argparse
+import re
 import shutil
 import time
 from pathlib import Path
@@ -51,6 +52,20 @@
     "hub": "regional",
     "bridge": "interchange",
 }
+SAFE_GRAPH_LITERAL_RE = re.compile(r"^[A-Za-z0-9_-]+$")
+
+
+def _sql_string_literal(value: str) -> str:
+    if not SAFE_GRAPH_LITERAL_RE.fullmatch(value):
+        raise ValueError(f"Unsafe SQL literal: {value!r}")
+    return f"'{value}'"
+
+
+def _validated_limit(value: int) -> int:
+    limit = int(value)
+    if limit <= 0:
+        raise ValueError(f"SQL limit must be positive: {value!r}")
+    return limit
 
 
 def parse_args() -> argparse.Namespace:
@@ -539,52 +554,54 @@ def query_direct_neighbor_sample(
 
 
 def query_two_hop_summary(db, origin_code: str) -> dict:
-    # origin_code is a script-local constant from the demo dataset.
+    safe_origin_code = _sql_string_literal(origin_code)
     result = db.query(
         "sql",
         f"""
         SELECT count(*) AS destination_count FROM (
-            MATCH {{type: City, as: src, where: (code = '{origin_code}')}}
+            MATCH {{type: City, as: src, where: (code = {safe_origin_code})}}
                   -ROAD->
                   {{type: City, as: mid}}
                   -ROAD->
                   {{type: City, as: dst}}
             RETURN DISTINCT dst.code AS code
         )
-        """,
+        """,  # nosec B608 - value validated via _sql_string_literal
     )
     row = result.first()
     require(row is not None, "Expected a two-hop summary row")
     return {"destination_count": row.get("destination_count")}
 
 
 def query_hub_inbound_count(db, hub_code: str) -> int:
+    safe_hub_code = _sql_string_literal(hub_code)
     result = db.query(
         "sql",
         f"""
         SELECT count(*) AS inbound_count FROM (
             MATCH {{type: City, as: src}}
                   -ROAD->
-                  {{type: City, as: hub, where: (code = '{hub_code}')}}
+                  {{type: City, as: hub, where: (code = {safe_hub_code})}}
             RETURN src.code AS code
         )
-        """,
+        """,  # nosec B608 - value validated via _sql_string_literal
     )
     row = result.first()
     require(row is not None, "Expected an inbound count row")
     return row.get("inbound_count")
 
 
 def query_region_sample(db, sample_limit: int) -> list[dict]:
+    safe_sample_limit = _validated_limit(sample_limit)
     result = db.query(
         "sql",
         f"""
         SELECT region, count(*) AS city_count, avg(demand_index) AS avg_demand
         FROM City
         GROUP BY region
         ORDER BY region
-        LIMIT {sample_limit}
-        """,
+        LIMIT {safe_sample_limit}
+        """,  # nosec B608 - value validated via _validated_limit
     )
     return rows_to_dicts(result, ["region", "city_count", "avg_demand"])
 

bindings/python/scripts/Dockerfile.build

@@ -11,7 +11,8 @@
 ARG PYTHON_VERSION=3.12
 ARG PACKAGE_NAME=arcadedb-embedded
 ARG PACKAGE_DESCRIPTION="ArcadeDB embedded multi-model database with bundled JRE - no Java installation required"
-ARG ARCADEDB_TAG=latest
+# Deterministic placeholder. The wrapper build script must pass the real ArcadeDB tag.
+ARG ARCADEDB_TAG=build-arg-required
 ARG TARGET_PLATFORM=linux-x64
 # When set to 1, prefer jars provided in bindings/python/local-jars/lib from the build context.
 # If no local jars are present, the build fails fast to avoid silently falling back.

bindings/python/scripts/build.sh

@@ -292,6 +292,13 @@ else
     # Determine Docker build platform (always Linux for cross-compilation)
     # We build ON linux/amd64 or linux/arm64, but FOR any target platform
     DOCKER_PLATFORM="${PLATFORM}"
+
+    if [[ -z "$DOCKER_TAG" ]]; then
+        echo -e "${RED}❌ Missing ArcadeDB Docker tag${NC}"
+        echo -e "${YELLOW}💡 Pass a version so Docker builds remain reproducible${NC}"
+        exit 1
+    fi
+
     # Build Docker image
     echo -e "${CYAN}📦 Building Docker image...${NC}"
 

bindings/python/src/arcadedb_embedded/vector.py

@@ -37,7 +37,7 @@ def to_java_float_array(vector):
         import numpy as np
 
         if isinstance(vector, np.ndarray):
-            vector = vector.tolist()
+            return jtypes.JArray(jtypes.JFloat)(vector)
     except ImportError:
         pass
 
@@ -69,12 +69,14 @@ def to_java_byte_array(vector):
         import numpy as np
 
         if isinstance(vector, np.ndarray):
+            if vector.dtype in (np.int8, np.uint8):
+                return jtypes.JArray(jtypes.JByte)(vector.tobytes())
             vector = vector.tolist()
     except ImportError:
         pass
 
     if isinstance(vector, (bytes, bytearray)):
-        vector = list(vector)
+        return jtypes.JArray(jtypes.JByte)(vector)
     elif not isinstance(vector, list):
         vector = list(vector)
 

bindings/python/tests/test_cypher.py

@@ -539,7 +539,7 @@ def test_opencypher_edge_typed_constraint_command(temp_db_path):
 
 
 def test_opencypher_is_typed_value_predicate(temp_db_path):
-    """OpenCypher should expose the GQL IS TYPED value predicate."""
+    """Verify that OpenCypher exposes the GQL IS TYPED value predicate."""
     with arcadedb.create_database(temp_db_path) as db:
         _ensure_opencypher(db)
 

bindings/python/tests/test_vector.py

@@ -19,6 +19,35 @@ def test_db(tmp_path):
     db.drop()
 
 
+def test_to_java_byte_array_accepts_bytes_like_fast_paths():
+    """to_java_byte_array should preserve signed byte semantics for bytes-like
+    inputs."""
+    np = pytest.importorskip("numpy")
+
+    assert list(arcadedb.to_java_byte_array(bytes([0, 127, 255]))) == [0, 127, -1]
+    assert list(arcadedb.to_java_byte_array(bytearray([1, 2, 255]))) == [1, 2, -1]
+    assert list(arcadedb.to_java_byte_array(np.array([0, 127, -1], dtype=np.int8))) == [
+        0,
+        127,
+        -1,
+    ]
+    assert list(
+        arcadedb.to_java_byte_array(np.array([0, 127, 255], dtype=np.uint8))
+    ) == [0, 127, -1]
+
+
+def test_to_java_float_array_accepts_numpy_directly():
+    """to_java_float_array should accept NumPy arrays without Python-list copies."""
+    np = pytest.importorskip("numpy")
+
+    assert list(
+        arcadedb.to_java_float_array(np.array([1.0, 2.0, 3.0], dtype=np.float32))
+    ) == pytest.approx([1.0, 2.0, 3.0])
+    assert list(
+        arcadedb.to_java_float_array(np.array([1.0, 2.0, 3.0], dtype=np.float64))
+    ) == pytest.approx([1.0, 2.0, 3.0])
+
+
 class TestLSMVectorIndex:
     """Test LSM Vector Index functionality."""
 

bindings/python/tests/test_vector_sql.py

@@ -370,7 +370,7 @@ def test_create_index_with_native_int8_encoding_sql(self, test_db):
         assert str(metadata.quantizationType) == "NONE"
 
     def test_vector_neighbors_on_native_int8_storage_sql(self, test_db):
-        """vectorNeighbors should work against native INT8-encoded storage."""
+        """Verify that vectorNeighbors works against native INT8-encoded storage."""
         test_db.command("sql", "CREATE VERTEX TYPE SqlNativeInt8SearchDoc")
         test_db.command("sql", "CREATE PROPERTY SqlNativeInt8SearchDoc.id STRING")
         test_db.command("sql", "CREATE PROPERTY SqlNativeInt8SearchDoc.vec BINARY")
@@ -619,7 +619,6 @@ def test_vector_neighbors_by_key_opencypher(self, test_db):
 
     def test_vector_neighbors_group_by_sql(self, test_db):
         """SQL vector.neighbors should support groupBy/groupSize options."""
-
         test_db.command("sql", "CREATE DOCUMENT TYPE GroupedDoc")
         test_db.command("sql", "CREATE PROPERTY GroupedDoc.source_file STRING")
         test_db.command("sql", "CREATE PROPERTY GroupedDoc.embedding ARRAY_OF_FLOATS")