iris-vector-graph 4.2.2__tar.gz → 4.2.3__tar.gz

{iris_vector_graph-4.2.2 → iris_vector_graph-4.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: iris-vector-graph
-Version: 4.2.2
+Version: 4.2.3
 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-4.2.2 → iris_vector_graph-4.2.3}/iris_vector_graph/cypher_api.py

@@ -198,6 +198,11 @@ def _run_cypher(query: str, parameters: dict | None = None, limit: int = 1000) -
                     _reset_engine()
                     continue
                 raise
+    error = getattr(result, "error", None)
+    if isinstance(error, str) and error:
+        # execute_sql folds a failed statement into IVGResult.error; answering "OK, no rows" for it hid
+        # a parameter error from the caller as an empty graph.
+        raise RuntimeError(error)
     columns = result.columns
     rows = result.rows
     if len(rows) > limit:

{iris_vector_graph-4.2.2 → iris_vector_graph-4.2.3}/iris_vector_graph/migrations/docs_and_edge_vectors.py

@@ -48,6 +48,8 @@ import logging
 from dataclasses import dataclass, field
 from typing import Callable, Dict, List, Optional, Sequence, Tuple
 
+from iris_vector_graph.schema import GraphSchema
+
 logger = logging.getLogger(__name__)
 
 #: The schema every statement here qualifies. Overridable for a non-default install.
@@ -264,10 +266,37 @@ def finish_docs(conn, *, schema: str = DEFAULT_SCHEMA) -> None:
 def prepare_edge_vectors(
     conn, dimension: int, *, dtype: str = "DOUBLE", schema: str = DEFAULT_SCHEMA
 ) -> None:
-    """Run :func:`edge_vectors_prepare_sql`, tolerating a re-run."""
+    """Run :func:`edge_vectors_prepare_sql`, tolerating a re-run.
+
+    A staging or quarantine table a failed pass left at a different width is rebuilt first: a re-run that
+    reused it refused every row again (-104), and the operator had to find and drop both by hand.
+    """
+    _reset_wrong_width_tables(conn, dimension, schema)
     _run_tolerantly(conn, edge_vectors_prepare_sql(dimension, dtype=dtype, schema=schema))
 
 
+def _reset_wrong_width_tables(conn, dimension: int, schema: str) -> None:
+    cursor = conn.cursor()
+    try:
+        for table in (f"{schema}.kg_EdgeEmbeddings{STAGING_SUFFIX}", f"{schema}.edge_vector_quarantine"):
+            declared = GraphSchema.get_embedding_dimension(cursor, table)
+            if declared is None or declared == int(dimension):
+                continue
+            rows = _read(cursor, f"SELECT COUNT(*) FROM {table}")
+            held = int(rows[0][0]) if rows and rows[0] and rows[0][0] else 0
+            if held:
+                raise RuntimeError(
+                    f"{table} holds {held} row(s) at width {declared}, but the edge vectors are being placed "
+                    f"at width {dimension}. Those rows cannot be moved to the new width; resolve them, then "
+                    "drop the table and re-run."
+                )
+            logger.warning("Rebuilding empty %s: it was left at width %s, the run needs %s", table, declared, dimension)
+            cursor.execute(f"DROP TABLE {table}")
+        _commit(conn)
+    finally:
+        _close(cursor)
+
+
 def finish_edge_vectors(conn, *, schema: str = DEFAULT_SCHEMA) -> None:
     """Run :func:`edge_vectors_finish_sql`, tolerating a re-run."""
     _run_tolerantly(conn, edge_vectors_finish_sql(schema))

{iris_vector_graph-4.2.2 → iris_vector_graph-4.2.3}/iris_vector_graph/migrations/graph_scoped_embeddings.py

@@ -812,6 +812,8 @@ class _Migrator:
         todo = [row for row in plan.rows if row.node_id in pending]
         # Each chunk is one transaction, in key order, so the watermark above still names exactly
         # the rows a killed pass completed: a chunk is in staging/quarantine whole or not at all.
