iris-vector-graph 4.4.1__tar.gz → 4.4.2__tar.gz

{iris_vector_graph-4.4.1 → iris_vector_graph-4.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: iris-vector-graph
-Version: 4.4.1
+Version: 4.4.2
 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
@@ -108,7 +108,7 @@ Description-Content-Type: text/markdown
 
 [![PyPI](https://img.shields.io/pypi/v/iris-vector-graph)](https://pypi.org/project/iris-vector-graph/)
 [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
-[![IRIS 2024.1+](https://img.shields.io/badge/IRIS-2024.1+-purple.svg)](https://www.intersystems.com/products/intersystems-iris/)
+[![IRIS 2025.1+](https://img.shields.io/badge/IRIS-2025.1+-purple.svg)](https://www.intersystems.com/products/intersystems-iris/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
 
 ---
@@ -204,7 +204,7 @@ Hardware: M3 Ultra, Community IRIS 2026.1, ARM64 Docker.
 Against Neo4j and Memgraph on the LDBC Social Network Benchmark at scale factor 10 (AWS `r7g.8xlarge`,
 2026-10-23, native Cypher with compiled plans), IVG's median time over 39 queries is 0.90x Neo4j's and 0.57x
 Memgraph's (Memgraph from the previous SF10 run on the same instance type)
-([report](docs/performance/alt-bench/REPORT_TEMPLATE.md#sf10-after-spec-257-aws-2026-10-23)).
+([report](docs/performance/ALT_VS_BASELINE.md#sf10-after-spec-257-aws-2026-10-23)).
 
 ### Algorithm comparison (vs Neo4j GDS and networkx)
 

{iris_vector_graph-4.4.1 → iris_vector_graph-4.4.2}/README.md

@@ -6,7 +6,7 @@
 
 [![PyPI](https://img.shields.io/pypi/v/iris-vector-graph)](https://pypi.org/project/iris-vector-graph/)
 [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
-[![IRIS 2024.1+](https://img.shields.io/badge/IRIS-2024.1+-purple.svg)](https://www.intersystems.com/products/intersystems-iris/)
+[![IRIS 2025.1+](https://img.shields.io/badge/IRIS-2025.1+-purple.svg)](https://www.intersystems.com/products/intersystems-iris/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
 
 ---
@@ -102,7 +102,7 @@ Hardware: M3 Ultra, Community IRIS 2026.1, ARM64 Docker.
 Against Neo4j and Memgraph on the LDBC Social Network Benchmark at scale factor 10 (AWS `r7g.8xlarge`,
 2026-10-23, native Cypher with compiled plans), IVG's median time over 39 queries is 0.90x Neo4j's and 0.57x
 Memgraph's (Memgraph from the previous SF10 run on the same instance type)
-([report](docs/performance/alt-bench/REPORT_TEMPLATE.md#sf10-after-spec-257-aws-2026-10-23)).
+([report](docs/performance/ALT_VS_BASELINE.md#sf10-after-spec-257-aws-2026-10-23)).
 
 ### Algorithm comparison (vs Neo4j GDS and networkx)
 

{iris_vector_graph-4.4.1 → iris_vector_graph-4.4.2}/iris_src/src/Graph/KG/Eraser.cls

@@ -195,6 +195,18 @@ ClassMethod EraseGraph(pGraph As %String = "") As %Integer
 			WHERE COALESCE(graph_id, '') = COALESCE(:tName, ''))
 		If (SQLCODE '= 0) && (SQLCODE '= 100) { $$$ThrowStatus(..SqlErr("kg_EdgeEmbeddings", SQLCODE)) }
 
+		// Whether ^NKG can hold any edge of this graph, decided HERE and not after the
+		// delete below. Since spec 252 the functional index on rdf_edges clears
+		// ^KG("out", graph) row by row as the rows go, so a read of ^KG afterwards finds
+		// nothing for a graph whose edges are rows. That read (it was
+		// $Data(^KG("out", key))) was always 0, InvalidateDerived never dropped ^NKG, and
+		// the sketches and edgeCount of the erased edges stayed behind: a sketch cannot
+		// have an element taken out, so CountDistinctKHop went on counting the far ends
+		// of edges that no longer exist. The rows and ^KG("out") are both still whole at
+		// this point, and this is the last statement before the rows go: the window left
+		// is the delete itself.
+		Set tNkgAtRisk = ..GraphEdgesInNKG(tKey, tName)
+
 		&sql(DELETE FROM Graph_KG.rdf_edges
 			WHERE COALESCE(graph_id, '') = COALESCE(:tName, ''))
 		If (SQLCODE '= 0) && (SQLCODE '= 100) { $$$ThrowStatus(..SqlErr("rdf_edges", SQLCODE)) }
@@ -210,7 +222,6 @@ ClassMethod EraseGraph(pGraph As %String = "") As %Integer
 		// One Kill per store, because the graph key is the FIRST subscript in every
 		// one of them. That is the whole return on ADR-0001: erasing a graph from
 		// ^KG is thirteen Kills rather than thirteen walks.
-		Set tHadEdges = $Data(^KG("out", tKey))
 		// out, in and the degree cache (gen, degc) belong to Graph.KG.Adjacency (spec 248),
 		// which kills them under the writer lock inside this transaction.
 		Set tSC = ##class(Graph.KG.Adjacency).RemoveGraph(tKey)
@@ -231,7 +242,7 @@ ClassMethod EraseGraph(pGraph As %String = "") As %Integer
 		// purge touches it. A surviving entry is a hash with no referent, not
 		// content, so it is left alone here and emptied only by EraseAll.
 
-		Do ..InvalidateDerived(tHadEdges)
+		Do ..InvalidateDerived(tNkgAtRisk)
 		Do ..EraseLedgerFor(tName)
 
 		TCOMMIT
@@ -339,6 +350,11 @@ ClassMethod EraseNodes(pGraph As %String = "", pPrefix As %String = "") As %Inte
 /// every id named, present or not, so adjacency left behind by an earlier
 /// SQL-only delete is removed too.
 ///
+/// ^NKG is dropped when edges went AND an erased id (or both ends of a removed edge) is
+/// interned in it. A purge of ids that were never interned leaves ^NKG standing: none
+/// of their edges can be in it (NKGMayHoldAny). ^KG("__version") and the cached
+/// algorithm answers are invalidated either way.
+///
 /// Returns the number of Graph_KG.nodes rows removed. One transaction for the
 /// whole list: the caller bounds the list, not this method.
 ClassMethod EraseNodeIds(pGraph As %String = "", pIdsJson As %String = "[]") As %Integer
@@ -377,6 +393,10 @@ ClassMethod EraseEdges(pGraph As %String = "", pEdgesJson As %String = "[]") As
 	Do ..CollectOrphanRoutes(.tRoute)
 
 	Set tRemoved = 0
+	// 1 once an edge this call names was in ^KG("out") before it was touched. The row count
+	// alone cannot say: an adjacency entry with no row behind it removes nothing from the
+	// table, yet its ^NKG sketch and edgeCount are exactly as stale as a row's.
+	Set tHadAdj = 0
 	Try {
 		TSTART
 		Set tIter = tArr.%GetIterator()
@@ -400,6 +420,10 @@ ClassMethod EraseEdges(pGraph As %String = "", pEdgesJson As %String = "[]") As
 				Set tEdge(tEid) = ""
 			}
 			&sql(CLOSE ivgEraseEdgeRows)
+			// Read before EraseEdgeRow: the per-row index clears the entry as the row goes.
+			If $Data(^KG("out", tKey, tS, tP, tO)) {
+				Set tHadAdj = 1
+			}
 			Set tEid = ""
 			For {
 				Set tEid = $Order(tEdge(tEid))
@@ -410,7 +434,7 @@ ClassMethod EraseEdges(pGraph As %String = "", pEdgesJson As %String = "[]") As
 			// when the entry is already gone.
 			Do ##class(Graph.KG.Adjacency).Remove(tKey, tS, tP, tO)
 		}
-		If tRemoved > 0 {
+		If (tRemoved > 0) || tHadAdj {
 			Kill ^KG("deg2p", tKey)
 			Kill ^KG("deg2p_exact", tKey)
 			Do ..InvalidateDerived(1)
@@ -437,6 +461,9 @@ ClassMethod EraseIdSet(pKey, pName As %String) As %Integer [ Private ]
 
 	Set tRemoved = 0
 	Set tHadEdges = 0
+	// 1 once anything this erase removed could be in ^NKG (see NKGMayHoldAny). Starts
+	// at 0: the answer is "no" until a node or an edge proves otherwise.
+	Set tNkgAtRisk = 0
 	Try {
 		TSTART
 		Set tId = ""
@@ -478,6 +505,13 @@ ClassMethod EraseIdSet(pKey, pName As %String) As %Integer [ Private ]
 			For {
 				Set tEid = $Order(tEdge(tEid))
 				Quit:tEid=""
+				// An edge is in ^NKG only if both its ends are interned (every ^NKG writer
+				// interns both). Looked at on the row's own spelling of the ends, not on tId:
+				// a legacy column with a case-folding collation can match this id to a row
+				// that spells it differently.
+				If 'tNkgAtRisk && ..NodeInterned($ListGet(tEdge(tEid), 1)) && ..NodeInterned($ListGet(tEdge(tEid), 3)) {
+					Set tNkgAtRisk = 1
+				}
 				Do ..EraseEdgeRow(tEid, tEdge(tEid), pKey, pName, .tRoute)
 				Set tHadEdges = 1
 			}
@@ -559,7 +593,14 @@ ClassMethod EraseIdSet(pKey, pName As %String) As %Integer [ Private ]
 			Kill ^KG("deg2p_exact", pKey)
 		}
 		If (tRemoved > 0) || tHadEdges {
-			Do ..InvalidateDerived(tHadEdges)
+			// ^NKG is dropped only for an erase that touched edges AND could have changed
+			// it. The ids are looked at here, after every removal above and not before: the
+			// interning is permanent, so a writer that interned an id while this loop ran
+			// is seen, and the window left is the few instructions to the TCOMMIT.
+			If tHadEdges && 'tNkgAtRisk {
+				Set tNkgAtRisk = ..NKGMayHoldAny()
+			}
+			Do ..InvalidateDerived(tHadEdges && tNkgAtRisk)
 		}
 		TCOMMIT
 	} Catch tEx {
@@ -775,8 +816,137 @@ ClassMethod EraseAll() As %Integer
 	Quit tRemoved
 }
 
+/// 1 when ^NKG may hold an edge of graph pName (index key pKey), 0 when it cannot.
+///
+/// The same argument as NKGMayHoldAny, put to a whole graph: every writer of an ^NKG edge
+/// interns BOTH its ends, so an edge is in ^NKG only if both ends have an
+/// ^NKG("$NI", id) entry. A graph none of whose edges has two interned ends has none in
+/// ^NKG, nor any count or sketch built from one, and erasing it leaves ^NKG as correct as
+/// it was. ^NKG has no graph dimension, so an edge the graph shares with a survivor is
+/// found here too (same ends, same spelling): the answer is then 1 and ^NKG is dropped,
+/// which is the safe direction.
+///
+/// Both homes of an edge are read, because neither implies the other: the adjacency
+/// (^KG("out"), which also holds edges with no row behind them) and the rows (which can
+/// be ahead of an adjacency that was never built). Either one finding an edge with two
+/// interned ends answers 1 and stops.
+///
+/// Called before the rows go: the per-row index (spec 252) clears ^KG("out", graph) as
+/// they do, and a read of either afterwards sees an empty graph.
+///
+/// The failure mode is a drop that was not needed (NodeInterned answers 1 when it cannot
+/// tell), never a stale index kept. The cost is one walk of the graph's edges, against an
+/// erase that already removes each of them from six stores.
+ClassMethod GraphEdgesInNKG(pKey, pName As %String) As %Boolean [ Private ]
+{
+	// The adjacency. A source that is not interned has no edge in ^NKG, so its subtree is
+	// not walked at all.
+	Set tS = ""
+	For {
+		Set tS = $Order(^KG("out", pKey, tS))
+		Quit:tS=""
+		If '..NodeInterned(tS) {
+			Continue
+		}
+		Set tP = ""
+		For {
+			Set tP = $Order(^KG("out", pKey, tS, tP))
+			Quit:tP=""
+			Set tO = ""
+			For {
+				Set tO = $Order(^KG("out", pKey, tS, tP, tO))
+				Quit:tO=""
+				If ..NodeInterned(tO) {
+					Return 1
+				}
+			}
+		}
+	}
+
+	// The rows. COALESCE on both sides, as everywhere in this class: the default graph has
+	// two spellings in graph_id, and an empty host variable binds as NULL.
+	Set tRowS = ""
+	Set tRowO = ""
+	Set tHit = 0
+	&sql(DECLARE ivgEraseGraphEnds CURSOR FOR
+		SELECT s, o_id INTO :tRowS, :tRowO
+		FROM Graph_KG.rdf_edges
+		WHERE COALESCE(graph_id, '') = COALESCE(:pName, ''))
+	&sql(OPEN ivgEraseGraphEnds)
+	If SQLCODE < 0 {
+		// Cannot read the rows, cannot say: the drop is the safe answer.
+		Return 1
+	}
+	For {
+		&sql(FETCH ivgEraseGraphEnds)
+		Quit:SQLCODE'=0
+		If ..NodeInterned(tRowS) && ..NodeInterned(tRowO) {
+			Set tHit = 1
+			Quit
+		}
+	}
+	&sql(CLOSE ivgEraseGraphEnds)
+	Quit tHit
+}
+
+/// 1 when any id in ^||IVG.EraseIds is interned in ^NKG.
+///
+/// WHY THIS IS THE TEST. Every writer of an ^NKG edge interns BOTH of its ends first:
+/// Graph.KG.Adjacency:Put, Graph.KG.Traversal:BuildNKG and the Rust kg_build_nkg all
+/// do, and nothing else writes ^NKG(-1), ^NKG(-2), ^NKG(-3) or ^NKG("$agg") (the
+/// per-source sketch is keyed by interned indexes too). So an edge with an end that
+/// has no ^NKG("$NI", id) entry is not in ^NKG, and neither is any count or sketch
+/// built from it. An erase whose ids are all un-interned removes only such edges and
+/// leaves ^NKG exactly as correct as it was.
+///
+/// The converse is why the drop stays for an interned id: its edges are in ^NKG, and
+/// Graph.KG.GraphIndex:DeleteIndex (reached from Adjacency:Remove) takes only the
+/// adjacency entries, not $meta edgeCount or the sketches.
+///
+/// ^NKG("$NI") is the only interning table. Interning is append-only (an id keeps its
+/// index when its last edge goes), so a "yes" can be an id whose edges are gone, and
+/// the drop is then merely not needed. Never the other way round.
+ClassMethod NKGMayHoldAny() As %Boolean [ Private ]
+{
+	Set tId = ""
+	For {
+		Set tId = $Order(^||IVG.EraseIds(tId))
+		Quit:tId=""
+		If ..NodeInterned(tId) {
+			Quit
+		}
+	}
+	Quit (tId '= "")
+}
+
+/// 1 when pId has an entry in ^NKG("$NI"), or when that cannot be told.
+///
+/// A subscript ^NKG could not hold raises <SUBSCRIPT> on the read. Interning such an id
+/// would have raised the same, so it is not interned; but "cannot tell" answers 1, so
+/// that the failure mode of this check is a drop that was not needed and never a
+/// stale index kept. An empty id is no node and is never an edge end.
+ClassMethod NodeInterned(pId As %String) As %Boolean [ Private ]
+{
+	If pId = "" {
+		Quit 0
+	}
+	Set tInterned = 1
+	Try {
+		Set tInterned = ($Data(^NKG("$NI", pId)) > 0)
+	} Catch {
+		Set tInterned = 1
+	}
+	Quit tInterned
+}
+
 /// Drop the derived indexes that cannot be attributed to one graph.
 ///
+/// pTouchedStructural is "this erase may have changed what ^NKG holds", not "this erase
+/// removed an edge": EraseIdSet passes 0 for an erase whose removed edges cannot be in
+/// ^NKG (NKGMayHoldAny), and EraseGraph for a graph none of whose edges can be
+/// (GraphEdgesInNKG). EraseEdges and EraseAll pass 1. The version bump
+/// and the AlgoCache purge below do not depend on it.
+///
 /// ^NKG interns node identifiers with no graph dimension and its counters are
 /// append-only, so there is no subtree to kill and no way to decrement it. The
 /// choice is between an absent ^NKG and a stale one. Absent is a state every

{iris_vector_graph-4.4.1 → iris_vector_graph-4.4.2}/iris_vector_graph/_engine/nodes_edges.py

@@ -1209,7 +1209,9 @@ class NodesEdgesMixin:
         edges in that graph (both directions) with the edges' reifications and
         embeddings, and their ``^KG`` adjacency, props and labels. It bumps
         ``^KG("__version")`` so a cached Arno snapshot is noticed as stale, and
-        drops ``^NKG`` when edges went.
+        drops ``^NKG`` when edges went and any erased node is interned in it. Nodes
+        that were never interned have no edge in ``^NKG``, so erasing only those
+        leaves it standing.
 
         Args:
             prefix: A non-empty id prefix, matched exactly (case-sensitive).
@@ -1231,7 +1233,7 @@ class NodesEdgesMixin:
             )
         canonical = validate_graph_name(graph)
         removed = int(self._store.delete_nodes_by_prefix(prefix, graph=canonical))
-        # EraseNodes drops ^NKG itself when it touched edges; nothing is deferred.
+        # EraseNodes drops ^NKG itself when it touched edges that ^NKG can hold; nothing is deferred.
         self._nkg_dirty = False
         return removed
 
@@ -1729,7 +1731,7 @@ class NodesEdgesMixin:
         deleted = 0
         for scope in self._delete_scopes([node_id], graph):
             deleted += self._delete_in_scope([node_id], scope)
-        # The Eraser drops ^NKG itself when edges went; nothing is deferred.
+        # The Eraser drops ^NKG itself when edges ^NKG can hold went; nothing is deferred.
         return deleted > 0
 
     def bulk_delete_nodes(

{iris_vector_graph-4.4.1 → iris_vector_graph-4.4.2}/iris_vector_graph/cypher/parser.py

@@ -655,13 +655,41 @@ class Parser:
         return True
 
     def _parse_union_branch(self) -> ast.CypherQuery:
-        parts = []
-        while self.peek().kind not in (
-            TokenType.EOF,
-            TokenType.UNION,
-            TokenType.RETURN,
+        # `USE GRAPH` prefixes the whole query. The translator rebuilds every branch
+        # without a graph context, so a branch-level one that parsed would scope
+        # nothing and read as though it did.
+        tok = self.peek()
+        if (
+            tok.kind == TokenType.IDENTIFIER
+            and tok.value
+            and tok.value.upper() == "USE"
+            and self.lexer.peek_ahead(1).kind == TokenType.IDENTIFIER
+            and (self.lexer.peek_ahead(1).value or "").upper() == "GRAPH"
         ):
-            parts.append(self.parse_query_part())
+            raise CypherParseError(
+                "USE GRAPH is only allowed at the start of a query and applies "
+                "to every UNION branch, not to one branch",
+                line=tok.line,
+                column=tok.column,
+            )
+
+        parts = []
+        # Every pass must consume a token or leave the loop. `parse_query_part` returns
+        # an empty part, consuming nothing, on any token it does not know (WITH, `)`,
+        # ORDER...); looping on that grew `parts` without bound.
+        while True:
+            if self.peek().kind == TokenType.WITH:
+                with_clause = self.parse_with_clause()
+                if not parts:
+                    # A branch opening with WITH: an empty part holds it, as in parse().
+                    parts.append(ast.QueryPart(clauses=[]))
+                parts[-1].with_clause = with_clause
+                parts.append(self.parse_query_part())
+                continue
+            part = self.parse_query_part()
+            if not part.clauses and part.procedure_call is None:
+                break
+            parts.append(part)
         ret = None
         skip_val = None
         limit_val = None
@@ -669,6 +697,14 @@ class Parser:
             ret = self.parse_return_clause()
             skip_val = self.parse_skip()
             limit_val = self.parse_limit()
+        if not parts and ret is None:
+            tok = self.peek()
+            raise CypherParseError(
+                "Expected a query after UNION, got "
+                f"{tok.kind.value if tok.kind.value else tok.kind}",
+                line=tok.line,
+                column=tok.column,
+            )
         q = ast.CypherQuery(query_parts=parts, return_clause=ret)
         q.union_queries = []
         q.skip = skip_val

{iris_vector_graph-4.4.1 → iris_vector_graph-4.4.2}/iris_vector_graph/cypher/translator.py

@@ -296,6 +296,101 @@ def _graph_scope_fragment(fragment: str, safe_graph: str) -> str:
             _aliased,
             fragment,
         )
+    return _scope_from_lists(fragment, safe_graph)
+
+
+_FROM_LIST_TOKEN = re.compile(
+    r"'(?:[^']|'')*'|\"[^\"]*\"|[(),]|\b(?:LEFT|RIGHT|INNER|CROSS|FULL|OUTER|JOIN|ON|WHERE|GROUP|ORDER"
+    r"|HAVING|UNION|LIMIT|FETCH|OFFSET)\b"
+)
+_FROM_LIST_STOP = frozenset(("WHERE", "GROUP", "ORDER", "HAVING", "UNION", "LIMIT", "FETCH", "OFFSET"))
+_FROM_LIST_JOIN = frozenset(("LEFT", "RIGHT", "INNER", "CROSS", "FULL", "OUTER", "JOIN"))
+
+
+def _scope_from_lists(fragment: str, safe_graph: str) -> str:
+    """Scope the graph-owned tables a sub-SELECT lists in its `FROM`, whatever the list looks like.
+
+    `_graph_scope_fragment` knows `FROM <table> [<alias>] WHERE`. The translator also emits sub-SELECTs that
+    list several tables, with commas (`EXISTS (SELECT 1 FROM nodes n2, rdf_labels l3, rdf_edges ex4 WHERE ..)`
+    for `NOT (a)-[:R]->(:Q)` and `EXISTS { MATCH .. }`) or with joins (a pattern comprehension's `FROM rdf_edges
+    epc3 JOIN nodes pct4 ON ..`, a `CALL { }` subquery's body). Those aliases are read out of the sub-SELECT's own
+    `FROM` / `JOIN` text, never guessed from their names: a table listed after a comma, or first, takes its
+    predicate in that sub-SELECT's `WHERE`; a joined table takes it in its `ON`, which keeps a `LEFT JOIN`'s null
+    row. A table whose alias already has a `graph_id` predicate in the fragment is left alone (idempotent).
+    """
+    import re as _re_fl
+
+    tables = {_table(name) for name in _GRAPH_SCOPED_TABLES}
+    # a later FROM is edited before an earlier one: an insertion moves only what follows it
+    for start in reversed([m.end() for m in _re_fl.finditer(r"\bFROM\s+", fragment)]):
+        # segments of the list: [begin, end, is_joined]; a join keyword or comma closes one and opens the next
+        segments = []
+        seg_begin, joined, in_kw = start, False, False
+        depth, stop_tok, stop_at = 0, None, len(fragment)
+        for t in _FROM_LIST_TOKEN.finditer(fragment, start):
+            w = t.group(0)
+            if w == "(":
+                depth += 1
+            elif w == ")":
+                if depth == 0:
+                    stop_tok, stop_at = ")", t.start()
+                    break
+                depth -= 1
+            elif depth:
+                continue
+            elif w == ",":
+                segments.append((seg_begin, t.start(), joined))
+                seg_begin, joined, in_kw = t.end(), False, False
+            elif w in _FROM_LIST_JOIN:
+                if not in_kw:
+                    segments.append((seg_begin, t.start(), joined))
+                    in_kw = True
+                if w == "JOIN":
+                    seg_begin, joined, in_kw = t.end(), True, False
+            elif w in _FROM_LIST_STOP:
+                stop_tok, stop_at = w, t.start()
+                break
+        segments.append((seg_begin, stop_at, joined))
+        if stop_tok == "WHERE":
+            where_end = stop_at + len("WHERE")
+            # the end of that WHERE: the next depth-0 clause keyword or an unmatched `)`
+            clause_end, depth = len(fragment), 0
+            for t in _FROM_LIST_TOKEN.finditer(fragment, where_end):
+                w = t.group(0)
+                if w == "(":
+                    depth += 1
+                elif w == ")":
+                    if depth == 0:
+                        clause_end = t.start()
+                        break
+                    depth -= 1
+                elif not depth and w in _FROM_LIST_STOP - {"WHERE"}:
+                    clause_end = t.start()
+                    break
+        else:
+            where_end = clause_end = stop_at
+        in_where, edits = [], []
+        for seg_begin, seg_end, is_joined in segments:
+            m = _re_fl.match(
+                r"\s*(\w+(?:\.\w+)?)(?:\s+(?:AS\s+)?(?!ON\b)(\w+))?(\s+ON\b)?", fragment[seg_begin:seg_end]
+            )
+            if not m or m.group(1) not in tables or not m.group(2) or f"{m.group(2)}.graph_id" in fragment:
+                continue
+            pred = f"COALESCE({m.group(2)}.graph_id, '') = COALESCE('{safe_graph}', '')"
+            if is_joined and m.group(3):
+                end = seg_begin + len(fragment[seg_begin:seg_end].rstrip())
+                edits.append((end, f" AND {pred}"))
+            else:
+                in_where.append(pred)
+        if in_where:
+            preds = " AND ".join(in_where)
+            if stop_tok == "WHERE":
+                edits.append((where_end, f" {preds} AND ("))
+                edits.append((len(fragment[:clause_end].rstrip()), ")"))
+            else:
+                edits.append((len(fragment[:stop_at].rstrip()), f" WHERE {preds}"))
+        for pos, text in sorted(edits, reverse=True):
+            fragment = fragment[:pos] + text + fragment[pos:]
     return fragment
 
 
@@ -346,12 +441,20 @@ def _apply_graph_scope_to_reads(context, safe_graph: str) -> None:
         return f"COALESCE({prefix}graph_id, '') = COALESCE('{safe_graph}', '')"
 
     tables = [_table(name) for name in _GRAPH_SCOPED_TABLES]
-
     for i, clause in enumerate(context.join_clauses):
-        for tbl in tables:
-            m = _re_gsr.search(rf"JOIN\s+{_re_gsr.escape(tbl)}\s+(\w+)\s+ON\b", clause)
+        # an undirected hop reads `rdf_edges` through a `_ueN` CTE that projects `graph_id`: it is joined by alias
+        for target in [_re_gsr.escape(tbl) for tbl in tables] + [r"_ue\d+"]:
+            # every join of the table, not the first: a nested OPTIONAL MATCH group joins several
+            for m in list(_re_gsr.finditer(rf"JOIN\s+{target}\s+(\w+)\s+ON\b", clause)):
+                if f"{m.group(1)}.graph_id" not in clause:
+                    clause = clause + f" AND {_pred(m.group(1) + '.')}"
+            # the first table of an OPTIONAL MATCH's nested group, `LEFT OUTER JOIN (rdf_edges e3 JOIN nodes n2 ON ..)
+            # ON <outer>`, has no ON of its own: its predicate joins the outer one, where a missing edge leaves the
+            # null row instead of dropping the node
+            m = _re_gsr.match(rf"\s*LEFT\s+OUTER\s+JOIN\s+\(\s*{target}\s+(\w+)\s+JOIN\b", clause)
             if m and f"{m.group(1)}.graph_id" not in clause:
                 clause = clause + f" AND {_pred(m.group(1) + '.')}"
+        for tbl in tables:
             # a node crossed in (`MATCH (a), (b)`) has no ON to carry it: it goes in WHERE, as the first node's does.
             # Unscoped, b matched its id in every graph and the read returned a row per graph holding it.
             m = _re_gsr.fullmatch(rf"CROSS\s+JOIN\s+{_re_gsr.escape(tbl)}\s+(\w+)", clause.strip())
@@ -3148,7 +3251,12 @@ def _to_sql_handle_with(part, context: TranslationContext, i: int, cypher_query=
     # MATCH before a WITH read every graph (`USE GRAPH 'g' MATCH (a:L) WITH a RETURN count(*)` counted other graphs'
     # rows). Idempotent; Stage CTEs are not graph-owned tables, so it touches only this stage's reads.
     if context.graph_context is not None:
-        _apply_graph_scope_to_reads(context, context.graph_context.replace("'", "''"))
+        _sg = context.graph_context.replace("'", "''")
+        _apply_graph_scope_to_reads(context, _sg)
+        # A sort key reads its property in a sub-SELECT built here, after the pass above: unscoped, the sort value
+        # for a node id two graphs share could come from the other graph's row.
+        sort_projections = [(a, _graph_scope_fragment(e, _sg)) for a, e in sort_projections]
+        order_by_items = [_graph_scope_fragment(o, _sg) for o in order_by_items]
     sql, stage_params = context.build_stage_sql(part.with_clause.distinct)
 
     # Inject sort projection columns into the inner SELECT if any complex ORDER BY expressions exist.
@@ -3289,7 +3397,7 @@ def _to_sql_handle_with(part, context: TranslationContext, i: int, cypher_query=
                     f"NOT EXISTS (SELECT 1 FROM {_table('rdf_labels')} WHERE label = ?)"
                 )
                 _ne_params.append(_lbl)
-        _where_clause = " AND ".join(_ne_parts)
+        _where_clause = _scope_null_row(context, " AND ".join(_ne_parts))
         sql = sql + f"\nUNION ALL\nSELECT {_null_sel} WHERE {_where_clause}"
         stage_params = list(stage_params) + _ne_params
         # Clear so the final SELECT doesn't emit a duplicate UNION ALL
@@ -3437,6 +3545,12 @@ def _tts_union_branches(cypher_query, params, engine=None, procedures=None):
             skip=branch.skip,
             limit=branch.limit,
             procedure_call=branch.procedure_call,
+            # A branch is a read of the same graph as the statement: `USE GRAPH` heads the whole query, and
+            # rebuilding the branch without it scoped no table in any branch. A branch that names its own
+            # graph keeps it.
+            graph_context=(
+                branch.graph_context if branch.graph_context is not None else cypher_query.graph_context
+            ),
         )
         branch_copy.union_queries = []
         # `engine=` is load-bearing, not cosmetic: it is what turns a branch's `LIMIT`
@@ -4237,32 +4351,12 @@ def _tts_finalize_context(cypher_query, context):
         # `variable_aliases`, so before this call `USE GRAPH` scoped nothing at
         # all in `MATCH (a)-[:R]->(b)`.
         _apply_graph_scope_to_reads(context, safe_graph)
-        # A CTE this statement defines is not a graph-owned table. `ivg.retrieve`
-        # fuses its arms into a `Retrieve` stage that projects a node ID and a score
-        # and no `graph_id` — the arms inside it are scoped already — so naming it
-        # out here made IRIS refuse the statement at Prepare with SQLCODE -29 Field
-        # 'RETRIEVE.GRAPH_ID' not found, which the driver's error path turns into
-        # zero rows: a scoped retrieval that reads as an empty graph.
-        stage_names = _defined_stage_names(context)
-        edge_aliases = [
-            v
-            for v in context.variable_aliases.values()
-            if v and v.startswith("e") and not v.startswith("ES_") and v not in stage_names
-        ]
-        for ea in edge_aliases:
-            context.where_conditions.append(f"{ea}.graph_id = '{safe_graph}'")
-        context.where_conditions.append(f"1=1")
-        graph_filter = f"'{safe_graph}'"
-        for ea in list(context.variable_aliases.values()):
-            if (
-                ea
-                and not ea.startswith("n")
-                and not ea.startswith("l")
-                and not ea.startswith("Stage")
-                and ea not in stage_names
-            ):
-                context.where_conditions.append(f"{ea}.graph_id = {graph_filter}")
-                break
+        # No alias is named here. The graph-owned tables are read out of the statement's own FROM / JOIN text by
+        # the pass above, so a derived relation (an UNWIND subquery `u2`, a CALL { } `scalar`, a `Retrieve` or
+        # `Stage` CTE, none of which has a `graph_id` column) is never given a predicate (SQLCODE -29 at Prepare,
+        # which the driver turns into zero rows), and a LEFT-joined relationship keeps its predicate in its ON
+        # clause, where the null row survives.
+        context.where_conditions.append("1=1")
     elif not getattr(cypher_query, "is_mutation", False) and _all_graphs_correlated(context):
         # reads only: a write's MATCH keeps today's matching until its own decision (spec 253 Phase 0 is reads)
         _correlate_graphs_in_reads(context)
@@ -4270,6 +4364,16 @@ def _tts_finalize_context(cypher_query, context):
     return order_by_items
 
 
+def _scope_null_row(context, condition: str) -> str:
+    """The null-row fallback of an OPTIONAL MATCH tests `NOT EXISTS (SELECT 1 FROM rdf_labels WHERE label = ?)`, and
+    is appended after the scope pass: unscoped, a label held only by another graph suppressed the null row, so
+    `USE GRAPH 'g' OPTIONAL MATCH (a:L) RETURN a` answered no row where g holds no `L`."""
+    graph = getattr(context, "graph_context", None)
+    if graph is None:
+        return condition
+    return _graph_scope_fragment(condition, graph.replace("'", "''"))
+
+
 def _build_null_row_not_exists(labels):
     """Build NOT EXISTS SQL for an anchor node's full label set.
 
@@ -4452,7 +4556,7 @@ def _tts_transactional_result(cypher_query, context, metadata, order_by_items):
                     f"NOT EXISTS (SELECT 1 FROM {_table('rdf_labels')} WHERE label = ?)"
                 )
                 optional_extra_params.append(label)
-        where_clause = " AND ".join(not_exists_parts)
+        where_clause = _scope_null_row(context, " AND ".join(not_exists_parts))
         optional_union_sql = f"\nUNION ALL\nSELECT {null_select} WHERE {where_clause}"
     elif sql is not None:
         optional_union_sql, _ou_params = _unlabelled_optional_null_union(
@@ -4739,7 +4843,7 @@ def _tts_select_result(cypher_query, context, metadata, order_by_items):
                     f"NOT EXISTS (SELECT 1 FROM {_table('rdf_labels')} WHERE label = ?)"
                 )
                 optional_extra_params.append(label)
-        where_clause = " AND ".join(not_exists_parts)
+        where_clause = _scope_null_row(context, " AND ".join(not_exists_parts))
         optional_union_sql = f"\nUNION ALL\nSELECT {null_select} WHERE {where_clause}"
     else:
         optional_union_sql, _ou_params = _unlabelled_optional_null_union(
@@ -12250,8 +12354,28 @@ def _value_key_predicate(col_sql, value_expr, context) -> str:
         return ""
     if not isinstance(value, str):
         return ""
-    prefix = value[:_VALUE_KEY_LEN].replace("'", "''")
-    return f" AND {m.group(1)}.val_key = '{prefix}'"
+    prefix = _value_key_prefix(value)
+    if prefix is None:
+        return ""
+    escaped = prefix.replace("'", "''")
+    return f" AND {m.group(1)}.val_key = '{escaped}'"
+
+
+def _value_key_prefix(value: str) -> Optional[str]:
+    """What ``$EXTRACT(val, 1, 128)`` stores for ``value``, or None when it cannot be written as a SQL literal.
+
+    IRIS counts UTF-16 code units, Python counts code points: a character outside the BMP (an emoji) is two units, so
+    ``value[:128]`` is longer than the stored key for any value with one in front and the equality matches no row. A cut
+    that falls between the two halves of a pair stores a lone surrogate, which no literal can carry: no predicate then
+    (the exact ``val`` comparison alone is still right, only unindexed).
+    """
+    units = value.encode("utf-16-le", "surrogatepass")
+    if len(units) <= _VALUE_KEY_LEN * 2:
+        return value
+    try:
+        return units[: _VALUE_KEY_LEN * 2].decode("utf-16-le")
+    except UnicodeDecodeError:
+        return None
 
 
 def _prop_eq_sql(col_sql: str, v, val_sql: str, context) -> str: