cypher-graphdb 0.7.2__tar.gz → 0.7.3__tar.gz

{cypher_graphdb-0.7.2/src/cypher_graphdb.egg-info → cypher_graphdb-0.7.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cypher_graphdb
-Version: 0.7.2
+Version: 0.7.3
 Summary: ORM like library and CLI for cypher query language supporting graph databases.
 Author-email: Wolfgang Miller <wolfgang.miller@petrarca-labs.com>
 License-Expression: Apache-2.0

{cypher_graphdb-0.7.2 → cypher_graphdb-0.7.3}/src/cypher_graphdb/backend.py

@@ -7,6 +7,7 @@ CypherBackend: Abstract base class for implementing graph database backends.
 
 import abc
 import re
+from collections.abc import Sequence
 from enum import Enum, auto
 from typing import Any
 
@@ -453,23 +454,27 @@ class CypherBackend(abc.ABC):
         edges: list[dict],
         src_label: str,
         dst_label: str,
-        src_ref_prop: str = "id",
-        dst_ref_prop: str = "id",
+        src_ref_prop: str | Sequence[str] = "id",
+        dst_ref_prop: str | Sequence[str] = "id",
         batch_size: int = 500,
     ) -> int:
-        """Create edges in batches by matching src/dst nodes on a reference property.
+        """Create edges in batches by matching src/dst nodes on a reference key.
 
         Each dict in edges must have "src" and "dst" keys whose values match
         the src_ref_prop/dst_ref_prop properties on source/destination nodes.
         Any additional keys are set as properties on the created edge.
 
+        A ref prop may name a single property or an ordered sequence of properties
+        (a composite key); for a composite key each "src"/"dst" is a parallel
+        sequence of values in the same order.
+
         Args:
             label: Edge label for all created edges.
             edges: List of dicts with "src", "dst", and optional edge properties.
             src_label: Label of source nodes. Required for optimal performance on AGE.
             dst_label: Label of destination nodes. Required for optimal performance on AGE.
-            src_ref_prop: Property name on source nodes to match against "src".
-            dst_ref_prop: Property name on destination nodes to match against "dst".
+            src_ref_prop: Property, or ordered sequence of properties, on source nodes to match against "src".
+            dst_ref_prop: As ``src_ref_prop``, for destination nodes.
             batch_size: Number of edges per UNWIND batch.
 
         Returns:

{cypher_graphdb-0.7.2 → cypher_graphdb-0.7.3}/src/cypher_graphdb/backends/age/agebulkwriter.py

@@ -14,6 +14,7 @@ committed immediately (DDL cannot run inside a user transaction in PostgreSQL)
 without affecting any surrounding data already written by the caller.
 """
 
+from collections.abc import Sequence
 from typing import Literal
 
 import psycopg
@@ -21,6 +22,7 @@ from loguru import logger
 from psycopg.sql import SQL, Composed, Identifier
 from psycopg.sql import Literal as SQLLiteral
 
+from cypher_graphdb.bulk_refs import as_ref_props, ref_key
 from cypher_graphdb.utils import chunk_list
 
 from .ageserializer import escape_value
@@ -62,7 +64,7 @@ class AGEBulkWriter:
         # edges all resolving against Method.qualified_name).
         # Invalidated by invalidate_graphid_cache() after node inserts that
         # change the graphid mapping.
-        self._graphid_cache: dict[tuple[str, str], dict[str, int]] = {}
+        self._graphid_cache: dict[tuple[str, tuple[str, ...]], dict[tuple, int]] = {}
         # Cached list of edge label names for bulk_delete_nodes.
         # Edge labels are stable within a connection lifetime -- populated on
         # first call to _list_edge_labels() and reused for all subsequent deletes.
@@ -124,8 +126,8 @@ class AGEBulkWriter:
         edges: list[dict],
         src_label: str,
         dst_label: str,
-        src_ref_prop: str = "id",
-        dst_ref_prop: str = "id",
+        src_ref_prop: str | Sequence[str] = "id",
+        dst_ref_prop: str | Sequence[str] = "id",
         batch_size: int = 500,
     ) -> int:
         """Insert edges via direct SQL INSERT into the AGE edge label table.