+        done = 0
+        logger.info("Placing %d row(s) of %s into graph-scoped storage", len(todo), plan.source)
         for chunk in _chunks(todo):
             placed: Dict[str, List[str]] = {}
             declined: Dict[str, List[str]] = {}
@@ -837,6 +839,9 @@ class _Migrator:
                     [plan.source, plan.dimension, plan.dtype, reason, *ids],
                 )
             self._commit()
+            done += len(chunk)
+            if done == len(todo) or (done // BATCH_ROWS) % 25 == 0:
+                logger.info("  %s: %d of %d rows placed", plan.source, done, len(todo))
         self._commit()
 
     def _reshape(self, cursor, plan: _Plan) -> None:
@@ -845,7 +850,15 @@ class _Migrator:
         self._tolerate(cursor, f"DROP TABLE {self._t(plan.source)}")
         self._commit()
         self._rename(cursor, staging, plan.source)
+        # The vector index is built by background work-queue workers while this call waits, and on a large
+        # table that is the long silent stretch of the upgrade (about 20 minutes for 206K 768-dim vectors).
+        logger.info(
+            "Building the vector index on %s; this can take many minutes for a large table and prints "
+            "nothing until it finishes",
+            plan.source,
+        )
         state, error = self.engine._attempt_route_index(cursor, plan.source)
+        logger.info("Vector index on %s: %s", plan.source, state)
         self._note_index(plan.source, state, error)
         self.engine._record_route_index_state(
             cursor, plan.source, plan.registry_graph, state, error

{iris_vector_graph-4.2.2 → iris_vector_graph-4.2.3}/iris_vector_graph/migrations/upgrade.py

@@ -237,6 +237,17 @@ def _resolve_steps(steps: Optional[Sequence[str]]) -> Tuple[str, ...]:
 
 
 def _run_step(name: str, conn, **kw) -> StepResult:
+    import time
+
+    started = time.perf_counter()
+    logger.info("upgrade_to_4_0_0: step %s starting%s", name, " (dry run)" if kw.get("dry_run") else "")
+    try:
+        return _run_step_body(name, conn, **kw)
+    finally:
+        logger.info("upgrade_to_4_0_0: step %s finished in %.1fs", name, time.perf_counter() - started)
+
+
+def _run_step_body(name: str, conn, **kw) -> StepResult:
     dry_run = kw["dry_run"]
     schema = kw["schema"]
 

{iris_vector_graph-4.2.2 → iris_vector_graph-4.2.3}/iris_vector_graph/stores/iris_sql_store.py

@@ -1132,7 +1132,12 @@ class IRISGraphStore:
     def execute_sql(self, sql: str, params: list, read_only: bool = True) -> IVGResult:
         cursor = self.conn.cursor()
         try:
-            cursor.execute(sql, params)
+            # No placeholders, no parameter list: a driver can reject `execute(sql, [])` against a statement
+            # it has cached with a different parameter count ("Invalid number of parameters").
+            if params:
+                cursor.execute(sql, params)
+            else:
+                cursor.execute(sql)
             cols = [d[0] for d in cursor.description] if cursor.description else []
             rows = cursor.fetchall()
             if "__rn" in cols:

{iris_vector_graph-4.2.2 → iris_vector_graph-4.2.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "iris-vector-graph"
-version = "4.2.2"
+version = "4.2.3"
 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-4.2.2 → iris_vector_graph-4.2.3}/tests/unit/test_cypher_api_admin.py

@@ -248,14 +248,15 @@ class TestNeo4jCompatVariants:
                 {"statement": "MATCH (m) RETURN count(m)", "parameters": {}},
             ]
         })
-        assert resp.status_code in (200, 401, 500)
+        assert resp.status_code in (200, 400, 401, 500)
 
     def test_neo4j_query_v2_different_db(self, client):
         """Query v2 with different db_name."""
         tc, _ = client
         resp = tc.post("/db/mydb/query/v2",
                        json={"statement": "MATCH (n) RETURN n", "parameters": {}})
