iris-vector-graph 2.15.0__tar.gz → 2.18.1__tar.gz

{iris_vector_graph-2.15.0 → iris_vector_graph-2.18.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: iris-vector-graph
-Version: 2.15.0
+Version: 2.18.1
 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
@@ -207,7 +207,7 @@ and [docs/performance/GRAPH_ALGORITHMS.md](docs/performance/GRAPH_ALGORITHMS.md)
 
 ```text
 ┌─────────────────────────────────────────────────────────────────────┐
-│                    iris-vector-graph  v2.1.0                        │
+│                    iris-vector-graph  v2.18.0                       │
 ├─────────────────────────────────────────────────────────────────────┤
 │                                                                     │
 │   ┌───────────────┐   ┌───────────────┐   ┌───────────────────┐    │
@@ -287,6 +287,87 @@ reference, SHACL shape writing, PROV-O vocabulary mapping, and integration patte
 
 ---
 
+## Named Graphs
+
+Scope nodes and edges to a named graph — useful for multi-tenant data, staging
+vs. production snapshots, or materializing a ledger reconstruction into an
+isolated subgraph.
+
+```python
+# Create a node in the "umls" named graph
+engine.create_node("C0027051", labels=["Concept"], graph="umls")
+
+# Create an edge in the same named graph
+engine.create_edge("C0027051", "ISA", "C0085580", graph="umls")
+
+# Cypher: USE GRAPH targets the context for CREATE and MERGE
+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")
+
+# delete_edge defaults to the default graph; pass all_graphs=True to sweep all
+engine.delete_edge("C0027051", "ISA", "C0085580", graph="umls")
+engine.delete_edge("C0027051", "ISA", "C0085580", all_graphs=True)
+```
+
+Nodes in the default graph use `graph=""` (empty-string sentinel); the BFS
+adjacency index (`^KG`) partitions by graph key so traversals stay within
+their graph. Existing code that never passes `graph=` is unaffected.
+
+See [docs/USER_GUIDE.md](docs/USER_GUIDE.md#named-graphs) for the full guide.
+
+---
+
+## Revision Ledger (Transaction-Time History)
+
+The structural graph (nodes, labels, properties, relationships, qualifiers) can
+be versioned with an opt-in, immutable revision ledger. A changeset applies
+atomically and produces exactly one revision; a failed operation applies
+nothing. This is **transaction time** (when the ledger recorded a change) and is
+independent of the temporal property graph's **event time** (`ts` on temporal
+edges), which is unchanged and unversioned.
+
+```python
+from iris_vector_graph.ledger import Changeset
+
+genesis = engine.ledger.enable()              # idempotent; captures the existing graph
+head = engine.ledger.head()
+
+cs = Changeset(actor="ingest:etl-42", actor_type="ingest",
+               message="equipment sync",
+               expected_head=head.revision_id,      # optimistic concurrency
+               idempotency_key="etl-42-2026-09-05")  # safe retry
+cs.create_node("pump-7", labels=["Equipment"], properties={"status": "ok"})
+cs.create_node("tank-2")
+r = cs.create_relationship("pump-7", "FEEDS", "tank-2", qualifiers={"weight": "1.0"})
+cs.set_qualifier(r, "capacity", "100")
+result = engine.ledger.commit(cs)              # StaleHeadError if another writer won
+
+engine.ledger.history(limit=20)                # deterministic, pageable, filterable
+engine.ledger.get_revision(result.revision.revision_id).records
+engine.ledger.diff(genesis.revision_id, result.revision.revision_id)
+engine.ledger.reconstruct(genesis.revision_id) # read-only graph as of a revision
+engine.ledger.export_reconstruction(result.revision.revision_id, "at-rev.ndjson")
+engine.ledger.verify()                         # replay from genesis == current tables?
+engine.ledger.verify(adopt=True)               # record any unrecorded (legacy) writes
+```
+
+Existing APIs keep working with a ledger enabled; writes made through them are
+"unrecorded" and are surfaced by `verify()`. `enable(strict=True)` (or
+`set_strict(True)`) rejects non-ledger structural writes with
+`LedgerStrictModeError`; reads, temporal writes, and index maintenance are
+unaffected. Relationships get a stable **statement identity** that survives
+qualifier changes and snapshot restore. Counters are in
+`engine.status().ledger`, the `Graph_KG.ledger_stats` table, and a metrics hook
+(`engine.ledger.register_metrics_hook`, see
+[docs/ledger-prometheus-hook.md](docs/ledger-prometheus-hook.md)).
+
+---
+
 ## Non-USER Namespace Deployment
 
 By default IVG connects to the `USER` namespace. When deploying against a
@@ -333,15 +414,15 @@ warning is emitted.
 
 ## Documentation
 
-| Document                                                 | Contents                                                    |
-| -------------------------------------------------------- | ----------------------------------------------------------- |
-| [User Guide](docs/USER_GUIDE.md)                         | Cypher examples, temporal edges, vector search, bulk loader |
-| [Admin Guide](docs/ADMIN_GUIDE.md)                       | Container setup, schema management, index rebuilding        |
-| [Admin API](docs/ADMIN_API.md)                           | Python API reference for engine administration              |
-| [Benchmarks](docs/performance/BENCHMARKS.md)             | Full methodology, LDBC SNB results, ingestion throughput    |
-| [Graph Algorithms](docs/performance/GRAPH_ALGORITHMS.md) | Centrality and community detection benchmark details        |
-| [Semantic Layer](docs/SEMANTIC_LAYER.md)                 | RDF export, SHACL validation, PROV-O provenance             |
-| [Changelog](CHANGELOG.md)                                | Full version history                                        |
+| Document                                                 | Contents                                                             |
+| -------------------------------------------------------- | -------------------------------------------------------------------- |
+| [User Guide](docs/USER_GUIDE.md)                         | Cypher examples, named graphs, ledger, temporal edges, vector search |
+| [Admin Guide](docs/ADMIN_GUIDE.md)                       | Container setup, schema management, index rebuilding                 |
+| [Admin API](docs/ADMIN_API.md)                           | Python API reference for engine administration                       |
+| [Benchmarks](docs/performance/BENCHMARKS.md)             | Full methodology, LDBC SNB results, ingestion throughput             |
+| [Graph Algorithms](docs/performance/GRAPH_ALGORITHMS.md) | Centrality and community detection benchmark details                 |
+| [Semantic Layer](docs/SEMANTIC_LAYER.md)                 | RDF export, SHACL validation, PROV-O provenance                      |
+| [Changelog](CHANGELOG.md)                                | Full version history                                                 |
 
 ---
 

{iris_vector_graph-2.15.0 → iris_vector_graph-2.18.1}/README.md

@@ -109,7 +109,7 @@ and [docs/performance/GRAPH_ALGORITHMS.md](docs/performance/GRAPH_ALGORITHMS.md)
 
 ```text
 ┌─────────────────────────────────────────────────────────────────────┐
-│                    iris-vector-graph  v2.1.0                        │
+│                    iris-vector-graph  v2.18.0                       │
 ├─────────────────────────────────────────────────────────────────────┤
 │                                                                     │
 │   ┌───────────────┐   ┌───────────────┐   ┌───────────────────┐    │
@@ -189,6 +189,87 @@ reference, SHACL shape writing, PROV-O vocabulary mapping, and integration patte
 
 ---
 
+## Named Graphs
+
+Scope nodes and edges to a named graph — useful for multi-tenant data, staging
+vs. production snapshots, or materializing a ledger reconstruction into an
+isolated subgraph.
+
+```python
+# Create a node in the "umls" named graph
+engine.create_node("C0027051", labels=["Concept"], graph="umls")
+
+# Create an edge in the same named graph
+engine.create_edge("C0027051", "ISA", "C0085580", graph="umls")
+
+# Cypher: USE GRAPH targets the context for CREATE and MERGE
+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")
+
+# delete_edge defaults to the default graph; pass all_graphs=True to sweep all
+engine.delete_edge("C0027051", "ISA", "C0085580", graph="umls")
+engine.delete_edge("C0027051", "ISA", "C0085580", all_graphs=True)
+```
+
+Nodes in the default graph use `graph=""` (empty-string sentinel); the BFS
+adjacency index (`^KG`) partitions by graph key so traversals stay within
+their graph. Existing code that never passes `graph=` is unaffected.
+
+See [docs/USER_GUIDE.md](docs/USER_GUIDE.md#named-graphs) for the full guide.
+
+---
+
+## Revision Ledger (Transaction-Time History)
+
+The structural graph (nodes, labels, properties, relationships, qualifiers) can
+be versioned with an opt-in, immutable revision ledger. A changeset applies
+atomically and produces exactly one revision; a failed operation applies
+nothing. This is **transaction time** (when the ledger recorded a change) and is
+independent of the temporal property graph's **event time** (`ts` on temporal
+edges), which is unchanged and unversioned.
+
+```python
+from iris_vector_graph.ledger import Changeset
+
+genesis = engine.ledger.enable()              # idempotent; captures the existing graph
+head = engine.ledger.head()
+
+cs = Changeset(actor="ingest:etl-42", actor_type="ingest",
+               message="equipment sync",
+               expected_head=head.revision_id,      # optimistic concurrency
+               idempotency_key="etl-42-2026-09-05")  # safe retry
+cs.create_node("pump-7", labels=["Equipment"], properties={"status": "ok"})
+cs.create_node("tank-2")
+r = cs.create_relationship("pump-7", "FEEDS", "tank-2", qualifiers={"weight": "1.0"})
+cs.set_qualifier(r, "capacity", "100")
+result = engine.ledger.commit(cs)              # StaleHeadError if another writer won
+
+engine.ledger.history(limit=20)                # deterministic, pageable, filterable
+engine.ledger.get_revision(result.revision.revision_id).records
+engine.ledger.diff(genesis.revision_id, result.revision.revision_id)
+engine.ledger.reconstruct(genesis.revision_id) # read-only graph as of a revision
+engine.ledger.export_reconstruction(result.revision.revision_id, "at-rev.ndjson")
+engine.ledger.verify()                         # replay from genesis == current tables?
+engine.ledger.verify(adopt=True)               # record any unrecorded (legacy) writes
+```
+
+Existing APIs keep working with a ledger enabled; writes made through them are
+"unrecorded" and are surfaced by `verify()`. `enable(strict=True)` (or
+`set_strict(True)`) rejects non-ledger structural writes with
+`LedgerStrictModeError`; reads, temporal writes, and index maintenance are
+unaffected. Relationships get a stable **statement identity** that survives
+qualifier changes and snapshot restore. Counters are in
+`engine.status().ledger`, the `Graph_KG.ledger_stats` table, and a metrics hook
+(`engine.ledger.register_metrics_hook`, see
+[docs/ledger-prometheus-hook.md](docs/ledger-prometheus-hook.md)).
+
+---
+
 ## Non-USER Namespace Deployment
 
 By default IVG connects to the `USER` namespace. When deploying against a
@@ -235,15 +316,15 @@ warning is emitted.
 
 ## Documentation
 
-| Document                                                 | Contents                                                    |
-| -------------------------------------------------------- | ----------------------------------------------------------- |
-| [User Guide](docs/USER_GUIDE.md)                         | Cypher examples, temporal edges, vector search, bulk loader |
-| [Admin Guide](docs/ADMIN_GUIDE.md)                       | Container setup, schema management, index rebuilding        |
-| [Admin API](docs/ADMIN_API.md)                           | Python API reference for engine administration              |
-| [Benchmarks](docs/performance/BENCHMARKS.md)             | Full methodology, LDBC SNB results, ingestion throughput    |
-| [Graph Algorithms](docs/performance/GRAPH_ALGORITHMS.md) | Centrality and community detection benchmark details        |
-| [Semantic Layer](docs/SEMANTIC_LAYER.md)                 | RDF export, SHACL validation, PROV-O provenance             |
-| [Changelog](CHANGELOG.md)                                | Full version history                                        |
+| Document                                                 | Contents                                                             |
+| -------------------------------------------------------- | -------------------------------------------------------------------- |
+| [User Guide](docs/USER_GUIDE.md)                         | Cypher examples, named graphs, ledger, temporal edges, vector search |
+| [Admin Guide](docs/ADMIN_GUIDE.md)                       | Container setup, schema management, index rebuilding                 |
+| [Admin API](docs/ADMIN_API.md)                           | Python API reference for engine administration                       |
+| [Benchmarks](docs/performance/BENCHMARKS.md)             | Full methodology, LDBC SNB results, ingestion throughput             |
+| [Graph Algorithms](docs/performance/GRAPH_ALGORITHMS.md) | Centrality and community detection benchmark details                 |
+| [Semantic Layer](docs/SEMANTIC_LAYER.md)                 | RDF export, SHACL validation, PROV-O provenance                      |
+| [Changelog](CHANGELOG.md)                                | Full version history                                                 |
 
 ---
 

{iris_vector_graph-2.15.0 → iris_vector_graph-2.18.1}/iris_src/src/Graph/KG/Algorithms.cls

@@ -5,10 +5,11 @@ Class Graph.KG.Algorithms Extends %RegisteredObject
 
 ClassMethod WCCJson(maxIter As %Integer = 100) As %String
 {
+	Set pGraph = 0
 	Set nodeCount = 0
 	Set node = ""
 	For {
-		Set node = $Order(^KG("deg", node))
+		Set node = $Order(^KG("deg", pGraph, node))
 		Quit:node=""
 		Set labels(node) = node
 		Set nodeCount = nodeCount + 1
@@ -16,7 +17,7 @@ ClassMethod WCCJson(maxIter As %Integer = 100) As %String
 	// Also include nodes that only appear as targets (no outgoing edges = no "deg" entry)
 	Set node = ""
 	For {
-		Set node = $Order(^KG("in", 0, node))
+		Set node = $Order(^KG("in", pGraph, node))
 		Quit:node=""
 		If '$Data(labels(node)) {
 			Set labels(node) = node
@@ -38,11 +39,11 @@ ClassMethod WCCJson(maxIter As %Integer = 100) As %String
 			// Check outgoing neighbors
 			Set p = ""
 			For {
-				Set p = $Order(^KG("out", 0, node, p))
+				Set p = $Order(^KG("out", pGraph, node, p))
 				Quit:p=""
 				Set o = ""
 				For {
-					Set o = $Order(^KG("out", 0, node, p, o))
+					Set o = $Order(^KG("out", pGraph, node, p, o))
 					Quit:o=""
 					Set nbrLabel = $Get(labels(o), o)
 					If minLabel ]] nbrLabel Set minLabel = nbrLabel
@@ -52,11 +53,11 @@ ClassMethod WCCJson(maxIter As %Integer = 100) As %String
 			// Check incoming neighbors
 			Set p = ""
 			For {
-				Set p = $Order(^KG("in", 0, node, p))
+				Set p = $Order(^KG("in", pGraph, node, p))
 				Quit:p=""
 				Set s = ""
 				For {
-					Set s = $Order(^KG("in", 0, node, p, s))
+					Set s = $Order(^KG("in", pGraph, node, p, s))
 					Quit:s=""
 					Set nbrLabel = $Get(labels(s), s)
 					If minLabel ]] nbrLabel Set minLabel = nbrLabel
@@ -84,17 +85,18 @@ ClassMethod WCCJson(maxIter As %Integer = 100) As %String
 
 ClassMethod CDLPJson(maxIter As %Integer = 10) As %String
 {
+	Set pGraph = 0
 	Set nodeCount = 0
 	Set node = ""
 	For {
-		Set node = $Order(^KG("deg", node))
+		Set node = $Order(^KG("deg", pGraph, node))
 		Quit:node=""
 		Set labels(node) = node
 		Set nodeCount = nodeCount + 1
 	}
 	Set node = ""
 	For {
-		Set node = $Order(^KG("in", 0, node))
+		Set node = $Order(^KG("in", pGraph, node))
 		Quit:node=""
 		If '$Data(labels(node)) {
 			Set labels(node) = node
@@ -116,11 +118,11 @@ ClassMethod CDLPJson(maxIter As %Integer = 10) As %String
 			// Count outgoing neighbor labels
 			Set p = ""
 			For {
-				Set p = $Order(^KG("out", 0, node, p))
+				Set p = $Order(^KG("out", pGraph, node, p))
 				Quit:p=""
 				Set o = ""
 				For {
-					Set o = $Order(^KG("out", 0, node, p, o))
+					Set o = $Order(^KG("out", pGraph, node, p, o))
 					Quit:o=""
 					Set nbrLabel = $Get(labels(o), o)
 					Set counts(nbrLabel) = $Get(counts(nbrLabel), 0) + 1
@@ -130,11 +132,11 @@ ClassMethod CDLPJson(maxIter As %Integer = 10) As %String
 			// Count incoming neighbor labels
 			Set p = ""
 			For {
-				Set p = $Order(^KG("in", 0, node, p))
+				Set p = $Order(^KG("in", pGraph, node, p))
 				Quit:p=""
 				Set s = ""
 				For {
-					Set s = $Order(^KG("in", 0, node, p, s))
+					Set s = $Order(^KG("in", pGraph, node, p, s))
 					Quit:s=""
 					Set nbrLabel = $Get(labels(s), s)
 					Set counts(nbrLabel) = $Get(counts(nbrLabel), 0) + 1

{iris_vector_graph-2.15.0 → iris_vector_graph-2.18.1}/iris_src/src/Graph/KG/Centrality.cls

@@ -8,10 +8,10 @@
 ///   - EigenvectorJson         — power iteration over raw adjacency A (NOT PageRank with α=1)
 ///
 /// Storage (read-only):
-///   ^KG("out", 0, s, p, o)   outbound edges (shard-0)
+///   ^KG("out", pGraph, s, p, o)   outbound edges (shard-0)
 ///   ^KG("in",  0, o, p, s)   inbound edges (shard-0)
-///   ^KG("deg", node)         total out-degree
-///   ^KG("degp", node, pred)  per-predicate out-degree
+///   ^KG("deg", pGraph, node)         total out-degree
+///   ^KG("degp", pGraph, node, pred)  per-predicate out-degree
 ///
 /// Process-private scratch (killed on exit):
 ///   ^||CENT(-score, node)    descending sort buffer (shared across algos)
@@ -37,6 +37,7 @@ Class Graph.KG.Centrality Extends %RegisteredObject [ SqlSchemaName = Graph_KG ]
 /// @returns JSON array: [{"id":"node","score":0.42,"degree":17}, ...] sorted desc by score
 ClassMethod DegreeCentralityJson(direction As %String = "out", predicate As %String = "", topK As %Integer = 10000) As %String
 {
+	Set pGraph = 0
     // Count nodes for normalization
     Set nodeCount = 0
     // Enumerate the full node set: outbound sources (^KG("deg")) UNION
@@ -45,13 +46,13 @@ ClassMethod DegreeCentralityJson(direction As %String = "out", predicate As %Str
     Kill ^||CENTNODES
     Set node = ""
     For {
-        Set node = $Order(^KG("deg", node))
+        Set node = $Order(^KG("deg", pGraph, node))
         Quit:node=""
         Set ^||CENTNODES(node) = ""
     }
     Set node = ""
     For {
-        Set node = $Order(^KG("in", 0, node))
+        Set node = $Order(^KG("in", pGraph, node))
         Quit:node=""
         Set ^||CENTNODES(node) = ""
     }
@@ -77,30 +78,30 @@ ClassMethod DegreeCentralityJson(direction As %String = "out", predicate As %Str
         If predicate = "" {
             // All predicates
             If direction = "out" {
-                Set deg = +$Get(^KG("deg", node))
+                Set deg = +$Get(^KG("deg", pGraph, node))
             } ElseIf direction = "in" {
-                // Walk ^KG("in", 0, node, p, s) and count
+                // Walk ^KG("in", pGraph, node, p, s) and count
                 Set p = ""
                 For {
-                    Set p = $Order(^KG("in", 0, node, p))
+                    Set p = $Order(^KG("in", pGraph, node, p))
                     Quit:p=""
                     Set s = ""
                     For {
-                        Set s = $Order(^KG("in", 0, node, p, s))
+                        Set s = $Order(^KG("in", pGraph, node, p, s))
                         Quit:s=""
                         Set deg = deg + 1
                     }
                 }
             } Else {
                 // both = out + in
-                Set deg = +$Get(^KG("deg", node))
+                Set deg = +$Get(^KG("deg", pGraph, node))
                 Set p = ""
                 For {
-                    Set p = $Order(^KG("in", 0, node, p))
+                    Set p = $Order(^KG("in", pGraph, node, p))
                     Quit:p=""
                     Set s = ""
                     For {
-                        Set s = $Order(^KG("in", 0, node, p, s))
+                        Set s = $Order(^KG("in", pGraph, node, p, s))
                         Quit:s=""
                         Set deg = deg + 1
                     }
@@ -109,20 +110,20 @@ ClassMethod DegreeCentralityJson(direction As %String = "out", predicate As %Str
         } Else {
             // Specific predicate
             If direction = "out" {
-                Set deg = +$Get(^KG("degp", node, predicate))
+                Set deg = +$Get(^KG("degp", pGraph, node, predicate))
             } ElseIf direction = "in" {
-                // Walk ^KG("in", 0, node, predicate, *)
+                // Walk ^KG("in", pGraph, node, predicate, *)
                 Set s = ""
                 For {
-                    Set s = $Order(^KG("in", 0, node, predicate, s))
+                    Set s = $Order(^KG("in", pGraph, node, predicate, s))
                     Quit:s=""
                     Set deg = deg + 1
                 }
             } Else {
-                Set deg = +$Get(^KG("degp", node, predicate))
+                Set deg = +$Get(^KG("degp", pGraph, node, predicate))
                 Set s = ""
                 For {
-                    Set s = $Order(^KG("in", 0, node, predicate, s))
+                    Set s = $Order(^KG("in", pGraph, node, predicate, s))
                     Quit:s=""
                     Set deg = deg + 1
                 }