@@ -143,8 +145,10 @@ class AGEBulkWriter:
             edges: List of dicts with at least "src" and "dst" keys.
             src_label: Vertex label of source nodes.
             dst_label: Vertex label of destination nodes.
-            src_ref_prop: Property name on source nodes to match "src" values.
-            dst_ref_prop: Property name on destination nodes to match "dst" values.
+            src_ref_prop: Property (or ordered sequence of properties) on source
+                nodes to match "src" values. A sequence forms a composite key;
+                each edge's "src" is then a parallel sequence of values.
+            dst_ref_prop: As ``src_ref_prop``, for destination nodes.
             batch_size: Number of rows per executemany batch.
 
         Returns:
@@ -155,17 +159,20 @@ class AGEBulkWriter:
 
         label_id = self._ensure_label(label, kind="e")
 
-        # Collect the unique ref values we actually need -- avoids loading
-        # the entire label table (which can be 200K+ rows in a shared graph).
-        src_refs = {e["src"] for e in edges}
-        dst_refs = {e["dst"] for e in edges}
+        src_props = as_ref_props(src_ref_prop)
+        dst_props = as_ref_props(dst_ref_prop)
 
-        # Build {ref_value: graphid} maps for only the referenced nodes
-        src_map = self._build_graphid_index(src_label, src_ref_prop, ref_values=src_refs)
-        if src_label == dst_label and src_ref_prop == dst_ref_prop:
-            dst_map = self._build_graphid_index(dst_label, dst_ref_prop, ref_values=src_refs | dst_refs)
+        # Collect the unique (composite) ref keys we actually need -- avoids
+        # loading the entire label table (200K+ rows in a shared graph).
+        src_refs = {ref_key(e["src"], len(src_props)) for e in edges}
+        dst_refs = {ref_key(e["dst"], len(dst_props)) for e in edges}
+
+        # Build {ref_key: graphid} maps for only the referenced nodes
+        src_map = self._build_graphid_index(src_label, src_props, ref_values=src_refs)
+        if src_label == dst_label and src_props == dst_props:
+            dst_map = self._build_graphid_index(dst_label, dst_props, ref_values=src_refs | dst_refs)
         else:
-            dst_map = self._build_graphid_index(dst_label, dst_ref_prop, ref_values=dst_refs)
+            dst_map = self._build_graphid_index(dst_label, dst_props, ref_values=dst_refs)
 
         total = 0
         skipped = 0
@@ -173,8 +180,8 @@ class AGEBulkWriter:
             for batch in chunk_list(edges, batch_size):
                 value_parts = []
                 for edge in batch:
-                    src_gid = src_map.get(edge["src"])
-                    dst_gid = dst_map.get(edge["dst"])
+                    src_gid = src_map.get(ref_key(edge["src"], len(src_props)))
+                    dst_gid = dst_map.get(ref_key(edge["dst"], len(dst_props)))
                     if src_gid is None or dst_gid is None:
                         skipped += 1
                         continue
@@ -479,51 +486,60 @@ class AGEBulkWriter:
             for k in keys_to_drop:
                 del self._graphid_cache[k]
 
-    def _build_graphid_index(self, label: str, ref_prop: str, ref_values: set[str] | None = None) -> dict[str, int]:
-        """Load a {ref_prop_value: graphid} mapping for nodes of a label.
+    def _build_graphid_index(
+        self, label: str, ref_props: Sequence[str], ref_values: set[tuple] | None = None
+    ) -> dict[tuple, int]:
+        """Load a {ref_key_tuple: graphid} mapping for nodes of a label.
+
+        ``ref_props`` is the ordered key: one property for a simple key, several
+        for a composite one. Keys in the returned map are value tuples aligned
+        with ``ref_props`` (always a tuple, even for a single prop), so a composite
+        key never collapses two nodes that merely share one property value.
 
-        When ``ref_values`` is provided, only loads graphids for those specific
-        property values (using a WHERE IN clause). This is critical for shared
-        graphs where a label table may contain hundreds of thousands of rows
-        across all sources, but only a small subset is needed for the current
-        edge batch.
+        When ``ref_values`` is provided (a set of value tuples), only loads
+        graphids for those specific keys (WHERE ... IN). Critical for shared
+        graphs where a label table may hold hundreds of thousands of rows across
+        all sources, but only a small subset is needed for the current edge batch.
 
         When ``ref_values`` is None, loads the entire table (used for small
         labels like structural edges).
 
-        Results are cached per (label, ref_prop) and incrementally extended
+        Results are cached per (label, ref_props) and incrementally extended
         when new ref_values are requested.
 
         Values returned by agtype_access_operator are agtype-quoted strings
         (e.g. '"mth:foo.bar"'), so we strip the surrounding quotes.
         """
-        cache_key = (label, ref_prop)
+        props = tuple(ref_props)
+        cache_key = (label, props)
         cached = self._graphid_cache.get(cache_key)
 
         if ref_values is not None and cached is not None:
-            # Check if all requested values are already in the cache
+            # Check if all requested keys are already in the cache
             missing = ref_values - cached.keys()
             if not missing:
                 return cached
-            # Only query the missing values
+            # Only query the missing keys
             ref_values = missing
 
         if ref_values is not None and ref_values:
-            sql_stmt = SQLBuilder.lookup_node_graphids_filtered_sql(self._graph_name, label, ref_prop, ref_values)
+            sql_stmt = SQLBuilder.lookup_node_graphids_filtered_sql(self._graph_name, label, props, ref_values)
         else:
-            sql_stmt = SQLBuilder.lookup_node_graphids_sql(self._graph_name, label, ref_prop)
+            sql_stmt = SQLBuilder.lookup_node_graphids_sql(self._graph_name, label, props)
 
         with self._conn.cursor() as cursor:
             cursor.execute(sql_stmt)
             rows = cursor.fetchall()
-        result = {str(r[0]).strip('"'): r[1] for r in rows}
+        # Each row is (val_0, ..., val_n, graphid); the key is the tuple of values.
+        n = len(props)
+        result = {tuple(str(v).strip('"') for v in r[:n]): r[n] for r in rows}
 
         # Merge into cache
         if cached is not None:
             cached.update(result)
-            logger.debug("Graphid index extended for {}.{}: +{} entries (total {})", label, ref_prop, len(result), len(cached))
+            logger.debug("Graphid index extended for {}.{}: +{} entries (total {})", label, props, len(result), len(cached))
             return cached
 
         self._graphid_cache[cache_key] = result
-        logger.debug("Graphid index built for {}.{}: {} entries", label, ref_prop, len(result))
+        logger.debug("Graphid index built for {}.{}: {} entries", label, props, len(result))
         return result

{cypher_graphdb-0.7.2 → cypher_graphdb-0.7.3}/src/cypher_graphdb/backends/age/agegraphdb.py

@@ -13,7 +13,7 @@ import hashlib
 import json
 import re
 import time
-from collections.abc import Iterator
+from collections.abc import Iterator, Sequence
 from typing import Any
 
 import psycopg
@@ -26,6 +26,7 @@ from tenacity import retry, retry_if_exception_type, stop_after_attempt, wait_ex
 
 # Import directly from the main package
 from cypher_graphdb.backend import BackendCapability, CypherBackend, ExecStatistics, SqlStatistics
+from cypher_graphdb.bulk_refs import as_ref_props, edge_match_pattern
 
 # Deferred at module level to avoid a circular import:
 # agegraphdb -> pagination (cyphergraphdb package) -> cyphergraphdb -> agegraphdb
@@ -1027,11 +1028,11 @@ class AGEGraphDB(CypherBackend):
         edges: list[dict],
         src_label: str,
         dst_label: str,
-        src_ref_prop: str = "id",
-        dst_ref_prop: str = "id",
+        src_ref_prop: str | Sequence[str] = "id",
+        dst_ref_prop: str | Sequence[str] = "id",
         batch_size: int = 500,
     ) -> int:
-        """Create edges in batches by matching src/dst nodes on a reference property.
+        """Create edges in batches by matching src/dst nodes on a reference key.
 
         When ``direct_bulk_insert`` is True and both ``src_label`` and ``dst_label``
         are specified, uses direct SQL INSERT via :class:`AGEBulkWriter` with
@@ -1042,8 +1043,10 @@ class AGEGraphDB(CypherBackend):
             edges: List of dicts with at least "src" and "dst" keys.
             src_label: Label of source nodes. Required for optimal performance on AGE.
             dst_label: Label of destination nodes. Required for optimal performance on AGE.
-            src_ref_prop: Property name on source nodes to match against "src".
-            dst_ref_prop: Property name on destination nodes to match against "dst".
+            src_ref_prop: Property (or ordered sequence of properties) on source
+                nodes to match against "src". A sequence forms a composite key and
+                each edge's "src" is then a parallel sequence of values.
+            dst_ref_prop: As ``src_ref_prop``, for destination nodes.
             batch_size: Number of edges per batch.
 
         Returns:
@@ -1059,8 +1062,8 @@ class AGEGraphDB(CypherBackend):
             )
 
         # Cypher UNWIND fallback (direct_bulk_insert disabled).
-        src_pat = f"(a:{src_label} {{{src_ref_prop}: e.src}})"
-        dst_pat = f"(b:{dst_label} {{{dst_ref_prop}: e.dst}})"
+        src_pat = edge_match_pattern("a", src_label, as_ref_props(src_ref_prop), "src")
+        dst_pat = edge_match_pattern("b", dst_label, as_ref_props(dst_ref_prop), "dst")
 
         total = 0
         for batch in chunk_list(edges, batch_size):

{cypher_graphdb-0.7.2 → cypher_graphdb-0.7.3}/src/cypher_graphdb/backends/age/ageserializer.py

@@ -37,12 +37,14 @@ def escape_string_inner(v: str) -> str:
 def escape_value(v: object) -> str:
     """Escape a Python value for inline AGE Cypher literals.
 
