iris-vector-graph 2.7.1__tar.gz → 2.8.0__tar.gz

{iris_vector_graph-2.7.1 → iris_vector_graph-2.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: iris-vector-graph
-Version: 2.7.1
+Version: 2.8.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

{iris_vector_graph-2.7.1 → iris_vector_graph-2.8.0}/iris_src/src/Graph/KG/TemporalIndex.cls

@@ -3,13 +3,20 @@ Class Graph.KG.TemporalIndex Extends %RegisteredObject
 
 Parameter BUCKET = 300;
 
-ClassMethod InsertEdge(source As %String, predicate As %String, target As %String, timestamp As %Integer = "", weight As %Double = 1.0, attrsJSON As %String = "", upsert As %Boolean = 0) As %Status
+/// Timestamp precision unit. "" = seconds (default). "ms" = milliseconds.
+Parameter TSUNIT As %String = "";
+
+/// Bucket width in milliseconds when TSUNIT="ms". Derived: BUCKET * 1000.
+Parameter BUCKETMS As %Integer = 300000;
+
+ClassMethod InsertEdge(source As %String, predicate As %String, target As %String, timestamp As %Integer = "", weight As %Double = 1.0, attrsJSON As %String = "", upsert As %Boolean = 0, suppressReverseIndex As %Boolean = 0) As %Status
 {
 	If timestamp = "" Set timestamp = ##class(%SYSTEM.SQL).DATEDIFF("ss", "1970-01-01 00:00:00", $ZDateTime($ZTimeStamp, 3, 1))
 	If upsert && $Data(^KG("tout", timestamp, source, predicate, target)) { Return 1 }
 	Set ^KG("tout", timestamp, source, predicate, target) = weight
-	Set ^KG("tin", timestamp, target, predicate, source) = weight
-	Set bucket = timestamp \ ..#BUCKET
+	If 'suppressReverseIndex { Set ^KG("tin", timestamp, target, predicate, source) = weight }
+	Set tBucketDiv = $Select(..#TSUNIT="ms": ..#BUCKETMS, 1: ..#BUCKET)
+	Set bucket = timestamp \ tBucketDiv
 	Set tmp = $Increment(^KG("bucket", bucket, source))
 	Set ^KG("out", 0, source, predicate, target) = weight
 	Set ^KG("in", 0, target, predicate, source) = weight
@@ -56,9 +63,11 @@ ClassMethod BulkInsert(batchJSON As %String, upsert As %Boolean = 0) As %Integer
 		If weight = "" Set weight = 1
 		If ts = 0 Set ts = ##class(%SYSTEM.SQL).DATEDIFF("ss", "1970-01-01 00:00:00", $ZDateTime($ZTimeStamp, 3, 1))
 		If upsert && $Data(^KG("tout", ts, source, predicate, target)) { Continue }
+		Set suppR = +item.%Get("suppress_reverse")
 		Set ^KG("tout", ts, source, predicate, target) = weight
-		Set ^KG("tin", ts, target, predicate, source) = weight
-		Set bucket = ts \ ..#BUCKET
+		If 'suppR { Set ^KG("tin", ts, target, predicate, source) = weight }
+		Set tBucketDiv = $Select(..#TSUNIT="ms": ..#BUCKETMS, 1: ..#BUCKET)
+		Set bucket = ts \ tBucketDiv
 		Set tmp = $Increment(^KG("bucket", bucket, source))
 		Set ^KG("out", 0, source, predicate, target) = weight
 		Set ^KG("in", 0, target, predicate, source) = weight
@@ -105,8 +114,9 @@ ClassMethod GetDistinctCount(source As %String, predicate As %String, tsStart As
 {
 	Set tsStart = +tsStart
 	Set tsEnd = +tsEnd
-	Set startBucket = tsStart \ ..#BUCKET
-	Set endBucket = tsEnd \ ..#BUCKET
+	Set tBucketDiv = $Select(..#TSUNIT="ms": ..#BUCKETMS, 1: ..#BUCKET)
+	Set startBucket = tsStart \ tBucketDiv
+	Set endBucket = tsEnd \ tBucketDiv
 	// Merge registers across buckets: element-wise max of 16 registers.
 	Set merged = $ListBuild(0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0)
 	For b = startBucket:1:endBucket {
@@ -200,8 +210,9 @@ ClassMethod GetVelocity(nodeId As %String, windowSec As %Integer = 300) As %Inte
 {
 	Set now = $ZTimeStamp
 	Set now = ##class(%SYSTEM.SQL).DATEDIFF("ss", "1970-01-01 00:00:00", $ZDateTime(now, 3, 1))
-	Set startBucket = (now - windowSec) \ ..#BUCKET
-	Set endBucket = now \ ..#BUCKET
+	Set tBucketDiv = $Select(..#TSUNIT="ms": ..#BUCKETMS, 1: ..#BUCKET)
+	Set startBucket = (now - windowSec) \ tBucketDiv
+	Set endBucket = now \ tBucketDiv
 	Set total = 0
 	For b = startBucket:1:endBucket {
 		Set total = total + $Get(^KG("bucket", b, nodeId), 0)
@@ -212,8 +223,9 @@ ClassMethod GetVelocity(nodeId As %String, windowSec As %Integer = 300) As %Inte
 ClassMethod FindBursts(predicate As %String, windowSec As %Integer, threshold As %Integer) As %String
 {
 	Set now = ##class(%SYSTEM.SQL).DATEDIFF("ss", "1970-01-01 00:00:00", $ZDateTime($ZTimeStamp, 3, 1))
-	Set startBucket = (now - windowSec) \ ..#BUCKET
-	Set endBucket = now \ ..#BUCKET
+	Set tBucketDiv = $Select(..#TSUNIT="ms": ..#BUCKETMS, 1: ..#BUCKET)
+	Set startBucket = (now - windowSec) \ tBucketDiv
+	Set endBucket = now \ tBucketDiv
 	Set result = "["
 	Set first = 1
 	Set b = startBucket - 1
@@ -254,10 +266,51 @@ ClassMethod Purge()
 ClassMethod PurgeBefore(tsEnd As %Integer)
 {
 	Set tsEnd = +tsEnd
+	Set tBucketDiv = $Select(..#TSUNIT="ms": ..#BUCKETMS, 1: ..#BUCKET)
+	// Only kill aggregate buckets strictly before the bucket containing tsEnd.
+	Set maxSafeBucket = (tsEnd \ tBucketDiv) - 1
+	Set ts = ""
+	For {
+		Set ts = $Order(^KG("tout", ts))
+		Quit:(ts = "")!(ts >= tsEnd)
+		Set s = ""
+		For {
+			Set s = $Order(^KG("tout", ts, s))
+			Quit:s=""
+			Set p = ""
+			For {
+				Set p = $Order(^KG("tout", ts, s, p))
+				Quit:p=""
+				Set o = ""
+				For {
+					Set o = $Order(^KG("tout", ts, s, p, o))
+					Quit:o=""
+					Kill ^KG("tout", ts, s, p, o)
+					Kill ^KG("tin",  ts, o, p, s)
+					Kill ^KG("edgeprop", ts, s, p, o)
+				}
+			}
+		}
+		// Only kill aggregate buckets that are fully expired.
+		Set bucket = ts \ tBucketDiv
+		If bucket <= maxSafeBucket {
+			Kill ^KG("tagg", bucket)
+			Kill ^KG("bucket", bucket)
+		}
+		Kill ^KG("tout", ts)
+	}
+}
+
+/// Delete raw temporal edges with ts < tsEnd, preserving aggregates.
+/// Returns the number of edges deleted. Strict < boundary.
+ClassMethod PurgeRawBefore(tsEnd As %Integer) As %Integer
+{
+	Set tsEnd = +tsEnd
+	Set count = 0
 	Set ts = ""
 	For {
 		Set ts = $Order(^KG("tout", ts))
-		Quit:(ts = "")!(ts > tsEnd)
+		Quit:(ts = "")!(ts >= tsEnd)
 		Set s = ""
 		For {
 			Set s = $Order(^KG("tout", ts, s))
@@ -273,15 +326,73 @@ ClassMethod PurgeBefore(tsEnd As %Integer)
 					Kill ^KG("tout", ts, s, p, o)
 					Kill ^KG("tin",  ts, o, p, s)
 					Kill ^KG("edgeprop", ts, s, p, o)
+					Set count = count + 1
 				}
 			}
 		}
-		// Remove tagg entries for buckets that are fully before tsEnd
-		Set bucket = ts \ ..#BUCKET
-		Kill ^KG("tagg", bucket)
-		Kill ^KG("bucket", bucket)
 		Kill ^KG("tout", ts)
 	}
+	Return count
+}
+
+/// Intern an attribute JSON object: canonicalize, hash, store once, return SHA1 hex.
+/// Returns "" on invalid JSON input. Idempotent.
+ClassMethod InternLabelSet(attrsJSON As %String) As %String
+{
+	Set tSC = $$$OK
+	Set obj = ##class(%DynamicObject).%FromJSON(attrsJSON)
+	If '$IsObject(obj) { Return "" }
+	// Collect keys into a local array for sorting
+	Set iter = obj.%GetIterator()
+	Kill keys
+	Set keyCount = 0
+	While iter.%GetNext(.key) {
+		Set keyCount = keyCount + 1
+		Set keys(key) = ""
+	}
+	// Build canonical JSON with sorted keys
+	Set canonical = "{"
+	Set first = 1
+	Set k = ""
+	For {
+		Set k = $Order(keys(k))
+		Quit:(k = "")
+		Set val = obj.%Get(k)
+		Set valType = obj.%GetTypeOf(k)
+		If 'first { Set canonical = canonical _ "," }
+		Set first = 0
+		// Encode key
+		Set canonical = canonical _ """" _ k _ """:"
+		// Encode value based on type
+		If valType = "number" {
+			Set canonical = canonical _ val
+		} ElseIf valType = "boolean" {
+			Set canonical = canonical _ $Select(val:"true", 1:"false")
+		} ElseIf valType = "null" {
+			Set canonical = canonical _ "null"
+		} Else {
+			Set canonical = canonical _ """" _ val _ """"
+		}
+	}
+	Set canonical = canonical _ "}"
+	// SHA1 hash → lowercase hex
+	Set hashBytes = $SYSTEM.Encryption.SHA1Hash(canonical)
+	Set hex = ""
+	For i = 1:1:$Length(hashBytes) {
+		Set b = $ASCII(hashBytes, i)
+		Set hex = hex _ $Extract("0123456789abcdef", (b \ 16) + 1) _ $Extract("0123456789abcdef", (b # 16) + 1)
+	}
+	// Store if absent
+	If '$Data(^KG("labelset", hex)) {
+		Set ^KG("labelset", hex) = canonical
+	}
+	Return hex
+}
+
+/// Return the canonical JSON for a known label set hash. Returns "" if unknown.
+ClassMethod ResolveLabelSet(hash As %String) As %String
+{
+	Return $Get(^KG("labelset", hash), "")
 }
 
 ClassMethod QueryWindowInbound(target As %String, predicate As %String, tsStart As %Integer, tsEnd As %Integer) As %String
@@ -323,8 +434,9 @@ ClassMethod GetAggregate(source As %String, predicate As %String, metric As %Str
 {
 	Set tsStart = +tsStart
 	Set tsEnd = +tsEnd
-	Set startBucket = tsStart \ ..#BUCKET
-	Set endBucket = tsEnd \ ..#BUCKET
+	Set tBucketDiv = $Select(..#TSUNIT="ms": ..#BUCKETMS, 1: ..#BUCKET)
+	Set startBucket = tsStart \ tBucketDiv
+	Set endBucket = tsEnd \ tBucketDiv
 	Set totalCount = 0, totalSum = 0
 	Set globalMin = "", globalMax = ""
 	For b = startBucket:1:endBucket {
@@ -349,8 +461,9 @@ ClassMethod GetBucketGroups(predicate As %String, tsStart As %Integer, tsEnd As
 {
 	Set tsStart = +tsStart
 	Set tsEnd = +tsEnd
-	Set startBucket = tsStart \ ..#BUCKET
-	Set endBucket = tsEnd \ ..#BUCKET
+	Set tBucketDiv = $Select(..#TSUNIT="ms": ..#BUCKETMS, 1: ..#BUCKET)
+	Set startBucket = tsStart \ tBucketDiv
+	Set endBucket = tsEnd \ tBucketDiv
 	Set prefixLen = $Length(sourcePrefix)
 	Kill totals
 	Set b = startBucket - 1

iris_vector_graph-2.8.0/iris_src/src/Graph/KG/TemporalIndexMS.cls

@@ -0,0 +1,18 @@
+/// Test subclass of TemporalIndex with TSUNIT="ms" and BUCKETMS=300000.
+/// Used only in integration tests (spec 204 Phase 6 T046-T048).
+/// Never call this from production code — use Graph.KG.TemporalIndex directly.
+Class Graph.KG.TemporalIndexMS Extends Graph.KG.TemporalIndex
+{
+
+Parameter TSUNIT As %String = "ms";
+
+Parameter BUCKETMS As %Integer = 300000;
+
+/// Return the edge count stored in ^KG("bucket", bucket, node).
+/// Used by tests to verify bucket key assignment without embedded Python.
+ClassMethod GetBucketCount(bucket As %Integer, node As %String) As %Integer
+{
+	Return +$Get(^KG("bucket", bucket, node), 0)
+}
+
+}

{iris_vector_graph-2.7.1 → iris_vector_graph-2.8.0}/iris_vector_graph/_engine/temporal.py

@@ -20,6 +20,7 @@ class TemporalMixin:
         weight: float = 1.0,
         attrs: dict = None,
         upsert: bool = False,
+        suppress_reverse_index: bool = False,
         graph: Optional[str] = None,
     ) -> bool:
         """Create a timestamped edge in the temporal index.
@@ -40,6 +41,7 @@ class TemporalMixin:
             source, predicate, target,
             timestamp=int(timestamp) if timestamp is not None else 0,
             weight=weight, attrs=attrs, upsert=upsert,
+            suppress_reverse_index=suppress_reverse_index,
         )
         if result.error is None and graph is not None:
             from iris_vector_graph.cypher.translator import _table
@@ -66,7 +68,8 @@ class TemporalMixin:
         return result.error is None
 
     def bulk_create_edges_temporal(
-        self, edges: list, upsert: bool = False, graph: Optional[str] = None
+        self, edges: list, upsert: bool = False,
+        suppress_reverse_index: bool = False, graph: Optional[str] = None
     ) -> int:
         normalized = [
             {
@@ -79,7 +82,9 @@ class TemporalMixin:
             }
             for e in edges
         ]
-        result = self._store.bulk_write_temporal_edges(normalized, upsert=upsert)
+        result = self._store.bulk_write_temporal_edges(
+            normalized, upsert=upsert, suppress_reverse_index=suppress_reverse_index
+        )
         try:
             count = int(result.rows[0][0]) if result.rows else 0
         except (TypeError, ValueError, IndexError):
@@ -143,6 +148,22 @@ class TemporalMixin:
             "Graph.KG.TemporalIndex", "PurgeBefore", int(ts)
         )
 
+    def purge_raw_before(self, ts_end: int) -> int:
+        """Delete raw temporal edges with ts < ts_end. Preserves aggregates.
+
+        Returns the number of edges deleted.
+        """
+        return self._store.purge_raw_before(ts_end)
+
+    def intern_label_set(self, attrs: dict) -> str:
+        """Canonicalize, hash, and intern an attribute dict. Returns SHA1 hex hash."""
+        import json as _json
+        return self._store.intern_label_set(_json.dumps(attrs, separators=(",", ":")))
+
+    def resolve_label_set(self, hash_hex: str) -> str:
+        """Return the canonical JSON for a known label set hash, or '' if unknown."""
+        return self._store.resolve_label_set(hash_hex)
+
     def get_edge_velocity(self, node_id: str, window_seconds: int = 300) -> int:
         result = self._iris_obj().classMethodValue(
             "Graph.KG.TemporalIndex", "GetVelocity", node_id, window_seconds

{iris_vector_graph-2.7.1 → iris_vector_graph-2.8.0}/iris_vector_graph/store_protocol.py

@@ -31,8 +31,13 @@ class GraphStore(Protocol):
                         label_filter: Optional[str]) -> IVGResult: ...
     def write_temporal_edge(self, source_id: str, predicate: str, target_id: str,
                              timestamp: int, weight: float = 1.0, attrs: Optional[dict] = None,
-                             upsert: bool = False) -> IVGResult: ...
-    def bulk_write_temporal_edges(self, edges: list, upsert: bool = False) -> IVGResult: ...
+                             upsert: bool = False,
+                             suppress_reverse_index: bool = False) -> IVGResult: ...
+    def bulk_write_temporal_edges(self, edges: list, upsert: bool = False,
+                                   suppress_reverse_index: bool = False) -> IVGResult: ...
+    def purge_raw_before(self, ts_end: int) -> int: ...
+    def intern_label_set(self, attrs_json: str) -> str: ...
+    def resolve_label_set(self, hash_hex: str) -> str: ...
     def execute_temporal_window_query(self, source_id: str, predicate: str,
                                        ts_start: int, ts_end: int,
                                        direction: str = "out") -> IVGResult: ...

{iris_vector_graph-2.7.1 → iris_vector_graph-2.8.0}/iris_vector_graph/stores/iris_sql_store.py

@@ -723,7 +723,7 @@ class IRISGraphStore:
     def write_temporal_edge(
         self, source_id: str, predicate: str, target_id: str,
         timestamp: int, weight: float = 1.0, attrs: Optional[dict] = None,
-        upsert: bool = False
+        upsert: bool = False, suppress_reverse_index: bool = False
     ) -> IVGResult:
         import json as _json
         attrs_json = _json.dumps(attrs) if attrs else ""
@@ -731,14 +731,17 @@ class IRISGraphStore:
             self._call_classmethod(
                 "Graph.KG.TemporalIndex", "InsertEdge",
                 source_id, predicate, target_id,
-                str(timestamp), str(weight), attrs_json, str(int(upsert)),
+                str(timestamp), str(weight), attrs_json,
+                str(int(upsert)), str(int(suppress_reverse_index)),
             )
         except Exception as e:
             logger.warning("write_temporal_edge failed: %s", e)
             return IVGResult(columns=[], rows=[], error=str(e)[:200])
         return IVGResult(columns=[], rows=[])
 
-    def bulk_write_temporal_edges(self, edges: list, upsert: bool = False) -> IVGResult:
+    def bulk_write_temporal_edges(
+        self, edges: list, upsert: bool = False, suppress_reverse_index: bool = False
+    ) -> IVGResult:
         import json as _json
         inserted = 0
         for edge in edges:
@@ -748,11 +751,35 @@ class IRISGraphStore:
             ts = edge.get("timestamp", 0)
             weight = float(edge.get("weight", 1.0))
             attrs = edge.get("attrs") or {}
-            result = self.write_temporal_edge(src, pred, tgt, ts, weight, attrs, upsert)
+            result = self.write_temporal_edge(
+                src, pred, tgt, ts, weight, attrs, upsert, suppress_reverse_index
+            )
             if not result.error:
                 inserted += 1
         return IVGResult(columns=["inserted"], rows=[[inserted]])
 
+    def purge_raw_before(self, ts_end: int) -> int:
+        result = self._call_classmethod(
+            "Graph.KG.TemporalIndex", "PurgeRawBefore", str(ts_end)
+        )
+        return int(str(result))
+
+    def intern_label_set(self, attrs_json: str) -> str:
+        result = self._call_classmethod(
+            "Graph.KG.TemporalIndex", "InternLabelSet", attrs_json
+        )
+        if result is None:
+            return ""
+        return str(result)
+
+    def resolve_label_set(self, hash_hex: str) -> str:
+        result = self._call_classmethod(
+            "Graph.KG.TemporalIndex", "ResolveLabelSet", hash_hex
+        )
+        if result is None:
+            return ""
+        return str(result)
+
     def execute_temporal_window_query(
         self, source_id: str, predicate: str,
         ts_start: int, ts_end: int, direction: str = "out"

{iris_vector_graph-2.7.1 → iris_vector_graph-2.8.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "iris-vector-graph"
-version = "2.7.1"
+version = "2.8.0"
 description = "Native graph database layer for InterSystems IRIS — openCypher, hybrid vector search, temporal property graph, RDF export, SHACL validation"
 readme = "README.md"
 license = "MIT"