matrx-orm 3.1.89__tar.gz → 3.1.91__tar.gz

{matrx_orm-3.1.89 → matrx_orm-3.1.91}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: matrx-orm
-Version: 3.1.89
+Version: 3.1.91
 Summary: Async-first PostgreSQL ORM with bidirectional migrations, schema introspection, many-to-many relationships, and built-in state caching
 Project-URL: Homepage, https://github.com/AI-Matrix-Engine/aidream-current
 Project-URL: Repository, https://github.com/AI-Matrix-Engine/aidream-current
@@ -25,7 +25,7 @@ Requires-Python: >=3.13
 Requires-Dist: asyncpg>=0.31.0
 Requires-Dist: cryptography>=43.0
 Requires-Dist: gitpython>=3.1.40
-Requires-Dist: matrx-utils>=2.0.19
+Requires-Dist: matrx-utils>=2.0.20
 Requires-Dist: psycopg-pool>=3.2.5
 Requires-Dist: psycopg[binary]>=3.2.5
 Requires-Dist: python-dotenv>=1.0

{matrx_orm-3.1.89 → matrx_orm-3.1.91}/matrx_orm/query/executor.py

@@ -494,6 +494,42 @@ class QueryExecutor:
     # Main SQL builder
     # ------------------------------------------------------------------
 
+    def _explicit_join_clauses(self, params: list[Any]) -> list[str]:
+        """SQL for every ``QueryBuilder.join()`` on this query.
+
+        Extracted so COUNT can emit the SAME joins the SELECT does. It could
+        not, and a ``.join(...).count()`` produced
+        ``SELECT COUNT(*) FROM base WHERE joined.col = $1`` — valid-looking SQL
+        that Postgres rejects with *missing FROM-clause entry*. Found 2026-08-20
+        via ``kg.entity.mentions``, which was dead on every call because its
+        total count is a joined count.
+        """
+        clauses: list[str] = []
+        for j in self._full_query_dict.get("joins", []) or []:
+            j_model = j.get("model")
+            if j_model is None or not hasattr(j_model, "_meta"):
+                raise ValidationError(
+                    model=self.model,
+                    reason="join() requires a model class with _meta",
+                    details={"join": j},
+                )
+            j_table = j_model._meta.qualified_table_name
+            j_type = (j.get("type") or "INNER").upper()
+            j_alias = j.get("alias")
+            j_on = j.get("on")
+            if not j_on:
+                raise ValidationError(
+                    model=self.model,
+                    reason="join() requires a non-empty `on` clause",
+                    details={"join": j},
+                )
+            j_on_sql = j_on.as_sql(params, current_table=self._base_ref())
+            if j_alias:
+                clauses.append(f"{j_type} JOIN {j_table} AS {j_alias} ON {j_on_sql}")
+            else:
+                clauses.append(f"{j_type} JOIN {j_table} ON {j_on_sql}")
+        return clauses
+
     def _build_query(self) -> tuple[str, list[Any]]:
         """Construct the SELECT SQL statement and bound parameter list."""
         params: list[Any] = []
@@ -536,29 +572,7 @@ class QueryExecutor:
 
         # 1b. Explicit JOIN clauses from QueryBuilder.join()
         explicit_joins: list[dict[str, Any]] = self._full_query_dict.get("joins", [])
-        for j in explicit_joins:
-            j_model = j.get("model")
-            if j_model is None or not hasattr(j_model, "_meta"):
-                raise ValidationError(
-                    model=self.model,
-                    reason="join() requires a model class with _meta",
-                    details={"join": j},
-                )
-            j_table = j_model._meta.qualified_table_name
-            j_type = (j.get("type") or "INNER").upper()
-            j_alias = j.get("alias")
-            j_on = j.get("on")
-            if not j_on:
-                raise ValidationError(
-                    model=self.model,
-                    reason="join() requires a non-empty `on` clause",
-                    details={"join": j},
-                )
-            j_on = j_on.as_sql(params, current_table=self._base_ref())
-            if j_alias:
-                join_clauses.append(f"{j_type} JOIN {j_table} AS {j_alias} ON {j_on}")
-            else:
-                join_clauses.append(f"{j_type} JOIN {j_table} ON {j_on}")
+        join_clauses.extend(self._explicit_join_clauses(params))
 
         # 2. Regular columns
         # When the caller lists an annotated alias in .values() (e.g. after
@@ -1550,18 +1564,33 @@ class QueryExecutor:
             return instances[0] if instances else None
         return self._make(results[0])
 
