iris-vector-graph 2.18.0__tar.gz → 2.18.2__tar.gz

{iris_vector_graph-2.18.0 → iris_vector_graph-2.18.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: iris-vector-graph
-Version: 2.18.0
+Version: 2.18.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
@@ -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,41 @@ 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
@@ -379,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.18.0 → iris_vector_graph-2.18.2}/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,41 @@ 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
@@ -281,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.18.0 → iris_vector_graph-2.18.2}/iris_vector_graph/_engine/nodes_edges.py

@@ -637,10 +637,19 @@ class NodesEdgesMixin:
             cursor.execute("START TRANSACTION")
 
             graph_id = graph if graph is not None else ""
-            cursor.execute(
-                f"INSERT INTO {self._t('nodes')} (node_id, graph_id) VALUES (?, ?)",
-                [node_id, graph_id],
-            )
+            # Use a schema-compatible INSERT: include graph_id only when the column
+            # exists (post-214 schema).  Pre-214 clusters that haven't run the migration
+            # yet still work; they just can't use named graphs until migrated.
+            if getattr(self, "_nodes_has_graph_id", True):
+                cursor.execute(
+                    f"INSERT INTO {self._t('nodes')} (node_id, graph_id) VALUES (?, ?)",
+                    [node_id, graph_id],
+                )
+            else:
+                cursor.execute(
+                    f"INSERT INTO {self._t('nodes')} (node_id) VALUES (?)",
+                    [node_id],
+                )
 
             if labels:
                 label_data = [[node_id, label] for label in labels]
@@ -954,7 +963,11 @@ class NodesEdgesMixin:
                 GraphSchema.disable_indexes(cursor)
 
             # 2. SQL templates (using %NOINDEX for speed)
-            node_sql = GraphSchema.get_bulk_insert_sql("nodes")
+            # Use graph-aware template only when the schema has the graph_id column.
+            _graph_col = getattr(self, "_nodes_has_graph_id", True)
+            node_sql = GraphSchema.get_bulk_insert_sql(
+                "nodes_with_graph" if _graph_col else "nodes"
+            )
             label_sql = GraphSchema.get_bulk_insert_sql("rdf_labels")
             prop_sql = GraphSchema.get_bulk_insert_sql("rdf_props")
 
@@ -969,8 +982,12 @@ class NodesEdgesMixin:
                     continue
 
                 created_ids.append(node_id)
-                # params: [node_id, node_id] for WHERE NOT EXISTS
-                valid_nodes.append([node_id, node_id])
+                # params depend on template: nodes_with_graph needs [node_id, graph_id, node_id];
+                # plain nodes needs [node_id, node_id]
+                if _graph_col:
+                    valid_nodes.append([node_id, "", node_id])
+                else:
+                    valid_nodes.append([node_id, node_id])
 
                 for label in node.get("labels", []):
                     # params: [s, label, s, label]

{iris_vector_graph-2.18.0 → iris_vector_graph-2.18.2}/iris_vector_graph/_engine/schema.py

@@ -175,6 +175,9 @@ class SchemaMixin:
 
         # 3. Ensure indexes and run schema migrations (e.g. column size upgrades)
         GraphSchema.ensure_indexes(cursor)
+        # Update the engine flag after migration — ensure_indexes runs
+        # add_graph_id_to_nodes which adds the column if absent.
+        self._nodes_has_graph_id = self._probe_nodes_graph_id()
 
         # 4. Check for dimension mismatch on existing tables; fix untyped vector column
         try:

{iris_vector_graph-2.18.0 → iris_vector_graph-2.18.2}/iris_vector_graph/_engine/vector.py

@@ -400,30 +400,72 @@ class VectorMixin:
     def kg_TXT(
         self, query_text: str, k: int = 50, min_confidence: int = 0
     ) -> List[Tuple[str, float]]:
-        """
-        Enhanced text search using server-side SQL procedure
+        """Full-text search over the docs table.
+
+        Prefers IRIS iFind (%FIND / %FIND.Rank) when the idx_docs_text_ifind index
+        exists, giving BM25-style ranking.  Falls back to LIKE-based search on
+        instances where iFind is not installed.
+
+        Note: the kg_TXT stored procedure is NOT used — IRIS registers it as a scalar
+        FUNCTION (SQLCODE -51 on CALL, SQLCODE -30 on SELECT … FROM).  Inline SQL is
+        the only reliable calling convention from DBAPI.
 
         Args:
-            query_text: Text query string
-            k: Number of results to return
-            min_confidence: Minimum confidence score (0-1000 scale)
+            query_text: Full-text query string.
+            k: Maximum number of results.
+            min_confidence: Minimum iFind rank score (0-1000, iFind path only).
 
         Returns:
-            List of (entity_id, relevance_score) tuples
+            List of (entity_id, score) tuples ordered by descending relevance.
         """
+        docs_table = self._t("docs")
         cursor = self.conn.cursor()
         try:
-            # Call server-side procedure for unified logic
-            # Signature: (queryText, k, minConfidence)
+            # iFind path — available when idx_docs_text_ifind exists
+            try:
+                if min_confidence > 0:
+                    cursor.execute(
+                        f"SELECT TOP ? d.id, %FIND.Rank(d.text, ?) AS bm25 "
+                        f"FROM {docs_table} d "
+                        f"WHERE %FIND(d.text, ?) > 0 AND %FIND.Rank(d.text, ?) >= ? "
+                        f"ORDER BY bm25 DESC",
+                        [k, query_text, query_text, query_text, min_confidence],
+                    )
+                else:
+                    cursor.execute(
+                        f"SELECT TOP ? d.id, %FIND.Rank(d.text, ?) AS bm25 "
+                        f"FROM {docs_table} d "
+                        f"WHERE %FIND(d.text, ?) > 0 "
+                        f"ORDER BY bm25 DESC",
+                        [k, query_text, query_text],
+                    )
+                results = cursor.fetchall()
+                return [(row[0], float(row[1])) for row in results]
+            except Exception as ifind_err:
+                if "-359" not in str(ifind_err) and "FIND" not in str(ifind_err).upper():
+                    raise
+                # iFind not available on this IRIS build — fall back to LIKE
+                logger.debug(
+                    "kg_TXT: iFind unavailable (%s), using LIKE fallback", ifind_err
+                )
+
+            # LIKE fallback — no BM25 ranking, score = 1.0 for all matches
+            terms = query_text.split()
+            if not terms:
+                return []
+            conditions = " AND ".join(["d.text LIKE ?" for _ in terms])
+            like_params = [f"%{t}%" for t in terms]
             cursor.execute(
-                "CALL iris_vector_graph.kg_TXT(?, ?, ?)",
-                [query_text, k, min_confidence],
+                f"SELECT TOP {k} d.id, 1.0 AS score "
+                f"FROM {docs_table} d "
+                f"WHERE {conditions}",
+                like_params,
             )
             results = cursor.fetchall()
-            return [(entity_id, float(score)) for entity_id, score in results]
+            return [(row[0], float(row[1])) for row in results]
 
         except Exception as e:
-            logger.error(f"kg_TXT failed: {e}")
+            logger.error("kg_TXT failed: %s", e)
             raise
         finally:
             cursor.close()

{iris_vector_graph-2.18.0 → iris_vector_graph-2.18.2}/iris_vector_graph/engine.py

@@ -212,6 +212,11 @@ class IRISGraphEngine(
             self._store._ledger_guard = self._ledger_guard
         except Exception:  # pragma: no cover - foreign store objects
             pass
+        # Assume graph_id column exists by default (post-214 schema).
+        # Set to False by initialize_schema() if the probe finds the column absent,
+        # allowing create_node to emit a compatible INSERT on pre-214 schemas.
+        # Defaulting True avoids an eager SQL round-trip on every engine construction.
+        self._nodes_has_graph_id: bool = True
         logger.debug(
             "IRISGraphEngine initialized (dim=%s dtype=%s)",
             embedding_dimension or "auto",
@@ -229,6 +234,24 @@ class IRISGraphEngine(
         """Per-instance table qualifier — use this instead of the free _table() in all mixin code."""
         return _table(name, prefix=self._schema_prefix)
 
+    def _probe_nodes_graph_id(self) -> bool:
+        """Return True if Graph_KG.nodes already has a graph_id column.
+
+        Called once at engine init.  Allows create_node to emit a compatible
+        INSERT on pre-214 schemas (no graph_id column) without failing.
+        """
+        try:
+            cur = self.conn.cursor()
+            cur.execute(
+                "SELECT COUNT(*) FROM INFORMATION_SCHEMA.COLUMNS "
+                "WHERE TABLE_SCHEMA = 'Graph_KG' AND TABLE_NAME = 'nodes' "
+                "AND COLUMN_NAME = 'graph_id'"
+            )
+            row = cur.fetchone()
+            return bool(row and int(row[0]) > 0)
+        except Exception:
+            return False
+
     @classmethod
     def from_connect(
         cls,

{iris_vector_graph-2.18.0 → iris_vector_graph-2.18.2}/iris_vector_graph/fusion.py

@@ -153,7 +153,12 @@ class HybridSearchFusion:
                 search_modes.append("text")
                 logger.info(f"Text search returned {len(text_results)} results")
             except Exception as e:
-                logger.warning(f"Text search failed: {e}")
+                # Re-raise so callers know hybrid fusion lost the text leg.
+                # A silent WARNING here made kg_TXT's SQLCODE -51 bug undetectable
+                # for multiple release cycles — callers saw "hybrid" results that
+                # were actually pure vector-only with no indication of the failure.
+                logger.error("kg_TXT failed — text leg absent from hybrid fusion: %s", e)
+                raise
 
         # Graph expansion (if we have initial results)
         if result_lists:

{iris_vector_graph-2.18.0 → iris_vector_graph-2.18.2}/iris_vector_graph/schema.py

@@ -111,6 +111,8 @@ CREATE TABLE Graph_KG.docs(
   text  VARCHAR(4000) %EXACT
 );
 
+CREATE INDEX idx_docs_text_ifind ON Graph_KG.docs(text) INDEXTYPE = %iFind.Index.Basic;
+
 CREATE TABLE IF NOT EXISTS Graph_KG.fhir_bridges (
     fhir_code        VARCHAR(64) %EXACT NOT NULL,
     kg_node_id       VARCHAR(256) %EXACT NOT NULL,
@@ -252,6 +254,10 @@ CREATE INDEX idx_edges_confidence ON Graph_KG.rdf_edges(JSON_VALUE(qualifiers, '
                 "idx_props_val_ifind",
                 "CREATE INDEX idx_props_val_ifind ON Graph_KG.rdf_props(val) INDEXTYPE = %iFind.Index.Basic",
             ),
+            (
+                "idx_docs_text_ifind",
+                "CREATE INDEX idx_docs_text_ifind ON Graph_KG.docs(text) INDEXTYPE = %iFind.Index.Basic",
+            ),
             (
                 "idx_edges_confidence",
                 "CREATE INDEX idx_edges_confidence ON Graph_KG.rdf_edges(JSON_VALUE(qualifiers, '$.confidence' RETURNING INTEGER))",
@@ -260,7 +266,7 @@ CREATE INDEX idx_edges_confidence ON Graph_KG.rdf_edges(JSON_VALUE(qualifiers, '
             ("drop_idx_props_key_val", "DROP INDEX idx_props_key_val"),
         ]
 
-        _OPTIONAL_INDEXES = {"idx_props_val_ifind", "idx_edges_confidence"}
+        _OPTIONAL_INDEXES = {"idx_props_val_ifind", "idx_docs_text_ifind", "idx_edges_confidence"}
 
         status = {}
         for name, sql in indexes:
@@ -371,18 +377,28 @@ CREATE INDEX idx_edges_confidence ON Graph_KG.rdf_edges(JSON_VALUE(qualifiers, '
             return False
 
     @staticmethod
-    def add_graph_id_to_nodes(cursor) -> Dict[str, Any]:
-        """Spec 214: add graph_id to nodes table; migrate __graph pseudo-props.
+    def add_graph_id_to_nodes(cursor, recreate_pk: bool = False) -> Dict[str, Any]:
+        """Spec 214: add graph_id column to nodes; migrate __graph pseudo-props.
+
+        This migration is safe to run on a live cluster.  It is additive-only by
+        default: it adds the column and migrates data without touching the primary key.
+        The compound PK recreation (step 4+) is gated behind ``recreate_pk=True``
+        and is intentionally NOT called from ``ensure_indexes`` because the IRIS
+        ``RENAME TABLE`` syntax is ``ALTER TABLE old RENAME new`` (without schema
+        qualification on the new name), and the intermediate ``DROP TABLE nodes``
+        step is destructive and non-recoverable on connection loss.
 
         Step 1 (DDL, auto-commits in IRIS):
           ALTER TABLE nodes ADD COLUMN graph_id VARCHAR(256) %EXACT NOT NULL DEFAULT ''
         Step 2-3 (DML transaction): migrate __graph rows; delete them from rdf_props.
-        Step 4-7 (recreation transaction): recreate nodes with new PK(node_id, graph_id)
-          and UNIQUE(node_id); rename or recreate FKs on dependent tables.
+        Step 4+ (optional, recreate_pk=True only): recreate nodes with compound PK
+          (node_id, graph_id) and UNIQUE(node_id).  Requires explicit opt-in because
+          it drops the existing nodes table — only safe on a fresh schema or after a
+          verified full backup.  IRIS rename syntax: ALTER TABLE nodes_new RENAME nodes
         """
         result: Dict[str, Any] = {"column_added": False, "rows_migrated": 0, "pk_recreated": False}
 