-    Handles None, bool, int, float, and str-coercible values. Strings are
-    escaped for double-quoted Cypher literals: backslashes, double quotes,
-    newlines, carriage returns, tabs, and null bytes are all handled.
+    Handles None, bool, int, float, list/tuple (nested), and str-coercible
+    values. Strings are escaped for double-quoted Cypher literals: backslashes,
+    double quotes, newlines, carriage returns, tabs, and null bytes are all
+    handled. A list/tuple becomes a Cypher list literal -- used for composite
+    edge-endpoint match keys (``e.src`` / ``e.dst``).
 
     Args:
-        v: Python value (None, bool, int, float, or str-coercible).
+        v: Python value (None, bool, int, float, list/tuple, or str-coercible).
 
     Returns:
         Cypher literal string representation.
@@ -53,6 +55,8 @@ def escape_value(v: object) -> str:
         return "true" if v else "false"
     if isinstance(v, int | float):
         return str(v)
+    if isinstance(v, (list, tuple)):
+        return "[" + ", ".join(escape_value(item) for item in v) + "]"
     return f'"{escape_string_inner(str(v))}"'
 
 

{cypher_graphdb-0.7.2 → cypher_graphdb-0.7.3}/src/cypher_graphdb/backends/age/agesqlbuilder.py

@@ -5,6 +5,7 @@ interface with Apache AGE graph functionality, including graph creation,
 Cypher query execution, and full-text search operations.
 """
 
+from collections.abc import Sequence
 from dataclasses import dataclass
 
 from psycopg import sql
@@ -280,52 +281,77 @@ class SQLBuilder:
             "WHERE g.name = %s AND l.name = %s"
         )
 
-    @classmethod
-    def lookup_node_graphids_sql(cls, graph_name: str, label: str, ref_prop: str) -> sql.Composed:
-        """SQL to look up graphids of all nodes of a label by a property value.
+    @staticmethod
+    def _prop_access(prop: str) -> sql.Composed:
+        """agtype_access_operator expression reading one property, matching the expression index."""
+        return sql.SQL("ag_catalog.agtype_access_operator(VARIADIC ARRAY[properties, {prop}::ag_catalog.agtype])").format(
+            prop=sql.Literal(f'"{prop}"'),
+        )
 
-        Returns (ref_value, graphid) pairs for every row in the label table.
-        Use ``lookup_node_graphids_filtered_sql`` when only a subset of values
-        is needed (avoids scanning hundreds of thousands of rows).
+    @classmethod
+    def lookup_node_graphids_sql(cls, graph_name: str, label: str, ref_props: Sequence[str]) -> sql.Composed:
+        """SQL to look up graphids of all nodes of a label by one or more property values.
+
+        Returns ``(ref_value_0, ..., ref_value_n, graphid)`` for every row in the
+        label table -- one value column per entry in ``ref_props``, in order, so
+        the caller can build a composite key. Use
+        ``lookup_node_graphids_filtered_sql`` when only a subset is needed
+        (avoids scanning hundreds of thousands of rows).
         """
-        return sql.SQL(
-            "SELECT ag_catalog.agtype_access_operator(VARIADIC ARRAY[properties, {prop}::ag_catalog.agtype])::text, id "
-            "FROM {schema}.{table}"
-        ).format(
+        value_cols = sql.SQL(", ").join(cls._prop_access(p) + sql.SQL("::text") for p in ref_props)
+        return sql.SQL("SELECT {cols}, id FROM {schema}.{table}").format(
+            cols=value_cols,
             schema=sql.Identifier(graph_name),
             table=sql.Identifier(label),
-            prop=sql.Literal(f'"{ref_prop}"'),
         )
 
     @classmethod
-    def lookup_node_graphids_filtered_sql(cls, graph_name: str, label: str, ref_prop: str, ref_values: set[str]) -> sql.Composed:
-        """SQL to look up graphids for a specific set of property values.
-
-        Uses a WHERE ... IN (...) clause with the same agtype_access_operator
-        expression as the expression index, so the btree index is used for
-        the filter. For 500 ref values against a 200K+ row table this turns
-        a sequential scan into 500 index lookups.
-
-        The ref values are cast to ``::ag_catalog.agtype`` to match the
-        expression index type exactly. Values containing double quotes or
-        backslashes are escaped for the agtype JSON string format before
-        being wrapped in the PostgreSQL string literal via sql.Literal.
+    def lookup_node_graphids_filtered_sql(
+        cls, graph_name: str, label: str, ref_props: Sequence[str], ref_values: set
+    ) -> sql.Composed:
+        """SQL to look up graphids for a specific set of (composite) property values.
+
+        ``ref_props`` is the ordered list of key properties; ``ref_values`` is a
+        set of value tuples (one element per prop, same order).
+
+        A single prop uses ``WHERE access IN (v, ...)`` -- the fast path that hits
+        the expression index. A composite key uses ``WHERE (a0 = v0 AND a1 = v1)
+        OR (...) OR ...``: AGE's agtype does not support SQL row-value comparison
+        (``(a, b) IN ((x, y))`` raises "cannot cast agtype string to type
+        boolean"), so the key is expanded into per-tuple AND groups.
+
+        Values are cast to ``::ag_catalog.agtype`` to match the expression index
+        type. Values containing double quotes or backslashes are escaped for the
+        agtype JSON string format before being wrapped via sql.Literal -- identical
+        escaping to the Cypher UNWIND path.
         """
-        # Build the IN list: each value is a double-quoted agtype string literal.
-        # escape_string_inner handles backslashes, double quotes, control chars,
-        # and null bytes -- identical escaping to the Cypher UNWIND path.
-        in_values = ", ".join(
-            sql.Literal('"' + escape_string_inner(v) + '"').as_string(None) + "::ag_catalog.agtype" for v in ref_values
-        )
-        return sql.SQL(
-            "SELECT ag_catalog.agtype_access_operator(VARIADIC ARRAY[properties, {prop}::ag_catalog.agtype])::text, id "
-            "FROM {schema}.{table} "
-            "WHERE ag_catalog.agtype_access_operator(VARIADIC ARRAY[properties, {prop}::ag_catalog.agtype]) IN ({in_vals})"
-        ).format(
+
+        def agtype_literal(v: str) -> sql.SQL:
+            return sql.SQL(sql.Literal('"' + escape_string_inner(v) + '"').as_string(None) + "::ag_catalog.agtype")
+
+        value_cols = sql.SQL(", ").join(cls._prop_access(p) + sql.SQL("::text") for p in ref_props)
+
+        # Match each key tuple as an AND of per-prop equalities, OR'd across tuples.
+        # agtype equality must use the ag_catalog.= operator -- a plain "=" (or a
+        # ::text cast) raises "cannot cast agtype string to type boolean". This
+        # uniform form covers both the single-prop and composite cases.
+        accessors = [cls._prop_access(p) for p in ref_props]
+        groups = [
+            sql.SQL("(")
+            + sql.SQL(" AND ").join(
+                sql.SQL("{a} OPERATOR(ag_catalog.=) {v}").format(a=accessors[i], v=agtype_literal(v))
+                for i, v in enumerate(value_tuple)
+            )
+            + sql.SQL(")")
+            for value_tuple in ref_values
+        ]
+        where = sql.SQL(" OR ").join(groups)
+
+        return sql.SQL("SELECT {cols}, id FROM {schema}.{table} WHERE {where}").format(
+            cols=value_cols,
             schema=sql.Identifier(graph_name),
             table=sql.Identifier(label),
-            prop=sql.Literal(f'"{ref_prop}"'),
-            in_vals=sql.SQL(in_values),
+            where=where,
         )
 
     @classmethod

{cypher_graphdb-0.7.2 → cypher_graphdb-0.7.3}/src/cypher_graphdb/backends/memgraph/memgraphdb.py

@@ -8,7 +8,7 @@ Classes:
 """
 
 import contextlib
-from collections.abc import Generator
+from collections.abc import Generator, Sequence
 from typing import Any
 
 import mgclient
@@ -17,6 +17,7 @@ from tenacity import retry, retry_if_exception_type, stop_after_attempt, wait_ex
 
 # Import directly from the main package
 from cypher_graphdb.backend import BackendCapability, CypherBackend, ExecStatistics
+from cypher_graphdb.bulk_refs import as_ref_props, edge_match_pattern, ref_param
 from cypher_graphdb.cyphergraphdb.pagination import Page
 from cypher_graphdb.cyphergraphdb.pagination_mixin import _resolve_col_names
 from cypher_graphdb.cypherparser import ParsedCypherQuery
@@ -660,8 +661,8 @@ class MemgraphDB(CypherBackend):
         edges: list[dict],
         src_label: str,
         dst_label: str,
-        src_ref_prop: str = "id",
-        dst_ref_prop: str = "id",
+        src_ref_prop: str | Sequence[str] = "id",
+        dst_ref_prop: str | Sequence[str] = "id",
         batch_size: int = 500,
     ) -> int:
         """Create edges in batches using parameterized UNWIND.
@@ -669,13 +670,17 @@ class MemgraphDB(CypherBackend):
         Each dict in edges must have "src" and "dst" keys. Additional keys
         are set as edge properties.
 
+        A ref prop may name a single property or an ordered sequence of properties
+        (a composite key); for a composite key each "src"/"dst" is a parallel
+        sequence of values matched element-wise against the props.
+
         Args:
             label: Edge label for all created edges.
             edges: List of dicts with "src", "dst", and optional edge properties.
             src_label: Label of source nodes. Required for optimal performance on AGE.
             dst_label: Label of destination nodes. Required for optimal performance on AGE.
-            src_ref_prop: Property name on source nodes to match against "src".
-            dst_ref_prop: Property name on destination nodes to match against "dst".
+            src_ref_prop: Property, or ordered sequence of properties, on source nodes to match against "src".
+            dst_ref_prop: As ``src_ref_prop``, for destination nodes.
             batch_size: Number of edges per UNWIND batch.
 
         Returns:
@@ -685,9 +690,12 @@ class MemgraphDB(CypherBackend):
         if not edges:
             return 0
 
+        src_props = as_ref_props(src_ref_prop)
+        dst_props = as_ref_props(dst_ref_prop)
+
         # Build MATCH patterns from label/prop names (not user values -- safe to inline)
-        src_pat = f"(a:{src_label} {{{src_ref_prop}: e.src}})" if src_label else f"(a {{{src_ref_prop}: e.src}})"
-        dst_pat = f"(b:{dst_label} {{{dst_ref_prop}: e.dst}})" if dst_label else f"(b {{{dst_ref_prop}: e.dst}})"
+        src_pat = edge_match_pattern("a", src_label, src_props, "src")
+        dst_pat = edge_match_pattern("b", dst_label, dst_props, "dst")
 
         # Collect edge property keys (beyond src/dst) from first row
         edge_prop_keys = [k for k in edges[0] if k not in ("src", "dst")]
@@ -698,6 +706,10 @@ class MemgraphDB(CypherBackend):
 
         cypher = f"UNWIND $edges AS e MATCH {src_pat} MATCH {dst_pat} CREATE (a)-[r:{label}]->(b){set_clause}"
 
+        # mgclient rejects tuples as query parameters; coerce each endpoint by its own
+        # key arity (source and destination may differ).
+        edges = [{**e, "src": ref_param(e["src"], len(src_props)), "dst": ref_param(e["dst"], len(dst_props))} for e in edges]
+
         total = 0
         for batch in chunk_list(edges, batch_size):
             cursor = self._conn.cursor()

cypher_graphdb-0.7.3/src/cypher_graphdb/bulk_refs.py

@@ -0,0 +1,85 @@
+"""Composite endpoint keys for bulk edge creation.
+
+``bulk_create_edges`` matches each endpoint node by a *reference key* -- one or
+more properties whose values identify the node. A single property is the common
+case (``"symbol"``), but it is only correct when that property is unique within
+the label. When it is not (e.g. the same ``symbol`` exists in several sources of
+a shared graph), the key must be composite (``("symbol", "source_key")``) so an
+edge binds to the intended node rather than an arbitrary match.
+
+These helpers normalise the ``str | Sequence[str]`` ref-prop argument and turn an
+edge's ``src``/``dst`` value (scalar or tuple) into a hashable key aligned with
+the prop order.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Any
+
+
+def as_ref_props(ref_prop: str | Sequence[str]) -> tuple[str, ...]:
+    """Normalise a ref-prop argument to an ordered tuple of property names.
+
+    A plain string becomes a one-tuple; a sequence is kept in order. Empty
+    sequences are rejected -- an endpoint must be matched on at least one prop.
+    """
+    if isinstance(ref_prop, str):
+        return (ref_prop,)
+    props = tuple(ref_prop)
+    if not props:
+        raise ValueError("ref_prop must name at least one property")
+    if not all(isinstance(p, str) for p in props):
+        raise TypeError("ref_prop sequence must contain only property-name strings")
+    return props
+
+
+def ref_key(value: Any, n_props: int) -> tuple[Any, ...]:
+    """Turn an edge's src/dst match value into a key tuple of length ``n_props``.
+
+    For a single-prop key the value is a scalar (wrapped into a one-tuple); for a
+    composite key the value must be a sequence whose length matches ``n_props``.
+    A tuple key is always returned so callers can index a composite map uniformly.
+    """
+    if n_props == 1:
+        # A one-element sequence is accepted too, but a bare scalar is the norm.
+        if isinstance(value, (list, tuple)):
+            seq = tuple(value)
+            if len(seq) != 1:
+                raise ValueError(f"expected 1 match value, got {len(seq)}")
+            return seq
+        return (value,)
+    if not isinstance(value, (list, tuple)):
+        raise TypeError(f"composite key needs a sequence of {n_props} values, got {type(value).__name__}")
+    seq = tuple(value)
+    if len(seq) != n_props:
+        raise ValueError(f"expected {n_props} match values, got {len(seq)}")
+    return seq
+
+
+def ref_param(value: Any, n_props: int) -> Any:
+    """Coerce one endpoint's match value to a driver-friendly query parameter.
+
+    A single-prop key stays a scalar; a composite key becomes a list (some drivers,
+    e.g. mgclient, reject tuples as parameters). Decided per endpoint from that
+    endpoint's own key arity: source and destination may differ (a composite caller
+    matched to a single-prop target), and coercing both on one endpoint's arity would
+    split a scalar string into characters.
+    """
+    return list(ref_key(value, n_props)) if n_props > 1 else value
+
+
+def edge_match_pattern(alias: str, node_label: str | None, props: Sequence[str], ref: str) -> str:
+    """Build a Cypher node-match pattern for one edge endpoint inside ``UNWIND ... AS e``.
+
+    ``ref`` is the UNWIND field carrying the match value ("src" or "dst"). A
+    single-prop key matches the scalar (``e.src``); a composite key matches each
+    property against the corresponding list element (``e.src[0]``, ``e.src[1]``, ...).
+    An empty ``node_label`` matches nodes of any label.
+    """
+    if len(props) == 1:
+        body = f"{props[0]}: e.{ref}"
+    else:
+        body = ", ".join(f"{p}: e.{ref}[{i}]" for i, p in enumerate(props))
+    head = f"{alias}:{node_label}" if node_label else alias
+    return f"({head} {{{body}}})"

{cypher_graphdb-0.7.2 → cypher_graphdb-0.7.3}/src/cypher_graphdb/cyphergraphdb/indexing.py

@@ -198,11 +198,11 @@ class IndexingMixin(_Host):
         src_refs: Sequence[Any] | None = None,
         dst_refs: Sequence[Any] | None = None,
         label: str | None = None,
-        src_ref_prop: str = "id",
-        dst_ref_prop: str = "id",
+        src_ref_prop: str | Sequence[str] = "id",
+        dst_ref_prop: str | Sequence[str] = "id",
         batch_size: int = 500,
     ) -> int:
-        """Create edges in batches by matching src/dst nodes on a reference property.
+        """Create edges in batches by matching src/dst nodes on a reference key.
 
         Accepts either plain dicts (traditional shape) or decorated
         ``GraphEdge`` instances (typed shape).
@@ -215,6 +215,15 @@ class IndexingMixin(_Host):
         ``src_refs`` / ``dst_refs`` lists; the edge properties come from
         ``flatten_properties()`` on each instance.
 
+        A ref prop may name a **single** property (the common case) or an ordered
+        **sequence** of properties forming a composite key. A composite key is the
+        correct choice when no single property is unique within the label (e.g. the
+        same ``symbol`` exists in several sources of a shared graph): matching on
+        ``("symbol", "source_key")`` binds each edge to the intended node instead of
+        an arbitrary one that happens to share the symbol. For a composite key each
+        ``src`` / ``dst`` (or ``src_refs`` / ``dst_refs`` element) is a parallel
+        sequence of values, in the same order as the props.
+
         Args:
             edges: Either a list of dicts (each with ``src``/``dst`` + props)
                 or a list of ``GraphEdge`` instances (all sharing the same
@@ -226,8 +235,9 @@ class IndexingMixin(_Host):
             label: Edge label. Required for dicts; optional for typed input.
             src_label: Label of source nodes. Required for optimal performance on AGE.
             dst_label: Label of destination nodes. Required for optimal performance on AGE.
-            src_ref_prop: Property name on source nodes to match against src refs.
-            dst_ref_prop: Property name on destination nodes to match against dst refs.
+            src_ref_prop: Property, or ordered sequence of properties (composite
+                key), on source nodes to match against src refs.
+            dst_ref_prop: As ``src_ref_prop``, for destination nodes.
             batch_size: Number of edges per batch.
 
         Returns:
@@ -254,6 +264,17 @@ class IndexingMixin(_Host):
                     src_ref_prop="qualified_name",
                     dst_ref_prop="qualified_name",
                 )
+
+            Composite key (disambiguate a non-unique property)::
+
+                cdb.bulk_create_edges(
+                    calls,
+                    src_refs=[("mod.foo.bar", "svc-a"), ("mod.foo.baz", "svc-a")],
+                    dst_refs=[("mod.target.a", "svc-a"), ("mod.target.b", "svc-a")],
+                    src_label="Method", dst_label="Method",
+                    src_ref_prop=("qualified_name", "source_key"),
+                    dst_ref_prop=("qualified_name", "source_key"),
+                )
         """
         assert self._backend
         derived_label, edge_dicts = normalize_edges_input(edges, src_refs, dst_refs, label)