-        assert resp.status_code in (200, 201, 401, 404, 422, 500)
+        # 400 is a statement the shared mock engine was told to fail (error surfaced, not hidden as OK).
+        assert resp.status_code in (200, 201, 400, 401, 404, 422, 500)
 
 
 class TestServerInfoVariants:

{iris_vector_graph-4.2.2 → iris_vector_graph-4.2.3}/tests/unit/test_cypher_api_coverage.py

@@ -233,9 +233,10 @@ class TestAdminEndpoints:
             columns=[], rows=[], error="parse error",
             metadata=MagicMock(warnings=[], index_usage=[], optimization_applied=[]),
         )
+        # A failed statement is an error to the caller, not "OK" with no rows (Mindwalk, 4.2.2).
         with patch("iris_vector_graph.cypher_api._get_engine", return_value=mock_eng):
-            result = _run_cypher("BAD", {})
-        assert "error" in result or isinstance(result, dict)
+            with pytest.raises(RuntimeError, match="parse error"):
+                _run_cypher("BAD", {})
 
 
 # ---------------------------------------------------------------------------

iris_vector_graph-4.2.3/tests/unit/test_edge_vector_resume_width.py

@@ -0,0 +1,107 @@
+"""A failed edge-vector step must not poison its resume.
+
+Mindwalk: an edge-vector step run at the wrong width left ``edge_vector_quarantine`` and
+``kg_EdgeEmbeddings_ivg400`` declared at that width, and a resume reused them, so every row failed again.
+"""
+
+import pytest
+
+from iris_vector_graph.migrations import docs_and_edge_vectors as dev
+
+
+class Conn:
+    def __init__(self, widths, rows):
+        self.widths = widths  # {"Graph_KG.table": declared width}
+        self.rows = rows  # {"Graph_KG.table": row count}
+        self.executed = []
+
+    def cursor(self):
+        return Cursor(self)
+
+    def commit(self):
+        pass
+
+
+class Cursor:
+    def __init__(self, conn):
+        self.conn = conn
+        self._rows = []
+
+    def execute(self, sql, params=None):
+        flat = " ".join(sql.split())
+        self.conn.executed.append(flat)
+        if flat.startswith("SELECT COUNT(*) FROM "):
+            self._rows = [(self.conn.rows.get(flat.rsplit(" ", 1)[1], 0),)]
+
+    def fetchall(self):
+        return self._rows
+
+    def fetchone(self):
+        return self._rows[0] if self._rows else None
+
+    def close(self):
+        pass
+
+
+@pytest.fixture
+def declared(monkeypatch):
+    def fake(cursor, table):
+        return cursor.conn.widths.get(table)
+
+    monkeypatch.setattr(dev.GraphSchema, "get_embedding_dimension", staticmethod(fake))
+
+
+def drops(conn):
+    return [s for s in conn.executed if s.startswith("DROP TABLE")]
+
+
+def test_an_empty_table_at_the_wrong_width_is_dropped_so_prepare_rebuilds_it(declared):
+    tables = {"Graph_KG.kg_EdgeEmbeddings_ivg400": 8, "Graph_KG.edge_vector_quarantine": 8}
+    conn = Conn(tables, {})
+
+    dev._reset_wrong_width_tables(conn, 16, "Graph_KG")
+
+    assert sorted(drops(conn)) == [
+        "DROP TABLE Graph_KG.edge_vector_quarantine",
+        "DROP TABLE Graph_KG.kg_EdgeEmbeddings_ivg400",
+    ]
+
+
+def test_a_table_at_the_right_width_is_left_alone(declared):
+    conn = Conn({"Graph_KG.kg_EdgeEmbeddings_ivg400": 16, "Graph_KG.edge_vector_quarantine": 16}, {})
+
+    dev._reset_wrong_width_tables(conn, 16, "Graph_KG")
+
+    assert drops(conn) == []
+
+
+def test_a_table_that_is_not_there_yet_is_left_alone(declared):
+    conn = Conn({}, {})
+
+    dev._reset_wrong_width_tables(conn, 16, "Graph_KG")
+
+    assert drops(conn) == []
+
+
+def test_a_wrong_width_table_that_holds_rows_is_refused_not_dropped(declared):
+    conn = Conn({"Graph_KG.edge_vector_quarantine": 8}, {"Graph_KG.edge_vector_quarantine": 5})
+
+    with pytest.raises(RuntimeError, match="edge_vector_quarantine.*8.*16"):
+        dev._reset_wrong_width_tables(conn, 16, "Graph_KG")
+
+    assert drops(conn) == []
+
+
+def test_each_upgrade_step_logs_when_it_starts_and_finishes(caplog, monkeypatch):
+    """Mindwalk: the embeddings step is silent for ~20 minutes and looks like a hang."""
+    import logging
+
+    from iris_vector_graph.migrations import upgrade as up
+
+    monkeypatch.setattr(up, "_run_step_body", lambda name, conn, **kw: up.StepResult(name))
+    with caplog.at_level(logging.INFO, logger=up.logger.name):
+        up._run_step("embeddings", object(), dry_run=False, schema="Graph_KG")
+
+    messages = [r.getMessage() for r in caplog.records]
+    assert any("step embeddings starting" in m for m in messages)
+    assert any("step embeddings finished in" in m for m in messages)

