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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: iris-vector-graph
-Version: 4.4.0
+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.0 → 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.0 → iris_vector_graph-4.4.2}/iris_src/src/Graph/KG/ArnoAccel.cls

@@ -54,11 +54,34 @@ ClassMethod CallFn(fn As %String, a1 As %String = "", a2 As %String = "", a3 As
 	If dllid = 0 $$$ThrowStatus($$$ERROR($$$GeneralError,"arno not loaded"))
 	Set fid = $Get(^ArnoAccel("fid", fn), 0)
 	If fid = 0 $$$ThrowStatus($$$ERROR($$$GeneralError,"arno function not found: "_fn))
-	If a1 = "" Return $ZF(-5, dllid, fid)
-	If a2 = "" Return $ZF(-5, dllid, fid, a1)
-	If a3 = "" Return $ZF(-5, dllid, fid, a1, a2)
-	If a4 = "" Return $ZF(-5, dllid, fid, a1, a2, a3)
-	Return $ZF(-5, dllid, fid, a1, a2, a3, a4)
+	// the library's readers leave the process in USER: put the caller's namespace back, or every later step on this
+	// connection runs against USER (4.4.0 E2E gate; spec 236 R3 did the same for Load and Build2HopExactStats)
+	Set tNs = $NAMESPACE
+	Try {
+		If a1 = "" {
+			Set tOut = $ZF(-5, dllid, fid)
+		} ElseIf a2 = "" {
+			Set tOut = $ZF(-5, dllid, fid, a1)
+		} ElseIf a3 = "" {
+			Set tOut = $ZF(-5, dllid, fid, a1, a2)
+		} ElseIf a4 = "" {
+			Set tOut = $ZF(-5, dllid, fid, a1, a2, a3)
+		} Else {
+			Set tOut = $ZF(-5, dllid, fid, a1, a2, a3, a4)
+		}
+	} Catch tEx {
+		Set $NAMESPACE = tNs
+		Throw tEx
+	}
+	Set $NAMESPACE = tNs
+	Quit tOut
+}
+
+/// The library's kg_khop_sample, kg_random_walk and kg_neighbor_agg read USER's graph whatever namespace calls them;
+/// elsewhere the answer would be USER's, so they are refused there.
+ClassMethod ReadsUser() As %Boolean [ Private ]
+{
+	Quit $NAMESPACE = "USER"
 }
 
 /// Reader revisions of the loaded callout build, as a JSON object {"<reader>": <int>}.
@@ -251,6 +274,7 @@ ClassMethod SubgraphJson(seedJson As %String, hops As %Integer = 2, edgeTypesJso
 /// Returns JSON: {"layers": [[{src,dst},...], ...], "seeds": [...]}
 ClassMethod KhopSampleJson(seedJson As %String, hops As %Integer = 2, fanout As %Integer = 16) As %String
 {
+	Quit:'..ReadsUser() "{""layers"":[], ""error"": ""arno reads USER only, not "_$NAMESPACE_"""}"
 	Try {
 		Do ..CacheGraphJson("KG")
 		Set result = ..CallFn("kg_khop_sample", "KG", seedJson, hops, fanout)
@@ -263,6 +287,7 @@ ClassMethod KhopSampleJson(seedJson As %String, hops As %Integer = 2, fanout As
 /// Random walk (DeepWalk/node2vec-style). Returns JSON array of walk sequences.
 ClassMethod RandomWalkJson(seedJson As %String, walkLength As %Integer = 20, numWalks As %Integer = 10) As %String
 {
+	Quit:'..ReadsUser() "[]"
 	Try {
 		Do ..CacheGraphJson("KG")
 		Set result = ..CallFn("kg_random_walk", "KG", seedJson, walkLength, numWalks)
@@ -275,6 +300,7 @@ ClassMethod RandomWalkJson(seedJson As %String, walkLength As %Integer = 20, num
 /// GraphSAGE-style mean neighbor aggregation. Returns JSON: {node: {agg_feat, degree}, ...}
 ClassMethod NeighborAggJson(seedJson As %String, hops As %Integer = 2) As %String
 {
+	Quit:'..ReadsUser() "{}"
 	Try {
 		Do ..CacheGraphJson("KG")
 		Set result = ..CallFn("kg_neighbor_agg", "KG", seedJson, hops)

{iris_vector_graph-4.4.0 → 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.0 → iris_vector_graph-4.4.2}/iris_src/src/Graph/KG/NKGAccelTraversal.cls

@@ -644,6 +644,9 @@ ClassMethod StructuralGuard(nodeIdx As %Integer, requiredPreds As %List) As %Boo
 
 ClassMethod Build2HopExact() As %Boolean
 {
+    // the library's kg_build_2hop_exact_stream reads USER's ^NKG and leaves the process in USER, so the sketch below
+    // would be written into USER's ^KG: refused elsewhere (4.4.0 E2E gate; the merged sketch is a USER-only store)
+    Quit:$NAMESPACE'="USER" 0
     If '##class(Graph.KG.NKGAccelLoader).IsLoaded() {
         Do ##class(Graph.KG.NKGAccelLoader).Load("/tmp/libarno_callout.so")
         If '##class(Graph.KG.NKGAccelLoader).IsLoaded() {

{iris_vector_graph-4.4.0 → 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.0 → 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