iris-vector-graph 2.4.2__tar.gz → 2.4.3__tar.gz

{iris_vector_graph-2.4.2 → iris_vector_graph-2.4.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: iris-vector-graph
-Version: 2.4.2
+Version: 2.4.3
 Summary: Transactional Graph + Vector retrieval system for InterSystems IRIS with hybrid search, openCypher, and GraphQL APIs
 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.4.2 → iris_vector_graph-2.4.3}/iris_vector_graph/_engine/query.py

@@ -355,8 +355,11 @@ class QueryMixin:
         max_hops = vl0.get("max_hops", 5)
         direction = vl0.get("direction", "out")
         def _extract_limit(s: str) -> int:
-            # IRIS SQL uses FETCH FIRST N ROWS ONLY; fall back to LIMIT N
+            # IRIS SQL uses FETCH FIRST N ROWS ONLY; the build-106 %qaqpre workaround
+            # emits SELECT TOP N instead; fall back to LIMIT N.
             m = _re.search(r"FETCH\s+FIRST\s+(\d+)\s+ROWS\s+ONLY", s, _re.IGNORECASE)
+            if not m:
+                m = _re.search(r"\bSELECT\s+(?:DISTINCT\s+)?TOP\s+(\d+)\b", s, _re.IGNORECASE)
             if not m:
                 m = _re.search(r"\bLIMIT\s+(\d+)", s, _re.IGNORECASE)
             return int(m.group(1)) if m else 0
@@ -563,8 +566,11 @@ class QueryMixin:
         import re as _re
         sql_str = sql_query.sql if isinstance(sql_query.sql, str) else (sql_query.sql[0] if sql_query.sql else "")
         if sql_query.sql:
-            # IRIS SQL uses "FETCH FIRST N ROWS ONLY" (not LIMIT N)
+            # IRIS SQL uses "FETCH FIRST N ROWS ONLY"; the build-106 %qaqpre workaround
+            # emits SELECT TOP N instead; fall back to LIMIT N.
             m = _re.search(r"FETCH\s+FIRST\s+(\d+)\s+ROWS\s+ONLY", sql_str, _re.IGNORECASE)
+            if not m:
+                m = _re.search(r"\bSELECT\s+(?:DISTINCT\s+)?TOP\s+(\d+)\b", sql_str, _re.IGNORECASE)
             if not m:
                 m = _re.search(r"\bLIMIT\s+(\d+)", sql_str, _re.IGNORECASE)
             if m:

{iris_vector_graph-2.4.2 → iris_vector_graph-2.4.3}/iris_vector_graph/cypher/translator.py

@@ -1044,9 +1044,14 @@ def _maybe_split_deep_joins(sql: str, params: list, context) -> str:
     if join_count <= JOIN_THRESHOLD:
         return sql
     import re as _re
-    select_m = _re.match(r'(SELECT\s+(?:DISTINCT\s+)?)(.*?)(\nFROM\s)', sql, _re.DOTALL)
+    # Capture an optional `TOP n` in the prefix (the FETCH-FIRST-+-JOIN workaround emits
+    # SELECT [DISTINCT] TOP n) so it stays attached to the SELECT keyword and is not
+    # swept into the column list.
+    select_m = _re.match(r'(SELECT\s+(?:DISTINCT\s+)?(?:TOP\s+\d+\s+)?)(.*?)(\nFROM\s)', sql, _re.DOTALL)
     if not select_m:
         return sql
+    # select_prefix carries any DISTINCT and TOP n; both propagate to the outer wrapper
+    # (line below), so the CTE wrap preserves the row cap from the TOP workaround.
     select_prefix = select_m.group(1)
     select_cols = select_m.group(2).strip()
     has_agg = bool(_re.search(r'\b(AVG|SUM|COUNT|MIN|MAX|STDEV|JSON_ARRAYAGG)\s*\(', select_cols))