-        # Step 1 — DDL (auto-commits)
+        # Step 1 — DDL (auto-commits in IRIS)
         try:
             cursor.execute(
                 "ALTER TABLE Graph_KG.nodes ADD COLUMN graph_id VARCHAR(256) %EXACT NOT NULL DEFAULT ''"
@@ -396,7 +412,7 @@ CREATE INDEX idx_edges_confidence ON Graph_KG.rdf_edges(JSON_VALUE(qualifiers, '
                 logger.warning("add_graph_id_to_nodes step1 failed: %s", e)
                 return result
 
-        # Step 2-3 — DML: migrate __graph values
+        # Step 2-3 — DML: migrate existing __graph pseudo-prop values
         try:
             cursor.execute(
                 "UPDATE Graph_KG.nodes n SET n.graph_id = "
@@ -415,7 +431,15 @@ CREATE INDEX idx_edges_confidence ON Graph_KG.rdf_edges(JSON_VALUE(qualifiers, '
         except Exception as e:
             logger.warning("add_graph_id_to_nodes migration DML failed: %s", e)
 
-        # Step 4-7 — check if compound PK already exists; if not, recreate table
+        if not recreate_pk:
+            # Default path: additive migration only. The UNIQUE(node_id) constraint on
+            # the existing table is sufficient for all current callers. The compound PK
+            # is only required for strict multi-tenant isolation and must be opted into
+            # explicitly via recreate_pk=True after a full backup.
+            return result
+
+        # Step 4+ — optional compound-PK recreation (recreate_pk=True only).
+        # Check if it already exists first — safe to skip if so.
         try:
             cursor.execute(
                 "SELECT COUNT(*) FROM INFORMATION_SCHEMA.TABLE_CONSTRAINTS "
@@ -446,20 +470,20 @@ CREATE INDEX idx_edges_confidence ON Graph_KG.rdf_edges(JSON_VALUE(qualifiers, '
                 "SELECT node_id, graph_id, created_at FROM Graph_KG.nodes"
             )
             cursor.execute("DROP TABLE Graph_KG.nodes")
-            # Attempt RENAME
-            renamed = False
+            # IRIS rename syntax: ALTER TABLE old_name RENAME new_name
+            # The new name must NOT be schema-qualified.
             try:
-                cursor.execute("RENAME TABLE Graph_KG.nodes_new TO Graph_KG.nodes")
-                renamed = True
-            except Exception:
-                pass
-            if not renamed:
-                # RENAME not supported; recreate FKs pointing at nodes_new under the new name.
-                # In IRIS, we can alias or accept nodes_new as the canonical table until a
-                # proper rename path is available.  Log a warning.
-                logger.warning(
-                    "RENAME TABLE not supported; Graph_KG.nodes_new has the new schema. "
-                    "Manual intervention required to rename nodes_new → nodes."
+                cursor.execute("ALTER TABLE Graph_KG.nodes_new RENAME nodes")
+                result["pk_recreated"] = True
+            except Exception as rename_err:
+                # Rename failed after DROP — data is in nodes_new, nodes is gone.
+                # Log loudly; caller must run ALTER TABLE Graph_KG.nodes_new RENAME nodes
+                # manually to recover.
+                logger.error(
+                    "add_graph_id_to_nodes: DROP succeeded but RENAME failed (%s). "
+                    "Data is in Graph_KG.nodes_new. Run: "
+                    "ALTER TABLE Graph_KG.nodes_new RENAME nodes",
+                    rename_err,
                 )
             try:
                 conn = getattr(cursor, "connection", None)
@@ -467,7 +491,6 @@ CREATE INDEX idx_edges_confidence ON Graph_KG.rdf_edges(JSON_VALUE(qualifiers, '
                     conn.commit()
             except Exception:
                 pass
-            result["pk_recreated"] = True
         except Exception as e:
             logger.warning("add_graph_id_to_nodes table recreation failed: %s", e)
             try:
@@ -585,7 +608,8 @@ CREATE INDEX idx_edges_confidence ON Graph_KG.rdf_edges(JSON_VALUE(qualifiers, '
             cursor.execute(sql, [node_id, label])
         """
         templates = {
-            "nodes": "INSERT INTO Graph_KG.nodes (node_id, graph_id) SELECT ?, ? WHERE NOT EXISTS (SELECT 1 FROM Graph_KG.nodes WHERE node_id = ? AND graph_id = ?)",
+            "nodes": "INSERT INTO Graph_KG.nodes (node_id) SELECT ? WHERE NOT EXISTS (SELECT 1 FROM Graph_KG.nodes WHERE node_id = ?)",
+            "nodes_with_graph": "INSERT INTO Graph_KG.nodes (node_id, graph_id) SELECT ?, ? WHERE NOT EXISTS (SELECT 1 FROM Graph_KG.nodes WHERE node_id = ?)",
             "rdf_labels": "INSERT INTO Graph_KG.rdf_labels (s, label) SELECT ?, ? WHERE NOT EXISTS (SELECT 1 FROM Graph_KG.rdf_labels WHERE s = ? AND label = ?)",
             "rdf_props": 'INSERT INTO Graph_KG.rdf_props (s, "key", val) SELECT ?, ?, ? WHERE NOT EXISTS (SELECT 1 FROM Graph_KG.rdf_props WHERE s = ? AND "key" = ?)',
             "rdf_edges": "INSERT INTO Graph_KG.rdf_edges (s, p, o_id) SELECT ?, ?, ? WHERE NOT EXISTS (SELECT 1 FROM Graph_KG.rdf_edges WHERE s = ? AND p = ? AND o_id = ?)",
@@ -789,13 +813,14 @@ END
             f"""
 CREATE OR REPLACE PROCEDURE {table_schema}.kg_TXT(
   IN q VARCHAR(4000),
-  IN k INT
+  IN k INT,
+  IN minConfidence INT
 )
 LANGUAGE SQL
 BEGIN
-  SELECT TOP :k d.id, %FIND.Rank(d.text, :q) AS bm25
+  SELECT d.id, %FIND.Rank(d.text, :q) AS bm25
   FROM {table_schema}.docs d
-  WHERE %FIND(d.text, :q) > 0
+  WHERE %FIND(d.text, :q) > 0 AND %FIND.Rank(d.text, :q) >= :minConfidence
   ORDER BY bm25 DESC;
 END
 """,
@@ -816,7 +841,7 @@ BEGIN
   ),
   K AS (
     SELECT ROW_NUMBER() OVER (ORDER BY bm25 DESC) AS r, id, bm25
-    FROM {table_schema}.kg_TXT(:qtext, :k2)
+    FROM {table_schema}.kg_TXT(:qtext, :k2, 0)
   ),
   F AS (
     SELECT COALESCE(V.id, K.id) AS id,

{iris_vector_graph-2.18.0 → iris_vector_graph-2.18.2}/pyproject.toml

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

{iris_vector_graph-2.18.0 → iris_vector_graph-2.18.2}/tests/conftest.py

@@ -59,17 +59,25 @@ def iris_test_container():
     except Exception:
         pass
 
-    # 2. If not found, fail rather than skip — a missing container is a developer
-    #    error, not an expected environment variant.  pytest.skip produces silent
-    #    fake-green; pytest.fail surfaces it as a hard failure.
-    #    CI may set IVG_AUTO_START_CONTAINER=1 to spin up the container instead.
+    # 2. If not found: fail on developer machines (missing container = error);
+    #    skip in CI when SKIP_IRIS_TESTS=true (container not provisioned in that job).
+    #    pytest.skip produces silent fake-green on dev machines — pytest.fail surfaces
+    #    the problem.  CI sets SKIP_IRIS_TESTS=true explicitly to opt into skipping.
     if container is None:
         auto_start = os.environ.get("IVG_AUTO_START_CONTAINER", "0") not in ("0", "false", "no")
-        if not auto_start:
+        if auto_start:
+            pass  # fall through to start the container
+        elif os.environ.get("SKIP_IRIS_TESTS", "false").lower() == "true":
+            pytest.skip(
+                f"IRIS container '{_GQS_CONTAINER}' not running — "
+                f"skipped because SKIP_IRIS_TESTS=true"
+            )
+        else:
             pytest.fail(
                 f"IRIS container '{_GQS_CONTAINER}' is not running. "
                 f"Start it with: scripts/enterprise-container.sh up\n"
-                f"(Set IVG_AUTO_START_CONTAINER=1 to start automatically.)"
+                f"(Set IVG_AUTO_START_CONTAINER=1 to start automatically, "
+                f"or SKIP_IRIS_TESTS=true to skip in CI.)"
             )
         _sp.run(["docker", "rm", "-f", _GQS_CONTAINER], capture_output=True)
         logger.info("Starting fresh Community IRIS container: %s", _GQS_CONTAINER)