post-graph 1.2.0__tar.gz → 1.3.0__tar.gz

{post_graph-1.2.0 → post_graph-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: post-graph
-Version: 1.2.0
+Version: 1.3.0
 Summary: High-performance PostgreSQL-backed graph database library supporting multi-tenant realms, space sub-grouping, schema-per-realm, shadow auditing, and append-only data history.
 Project-URL: Homepage, https://github.com/crajah/post-graph
 Project-URL: Repository, https://github.com/crajah/post-graph

{post_graph-1.2.0 → post_graph-1.3.0}/post_graph/__init__.py

@@ -20,7 +20,7 @@ try:
 except ImportError:
     SQLAlchemyPostGraph = None
 
-__version__ = "1.2.0"
+__version__ = "1.3.0"
 
 __all__ = [
     "JSON_NULL",

{post_graph-1.2.0 → post_graph-1.3.0}/post_graph/client_asyncpg.py

@@ -1289,6 +1289,50 @@ class AsyncPostGraph:
         else:
             return await _op(self.connection)
 
+    async def count_edges(
+        self,
+        table_name: str,
+        realm: str,
+        filters: Optional[Dict[str, Any]] = None,
+        space: Optional[str] = None,
+        relation_type: Optional[str] = None,
+        where: Optional[List[tuple]] = None,
+    ) -> int:
+        """COUNT(*) over edges under the same predicates as :meth:`find_edges`."""
+        self._validate_identifier(table_name)
+        table_ref = self._get_table_ref(table_name, realm)
+
+        async def _op(conn):
+            params: list = [realm]
+            clauses = ""
+            if space and space != RESERVED_SPACE_ALL:
+                params.append(space)
+                clauses += f" AND (t.space = ${len(params)} OR (${len(params)} = 'default' AND (t.space IS NULL OR t.space = 'default')))"
+            if relation_type:
+                params.append(relation_type)
+                clauses += f" AND t.relation_type = ${len(params)}"
+            containment, absent_keys = self._prepare_filters(filters)
+            if containment is not None:
+                params.append(containment)
+                clauses += f" AND t.payload @> ${len(params)}::jsonb"
+            for key in absent_keys:
+                params.append(key)
+                clauses += f" AND NOT jsonb_exists(t.payload, ${len(params)})"
+            where_sql, _ = self._compile_where(where, params)
+            clauses += where_sql
+            try:
+                return await conn.fetchval(
+                    f"SELECT COUNT(*) FROM {table_ref} t WHERE t.realm = $1{clauses}",
+                    *params)
+            except asyncpg.UndefinedTableError:
+                raise TableNotFoundError(f"Edge table '{table_name}' does not exist.")
+
+        if isinstance(self.connection, asyncpg.Pool):
+            async with self.connection.acquire() as conn:
+                return await _op(conn)
+        else:
+            return await _op(self.connection)
+
     async def delete_vertices(
         self,
         table_name: str,
@@ -2328,18 +2372,23 @@ class AsyncPostGraph:
         self,
         table_name: str,
         realm: str,
-        filters: Dict[str, Any],
+        filters: Optional[Dict[str, Any]] = None,
         space: Optional[str] = None,
         relation_type: Optional[str] = None,
         limit: Optional[int] = None,
+        where: Optional[List[tuple]] = None,
+        order_by: Optional[str] = None,
+        descending: bool = False,
     ) -> List[Edge]:
         """Find edges whose payload matches the given key-value filters.
 
-        Matching is by JSONB containment; see :meth:`find_vertices` for the
-        semantics (type-sensitive, index-backed, containment for nested
-        values). Optional *relation_type* further restricts results.
+        Matching is by JSONB containment; *where*, *order_by* and *descending*
+        behave exactly as on :meth:`find_vertices`. Optional *relation_type*
+        further restricts results.
         """
         self._validate_identifier(table_name)
+        if order_by is not None:
+            self._validate_payload_key(order_by)
         table_ref = self._get_table_ref(table_name, realm)
 
         async def _op(conn):
@@ -2358,6 +2407,15 @@ class AsyncPostGraph:
             for key in absent_keys:
                 params.append(key)
                 clauses += f" AND NOT jsonb_exists(t.payload, ${len(params)})"
+            where_sql, numeric_keys = self._compile_where(where, params)
+            clauses += where_sql
+            if order_by is not None:
+                acc = f"t.payload->>'{order_by}'"
+                if order_by in numeric_keys:
+                    acc = f"({acc})::numeric"
+                order_clause = f"ORDER BY {acc} {'DESC' if descending else 'ASC'}, t.id ASC"
+            else:
+                order_clause = "ORDER BY t.id ASC"
             limit_clause = ""
             if limit:
                 params.append(limit)
@@ -2369,7 +2427,7 @@ class AsyncPostGraph:
                    to_jsonb(t)->>'embedding' AS embedding_text
             FROM {table_ref} t
             WHERE t.realm = $1{clauses}
-            ORDER BY t.id ASC{limit_clause}
+            {order_clause}{limit_clause}
             """
             try:
                 rows = await conn.fetch(query, *params)

{post_graph-1.2.0 → post_graph-1.3.0}/post_graph/client_sqlalchemy.py

@@ -1511,6 +1511,51 @@ class SQLAlchemyPostGraph:
         async with self.engine_or_connection.connect() as conn:
             return await _op(conn)
 
+    async def count_edges(
+        self,
+        table_name: str,
+        realm: str,
+        filters: Optional[Dict[str, Any]] = None,
+        space: Optional[str] = None,
+        relation_type: Optional[str] = None,
+        where: Optional[List[tuple]] = None,
+    ) -> int:
+        """COUNT(*) over edges under the same predicates as :meth:`find_edges`."""
+        self._validate_identifier(table_name)
+        table_ref = self._get_table_ref(table_name, realm)
+
+        async def _op(conn):
+            params: Dict[str, Any] = {"realm": realm}
+            clauses = ""
+            if space and space != RESERVED_SPACE_ALL:
+                params["space"] = space
+                clauses += " AND (t.space = :space OR (:space = 'default' AND (t.space IS NULL OR t.space = 'default')))"
+            if relation_type:
+                params["rtype"] = relation_type
+                clauses += " AND t.relation_type = :rtype"
+            containment, absent_keys = self._prepare_filters(filters)
+            if containment is not None:
+                params["fjson"] = containment
+                clauses += " AND t.payload @> CAST(:fjson AS jsonb)"
+            for i, key in enumerate(absent_keys):
+                pname = f"fabs{i}"
+                params[pname] = key
+                clauses += f" AND NOT jsonb_exists(t.payload, :{pname})"
+            where_sql, _ = self._compile_where(where, params)
+            clauses += where_sql
+            try:
+                result = await conn.execute(text(
+                    f"SELECT COUNT(*) FROM {table_ref} t WHERE t.realm = :realm{clauses}"),
+                    params)
+                return int(result.scalar_one())
+            except ProgrammingError:
+                raise TableNotFoundError(f"Edge table '{table_name}' does not exist.")
+
+        if isinstance(self.engine_or_connection, AsyncConnection):
+            return await _op(self.engine_or_connection)
+        async with self.engine_or_connection.connect() as conn:
+            return await _op(conn)
+
     async def delete_vertices(
         self,
         table_name: str,
@@ -2272,19 +2317,23 @@ class SQLAlchemyPostGraph:
         self,
         table_name: str,
         realm: str,
-        filters: Dict[str, Any],
+        filters: Optional[Dict[str, Any]] = None,
         space: Optional[str] = None,
         relation_type: Optional[str] = None,
         limit: Optional[int] = None,
+        where: Optional[List[tuple]] = None,
+        order_by: Optional[str] = None,
+        descending: bool = False,
     ) -> List[Edge]:
         """Find edges whose payload matches the given key-value filters.
 
-        Matching is by JSONB containment; see :meth:`find_vertices` for the
-        semantics (type-sensitive, index-backed, containment for nested
-        values, sentinels for null and absent keys). Optional *relation_type*
+        Matching is by JSONB containment; *where*, *order_by* and *descending*
+        behave exactly as on :meth:`find_vertices`. Optional *relation_type*
         further restricts results.
         """
         self._validate_identifier(table_name)
+        if order_by is not None:
+            self._validate_payload_key(order_by)
         table_ref = self._get_table_ref(table_name, realm)
 
         async def _op(conn):
@@ -2304,6 +2353,15 @@ class SQLAlchemyPostGraph:
                 pname = f"fabs{i}"
                 params[pname] = key
                 clauses += f" AND NOT jsonb_exists(t.payload, :{pname})"
+            where_sql, numeric_keys = self._compile_where(where, params)
+            clauses += where_sql
+            if order_by is not None:
+                acc = f"t.payload->>'{order_by}'"
+                if order_by in numeric_keys:
+                    acc = f"({acc})::numeric"
+                order_clause = f"ORDER BY {acc} {'DESC' if descending else 'ASC'}, t.id ASC"
+            else:
+                order_clause = "ORDER BY t.id ASC"
             limit_clause = ""
             if limit:
                 params["limit"] = limit
@@ -2315,7 +2373,7 @@ class SQLAlchemyPostGraph:
                    to_jsonb(t)->>'embedding' AS embedding_text
             FROM {table_ref} t
             WHERE t.realm = :realm{clauses}
-            ORDER BY t.id ASC{limit_clause}
+            {order_clause}{limit_clause}
             """
             try:
                 result = await conn.execute(text(query), params)

{post_graph-1.2.0 → post_graph-1.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "post-graph"
-version = "1.2.0"
+version = "1.3.0"
 description = "High-performance PostgreSQL-backed graph database library supporting multi-tenant realms, space sub-grouping, schema-per-realm, shadow auditing, and append-only data history."
 readme = "README.md"
 requires-python = ">=3.9"

{post_graph-1.2.0 → post_graph-1.3.0}/tests/test_range_queries.py

@@ -239,3 +239,64 @@ class TestSchemaPerRealm:
                 await c.delete_realm(realm)
             except Exception:
                 pass
+
+
+class TestEdgeRangeQueries:
+    """The same where/order_by semantics on edges, which is what a bi-temporal
+    relation store needs: t_created/t_expired live on edge payloads."""
+
+    async def _seed_edges(self, c, realm):
+        await c.create_vertex_table("rq_nodes2", realm=realm)
+        await c.create_edge_table("rq_rel", from_vertex_table="rq_nodes2",
+                                  to_vertex_table="rq_nodes2", realm=realm)
+        a = await c.add_vertex("rq_nodes2", realm=realm, payload={"name": "a"})
+        b = await c.add_vertex("rq_nodes2", realm=realm, payload={"name": "b"})
+        stamps = ["2026-01-01T00:00:00", "2026-02-01T00:00:00", "2026-03-01T00:00:00"]
+        for i, ts in enumerate(stamps):
+            payload = {"t_created": ts, "k": i}
+            if i == 0:
+                payload["t_expired"] = "2026-02-15T00:00:00"
+            await c.add_edge("rq_rel", realm=realm, from_id=a.id, to_id=b.id,
+                             relation_type=f"r{i}", payload=payload)
+        return "rq_rel"
+
+    async def test_edge_where_text_range_and_order(self, any_client, clean_realm):
+        c, realm = any_client, clean_realm
+        t = await self._seed_edges(c, realm)
+        got = await c.find_edges(t, realm=realm,
+                                 where=[("t_created", ">", "2026-01-15T00:00:00")],
+                                 order_by="t_created", descending=True)
+        assert [e.payload["k"] for e in got] == [2, 1]
+
+    async def test_edge_is_null_and_not_null(self, any_client, clean_realm):
+        c, realm = any_client, clean_realm
+        t = await self._seed_edges(c, realm)
+        expired = await c.find_edges(t, realm=realm,
+                                     where=[("t_expired", "not_null", None)])
+        assert [e.payload["k"] for e in expired] == [0]
+        live = await c.find_edges(t, realm=realm,
+                                  where=[("t_expired", "is_null", None)])
+        assert sorted(e.payload["k"] for e in live) == [1, 2]
+
+    async def test_count_edges(self, any_client, clean_realm):
+        c, realm = any_client, clean_realm
+        t = await self._seed_edges(c, realm)
+        assert await c.count_edges(t, realm=realm) == 3
+        assert await c.count_edges(
+            t, realm=realm,
+            where=[("t_created", ">=", "2026-02-01T00:00:00")]) == 2
+        assert await c.count_edges(t, realm=realm, relation_type="r0") == 1
+
+    async def test_edge_numeric_where(self, any_client, clean_realm):
+        c, realm = any_client, clean_realm
+        t = await self._seed_edges(c, realm)
+        got = await c.find_edges(t, realm=realm, where=[("k", ">=", 1)],
+                                 order_by="k")
+        assert [e.payload["k"] for e in got] == [1, 2]
+
+    async def test_edge_payload_index(self, any_client, clean_realm):
+        c, realm = any_client, clean_realm
+        t = await self._seed_edges(c, realm)
+        n1 = await c.create_payload_index(t, realm=realm, key="t_created")
+        n2 = await c.create_payload_index(t, realm=realm, key="t_created")
+        assert n1 == n2 == f"idx_{t}_payload_t_created"