iris-vector-graph 2.4.6__tar.gz → 2.5.0__tar.gz

{iris_vector_graph-2.4.6 → iris_vector_graph-2.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: iris-vector-graph
-Version: 2.4.6
+Version: 2.5.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
@@ -26,6 +26,8 @@ Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
 Requires-Python: >=3.10
 Requires-Dist: intersystems-iris>=1.0.0
 Requires-Dist: iris-embedded-python-wrapper>=0.5.20
+Provides-Extra: ai
+Requires-Dist: iris-agentic-dev>=1.0; extra == 'ai'
 Provides-Extra: biodata
 Requires-Dist: biopython>=1.81; extra == 'biodata'
 Requires-Dist: bioservices>=1.11.0; extra == 'biodata'
@@ -197,7 +199,7 @@ and [docs/performance/GRAPH_ALGORITHMS.md](docs/performance/GRAPH_ALGORITHMS.md)
 
 ## Architecture
 
-```
+```text
 ┌─────────────────────────────────────────────────────────────────────┐
 │                    iris-vector-graph  v2.1.0                        │
 ├─────────────────────────────────────────────────────────────────────┤
@@ -293,6 +295,29 @@ reference, SHACL shape writing, PROV-O vocabulary mapping, and integration patte
 
 ---
 
+## AI Agent Development
+
+When building agents that use IVG as a knowledge graph backend, install the
+[iris-agentic-dev](https://github.com/intersystems-community/iris-agentic-dev) MCP
+toolkit for ObjectScript compilation, global inspection, and IRIS method invocation
+from your agent's tool loop:
+
+```bash
+pip install iris-agentic-dev
+```
+
+This gives your agent `iris_compile`, `iris_execute`, `iris_global`, and related tools
+that work alongside IVG's Python API.
+
+Skill files with agent-oriented quickstarts:
+
+- [`skills/iris-vector-graph/SKILL.md`](skills/iris-vector-graph/SKILL.md) — IVG API,
+  temporal edges, SHACL, globals, container setup, common gotchas
+- [`skills/ivg-arno/SKILL.md`](skills/ivg-arno/SKILL.md) — Arno Rust acceleration,
+  BFS at scale, enterprise container, ASQ query syntax
+
+---
+
 ## License
 
 MIT. See [LICENSE](LICENSE).

{iris_vector_graph-2.4.6 → iris_vector_graph-2.5.0}/README.md

@@ -105,7 +105,7 @@ and [docs/performance/GRAPH_ALGORITHMS.md](docs/performance/GRAPH_ALGORITHMS.md)
 
 ## Architecture
 
-```
+```text
 ┌─────────────────────────────────────────────────────────────────────┐
 │                    iris-vector-graph  v2.1.0                        │
 ├─────────────────────────────────────────────────────────────────────┤
@@ -201,6 +201,29 @@ reference, SHACL shape writing, PROV-O vocabulary mapping, and integration patte
 
 ---
 
+## AI Agent Development
+
+When building agents that use IVG as a knowledge graph backend, install the
+[iris-agentic-dev](https://github.com/intersystems-community/iris-agentic-dev) MCP
+toolkit for ObjectScript compilation, global inspection, and IRIS method invocation
+from your agent's tool loop:
+
+```bash
+pip install iris-agentic-dev
+```
+
+This gives your agent `iris_compile`, `iris_execute`, `iris_global`, and related tools
+that work alongside IVG's Python API.
+
+Skill files with agent-oriented quickstarts:
+
+- [`skills/iris-vector-graph/SKILL.md`](skills/iris-vector-graph/SKILL.md) — IVG API,
+  temporal edges, SHACL, globals, container setup, common gotchas
+- [`skills/ivg-arno/SKILL.md`](skills/ivg-arno/SKILL.md) — Arno Rust acceleration,
+  BFS at scale, enterprise container, ASQ query syntax
+
+---
+
 ## License
 
 MIT. See [LICENSE](LICENSE).

{iris_vector_graph-2.4.6 → iris_vector_graph-2.5.0}/iris_src/src/Graph/KG/BM25Index.cls

@@ -13,6 +13,9 @@
 ///   ^BM25Idx(name, "tf",   term, docId) integer — term frequency (term-first!)
 ///   ^BM25Idx(name, "len",  docId)       integer — document token count
 ///
+/// Stopwords: common English function words stored in ^BM25Idx("__stop__", word)
+/// at class-load time. Filtered out during Tokenize to reduce IDF noise.
+///
 /// Usage:
 ///   set result = ##class(Graph.KG.BM25Index).Build("ncit", $ListBuild("name","definition"))
 ///   set hits   = ##class(Graph.KG.BM25Index).Search("ncit", "ankylosing spondylitis", 10)
@@ -20,29 +23,54 @@ Class Graph.KG.BM25Index Extends %RegisteredObject
 {
 
 // ================================================================
-// Tokenize — private helper used by Build, Search, Insert
+// InitStopwords — populate ^BM25Idx("__stop__") once per process
+// ================================================================
+
+ClassMethod InitStopwords() [ Private ]
+{
+    If $Data(^BM25Idx("__stop__", "the")) Return
+    Set words = "a,an,the,and,or,but,in,on,at,to,for,of,with,by,from,is,are,was,were,be,been,being,have,has,had,do,does,did,will,would,could,should,may,might,shall,this,that,these,those,it,its,i,we,you,he,she,they,them,their,our,your,his,her,not,no,nor,so,yet,both,either,neither,each,all,any,such,as,if,than,then,there,here,when,where,which,who,what,how"
+    Set n = $LENGTH(words, ",")
+    For i = 1:1:n {
+        Set w = $PIECE(words, ",", i)
+        Set ^BM25Idx("__stop__", w) = 1
+    }
+}
+
+// ================================================================
+// Tokenize — private helper used by Build, Search, Insert, Delete
 // ================================================================
 
 ClassMethod Tokenize(text As %String) As %List [ Private ]
 {
+    Do ..InitStopwords()
     Set lower = $ZCONVERT(text, "L")
     // Try iFind tokenizer first (better punctuation handling, base IRIS)
+    Set raw = ""
     Try {
-        Set tokens = ##class(%iFind.Utils).Analyze(lower, "en", 1)
-        Return tokens
+        Set raw = ##class(%iFind.Utils).Analyze(lower, "en", 1)
     } Catch {}
-    // Fallback: iterate chars, accumulate alphanumeric runs
-    Set result = "", tok = ""
-    For i = 1:1:$LENGTH(lower) {
-        Set c = $EXTRACT(lower, i)
-        If c?1AN {
-            Set tok = tok_c
-        } ElseIf tok '= "" {
-            Set result = result_$LISTBUILD(tok)
-            Set tok = ""
+    If raw = "" {
+        // Fallback: iterate chars, accumulate alphanumeric runs
+        Set tok = ""
+        For i = 1:1:$LENGTH(lower) {
+            Set c = $EXTRACT(lower, i)
+            If c?1AN {
+                Set tok = tok_c
+            } ElseIf tok '= "" {
+                Set raw = raw_$LISTBUILD(tok)
+                Set tok = ""
+            }
         }
+        If tok '= "" Set raw = raw_$LISTBUILD(tok)
+    }
+    // Filter stopwords
+    Set result = "", tIdx = 0
+    While $LISTNEXT(raw, tIdx, tok) {
+        If tok = "" Continue
+        If $Data(^BM25Idx("__stop__", tok)) Continue
+        Set result = result_$LISTBUILD(tok)
     }
-    If tok '= "" Set result = result_$LISTBUILD(tok)
     Return result
 }
 
@@ -54,85 +82,71 @@ ClassMethod Build(name As %String, propsCSV As %String, k1 As %Double = 1.5, b A
 {
     Kill ^BM25Idx(name)
 
-    Set N = 0
-    Set totalLen = 0
+    // Build an IN-list literal from propsCSV for the single batch query.
+    // e.g. "name,definition" → "'name','definition'"
+    Set inList = ""
+    Set nProps = $LENGTH(propsCSV, ",")
+    For pi = 1:1:nProps {
+        Set propKey = $ZSTRIP($PIECE(propsCSV, ",", pi), "<>W")
+        If propKey = "" Continue
+        Set escaped = $Replace(propKey, "'", "''")
+        Set inList = inList _ $Select(inList="":"", 1:",") _ "'" _ escaped _ "'"
+    }
+    If inList = "" Return "{""indexed"":0,""avgdl"":0,""vocab_size"":0}"
 
-    Set sql = "SELECT node_id FROM Graph_KG.nodes"
+    // One query fetches all (node_id, val) pairs for the requested properties.
+    // Ordered by node_id so we can accumulate per-doc by scanning in sequence.
+    Set sql = "SELECT n.node_id, p.val FROM Graph_KG.nodes n "
+            _ "LEFT JOIN Graph_KG.rdf_props p ON p.s = n.node_id AND p.key IN ("_inList_") "
+            _ "ORDER BY n.node_id"
     Set stmt = ##class(%SQL.Statement).%New()
     Do stmt.%Prepare(sql)
     Set rs = stmt.%Execute()
 
+    Set N = 0
+    Set totalLen = 0
+    Set curDoc = ""
+    Set docText = ""
+
     While rs.%Next() {
         Set docId = rs.%Get("node_id")
+        Set val = rs.%GetData(2)  // p.val (NULL when no matching prop row)
 
-        Set docText = ""
-        Set nProps = $LENGTH(propsCSV, ",")
-        For pi = 1:1:nProps {
-            Set propKey = $PIECE(propsCSV, ",", pi)
-            Set propKey = $ZSTRIP(propKey, "<>W")
-            If propKey = "" Continue
-            Set pSql = "SELECT val FROM Graph_KG.rdf_props WHERE s = ? AND key = ?"
-            Set pStmt = ##class(%SQL.Statement).%New()
-            Do pStmt.%Prepare(pSql)
-            Set pRs = pStmt.%Execute(docId, propKey)
-            While pRs.%Next() {
-                Set docText = docText_" "_pRs.%Get("val")
+        If docId '= curDoc {
+            // Flush previous doc
+            If curDoc '= "" {
+                Do ..IndexDoc(name, curDoc, docText, .N, .totalLen)
             }
+            Set curDoc = docId
+            Set docText = $Select(val="":"", 1:val)
+        } Else {
+            If val '= "" Set docText = docText _ " " _ val
         }
-
-        Set tokens = ..Tokenize(docText)
-        Set docLen = $LISTLENGTH(tokens)
-        If docLen = 0 Continue
-
-        Kill tfMap
-        Set tIdx = 0
-        While $LISTNEXT(tokens, tIdx, tok) {
-            If tok = "" Continue
-            Set tfMap(tok) = $Get(tfMap(tok), 0) + 1
-        }
-
-        Set tok = ""
-        For { 
-            Set tok = $Order(tfMap(tok))
-            Quit:tok=""
-            Set ^BM25Idx(name, "tf", tok, docId) = tfMap(tok)
-        }
-
-        Set ^BM25Idx(name, "len", docId) = docLen
-        Set N = N + 1
-        Set totalLen = totalLen + docLen
+    }
+    // Flush last doc
+    If curDoc '= "" {
+        Do ..IndexDoc(name, curDoc, docText, .N, .totalLen)
     }
 
-    // Compute and store IDF for all terms
+    // Compute IDF for all terms from accumulated tf subscripts
     Set avgdl = $Select(N > 0: totalLen / N, 1: 0)
     Set vocabSize = 0
     Set term = ""
-    For {
-        Set term = $Order(^BM25Idx(name, "idf", term))
-        Quit:term=""
-        Kill ^BM25Idx(name, "idf", term)
-    }
-
-    // Compute IDF from df (document frequency) via tf subscripts
-    Set term = ""
     For {
         Set term = $Order(^BM25Idx(name, "tf", term))
         Quit:term=""
-        // Count df = number of docs containing this term
         Set df = 0
-        Set docId = ""
+        Set d = ""
         For {
-            Set docId = $Order(^BM25Idx(name, "tf", term, docId))
-            Quit:docId=""
+            Set d = $Order(^BM25Idx(name, "tf", term, d))
+            Quit:d=""
             Set df = df + 1
         }
-        // Robertson IDF: log((N - df + 0.5) / (df + 0.5) + 1)
         Set idf = $ZLN((N - df + 0.5) / (df + 0.5) + 1)
         Set ^BM25Idx(name, "idf", term) = idf
         Set vocabSize = vocabSize + 1
     }
 
-    // Store config
     Set ^BM25Idx(name, "cfg", "N") = N
     Set ^BM25Idx(name, "cfg", "avgdl") = avgdl
     Set ^BM25Idx(name, "cfg", "k1") = k1
@@ -142,6 +156,29 @@ ClassMethod Build(name As %String, propsCSV As %String, k1 As %Double = 1.5, b A
     Return "{""indexed"":"_N_",""avgdl"":"_avgdl_",""vocab_size"":"_vocabSize_"}"
 }
 
+// Accumulate tf and length for one document — shared by Build batch loop.
+ClassMethod IndexDoc(name As %String, docId As %String, docText As %String, ByRef N As %Integer, ByRef totalLen As %Integer) [ Private ]
+{
+    Set tokens = ..Tokenize(docText)
+    Set docLen = $LISTLENGTH(tokens)
+    If docLen = 0 Return
+    Kill tfMap
+    Set tIdx = 0
+    While $LISTNEXT(tokens, tIdx, tok) {
+        If tok = "" Continue
+        Set tfMap(tok) = $Get(tfMap(tok), 0) + 1
+    }
+    Set tok = ""
+    For {
+        Set tok = $Order(tfMap(tok))
+        Quit:tok=""
+        Set ^BM25Idx(name, "tf", tok, docId) = tfMap(tok)
+    }
+    Set ^BM25Idx(name, "len", docId) = docLen
+    Set N = N + 1
+    Set totalLen = totalLen + docLen
+}
+
 // ================================================================
 // Search — BM25 ranked retrieval
 // ================================================================
@@ -185,29 +222,31 @@ ClassMethod Search(name As %String, queryText As %String, k As %Integer = 10) As
     }
 
     // Sort by score descending — collect top k
-    // Use inverted score as subscript for natural $Order sorting
+    // Scale score to a 12-decimal fixed-point integer subscript so $Order
+    // gives ascending-numeric order; we iterate in reverse with $Order(...,-1).
+    // This avoids the "10M offset" overflow that breaks when BM25 scores exceed it.
     Kill ^||bm25sorted
     Set docId = ""
     For {
         Set docId = $Order(^||bm25scores(docId), 1, score)
         Quit:docId=""
-        // Negate score for descending sort (use large offset to avoid negative subscripts)
-        Set negScore = 10000000 - score
-        Set ^||bm25sorted(negScore, docId) = score
+        // Multiply by 1e12 and round to integer → subscript safe for any BM25 score
+        Set sortKey = $NUMBER(score * 1000000000000, 0)
+        Set ^||bm25sorted(sortKey, docId) = score
     }
 
-    // Build JSON result array
+    // Walk in descending order using $Order with direction -1
     Set result = "["
     Set count = 0
-    Set negScore = ""
+    Set sortKey = ""
     For {
         If count >= k Quit
-        Set negScore = $Order(^||bm25sorted(negScore))
-        Quit:negScore=""
+        Set sortKey = $Order(^||bm25sorted(sortKey), -1)
+        Quit:sortKey=""
         Set docId = ""
         For {
             If count >= k Quit
-            Set docId = $Order(^||bm25sorted(negScore, docId), 1, score)
+            Set docId = $Order(^||bm25sorted(sortKey, docId), 1, score)
             Quit:docId=""
             If count > 0 Set result = result_","
             Set safeId = $Replace(docId, """", "\""")
@@ -284,10 +323,11 @@ ClassMethod Insert(name As %String, docId As %String, text As %String) As %Integ
             Quit:d=""
             Set df = df + 1
         }
+        // Check for new term BEFORE overwriting idf entry
+        Set isNewTerm = '$Data(^BM25Idx(name, "idf", tok))
         Set idf = $ZLN((N - df + 0.5) / (df + 0.5) + 1)
         Set ^BM25Idx(name, "idf", tok) = idf
-        // Update vocab_size if this is a new term
-        If '$Data(^BM25Idx(name, "idf", tok)) {
+        If isNewTerm {
             Set ^BM25Idx(name, "cfg", "vocab_size") = $Increment(^BM25Idx(name, "cfg", "vocab_size"))
         }
     }
@@ -295,6 +335,63 @@ ClassMethod Insert(name As %String, docId As %String, text As %String) As %Integ
     Return 1
 }
 
+// ================================================================
+// Delete — remove a single document from the index
+// ================================================================
+
+ClassMethod Delete(name As %String, docId As %String) As %Integer
+{
+    Set oldLen = +$Get(^BM25Idx(name, "len", docId), 0)
+    If oldLen = 0 Return 0  // doc not in index
+
+    Set N = +$Get(^BM25Idx(name, "cfg", "N"), 0)
+    Set totalLen = N * +$Get(^BM25Idx(name, "cfg", "avgdl"), 0)
+
+    // Collect terms this doc contributed to
+    Kill affectedTerms
+    Set term = ""
+    For {
+        Set term = $Order(^BM25Idx(name, "tf", term))
+        Quit:term=""
+        If $Data(^BM25Idx(name, "tf", term, docId)) {
+            Kill ^BM25Idx(name, "tf", term, docId)
+            Set affectedTerms(term) = 1
+        }
+    }
+    Kill ^BM25Idx(name, "len", docId)
+
+    // Update doc count and avgdl
+    Set N = N - 1
+    Set totalLen = totalLen - oldLen
+    Set ^BM25Idx(name, "cfg", "N") = N
+    Set ^BM25Idx(name, "cfg", "avgdl") = $Select(N > 0: totalLen / N, 1: 0)
+
+    // Recompute IDF for affected terms; remove terms that now have df=0
+    Set term = ""
+    For {
+        Set term = $Order(affectedTerms(term))
+        Quit:term=""
+        Set df = 0
+        Set d = ""
+        For {
+            Set d = $Order(^BM25Idx(name, "tf", term, d))
+            Quit:d=""
+            Set df = df + 1
+        }
+        If df = 0 {
+            Kill ^BM25Idx(name, "idf", term)
+            Set ^BM25Idx(name, "cfg", "vocab_size") = $Increment(^BM25Idx(name, "cfg", "vocab_size"), -1)
+        } Else {
+            If N > 0 {
+                Set idf = $ZLN((N - df + 0.5) / (df + 0.5) + 1)
+                Set ^BM25Idx(name, "idf", term) = idf
+            }
+        }
+    }
+
+    Return 1
+}
+
 // ================================================================
 // Drop — remove entire index
 // ================================================================

{iris_vector_graph-2.4.6 → iris_vector_graph-2.5.0}/iris_vector_graph/_engine/nodes_edges.py

@@ -408,6 +408,198 @@ class NodesEdgesMixin:
         ids = self.get_node_ids_by_label(label)
         return self.get_nodes(ids) if ids else []
 
+    # ------------------------------------------------------------------
+    # Property-side primitives (v2.5.0)
+    # Single-table scans over rdf_props / nodes only — no JOIN, no FETCH FIRST.
+    # ------------------------------------------------------------------
+
+    def get_node_ids_by_property(
+        self,
+        key: str,
+        val: Optional[str] = None,
+        limit: Optional[int] = None,
+    ) -> List[str]:
+        """Subject ids carrying property `key`, optionally filtered to `= val`.
+
+        Direct mirror of get_node_ids_by_label for the property dimension.
+        Single-table scan; no JOIN; uses TOP n (never FETCH FIRST).
+
+        Args:
+            key: Property name.
+            val: Optional exact value filter.  None means "carries the key at all".
+            limit: Cap on returned rows.  Non-positive means no limit.
+
+        Returns:
+            List of node ids.
+        """
+        top = f"TOP {int(limit)} " if limit and int(limit) > 0 else ""
+        sql = f'SELECT {top}s FROM {_table("rdf_props")} WHERE "key" = ?'
+        params: List[Any] = [key]
+        if val is not None:
+            sql += " AND val = ?"
+            params.append(val)
+        cursor = self.conn.cursor()
+        try:
+            cursor.execute(sql, params)
+            return [row[0] for row in cursor.fetchall() if row and row[0]]
+        except Exception as e:
+            logger.error("get_node_ids_by_property(%s) failed: %s", key, e)
+            return []
+        finally:
+            cursor.close()
+
+    def get_nodes_by_property(
+        self,
+        key: str,
+        val: Optional[str] = None,
+        limit: Optional[int] = None,
+    ) -> List[Dict[str, Any]]:
+        """Hydrated nodes carrying property `key` (optionally `= val`).
+
+        Equivalent to get_node_ids_by_property + get_nodes.
+        """
+        ids = self.get_node_ids_by_property(key, val=val, limit=limit)
+        return self.get_nodes(ids) if ids else []
+
+    def get_property_pairs(self, key: str) -> List[tuple]:
+        """(subject, value) pairs for every row under property `key`.
+
+        Returns one pair per subject (the schema enforces PK on (s, key)).
+        Useful when you need both the subject id and the value in one pass
+        without hydrating full nodes via get_nodes.
+        """
+        sql = f'SELECT s, val FROM {_table("rdf_props")} WHERE "key" = ?'
+        cursor = self.conn.cursor()
+        try:
+            cursor.execute(sql, [key])
+            return [(row[0], row[1]) for row in cursor.fetchall() if row and row[0]]
+        except Exception as e:
+            logger.error("get_property_pairs(%s) failed: %s", key, e)
+            return []
+        finally:
+            cursor.close()
+
+    def get_property_values(self, key: str) -> List[str]:
+        """Every value stored under property `key`, across all subjects.
+
+        Value-side scan without subject context: use to seed dedup sets in one
+        pass over large property populations (e.g. all source_urls).
+        """
+        sql = f'SELECT val FROM {_table("rdf_props")} WHERE "key" = ?'
+        cursor = self.conn.cursor()
+        try:
+            cursor.execute(sql, [key])
+            return [row[0] for row in cursor.fetchall() if row and row[0]]
+        except Exception as e:
+            logger.error("get_property_values(%s) failed: %s", key, e)
+            return []
+        finally:
+            cursor.close()
+
+    def property_value_exists(self, key: str, like: str) -> bool:
+        """True if any row under `key` has a value matching SQL LIKE `like`.
+
+        TOP 1 probe — never FETCH FIRST (SIGSEGV on IRIS AI builds, DP-451209).
+        """
+        sql = f'SELECT TOP 1 1 FROM {_table("rdf_props")} WHERE "key" = ? AND val LIKE ?'
+        cursor = self.conn.cursor()
+        try:
+            cursor.execute(sql, [key, like])
+            return cursor.fetchone() is not None
+        except Exception as e:
+            logger.error("property_value_exists(%s LIKE %s) failed: %s", key, like, e)
+            return False
+        finally:
+            cursor.close()
+
+    def get_property_pairs_like(
+        self,
+        key: str,
+        like: str,
+        limit: Optional[int] = None,
+    ) -> List[tuple]:
+        """(subject, value) pairs under `key` whose value matches SQL LIKE `like`.
+
+        Keyword-search primitive: bounded LIKE probe beats hydrating all nodes.
+        `limit` non-positive means no cap.
+        """
+        top = f"TOP {int(limit)} " if limit and int(limit) > 0 else ""
+        sql = (
+            f'SELECT {top}s, val FROM {_table("rdf_props")} '
+            f'WHERE "key" = ? AND val LIKE ?'
+        )
+        cursor = self.conn.cursor()
+        try:
+            cursor.execute(sql, [key, like])
+            return [(row[0], row[1]) for row in cursor.fetchall() if row and row[0]]
+        except Exception as e:
+            logger.error("get_property_pairs_like(%s LIKE %s) failed: %s", key, like, e)
+            return []
+        finally:
+            cursor.close()
+
+    def get_json_field_values(self, key: str, field: str) -> List[str]:
+        """Values of one JSON `field` inside every `key` blob, extracted server-side.
+
+        Uses $PIECE extraction to avoid moving multi-MB JSON blobs to Python.
+        """
+        sql = (
+            f"SELECT $PIECE($PIECE(val, '\"{field}\": \"', 2), '\"', 1) "
+            f'FROM {_table("rdf_props")} WHERE "key" = ? AND val LIKE ?'
+        )
+        cursor = self.conn.cursor()
+        try:
+            cursor.execute(sql, [key, f"%{field}%"])
+            return [row[0] for row in cursor.fetchall() if row and row[0]]
+        except Exception as e:
+            logger.error("get_json_field_values(%s.%s) failed: %s", key, field, e)
+            return []
+        finally:
+            cursor.close()
+
+    def get_node_ids_like(self, pattern: str) -> List[str]:
+        """Node ids matching a SQL LIKE `pattern`.
+
+        Used for test-fixture cleanup (ids like `test-run-1234:%`) and for
+        producing the id list that bulk_delete_nodes requires.
+        """
+        sql = f"SELECT node_id FROM {_table('nodes')} WHERE node_id LIKE ?"
+        cursor = self.conn.cursor()
+        try:
+            cursor.execute(sql, [pattern])
+            return [row[0] for row in cursor.fetchall() if row and row[0]]
+        except Exception as e:
+            logger.error("get_node_ids_like(%s) failed: %s", pattern, e)
+            return []
+        finally:
+            cursor.close()
+
+    def count_subjects_with_property(
+        self,
+        key: str,
+        val: Optional[str] = None,
+    ) -> int:
+        """COUNT(*) of subjects carrying `key` (optionally `= val`).
+
+        Does not hydrate nodes — pure count for cardinality estimates.
+        """
+        sql = f'SELECT COUNT(*) FROM {_table("rdf_props")} WHERE "key" = ?'
+        params: List[Any] = [key]
+        if val is not None:
+            sql += " AND val = ?"
+            params.append(val)
+        cursor = self.conn.cursor()
+        try:
+            cursor.execute(sql, params)
+            row = cursor.fetchone()
+            return int(row[0]) if row and row[0] else 0
+        except Exception as e:
+            logger.error(
+                "count_subjects_with_property(%s=%s) failed: %s", key, val, e
+            )
+            return 0
+        finally:
+            cursor.close()
 
     def create_node(
         self, node_id: str, labels: List[str] = None, properties: Dict[str, Any] = None,