-    async def count(self) -> int:
-        """COUNT(*) for the current WHERE clause."""
+    def _build_count_query(self) -> tuple[str, list[Any]]:
+        """SQL + params for ``COUNT(*)`` over the current query.
+
+        Separate from :meth:`count` so the emission is testable without a
+        database — the join bug below shipped precisely because nothing could
+        assert on this string.
+        """
         params: list[Any] = []
         from_target = self._from_target(params)
+        # JOINs belong to the count as much as to the select — a WHERE that
+        # references a joined table is unrunnable without them.
+        join_clauses = self._explicit_join_clauses(params)
         where_clause, where_params = self._extract_where_clause()
         if where_clause and params:
             where_clause = _shift_param_refs(where_clause, len(params))
         params.extend(where_params)
 
         count_sql = f"SELECT COUNT(*) as count FROM {from_target}"
+        if join_clauses:
+            count_sql += " " + " ".join(join_clauses)
         if where_clause:
             count_sql += f" WHERE {where_clause}"
+        return count_sql, params
+
+    async def count(self) -> int:
+        """COUNT(*) for the current WHERE clause."""
+        count_sql, params = self._build_count_query()
 
         try:
             statement_timeout = self._full_query_dict.get("timeout")

{matrx_orm-3.1.89 → matrx_orm-3.1.91}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "matrx-orm"
-version = "3.1.89"
+version = "3.1.91"
 description = "Async-first PostgreSQL ORM with bidirectional migrations, schema introspection, many-to-many relationships, and built-in state caching"
 readme = "README.md"
 license = { text = "MIT" }
@@ -41,7 +41,7 @@ dependencies = [
     "gitpython>=3.1.40",
     "psycopg[binary]>=3.2.5",
     "psycopg-pool>=3.2.5",
-    "matrx-utils>=2.0.19",
+    "matrx-utils>=2.0.20",
     "pyyaml>=6.0.3",
     "python-dotenv>=1.0",
     "cryptography>=43.0",

{matrx_orm-3.1.89 → matrx_orm-3.1.91}/tests/level1/test_join_and_aggregate.py

@@ -18,7 +18,7 @@ the RAG ORM cleanup plan:
 from __future__ import annotations
 
 import pytest
-from matrx_orm import ColumnComparison, F
+from matrx_orm import ColumnComparison, Compare, F
 from matrx_orm.core.base import Model, ModelMeta
 from matrx_orm.core.expressions import Count, Min, Sum
 from matrx_orm.core.fields import (
@@ -396,3 +396,56 @@ class TestGroupByBareValuesProjectsGroupedColumns:
         assert "entity_id" in select_clause
         assert "COUNT(id) AS n" in sql
         assert "confidence" not in select_clause
+
+
+class TestJoinedCountSqlEmission:
+    """``count()`` must emit the SAME joins the select does.
+
+    Live defect (2026-08-20): it did not. ``kg.entity.mentions`` counts its
+    total through a join, so every call produced
+    ``SELECT COUNT(*) FROM rag.kg_chunks WHERE rag.kg_chunk_entities.entity_id = $1``
+    and Postgres rejected it with *missing FROM-clause entry for table
+    "kg_chunk_entities"* — the node was dead on 100% of calls.
+    """
+
+    def _joined_builder(self):
+        CE = _make_chunk_entity_model()
+        C = _make_chunk_model()
+        return (
+            QueryBuilder(C)
+            .join(
+                CE,
+                on=ColumnComparison(
+                    F("rag.kg_chunk_entities.chunk_id"), "=", F("rag.kg_chunks.id")
+                ),
+            )
+            .filter(
+                Compare(
+                    F("rag.kg_chunk_entities.entity_id"),
+                    "=",
+                    "33333333-3333-3333-3333-333333333333",
+                )
+            )
+        )
+
+    def test_count_includes_the_join(self):
+        sql, params = QueryExecutor(self._joined_builder()._build_query())._build_count_query()
+        assert sql.startswith("SELECT COUNT(*) as count FROM rag.kg_chunks")
+        assert (
+            "INNER JOIN rag.kg_chunk_entities "
+            "ON rag.kg_chunk_entities.chunk_id = rag.kg_chunks.id" in sql
+        )
+        from_pos = sql.index("FROM rag.kg_chunks")
+        join_pos = sql.index("INNER JOIN rag.kg_chunk_entities")
+        where_pos = sql.index("WHERE")
+        assert from_pos < join_pos < where_pos
+        assert params[-1] == "33333333-3333-3333-3333-333333333333"
+
+    def test_count_without_a_join_is_unchanged(self):
+        O = _make_order_model()
+        qb = QueryBuilder(O).filter(status="paid")
+        sql, params = QueryExecutor(qb._build_query())._build_count_query()
+        assert "JOIN" not in sql
+        assert sql.startswith("SELECT COUNT(*) as count FROM ")
+        assert "orders" in sql
+        assert params == ["paid"]