iris-vector-graph 3.0.1__tar.gz → 3.1.0__tar.gz

{iris_vector_graph-3.0.1 → iris_vector_graph-3.1.0}/.gitignore

@@ -35,6 +35,11 @@ Thumbs.db
 *.tar
 *.rar
 
+# ...except the snapshot archives old releases wrote. These are test fixtures: an
+# upgrade test needs an artifact a previous version actually produced, and that
+# cannot be regenerated once the release is in the past.
+!tests/fixtures/snapshots/*.zip
+
 # Data directories (large test datasets)
 data/
 
@@ -52,6 +57,8 @@ data/
 
 # Test coverage
 coverage/
+coverage*.json
+*,cover
 .nyc_output
 
 # Python cache

{iris_vector_graph-3.0.1 → iris_vector_graph-3.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: iris-vector-graph
-Version: 3.0.1
+Version: 3.1.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
@@ -209,7 +209,7 @@ and [docs/performance/GRAPH_ALGORITHMS.md](docs/performance/GRAPH_ALGORITHMS.md)
 
 ```text
 ┌─────────────────────────────────────────────────────────────────────┐
-│                    iris-vector-graph  v2.18.5                       │
+│                          iris-vector-graph                          │
 ├─────────────────────────────────────────────────────────────────────┤
 │                                                                     │
 │   ┌───────────────┐   ┌───────────────┐   ┌───────────────────┐    │
@@ -308,8 +308,15 @@ engine.execute_cypher("USE GRAPH umls CREATE (n:Concept {id: 'C0001234'})")
 # Import an NDJSON file into a named graph
 engine.import_graph_ndjson("export.ndjson", graph="staging")
 
-# Drop everything scoped to a named graph (nodes, edges, labels, props)
-engine.drop_graph("staging")
+# Erase one graph's content from every store: SQL rows, ^KG adjacency,
+# degree counters, all five temporal trees. drop_graph() is a deprecated alias.
+engine.erase_graph("staging")
+
+# Erase every graph, including the stores no per-graph erase can reach
+engine.erase_all()
+
+# Independent per-graph, bidirectional drift check between SQL and ^KG
+engine.verify_graph("umls")["ok"]
 
 # delete_edge defaults to the default graph; pass all_graphs=True to sweep all
 engine.delete_edge("C0027051", "ISA", "C0085580", graph="umls")
@@ -380,27 +387,63 @@ different namespace, pass `namespace=` at engine construction:
 from iris_vector_graph import IRISGraphEngine
 import iris.dbapi as dbapi
 
-conn = dbapi.connect(hostname="...", port=1972, namespace="HSCUSTOM", ...)
-engine = IRISGraphEngine(conn, namespace="HSCUSTOM")
+conn = dbapi.connect(hostname="...", port=1972, namespace="MYGRAPH", ...)
+engine = IRISGraphEngine(conn, namespace="MYGRAPH")
 ```
 
+`MYGRAPH` is a placeholder — use a namespace you own and have deployed IVG
+into. A namespace an installed product manages (a HealthShare/Ensemble
+platform or customization namespace) is the wrong home for IVG's schema: that
+product's own upgrade process owns the class and table set there.
+
 On first use, the engine probes `$Data(^KG("deg"))` to verify the `^KG`
 globals are accessible. If they are absent a `WARNING` is logged naming the
 namespace and the fix. Set `IVG_STRICT_NAMESPACE=1` to upgrade the warning
 to a raised `NamespaceMismatchWarning`.
 
+### A namespace is an IVG namespace only once the classes are deployed
+
+`Graph.KG.*` ObjectScript is what gives a namespace IVG's behaviour. A
+namespace whose schema was built by DDL alone — plain `CREATE TABLE`, or
+`initialize_schema(auto_deploy_objectscript=False)` — is a shell that looks
+right and behaves differently:
+
+| Property                                                               | Classes deployed                            | DDL only       |
+| ---------------------------------------------------------------------- | ------------------------------------------- | -------------- |
+| `rdf_edges.graph_id`                                                   | required, defaults to the default-graph key | nullable       |
+| `rdf_edges` primary key                                                | `ID`                                        | `edge_id`      |
+| `Graph.KG.Edge` / `Eraser` / `TemporalIndex`                           | present                                     | absent         |
+| Schema migrations (`tighten_graph_id_column`, `add_graph_id_to_nodes`) | applied                                     | never reach it |
+| Traversal, temporal and erasure acceleration                           | native ObjectScript                         | none           |
+
+Check a namespace before trusting it:
+
+```sql
+SELECT COUNT(*) FROM %Dictionary.ClassDefinition WHERE Name = 'Graph.KG.Edge'
+```
+
+Zero means DDL-only. Deploy the classes into that namespace — `initialize_schema()`
+with auto-deploy, or `$SYSTEM.OBJ.LoadDir("<path>/iris_src/src", "ck", .err, 1)`
+from a session in that namespace — before writing data.
+
+Also note IRIS auto-generates a compatibility view `SQLUser.rdf_edges` over
+`Graph_KG.rdf_edges`. When you query the catalog, filter
+`TABLE_SCHEMA = 'Graph_KG'`; the view carries no column defaults, so reading
+the wrong row makes a required `graph_id` look nullable.
+
 ### CPF global mapping
 
 If your graph data lives in a separate database, map the `^KG` global in the
 IRIS CPF file so the probe passes without copying data:
 
 ```ini
-[Map.HSCUSTOM]
+[Map.MYGRAPH]
 Global=^KG,Directory=/db/IRISLOCALDATA/
 ```
 
-After mapping, `$Data(^KG("deg"))` returns non-zero in `HSCUSTOM` and no
-warning is emitted.
+After mapping, `$Data(^KG("deg"))` returns non-zero in that namespace and no
+warning is emitted. Global mapping brings the data, not the behaviour — the
+classes still have to be deployed into the namespace.
 
 ### Env var controls
 

{iris_vector_graph-3.0.1 → iris_vector_graph-3.1.0}/README.md

@@ -109,7 +109,7 @@ and [docs/performance/GRAPH_ALGORITHMS.md](docs/performance/GRAPH_ALGORITHMS.md)
 
 ```text
 ┌─────────────────────────────────────────────────────────────────────┐
-│                    iris-vector-graph  v2.18.5                       │
+│                          iris-vector-graph                          │
 ├─────────────────────────────────────────────────────────────────────┤
 │                                                                     │
 │   ┌───────────────┐   ┌───────────────┐   ┌───────────────────┐    │
@@ -208,8 +208,15 @@ engine.execute_cypher("USE GRAPH umls CREATE (n:Concept {id: 'C0001234'})")
 # Import an NDJSON file into a named graph
 engine.import_graph_ndjson("export.ndjson", graph="staging")
 
-# Drop everything scoped to a named graph (nodes, edges, labels, props)
-engine.drop_graph("staging")
+# Erase one graph's content from every store: SQL rows, ^KG adjacency,
+# degree counters, all five temporal trees. drop_graph() is a deprecated alias.
+engine.erase_graph("staging")
+
+# Erase every graph, including the stores no per-graph erase can reach
+engine.erase_all()
+
+# Independent per-graph, bidirectional drift check between SQL and ^KG
+engine.verify_graph("umls")["ok"]
 
 # delete_edge defaults to the default graph; pass all_graphs=True to sweep all
 engine.delete_edge("C0027051", "ISA", "C0085580", graph="umls")
@@ -280,27 +287,63 @@ different namespace, pass `namespace=` at engine construction:
 from iris_vector_graph import IRISGraphEngine
 import iris.dbapi as dbapi
 
-conn = dbapi.connect(hostname="...", port=1972, namespace="HSCUSTOM", ...)
-engine = IRISGraphEngine(conn, namespace="HSCUSTOM")
+conn = dbapi.connect(hostname="...", port=1972, namespace="MYGRAPH", ...)
+engine = IRISGraphEngine(conn, namespace="MYGRAPH")
 ```
 
+`MYGRAPH` is a placeholder — use a namespace you own and have deployed IVG
+into. A namespace an installed product manages (a HealthShare/Ensemble
+platform or customization namespace) is the wrong home for IVG's schema: that
+product's own upgrade process owns the class and table set there.
+
 On first use, the engine probes `$Data(^KG("deg"))` to verify the `^KG`
 globals are accessible. If they are absent a `WARNING` is logged naming the
 namespace and the fix. Set `IVG_STRICT_NAMESPACE=1` to upgrade the warning
 to a raised `NamespaceMismatchWarning`.
 
+### A namespace is an IVG namespace only once the classes are deployed
+
+`Graph.KG.*` ObjectScript is what gives a namespace IVG's behaviour. A
+namespace whose schema was built by DDL alone — plain `CREATE TABLE`, or
+`initialize_schema(auto_deploy_objectscript=False)` — is a shell that looks
+right and behaves differently:
+
+| Property                                                               | Classes deployed                            | DDL only       |
+| ---------------------------------------------------------------------- | ------------------------------------------- | -------------- |
+| `rdf_edges.graph_id`                                                   | required, defaults to the default-graph key | nullable       |
+| `rdf_edges` primary key                                                | `ID`                                        | `edge_id`      |
+| `Graph.KG.Edge` / `Eraser` / `TemporalIndex`                           | present                                     | absent         |
+| Schema migrations (`tighten_graph_id_column`, `add_graph_id_to_nodes`) | applied                                     | never reach it |
+| Traversal, temporal and erasure acceleration                           | native ObjectScript                         | none           |
+
+Check a namespace before trusting it:
+
+```sql
+SELECT COUNT(*) FROM %Dictionary.ClassDefinition WHERE Name = 'Graph.KG.Edge'
+```
+
+Zero means DDL-only. Deploy the classes into that namespace — `initialize_schema()`
+with auto-deploy, or `$SYSTEM.OBJ.LoadDir("<path>/iris_src/src", "ck", .err, 1)`
+from a session in that namespace — before writing data.
+
+Also note IRIS auto-generates a compatibility view `SQLUser.rdf_edges` over
+`Graph_KG.rdf_edges`. When you query the catalog, filter
+`TABLE_SCHEMA = 'Graph_KG'`; the view carries no column defaults, so reading
+the wrong row makes a required `graph_id` look nullable.
+
 ### CPF global mapping
 
 If your graph data lives in a separate database, map the `^KG` global in the
 IRIS CPF file so the probe passes without copying data:
 
 ```ini
-[Map.HSCUSTOM]
+[Map.MYGRAPH]
 Global=^KG,Directory=/db/IRISLOCALDATA/
 ```
 
-After mapping, `$Data(^KG("deg"))` returns non-zero in `HSCUSTOM` and no
-warning is emitted.
+After mapping, `$Data(^KG("deg"))` returns non-zero in that namespace and no
+warning is emitted. Global mapping brings the data, not the behaviour — the
+classes still have to be deployed into the namespace.
 
 ### Env var controls
 

{iris_vector_graph-3.0.1 → iris_vector_graph-3.1.0}/iris_src/src/Graph/KG/Edge.cls

@@ -1,9 +1,10 @@
-/// Graph.KG.Edge - RDF-style edge storage with functional graph index
-/// 
-/// Uses Graph.KG.GraphIndex to maintain ^KG adjacency list global:
-///   ^KG("out", s, p, o) = rowID
-///   ^KG("in", o, p, s) = rowID  
-///   ^KG("deg", node) = count
+/// Graph.KG.Edge - RDF-style edge storage
+///
+/// Adjacency (^KG("out"/"in"/"deg"/"degp")) is NOT maintained by this class.
+/// It is written by Graph.KG.EdgeScan:WriteAdjacency, which is graph-scoped.
+/// This class carried a functional index (Graph.KG.GraphIndex) that wrote
+/// ^KG("out", 0, ...) for every graph and ^KG("deg", s) with no graph key,
+/// silently routing named-graph edges into the default graph. See ADR-0001.
 ///
 /// IMPORTANT: Class must be Final to avoid %%CLASSNAME implicit clustering
 Class Graph.KG.Edge Extends %Persistent [ Final, DdlAllowed, SqlTableName = rdf_edges ]
@@ -24,9 +25,6 @@ Property qualifiers As %String(MAXLEN = "") [ SqlColumnNumber = 5 ];
 /// Named graph identifier for USE GRAPH filtering
 Property graphId As %String(COLLATION = "EXACT", MAXLEN = 500) [ SqlColumnNumber = 6, SqlFieldName = graph_id ];
 
-/// Functional index that populates ^KG graph global
-Index GraphIdx On (s, p, oId, qualifiers) As Graph.KG.GraphIndex;
-
 /// UNIQUE constraint on (s, p, o_id) to prevent duplicate edges
 Index uspo On (s, p, oId) [ Unique ];
 

iris_vector_graph-3.1.0/iris_src/src/Graph/KG/EdgeScan.cls

@@ -0,0 +1,386 @@
+/// Graph.KG.EdgeScan — adjacency-global maintenance + scan procedures.
+///
+/// ============================================================================
+/// ^KG ADJACENCY LAYOUT OF RECORD (spec 214 — named-graph aware)
+/// ============================================================================
+///
+///     ^KG("out", graph, s, p, o) = weight
+///     ^KG("in",  graph, o, p, s) = weight
+///     ^KG("deg", graph, s)           = out-degree
+///     ^KG("degp", graph, s, p)       = per-predicate out-degree
+///
+/// graph is the derived index key, not the graph name: integer 0 for the default
+/// graph, the name itself otherwise. Derive it with Graph.KG.GraphKey.ForIndex()
+/// (ADR-0001, ADR-0003). The earlier note here said "" was the default sentinel;
+/// it is not, and never was in this global — WriteAdjacency has always defaulted
+/// the parameter to 0.
+///
+/// Merged-view traversal iterates the full ^KG("out") tree (all graph subscripts).
+/// Graph-filtered traversal uses a fixed graph subscript. KNOWN AMBIGUITY:
+/// MatchEdges reads 0 as "every graph", while WriteAdjacency and DeleteAdjacency
+/// read 0 as "the default graph". MatchEdges therefore cannot ask for the default
+/// graph alone and answers across graphs when asked for it.
+///
+/// ^NKG is per-identifier (no graph dimension); InternNode unchanged.
+/// ============================================================================
+Class Graph.KG.EdgeScan Extends %RegisteredObject
+{
+
+/// Scan adjacency globals. graph="" returns merged view across all graphs.
+ClassMethod MatchEdges(sourceId As %String, predicate As %String, shard As %Integer = 0, graph = 0) As %String [ SqlProc, SqlName = MatchEdges ]
+{
+	Set results = ##class(%DynamicArray).%New()
+	Set sourceId = $Get(sourceId, "")
+	Set predicate = $Get(predicate, "")
+
+	// Build the list of graph subscripts to iterate
+	Kill tGraphs
+	// graph=0 means merged view (all graphs); non-0 = specific named graph
+	If (graph '= 0) && (graph '= "") {
+		Set tGraphs(graph) = ""
+	} Else {
+		Set g = ""
+		For {
+			Set g = $Order(^KG("out", g))
+			Quit:g=""
+			Set tGraphs(g) = ""
+		}
+	}
+
+	Set g = ""
+	For {
+		Set g = $Order(tGraphs(g))
+		Quit:g=""
+		If sourceId '= "" {
+			If $Length(predicate) > 0 {
+				Set o = ""
+				For {
+					Set o = $Order(^KG("out", g, sourceId, predicate, o))
+					Quit:o=""
+					Set w = $Get(^KG("out", g, sourceId, predicate, o), 1.0)
+					Set entry = ##class(%DynamicObject).%New()
+					Do entry.%Set("s", sourceId) Do entry.%Set("p", predicate) Do entry.%Set("o", o) Do entry.%Set("w", +w)
+					Do results.%Push(entry)
+				}
+			} Else {
+				Set p = ""
+				For {
+					Set p = $Order(^KG("out", g, sourceId, p))
+					Quit:p=""
+					Set o = ""
+					For {
+						Set o = $Order(^KG("out", g, sourceId, p, o))
+						Quit:o=""
+						Set w = $Get(^KG("out", g, sourceId, p, o), 1.0)
+						Set entry = ##class(%DynamicObject).%New()
+						Do entry.%Set("s", sourceId) Do entry.%Set("p", p) Do entry.%Set("o", o) Do entry.%Set("w", +w)
+						Do results.%Push(entry)
+					}
+				}
+			}
+		} Else {
+			Set s = ""
+			For {
+				Set s = $Order(^KG("out", g, s))
+				Quit:s=""
+				Set p = ""
+				For {
+					Set p = $Order(^KG("out", g, s, p))
+					Quit:p=""
+					If ($Length(predicate) > 0) && (p '= predicate) Continue
+					Set o = ""
+					For {
+						Set o = $Order(^KG("out", g, s, p, o))
+						Quit:o=""
+						Set w = $Get(^KG("out", g, s, p, o), 1.0)
+						Set entry = ##class(%DynamicObject).%New()
+						Do entry.%Set("s", s) Do entry.%Set("p", p) Do entry.%Set("o", o) Do entry.%Set("w", +w)
+						Do results.%Push(entry)
+					}
+				}
+			}
+		}
+	}
+
+	Return results.%ToJSON()
+}
+
+/// Write adjacency entries for one edge. graph="" = default graph (spec 214).
+ClassMethod WriteAdjacency(s As %String, p As %String, o As %String, w As %String = "1.0", graph = 0)
+{
+	Set ^KG("out", graph, s, p, o) = +w
+	Set ^KG("in", graph, o, p, s) = +w
+	Set tmp = $Increment(^KG("deg", graph, s))
+	Set tmp = $Increment(^KG("degp", graph, s, p))
+	// ^NKG is per-identifier (no graph dimension); unchanged by spec 214
+	If $Data(^NKG("$meta", "nodeCount")) {
+		Set sIdx = ##class(Graph.KG.GraphIndex).InternNode(s)
+		Set oIdx = ##class(Graph.KG.GraphIndex).InternNode(o)
+		Set pIdx = ##class(Graph.KG.GraphIndex).InternLabel(p)
+		If '$Data(^NKG(-1, sIdx, -(pIdx+1), oIdx)) {
+			Set ^NKG(-1, sIdx, -(pIdx+1), oIdx) = +w
+			Set ^NKG(-2, oIdx, -(pIdx+1), sIdx) = +w
+			Set tmp = $Increment(^NKG(-3, sIdx))
+			Set tmp = $Increment(^NKG("$meta", "edgeCount"))
+		}
+		Set tmp = $Increment(^NKG("$meta", "version"))
+		Do ##class(Graph.KG.GraphIndex).UpdateStructuralHLL(sIdx, pIdx, oIdx)
+	}
+}
+
+/// Write the four structural adjacency stores for one edge, without interning.
+///
+/// WriteAdjacency's twin, for callers whose edges must be visible to the ^KG
+/// readers but are deliberately absent from ^NKG: a temporal edge keeps a
+/// structural shadow so MatchEdges and the centrality readers see it, and is
+/// interned only by a BuildNKG. That is the ADJACENCY CONTRACT documented on
+/// create_edge_temporal, and calling WriteAdjacency instead would quietly break
+/// it by interning on every temporal insert.
+///
+/// Idempotent in the counters, which WriteAdjacency is not, because several
+/// temporal edges at different timestamps are one structural edge and ^KG("deg")
+/// counts structural edges. TemporalIndex used to write ^KG("out") once and
+/// increment ^KG("deg") once per timestamp — so the degree over-counted — and
+/// never wrote ^KG("degp") at all. That also left DeleteAdjacency unusable as the
+/// inverse, since it decrements each counter exactly once.
+ClassMethod WriteAdjacencyShadow(s As %String, p As %String, o As %String, w As %String = "1.0", graph = 0)
+{
+	// Same structural edge at a new timestamp: refresh the weight, leave the
+	// counters alone. Killing and rewriting would be the same thing more slowly.
+	Set tExists = $Data(^KG("out", graph, s, p, o))
+	Set ^KG("out", graph, s, p, o) = +w
+	Set ^KG("in", graph, o, p, s) = +w
+	If 'tExists {
+		Set tmp = $Increment(^KG("deg", graph, s))
+		Set tmp = $Increment(^KG("degp", graph, s, p))
+	}
+}
+
+/// Delete adjacency entries for one edge, including its counters.
+///
+/// graph is an already-derived index key, as WriteAdjacency takes: integer 0 for
+/// the default graph, the graph name otherwise. Derive it with
+/// Graph.KG.GraphKey.ForIndex() before calling — ForIndex() rejects "0", so it
+/// cannot be applied to a key that has already been derived (ADR-0003).
+///
+/// This owns all four stores WriteAdjacency writes. It used to remove only
+/// ^KG("out") and ^KG("in") and delegate the counters to
+/// Graph.KG.GraphIndex:DeleteIndex, which hardcoded the graph key to 0 and
+/// spelled the counters ^KG("deg", s) — one subscript short, so the node id
+/// landed in the graph-key position. The real counter was never decremented, a
+/// bogus entry appeared beside every real graph, and the hardcoded 0 reached into
+/// the default graph and deleted its entry for the same triple. Splitting one
+/// global across two modules is what allowed the two to disagree.
+ClassMethod DeleteAdjacency(s As %String, p As %String, o As %String, graph = 0)
+{
+	// Only decrement when the entry was really there. A blind decrement makes a
+	// repeated delete drive the counter negative, which reads as fresh drift.
+	If $Data(^KG("out", graph, s, p, o)) {
+		Kill ^KG("out", graph, s, p, o)
+		Set tDeg = $Increment(^KG("deg", graph, s), -1)
+		Set tDegP = $Increment(^KG("degp", graph, s, p), -1)
+		// A zero counter is not neutral: it still claims the node is in the graph.
+		If tDeg <= 0 {
+			Kill ^KG("deg", graph, s)
+		}
+		If tDegP <= 0 {
+			Kill ^KG("degp", graph, s, p)
+		}
+	}
+	Kill ^KG("in", graph, o, p, s)
+	If $Data(^NKG("$meta", "nodeCount")) {
+		Do ##class(Graph.KG.GraphIndex).DeleteIndex("", s, p, o, "")
+	}
+}
+
+/// Remove one edge's adjacency from every graph it appears in.
+///
+/// "Every graph" is not a key value, so DeleteAdjacency cannot express it by
+/// being handed one — it would have to be called once per graph, and the caller
+/// would need the list. The walk therefore lives beside the delete it drives
+/// rather than in Python, on the far side of the seam from ^KG.
+///
+/// Collect first, delete after: DeleteAdjacency mutates the tree being walked.
+ClassMethod DeleteAdjacencyAllGraphs(s As %String, p As %String, o As %String)
+{
+	Kill tGraphs
+	Set g = ""
+	For {
+		Set g = $Order(^KG("out", g))
+		Quit:g=""
+		If $Data(^KG("out", g, s, p, o)) {
+			Set tGraphs(g) = ""
+		}
+	}
+	// ^KG("in") is checked separately: a half-written edge may have only the
+	// mirror, and leaving it behind is the drift this method exists to remove.
+	Set g = ""
+	For {
+		Set g = $Order(^KG("in", g))
+		Quit:g=""
+		If $Data(^KG("in", g, o, p, s)) {
+			Set tGraphs(g) = ""
+		}
+	}
+	Set g = ""
+	For {
+		Set g = $Order(tGraphs(g))
+		Quit:g=""
+		Do ..DeleteAdjacency(s, p, o, g)
+	}
+}
+
+/// Bulk ingest edges via SQL INSERT + persistent ^KG global writes.
+///
+/// graph_id is named explicitly and written as '', the same spelling create_edge
+/// uses. Omitting the column left NULL, giving the default graph two spellings in
+/// one table: every reader matching one of them silently missed the other half.
+/// This writes the default graph only, which is what the hardcoded
+/// WriteAdjacency graph key below has always meant.
+ClassMethod BulkIngestEdgesSQL(edgesJson As %String, predicate As %String = "KNOWS") As %Integer
+{
+	Set data = {}.%FromJSON(edgesJson)
+	Set n = 0
+	TSTART
+	Set iter = data.%GetIterator()
+	While iter.%GetNext(.idx, .edge) {
+		Set s = edge.s
+		Set p = $Select(edge.p'="":edge.p, 1:predicate)
+		Set o = edge.o
+		If (s = "") || (o = "") { Continue }
+		If s = o { Continue }
+		&sql(INSERT INTO Graph_KG.rdf_edges (s, p, o_id, graph_id) VALUES (:s, :p, :o, ''))
+		If (SQLCODE '= 0) && (SQLCODE '= -119) { Continue }
+		Do ..WriteAdjacency(s, p, o, "1.0", 0)
+		Set n = n + 1
+	}
+	TCOMMIT
+	Quit n
+}
+
+ClassMethod BulkIngestEdgesFile(filePath As %String, predicate As %String = "KNOWS") As %Integer
+{
+	Set stream = ##class(%Stream.FileCharacter).%New()
+	Do stream.LinkToFile(filePath)
+	Set json = ""
+	While 'stream.AtEnd {
+		Set json = json _ stream.Read(32000)
+	}
+	Quit ..BulkIngestEdgesSQL(json, predicate)
+}
+
+ClassMethod BulkIngestNodesSQL(nodesJson As %String) As %Integer
+{
+	Set data = {}.%FromJSON(nodesJson)
+	Set n = 0
+	TSTART
+	Set iter = data.%GetIterator()
+	While iter.%GetNext(.idx, .node) {
+		Set id = node.id
+		If id = "" { Continue }
+		&sql(INSERT INTO Graph_KG.nodes (node_id, graph_id) VALUES (:id, ''))
+		If (SQLCODE '= 0) && (SQLCODE '= -119) { Continue }
+		If $IsObject(node.labels) {
+			Set liter = node.labels.%GetIterator()
+			While liter.%GetNext(.li, .label) {
+				If label = "" { Continue }
+				&sql(INSERT INTO Graph_KG.rdf_labels (s, label) VALUES (:id, :label))
+			}
+		}
+		If $IsObject(node.props) {
+			Set piter = node.props.%GetIterator()
+			While piter.%GetNext(.key, .val) {
+				If key = "" { Continue }
+				Try {
+					Set valStr = $Select($IsObject(val):val.%ToJSON(), $IsValidNum(val):val, 1:""""_$Replace($ZConvert(val,"O","UTF8"),"""","""""")_"""")
+					&sql(INSERT INTO Graph_KG.rdf_props (s, "key", val) VALUES (:id, :key, :valStr))
+				} Catch ex { }
+			}
+		}
+		Set n = n + 1
+	}
+	TCOMMIT
+	Quit n
+}
+
+/// Remove all ^KG adjacency for each node in a JSON array, in every graph.
+///
+/// Delegates every edge to DeleteAdjacency instead of killing subtrees, because
+/// removing a node touches both ends of each of its edges:
+///
+///   its outbound edges leave a mirror ^KG("in") entry at each target, and
+///   its inbound edges leave every source over-counting its own out-degree.
+///
+/// Killing ^KG("out", g, node) and ^KG("in", g, node) directly reached neither.
+/// It also left ^KG("degp") behind entirely. Iterating and delegating keeps the
+/// per-edge invariant in one place rather than restating it here, where it drifted.
+ClassMethod BulkDeleteAdjacency(nodeIdsJSON As %String) As %Integer
+{
+	Set arr = ##class(%DynamicArray).%FromJSON(nodeIdsJSON)
+	Set count = 0
+	Set iter = arr.%GetIterator()
+	While iter.%GetNext(.idx, .nodeId) {
+		If nodeId = "" { Continue }
+		// Collect first, delete after: DeleteAdjacency mutates the tree being walked.
+		// Both directions are collected as (graph, source, predicate, target) so a
+		// single delete loop covers edges out of the node and into it.
+		Kill tEdges
+		Set g = ""
+		For {
+			Set g = $Order(^KG("out", g))
+			Quit:g=""
+			Set p = ""
+			For {
+				Set p = $Order(^KG("out", g, nodeId, p))
+				Quit:p=""
+				Set o = ""
+				For {
+					Set o = $Order(^KG("out", g, nodeId, p, o))
+					Quit:o=""
+					Set tEdges(g, nodeId, p, o) = ""
+				}
+			}
+		}
+		Set g = ""
+		For {
+			Set g = $Order(^KG("in", g))
+			Quit:g=""
+			Set p = ""
+			For {
+				Set p = $Order(^KG("in", g, nodeId, p))
+				Quit:p=""
+				Set s = ""
+				For {
+					Set s = $Order(^KG("in", g, nodeId, p, s))
+					Quit:s=""
+					Set tEdges(g, s, p, nodeId) = ""
+				}
+			}
+		}
+		Set g = ""
+		For {
+			Set g = $Order(tEdges(g))
+			Quit:g=""
+			Set s = ""
+			For {
+				Set s = $Order(tEdges(g, s))
+				Quit:s=""
+				Set p = ""
+				For {
+					Set p = $Order(tEdges(g, s, p))
+					Quit:p=""
+					Set o = ""
+					For {
+						Set o = $Order(tEdges(g, s, p, o))
+						Quit:o=""
+						Do ..DeleteAdjacency(s, p, o, g)
+					}
+				}
+			}
+		}
+		Set count = count + 1
+	}
+	Quit count
+}
+
+}