iris-vector-graph 2.19.1__tar.gz → 2.20.0__tar.gz

{iris_vector_graph-2.19.1 → iris_vector_graph-2.20.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: iris-vector-graph
-Version: 2.19.1
+Version: 2.20.0
 Summary: Native graph database layer for InterSystems IRIS — openCypher, hybrid vector search, temporal property graph, RDF export, SHACL validation
 Project-URL: Homepage, https://github.com/intersystems-community/iris-vector-graph
 Project-URL: Documentation, https://github.com/intersystems-community/iris-vector-graph/tree/main/docs

{iris_vector_graph-2.19.1 → iris_vector_graph-2.20.0}/iris_vector_graph/_engine/query.py

@@ -11,6 +11,98 @@ from iris_vector_graph._engine.ledger import ledger_check as _ledger_check
 
 logger = logging.getLogger(__name__)
 
+_CARTESIAN_PAT = re.compile(
+    r'\bJOIN\s+\S+\s+(?P<alias>\w+)\s+ON\s+1\s*=\s*1\b',
+    re.IGNORECASE,
+)
+_ORDER_CLAUSE_PAT = re.compile(r'\n(?:ORDER|HAVING|GROUP)\b', re.IGNORECASE)
+
+
+def extract_vlp_source_ids(
+    sql_query,
+    source_labels: List[str],
+    source_alias: str,
+    target_alias: str,
+    store,
+) -> List[str]:
+    """Find source node IDs for a variable-length-path Cypher query.
+
+    This is the single authoritative implementation of VLP source extraction,
+    used by both _execute_var_length_labeled and
+    _execute_var_length_labeled_path_funcs.
+
+    Three paths, in priority order:
+
+    1. **Label-based** (``source_labels`` non-empty): call ``store.query_nodes``
+       per label and intersect the results.
+
+    2. **Direct node_id = ?** (WHERE clause binds ``source_alias.node_id = ?``):
+       extract the parameter value directly — no DB round-trip.
+
+    3. **Cartesian SQL** (full-SQL DISTINCT query): detect the
+       ``JOIN target_alias ON 1=1`` cartesian boundary, build a
+       ``SELECT DISTINCT source_alias.node_id`` query with all original params,
+       and run it against the store's connection.
+
+    Returns an empty list when extraction finds no source IDs (callers decide
+    what to return for empty results, since result shapes differ).
+    """
+    if store is None:
+        return []
+
+    # ── Path 1: label-based ──────────────────────────────────────────────────
+    if source_labels:
+        label_sets = []
+        for lbl in source_labels:
+            try:
+                lbl_result = store.query_nodes(label_filter=lbl)
+                label_sets.append({row[0] for row in lbl_result.rows if row and row[0]})
+            except Exception as exc:
+                logger.debug("extract_vlp_source_ids: label lookup failed for %s: %s", lbl, exc)
+        if not label_sets:
+            return []
+        common = label_sets[0]
+        for s in label_sets[1:]:
+            common = common & s
+        return list(common)
+
+    sql_str = sql_query.sql if isinstance(sql_query.sql, str) else ""
+
+    # ── Path 2: direct node_id = ? fast path ────────────────────────────────
+    if source_alias:
+        direct_pat = re.compile(
+            r'\b' + re.escape(source_alias) + r'\.node_id\s*=\s*\?',
+            re.IGNORECASE,
+        )
+        if direct_pat.search(sql_str):
+            params_list = sql_query.parameters[0] if sql_query.parameters else []
+            for pv in params_list:
+                if isinstance(pv, str) and pv:
+                    return [pv]
+
+    # ── Path 3: cartesian SQL extraction ────────────────────────────────────
+    if source_alias and target_alias:
+        target_cartesian_pat = re.compile(
+            r'\bJOIN\s+\S+\s+' + re.escape(target_alias) + r'\s+ON\s+1\s*=\s*1\b',
+            re.IGNORECASE,
+        )
+        m = target_cartesian_pat.search(sql_str)
+        if m:
+            full_from_where = sql_str[sql_str.lower().find('\nfrom '):].strip()
+            order_m = _ORDER_CLAUSE_PAT.search(full_from_where)
+            if order_m:
+                full_from_where = full_from_where[:order_m.start()].strip()
+            src_query = f"SELECT DISTINCT {source_alias}.node_id {full_from_where}"
+            params_list = sql_query.parameters[0] if sql_query.parameters else []
+            try:
+                cursor = store.conn.cursor()
+                cursor.execute(src_query, list(params_list))
+                return [row[0] for row in cursor.fetchall() if row and row[0]]
+            except Exception as exc:
+                logger.debug("extract_vlp_source_ids: cartesian SQL failed: %s", exc)
+
+    return []
+
 
 def _split_top_level_and(where_clause: str) -> list:
     """Split a SQL WHERE clause on top-level AND conjuncts only.
@@ -463,20 +555,19 @@ class QueryMixin:
         source_labels = vl0.get("source_labels") or []
         source_alias_r = vl0.get("source_alias") or ""
 
-        # Fast-path: extract source_id when the WHERE clause directly binds
-        # source_alias.node_id = ? with a single parameter. This covers the common
-        # "MATCH (a)-[*..]->(b) WHERE a.node_id = $src" pattern without needing a DB query.
+        # Fast-path: extract source_id only when the WHERE clause directly binds
+        # source_alias.node_id = ? — uses Path 2 of extract_vlp_source_ids.
+        # Multi-source cases (label-based or cartesian-SQL) are handled downstream
+        # by _execute_var_length_labeled / _execute_var_length_labeled_path_funcs.
         if source_id is None and src_id_param is None and source_alias_r:
-            import re as _re_fast
-            sql_str_fast = sql_query.sql if isinstance(sql_query.sql, str) else ""
-            direct_m = _re_fast.search(
-                r'\b' + _re_fast.escape(source_alias_r) + r'\.node_id\s*=\s*\?',
-                sql_str_fast,
-                _re_fast.IGNORECASE,
+            direct_pat = re.compile(
+                r'\b' + re.escape(source_alias_r) + r'\.node_id\s*=\s*\?',
+                re.IGNORECASE,
             )
-            if direct_m:
-                params_fast = sql_query.parameters[0] if sql_query.parameters else []
-                for pv in params_fast:
+            sql_str_chk = sql_query.sql if isinstance(sql_query.sql, str) else ""
+            if direct_pat.search(sql_str_chk):
+                params_chk = sql_query.parameters[0] if sql_query.parameters else []
+                for pv in params_chk:
                     if isinstance(pv, str) and pv:
                         source_id = pv
                         break
@@ -588,65 +679,14 @@ class QueryMixin:
         col_map = sql_query.column_name_map or {}
         sql_str = sql_query.sql if isinstance(sql_query.sql, str) else ""
 
-        # Step 1: Collect source node IDs (same logic as _execute_var_length_labeled)
-        source_ids: list = []
-        if source_labels:
-            label_sets = []
-            for lbl in source_labels:
-                try:
-                    lbl_result = self._store.query_nodes(label_filter=lbl)
-                    label_sets.append({row[0] for row in lbl_result.rows if row and row[0]})
-                except Exception as exc:
-                    logger.debug("label lookup failed for %s: %s", lbl, exc)
-            if label_sets:
-                common = label_sets[0]
-                for s in label_sets[1:]:
-                    common = common & s
-                source_ids = list(common)
-        elif source_alias and target_alias:
-            # Source bound in prior MATCH: extract IDs from SQL
-            cartesian_pat = _re.compile(
-                r'\bJOIN\s+\S+\s+' + _re.escape(target_alias) + r'\s+ON\s+1\s*=\s*1\b',
-                _re.IGNORECASE,
-            )
-            m = cartesian_pat.search(sql_str)
-            if m:
-                from_start = sql_str.find('\nFROM ')
-                if from_start == -1:
-                    from_start = sql_str.lower().find('\nfrom ')
-                src_portion = sql_str[from_start:m.start()].strip()
-                src_query = f"SELECT DISTINCT {source_alias}.node_id {src_portion}"
-                # Build source-ID query: use full SQL (preserving all JOINs and
-                # WHERE) but SELECT only DISTINCT source node_id. Post-boundary
-                # target aliases are stripped from SELECT but kept in FROM/WHERE so
-                # all params stay in their original order. DISTINCT collapses the
-                # Cartesian product with target rows.
-                from_start_full = sql_str.find('\nFROM ')
-                if from_start_full == -1:
-                    from_start_full = sql_str.lower().find('\nfrom ')
-                full_from_where = sql_str[from_start_full:].strip()
-                # Identify and strip ORDER/HAVING/GROUP clauses
-                order_m = _re.search(r'\n(?:ORDER|HAVING|GROUP)\b', full_from_where, _re.IGNORECASE)
-                if order_m:
-                    full_from_where = full_from_where[:order_m.start()].strip()
-                src_query = f"SELECT DISTINCT {source_alias}.node_id {full_from_where}"
-                # All original params apply (the Cartesian product with target is
-                # collapsed by DISTINCT; target prop conditions become no-ops for
-                # source-only rows since LEFT JOINs return NULL for unmatched rows).
-                params_list = sql_query.parameters[0] if sql_query.parameters else []
-                src_params = list(params_list)
-                post_params = []
-                # No post_where_conds — all WHERE conditions are passed through the query.
-                # (post_where_conds stays empty; target filtering handled by BFS result
-                # intersection + target_labels + _filter_nodes_by_post_where below.)
-                try:
-                    cursor = self._store.conn.cursor()
-                    cursor.execute(src_query, src_params)
-                    for row in cursor.fetchall():
-                        if row and row[0]:
-                            source_ids.append(row[0])
-                except Exception as exc:
-                    logger.debug("Source ID extraction query failed: %s", exc)
+        # Step 1: Collect source node IDs via the shared extraction module.
+        source_ids = extract_vlp_source_ids(
+            sql_query=sql_query,
+            source_labels=source_labels,
+            source_alias=source_alias,
+            target_alias=target_alias,
+            store=getattr(self, "_store", None),
+        )
 
         if not source_ids:
             columns = _build_path_func_columns(return_path_funcs, source_var, target_var, col_map, path_named_var)
@@ -980,64 +1020,18 @@ class QueryMixin:
             )
         )
 
-        # Step 1: Collect source node IDs
-        # Also track post-boundary conditions for target property filtering.
-        source_ids: list = []
+        # Step 1: Collect source node IDs via the shared extraction module.
+        source_ids = extract_vlp_source_ids(
+            sql_query=sql_query,
+            source_labels=source_labels,
+            source_alias=source_alias,
+            target_alias=target_alias,
+            store=getattr(self, "_store", None),
+        )
+        # post_where_conds and post_params are unused after the extraction refactor
+        # but kept to avoid NameError in downstream code that references them.
         post_where_conds: list = []
         post_params: list = []
-        if source_labels:
-            # Case 1: Source labeled in this MATCH pattern → use query_nodes per label
-            # Multiple labels use AND semantics: intersect the sets
-            label_sets = []
-            for lbl in source_labels:
-                try:
-                    lbl_result = self._store.query_nodes(label_filter=lbl)
-                    label_sets.append({row[0] for row in lbl_result.rows if row and row[0]})
-                except Exception as exc:
-                    logger.debug("label lookup failed for %s: %s", lbl, exc)
-            if label_sets:
-                common = label_sets[0]
-                for s in label_sets[1:]:
-                    common = common & s
-                source_ids = list(common)
-        elif source_alias and target_alias:
-            # Case 2: Source bound in prior MATCH — extract IDs by running a trimmed
-            # version of the SQL that stops before the Cartesian JOIN on target_alias.
-            # Pattern: "JOIN nodes {target_alias} ON 1=1" marks the boundary.
-            cartesian_pat = _re.compile(
-                r'\bJOIN\s+\S+\s+' + _re.escape(target_alias) + r'\s+ON\s+1\s*=\s*1\b',
-                _re.IGNORECASE,
-            )
-            m = cartesian_pat.search(sql_str)
-            if m:
-                # Build: SELECT DISTINCT {source_alias}.node_id FROM ... (source joins only)
-                # Use the FROM clause up to but not including the Cartesian JOIN
-                from_start = sql_str.find('\nFROM ')
-                if from_start == -1:
-                    from_start = sql_str.lower().find('\nfrom ')
-                src_portion = sql_str[from_start:m.start()].strip()
-                # Use full SQL (all JOINs + WHERE) to extract distinct source node IDs.
-                # DISTINCT collapses the Cartesian product with target rows.
-                # All original params apply unchanged.
-                from_start_full = sql_str.find('\nFROM ')
-                if from_start_full == -1:
-                    from_start_full = sql_str.lower().find('\nfrom ')
-                full_from_where = sql_str[from_start_full:].strip()
-                order_m2 = _re.search(r'\n(?:ORDER|HAVING|GROUP)\b', full_from_where, _re.IGNORECASE)
-                if order_m2:
-                    full_from_where = full_from_where[:order_m2.start()].strip()
-                src_query = f"SELECT DISTINCT {source_alias}.node_id {full_from_where}"
-                params_list = sql_query.parameters[0] if sql_query.parameters else []
-                src_params = list(params_list)
-                post_params = []
-                try:
-                    cursor = self._store.conn.cursor()
-                    cursor.execute(src_query, src_params)
-                    for row in cursor.fetchall():
-                        if row and row[0]:
-                            source_ids.append(row[0])
-                except Exception as exc:
-                    logger.debug("Source ID extraction query failed: %s", exc)
 
         if not source_ids:
             if is_count:

{iris_vector_graph-2.19.1 → iris_vector_graph-2.20.0}/iris_vector_graph/engine.py

@@ -129,6 +129,74 @@ def _bfs_stream_pages(conn, tag, page_size=500):
         cursor_o = page.get("next_o", "")
 
 
+# ── Sub-engine namespaces (spec-arch-2) ────────────────────────────────────
+# Each sub-engine is a thin delegator that groups related methods by domain.
+# All 192 top-level methods remain unchanged — sub-engines are additive only.
+# Callers who only need graph mutations learn `engine.graph.*`; temporal callers
+# learn `engine.temporal.*`. Fixture setup and IDE autocomplete improve because
+# the relevant method surface is 10-30 methods, not 192.
+
+class _GraphSubEngine:
+    """Structural graph mutations and queries."""
+    __slots__ = ("_e",)
+    def __init__(self, e): self._e = e
+    def create_node(self, *a, **kw): return self._e.create_node(*a, **kw)
+    def create_edge(self, *a, **kw): return self._e.create_edge(*a, **kw)
+    def upsert_node(self, *a, **kw): return self._e.upsert_node(*a, **kw)
+    def delete_node(self, *a, **kw): return self._e.delete_node(*a, **kw)
+    def delete_edge(self, *a, **kw): return self._e.delete_edge(*a, **kw)
+    def bulk_create_nodes(self, *a, **kw): return self._e.bulk_create_nodes(*a, **kw)
+    def bulk_create_edges(self, *a, **kw): return self._e.bulk_create_edges(*a, **kw)
+    def get_node_count(self, *a, **kw): return self._e.get_node_count(*a, **kw)
+    def get_edge_count(self, *a, **kw): return self._e.get_edge_count(*a, **kw)
+    def get_labels(self, *a, **kw): return self._e.get_labels(*a, **kw)
+    def get_relationship_types(self, *a, **kw): return self._e.get_relationship_types(*a, **kw)
+
+
+class _CypherSubEngine:
+    """Cypher query execution and adjacency index management."""
+    __slots__ = ("_e",)
+    def __init__(self, e): self._e = e
+    def execute_cypher(self, *a, **kw): return self._e.execute_cypher(*a, **kw)
+    def execute_bfs(self, *a, **kw): return self._e.execute_bfs(*a, **kw)
+    def execute_knn_vec(self, *a, **kw): return self._e.execute_knn_vec(*a, **kw)
+    def sync(self, *a, **kw): return self._e.sync(*a, **kw)
+    def rebuild_nkg(self, *a, **kw): return self._e.rebuild_nkg(*a, **kw)
+    def rebuild_kg(self, *a, **kw): return self._e.rebuild_kg(*a, **kw)
+
+
+class _TemporalSubEngine:
+    """Temporal edge graph — event-time writes and window queries."""
+    __slots__ = ("_e",)
+    def __init__(self, e): self._e = e
+    def create_edge_temporal(self, *a, **kw): return self._e.create_edge_temporal(*a, **kw)
+    def bulk_create_edges_temporal(self, *a, **kw): return self._e.bulk_create_edges_temporal(*a, **kw)
+    def get_edges_in_window(self, *a, **kw): return self._e.get_edges_in_window(*a, **kw)
+    def get_edge_velocity(self, *a, **kw): return self._e.get_edge_velocity(*a, **kw)
+    def find_burst_nodes(self, *a, **kw): return self._e.find_burst_nodes(*a, **kw)
+    def get_edge_attrs(self, *a, **kw): return self._e.get_edge_attrs(*a, **kw)
+    def get_temporal_aggregate(self, *a, **kw): return self._e.get_temporal_aggregate(*a, **kw)
+    def get_bucket_groups(self, *a, **kw): return self._e.get_bucket_groups(*a, **kw)
+    def get_bucket_group_targets(self, *a, **kw): return self._e.get_bucket_group_targets(*a, **kw)
+    def purge_raw_before(self, *a, **kw): return self._e.purge_raw_before(*a, **kw)
+
+
+class _AlgorithmsSubEngine:
+    """Graph algorithms — centrality, community detection, ranking."""
+    __slots__ = ("_e",)
+    def __init__(self, e): self._e = e
+    def degree_centrality(self, *a, **kw): return self._e.degree_centrality(*a, **kw)
+    def betweenness_centrality(self, *a, **kw): return self._e.betweenness_centrality(*a, **kw)
+    def closeness_centrality(self, *a, **kw): return self._e.closeness_centrality(*a, **kw)
+    def eigenvector_centrality(self, *a, **kw): return self._e.eigenvector_centrality(*a, **kw)
+    def leiden_communities(self, *a, **kw): return self._e.leiden_communities(*a, **kw)
+    def pagerank(self, *a, **kw): return self._e.pagerank(*a, **kw)
+    def execute_wcc(self, *a, **kw): return self._e.execute_wcc(*a, **kw)
+    def execute_scc(self, *a, **kw): return self._e.execute_scc(*a, **kw)
+    def execute_k_core(self, *a, **kw): return self._e.execute_k_core(*a, **kw)
+    def execute_triangle_count(self, *a, **kw): return self._e.execute_triangle_count(*a, **kw)
+
+
 class IRISGraphEngine(
     LedgerMixin,
     RdfExportMixin,
@@ -217,6 +285,11 @@ class IRISGraphEngine(
         # allowing create_node to emit a compatible INSERT on pre-214 schemas.
         # Defaulting True avoids an eager SQL round-trip on every engine construction.
         self._nodes_has_graph_id: bool = True
+        # Sub-engine namespaces (additive — top-level methods unchanged)
+        self.graph = _GraphSubEngine(self)
+        self.cypher = _CypherSubEngine(self)
+        self.temporal = _TemporalSubEngine(self)
+        self.algorithms = _AlgorithmsSubEngine(self)
         logger.debug(
             "IRISGraphEngine initialized (dim=%s dtype=%s)",
             embedding_dimension or "auto",

{iris_vector_graph-2.19.1 → iris_vector_graph-2.20.0}/iris_vector_graph/ledger/client.py

@@ -101,6 +101,26 @@ class CommitResult:
     post_commit_error: Optional[str] = None
 
 
+@dataclass
+class _CommitWireResult:
+    """Raw result from the transport layer — no exceptions, no side effects.
+
+    ``_send_changeset`` populates this and returns it to ``commit()``, which
+    then maps it to exceptions (on failure) or ``CommitResult`` (on success).
+    Keeping transport (chunking, ObjectScript call, JSON parsing) separate from
+    semantics (NKG dirty, post_commit SQL, metrics) makes each independently
+    testable with a simple mock.
+    """
+
+    ok: bool
+    revision_id: Optional[str]
+    replayed: bool
+    stmt_ids: dict
+    error_code: Optional[str]
+    reason: Optional[str]
+    raw_resp: dict
+
+
 @dataclass
 class HistoryPage:
     revisions: List[RevisionInfo]
@@ -223,8 +243,12 @@ class GraphLedger:
 
     # -- commit ----------------------------------------------------------------
 
-    def commit(self, changeset: Changeset, *, kind: str = "changeset") -> CommitResult:
-        changeset.validate()
+    def _send_changeset(self, changeset: Changeset, *, kind: str = "changeset") -> "_CommitWireResult":
+        """Transport layer: chunk, call ObjectScript, parse JSON → _CommitWireResult.
+
+        Never raises. All errors are encoded in the result's ``ok=False`` path.
+        Has no side effects on the engine or store — purely I/O.
+        """
         payload = changeset.canonical_json()
         meta = {
             "fingerprint": changeset.fingerprint(),
@@ -234,21 +258,26 @@ class GraphLedger:
             "schema": self._schema(),
             "staged": False,
         }
-        t0 = time.perf_counter()
-        if len(payload) <= CHUNK_CHARS:
-            raw = self._call("Commit", payload, json.dumps(meta))
-        else:
-            token = uuid.uuid4().hex
-            iris_obj = self._iris()
-            idx = 0
-            for start in range(0, len(payload), CHUNK_CHARS):
-                idx += 1
-                iris_obj.classMethodValue(
-                    LEDGER_CLASS, "StageChunk", token, idx, payload[start : start + CHUNK_CHARS]
-                )
-            meta["staged"] = True
-            raw = self._call("Commit", token, json.dumps(meta))
-        duration_ms = (time.perf_counter() - t0) * 1000.0
+        try:
+            if len(payload) <= CHUNK_CHARS:
+                raw = self._call("Commit", payload, json.dumps(meta))
+            else:
+                token = uuid.uuid4().hex
+                iris_obj = self._iris()
+                idx = 0
+                for start in range(0, len(payload), CHUNK_CHARS):
+                    idx += 1
+                    iris_obj.classMethodValue(
+                        LEDGER_CLASS, "StageChunk", token, idx, payload[start : start + CHUNK_CHARS]
+                    )
+                meta["staged"] = True
+                raw = self._call("Commit", token, json.dumps(meta))
+        except Exception as exc:
+            return _CommitWireResult(
+                ok=False, revision_id=None, replayed=False, stmt_ids={},
+                error_code="inconsistent", reason=str(exc),
+                raw_resp={"ok": False, "error": "inconsistent", "reason": str(exc)},
+            )
         try:
             resp = (
                 json.loads(raw)
@@ -261,8 +290,25 @@ class GraphLedger:
                 "error": "inconsistent",
                 "reason": f"non-JSON response: {raw[:200]!r}",
             }
+        revision = resp.get("revision") or {}
+        return _CommitWireResult(
+            ok=bool(resp.get("ok", False)),
+            revision_id=revision.get("revision_id") if revision else None,
+            replayed=bool(resp.get("replayed", False)),
+            stmt_ids=resp.get("stmt_ids") or {},
+            error_code=resp.get("error") if not resp.get("ok", False) else None,
+            reason=resp.get("reason"),
+            raw_resp=resp,
+        )
 
-        if not resp.get("ok", False):
+    def commit(self, changeset: Changeset, *, kind: str = "changeset") -> CommitResult:
+        changeset.validate()
+        t0 = time.perf_counter()
+        wire = self._send_changeset(changeset, kind=kind)
+        duration_ms = (time.perf_counter() - t0) * 1000.0
+
+        if not wire.ok:
+            resp = wire.raw_resp
             self._emit(
                 resp.get("error", "error"), None, changeset, duration_ms, reason=resp.get("reason")
             )
@@ -274,9 +320,10 @@ class GraphLedger:
                 raise NodeNotFoundError(missing_node=missing)
             raise from_commit_error(resp)
 
+        resp = wire.raw_resp
         info = RevisionInfo.from_wire(resp["revision"])
-        replayed = bool(resp.get("replayed", False))
-        stmt_ids = {int(k): str(v) for k, v in (resp.get("stmt_ids") or {}).items()}
+        replayed = wire.replayed
+        stmt_ids = {int(k): str(v) for k, v in (wire.stmt_ids or {}).items()}
         self._emit("replayed" if replayed else "success", info, changeset, duration_ms)
 
         if not replayed and any(