@@ -1543,6 +1548,27 @@ def apply_pagination(
     if limit is not None or skip is not None:
         if "\nFROM " not in sql and "FROM " not in sql.split("\n")[0]:
             sql = sql.rstrip() + "\nFROM (SELECT 1) __dual"
+    # Build-106 workaround: IRIS 2026.3.0AI build 106 SIGSEGVs in %qaqpre when a
+    # multi-table JOIN is combined with `FETCH FIRST n ROWS ONLY` on VARCHAR-keyed
+    # tables (the ivg schema). `SELECT TOP n` does NOT crash. When the engine has
+    # detected the bug (engine._fetch_first_unsafe, set by a connect-time probe) and
+    # there is a LIMIT with NO SKIP (TOP cannot express OFFSET), emit TOP instead.
+    engine = getattr(context, "_engine", None)
+    fetch_first_unsafe = bool(getattr(engine, "_fetch_first_unsafe", False))
+    if (
+        limit is not None
+        and skip is None
+        and fetch_first_unsafe
+        and sql.lstrip().upper().startswith("SELECT ")
+        and " TOP " not in sql.split("\n", 1)[0].upper()
+    ):
+        # Inject `TOP n` right after the leading SELECT (and after DISTINCT if present).
+        head, sep, rest = sql.partition("SELECT ")
+        if rest[:9].upper().startswith("DISTINCT "):
+            rest = "DISTINCT " + f"TOP {limit} " + rest[9:]
+        else:
+            rest = f"TOP {limit} " + rest
+        return head + sep + rest
     if limit is not None:
         sql += f"\nFETCH FIRST {limit} ROWS ONLY"
     if skip is not None:

{iris_vector_graph-2.4.2 → iris_vector_graph-2.4.3}/iris_vector_graph/engine.py

@@ -143,6 +143,7 @@ class IRISGraphEngine(RdfExportMixin, ShaclMixin, ProvMixin, TemporalMixin, Snap
         self._rel_mapping_cache: Optional[Dict[tuple, dict]] = None
         self._connection_params: Optional[Dict[str, Any]] = None
         self._nkg_dirty: bool = False
+        self._fetch_first_unsafe_cached: Optional[bool] = None  # build-106 %qaqpre probe (lazy)
         self._native_conn = None  # dedicated connection for iris.createIRIS — never used for cursor DDL
         self._index_registry: Dict[str, str] = self._build_index_registry()
         self._pending_index_config: Dict[str, Any] = {}
@@ -209,6 +210,69 @@ class IRISGraphEngine(RdfExportMixin, ShaclMixin, ProvMixin, TemporalMixin, Snap
             )
         return cls(conn, embedding_dimension=embedding_dimension, **kwargs)
 
+    @property
+    def _fetch_first_unsafe(self) -> bool:
+        """True when this IRIS build SIGSEGVs in %qaqpre on a multi-table JOIN combined
+        with `FETCH FIRST n ROWS ONLY` (observed on irishealth 2026.3.0AI build 106).
+
+        Detected once and cached. Primary signal is a behavioral probe run in a
+        SUBPROCESS (the crash is a hard SIGSEGV — uncatchable in-process), gated on
+        having stored connection params. Falls back to a $ZVERSION build check when a
+        subprocess probe is not possible (e.g. embedded context). Defaults to safe
+        (False) if neither can determine — `TOP` is only a workaround, never required.
+        """
+        if self._fetch_first_unsafe_cached is None:
+            self._fetch_first_unsafe_cached = self._detect_fetch_first_unsafe()
+        return self._fetch_first_unsafe_cached
+
+    def _detect_fetch_first_unsafe(self) -> bool:
+        # Subprocess behavioral probe (most reliable): run the crashing shape against a
+        # VARCHAR-keyed temp table; SIGSEGV (rc -11 / 139) => unsafe.
+        if self._connection_params:
+            try:
+                import subprocess, sys, json
+                cp = json.dumps(self._connection_params)
+                script = (
+                    "import iris, json, sys\n"
+                    f"cp = json.loads(r'''{cp}''')\n"
+                    "c = iris.dbapi.connect(**cp); cur = c.cursor()\n"
+                    "for d in ['CREATE TABLE ivg_ff_probe_a (id VARCHAR(64))',"
+                    "'CREATE TABLE ivg_ff_probe_b (sid VARCHAR(64))']:\n"
+                    "    try: cur.execute(d)\n"
+                    "    except Exception: pass\n"
+                    "cur.execute('SELECT a.id FROM ivg_ff_probe_a a JOIN ivg_ff_probe_b b "
+                    "ON b.sid=a.id FETCH FIRST 1 ROWS ONLY'); cur.fetchall()\n"
+                    "print('OK')\n"
+                )
+                r = subprocess.run([sys.executable, "-c", script],
+                                   capture_output=True, text=True, timeout=60)
+                if r.returncode in (-11, 139, -6, 134):
+                    logger.warning(
+                        "IRIS build SIGSEGVs in %%qaqpre on FETCH FIRST + multi-table JOIN "
+                        "(observed on 2026.2.0AI and 2026.3.0AI AI builds); ivg will emit "
+                        "TOP for LIMIT-only queries to avoid the crash."
+                    )
+                    return True
+                return False
+            except Exception as e:
+                logger.debug("fetch-first probe failed, falling back to version check: %s", e)
+        # Fallback: $ZVERSION check (no crash risk) when a subprocess probe is not
+        # possible (e.g. embedded context with no stored connection params). The bug
+        # has been observed on the IRIS "AI" build line (2026.2.0AI build 161 and
+        # 2026.3.0AI build 106); treat AI builds as unsafe conservatively. Non-AI
+        # builds are assumed safe (FETCH FIRST retained). If a future build fixes it,
+        # this fallback can be narrowed — the subprocess probe remains authoritative.
+        try:
+            cur = self.conn.cursor()
+            cur.execute("SELECT $ZVERSION")
+            ver = str(cur.fetchone()[0])
+            import re as _re
+            if _re.search(r"20\d\d\.\d+\.\d+AI", ver):
+                return True
+        except Exception:
+            pass
+        return False
+
     def _reconnect_if_stale(self) -> None:
         try:
             cur = self.conn.cursor()

{iris_vector_graph-2.4.2 → iris_vector_graph-2.4.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "iris-vector-graph"
-version = "2.4.2"
+version = "2.4.3"
 description = "Transactional Graph + Vector retrieval system for InterSystems IRIS with hybrid search, openCypher, and GraphQL APIs"
 readme = "README.md"
 license = "MIT"

iris_vector_graph-2.4.3/tests/unit/test_fetch_first_join_bug.py

@@ -0,0 +1,56 @@
+"""Translator tests for the FETCH FIRST + JOIN %qaqpre crash workaround (build-106).
+
+ROOT CAUSE (proven on a live irishealth:2026.3.0AI.106.0 container): the DB-API driver
+SIGSEGVs in %qaqpre when executing a query that combines a multi-table JOIN with
+`FETCH FIRST n ROWS ONLY` on VARCHAR-keyed tables (the ivg schema). It is NOT the
+INNER JOIN keyword (the original report's guess) — comma-join and LEFT OUTER JOIN crash
+too. `SELECT TOP n` does NOT crash and is the fix.
+
+The engine detects the bug at connect time (subprocess probe) and sets
+`engine._fetch_first_unsafe`. When set, the translator emits `SELECT TOP n` instead of a
+trailing `FETCH FIRST n ROWS ONLY` for LIMIT-only queries.
+"""
+import pytest
+from iris_vector_graph.cypher.translator import translate_to_sql
+from iris_vector_graph.cypher.parser import parse_query
+
+
+class _StubEngine:
+    """Minimal engine carrying just the bug flag the translator reads."""
+    def __init__(self, fetch_first_unsafe):
+        self._fetch_first_unsafe = fetch_first_unsafe
+    def get_table_mapping(self, label):
+        return None
+
+
+def _sql(cypher, *, unsafe, params=None):
+    ast = parse_query(cypher)
+    res = translate_to_sql(ast, params or {}, engine=_StubEngine(unsafe))
+    return res if isinstance(res, str) else str(res)
+
+
+class TestFetchFirstJoinWorkaround:
+    CYPHER = "MATCH (n)-[:R]->(m) RETURN n.node_id AS id LIMIT 5"
+
+    def test_unsafe_build_emits_top_not_fetch_first(self):
+        sql = _sql(self.CYPHER, unsafe=True)
+        assert "FETCH FIRST" not in sql, f"FETCH FIRST must not be emitted on unsafe build:\n{sql}"
+        assert "TOP 5" in sql, f"expected SELECT TOP 5:\n{sql}"
+
+    def test_safe_build_keeps_fetch_first(self):
+        sql = _sql(self.CYPHER, unsafe=False)
+        # On safe builds the existing FETCH FIRST behavior is preserved.
+        assert "FETCH FIRST 5 ROWS ONLY" in sql, f"expected FETCH FIRST on safe build:\n{sql}"
+
+    def test_unsafe_limit_only_simple_match(self):
+        sql = _sql("MATCH (n) RETURN n.node_id LIMIT 3", unsafe=True)
+        assert "FETCH FIRST" not in sql
+        assert "TOP 3" in sql
+
+    def test_unsafe_skip_plus_limit_keeps_fetch_first(self):
+        # TOP cannot express OFFSET; SKIP+LIMIT must retain FETCH FIRST + OFFSET
+        # (rare; residual build-106 risk is documented in apply_pagination).
+        sql = _sql("MATCH (n) RETURN n.node_id SKIP 2 LIMIT 4", unsafe=True)
+        assert "OFFSET 2" in sql
+        assert "FETCH FIRST 4 ROWS ONLY" in sql
+        assert "TOP 4" not in sql