iris_vector_graph-4.2.3/tests/unit/test_execute_sql_error_surface.py

@@ -0,0 +1,58 @@
+"""A failed statement is an error to the caller, and a statement with no parameters is sent with none.
+
+Mindwalk (4.2.2, a populated 653K-node graph): ``MATCH (n) RETURN count(n) AS c`` through ``/api/cypher`` came back
+``status OK, rows []`` while the server logged ``<PARAMETER ERROR> Invalid number of parameters``. ``execute_sql``
+had caught the error into ``IVGResult.error`` and ``_run_cypher`` never looked at it. The statement itself was
+sent as ``cursor.execute(sql, [])`` for a query with no placeholders.
+"""
+
+from unittest.mock import MagicMock
+
+import pytest
+
+from iris_vector_graph.stores.iris_sql_store import IRISGraphStore
+
+
+def _store(cursor):
+    store = IRISGraphStore.__new__(IRISGraphStore)
+    store.conn = MagicMock()
+    store.conn.cursor.return_value = cursor
+    return store
+
+
+def test_a_statement_without_parameters_is_executed_without_a_parameter_list():
+    cursor = MagicMock()
+    cursor.description = [("c",)]
+    cursor.fetchall.return_value = [(7,)]
+
+    result = _store(cursor).execute_sql("SELECT COUNT(*) AS c FROM Graph_KG.nodes", [])
+
+    cursor.execute.assert_called_once_with("SELECT COUNT(*) AS c FROM Graph_KG.nodes")
+    assert result.rows == [[7]]
+
+
+def test_a_statement_with_parameters_still_gets_them():
+    cursor = MagicMock()
+    cursor.description = [("n",)]
+    cursor.fetchall.return_value = []
+
+    _store(cursor).execute_sql("SELECT 1 FROM t WHERE a = ?", ["x"])
+
+    cursor.execute.assert_called_once_with("SELECT 1 FROM t WHERE a = ?", ["x"])
+
+
+def test_the_cypher_api_turns_a_failed_statement_into_an_error():
+    from iris_vector_graph import cypher_api
+    from iris_vector_graph.stores.iris_sql_store import IVGResult
+
+    class Engine:
+        def execute_cypher(self, query, parameters=None):
+            return IVGResult(columns=[], rows=[], error="<PARAMETER ERROR>; Details: Invalid number of parameters.")
+
+    cypher_api._engine_cache = Engine()
+    try:
+        with pytest.raises(Exception) as caught:
+            cypher_api._run_cypher("MATCH (n) RETURN count(n) AS c")
+    finally:
+        cypher_api._reset_engine()
+    assert "Invalid number of parameters" in str(caught.value)