AxiomQuery 0.1.0__tar.gz → 0.3.0__tar.gz

axiomquery-0.3.0/CHANGELOG.md

@@ -0,0 +1,63 @@
+# Changelog
+
+All notable changes to `AxiomQuery` are documented here.
+
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [0.3.0] — 2026-04-26
+
+### Added
+
+- `search()` / `asearch()` — streaming iteration over large result sets via SQLAlchemy server-side cursors with `yield_per=1000`
+  - Sync `search()` returns a Python iterator (consume with `for`); async `asearch()` returns an `AsyncScalarResult` (consume with `async for`)
+  - Single-pass; no `limit` / `offset` (use `list()` / `alist()` for paginated/materialised access)
+- `DEFAULT_PREFETCH = 1000` module-level constant in `engine.py`
+- Internal `_build_stmt()` helper consolidating the `select + where + order_by + limit + offset` block shared by `list` / `alist` / `search` / `asearch` / `read_group`
+
+### Changed
+
+- `list()` / `alist()` continue to return a materialised `list` — behaviour and signature unchanged from 0.2.0 callers' perspective
+
+---
+
+## [0.2.0] — 2026-04-13
+
+### Added
+
+- M2O (Many-to-One) relational field filtering via dot-notation (e.g. `["customer.name", "ilike", "%Alice%"]`)
+  - Generates an `EXISTS` subquery joining the referenced table on the local FK column
+  - Composes freely with scalar filters and O2M child filters in the same domain
+- `RelatedSchema` dataclass in `schema.py` to capture M2O relationship metadata (referenced table, local FK column, columns)
+- `related` field on `ModelSchema` mapping relationship attribute names to their `RelatedSchema`
+
+---
+
+## [0.1.1] — 2026-04-05
+Acknowledgement and Inspiration Added
+
+### Added
+- updated the README.md file with details
+
+## [0.1.0] — 2026-03-29
+
+Initial release.
+
+### Added
+
+- `QueryEngine` — specification-based query facade for any SQLAlchemy 2.0 ORM model
+- `list()` / `alist()` — filtered record retrieval with `limit`, `offset`, `order_by`
+- `read_group()` / `aread_group()` — grouped aggregation (GROUP BY + HAVING) with `__domain` drill-down per group
+- Domain filter DSL — composable JSON expressions: `[field, op, value]`, `{"and": [...]}`, `{"or": [...]}`, `{"not": ...}`
+- Full operator set: `=` `!=` `>` `<` `>=` `<=` `in` `not in` `like` `ilike` `is_null`
+- Child field filtering via EXISTS subquery (dot notation: `"lines.quantity"`)
+- Child field aggregation via LEFT JOIN (`"lines.quantity:sum"`)
+- Date granularity grouping: `day` `week` `month` `quarter` `year`
+- Aggregate functions: `count` `sum` `avg` `min` `max`
+- HAVING filter on aggregate aliases
+- Schema auto-derived from `inspect(model_class)` — O2M relationships are children by convention
+- Sync (`Session`) and async (`AsyncSession`) APIs
+- `QueryError` with `code` and `message` — field validation at compile time, before DB
+- `py.typed` marker — PEP 561 inline type annotations

{axiomquery-0.1.0 → axiomquery-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: AxiomQuery
-Version: 0.1.0
+Version: 0.3.0
 Summary: Specification-based query and aggregation engine for SQLAlchemy 2.0 ORM models
 Project-URL: Source Code, https://github.com/Axiom-Dev-Labs/AxiomQuery
 Project-URL: Bug Tracker, https://github.com/Axiom-Dev-Labs/AxiomQuery/issues
@@ -230,3 +230,24 @@ python examples/example_async.py
 ```
 
 Both cover: simple filters, AND / OR / NOT, combined nesting, child EXISTS filtering, pagination, `read_group` with domain / date granularity / child aggregation / HAVING, and `__domain` drill-down.
+
+Here is an improved, livelier version of your acknowledgement note, complete with emojis and the added context about the Specification pattern acting as the core inspiration for the library. It is formatted directly for your `README.md`.
+
+***
+
+## 🙌 Acknowledgements & Inspirations
+
+The creation of AxiomQuery was sparked by a desire to cleanly bridge pure domain logic with robust data access. The conceptual "trigger point" for this library came from **Martin Fowler and Eric Evans' Specification Pattern**—a brilliant blueprint for encapsulating business rules. However, it was the phenomenal foundation of **SQLAlchemy 2.0** that provided the mechanical reality, making it possible to seamlessly translate those decoupled domain specifications into highly optimized SQL. 
+
+A huge thank you to the maintainers and contributors of SQLAlchemy. AxiomQuery is built explicitly as a specification-based query and aggregation engine for SQLAlchemy 2.0 ORM models, and it relies entirely on several of their most powerful features:
+
+* 🔍 **Incredible Introspection (`inspect()`):** AxiomQuery automatically derives all necessary schema data—including `mapper.columns`, one-to-many relationships (`RelationshipDirection.ONETOMANY`), and foreign key synchronization pairs—directly from SQLAlchemy's introspection tools. This allows the engine to extract everything the compiler needs without ever forcing the developer to write duplicate descriptor code.
+* 🏗️ **Robust Expression Language:** Our underlying AST compiler relies heavily on SQLAlchemy's composable query constructs. Mapping our 11 supported operators to native methods makes it incredibly easy to safely compile complex SQL `WHERE` clauses. It seamlessly handles advanced requirements, such as utilizing `EXISTS` subqueries for parent-child filtering and executing `LEFT JOIN` aggregations with database-specific date truncations.
+* 🔌 **Decoupled Session Management:** Because SQLAlchemy cleanly separates the ORM models from the active database connection, AxiomQuery can operate as a thin, highly reusable facade. The library expects a caller-owned session (whether standard or an `AsyncSession`), allowing developers to easily manage transactions across multiple engines without friction.
+
+Thank you for providing the introspection and query-building tools that make translating dynamic JSON expressions into complex SQL queries a reality! ✨
+
+### 📚 References
+
+* **The Specification Pattern:** [Specifications by Martin Fowler & Eric Evans (PDF)](https://martinfowler.com/apsupp/spec.pdf) - The foundational paper that inspired the core domain-driven architecture of this library.
+* **SQLAlchemy 2.0:** [Official Documentation](https://docs.sqlalchemy.org/en/20/) - The robust ORM and toolkit that powers the AxiomQuery engine.

{axiomquery-0.1.0 → axiomquery-0.3.0}/README.md

@@ -187,3 +187,24 @@ python examples/example_async.py
 ```
 
 Both cover: simple filters, AND / OR / NOT, combined nesting, child EXISTS filtering, pagination, `read_group` with domain / date granularity / child aggregation / HAVING, and `__domain` drill-down.
+
+Here is an improved, livelier version of your acknowledgement note, complete with emojis and the added context about the Specification pattern acting as the core inspiration for the library. It is formatted directly for your `README.md`.
+
+***
+
+## 🙌 Acknowledgements & Inspirations
+
+The creation of AxiomQuery was sparked by a desire to cleanly bridge pure domain logic with robust data access. The conceptual "trigger point" for this library came from **Martin Fowler and Eric Evans' Specification Pattern**—a brilliant blueprint for encapsulating business rules. However, it was the phenomenal foundation of **SQLAlchemy 2.0** that provided the mechanical reality, making it possible to seamlessly translate those decoupled domain specifications into highly optimized SQL. 
+
+A huge thank you to the maintainers and contributors of SQLAlchemy. AxiomQuery is built explicitly as a specification-based query and aggregation engine for SQLAlchemy 2.0 ORM models, and it relies entirely on several of their most powerful features:
+
+* 🔍 **Incredible Introspection (`inspect()`):** AxiomQuery automatically derives all necessary schema data—including `mapper.columns`, one-to-many relationships (`RelationshipDirection.ONETOMANY`), and foreign key synchronization pairs—directly from SQLAlchemy's introspection tools. This allows the engine to extract everything the compiler needs without ever forcing the developer to write duplicate descriptor code.
+* 🏗️ **Robust Expression Language:** Our underlying AST compiler relies heavily on SQLAlchemy's composable query constructs. Mapping our 11 supported operators to native methods makes it incredibly easy to safely compile complex SQL `WHERE` clauses. It seamlessly handles advanced requirements, such as utilizing `EXISTS` subqueries for parent-child filtering and executing `LEFT JOIN` aggregations with database-specific date truncations.
+* 🔌 **Decoupled Session Management:** Because SQLAlchemy cleanly separates the ORM models from the active database connection, AxiomQuery can operate as a thin, highly reusable facade. The library expects a caller-owned session (whether standard or an `AsyncSession`), allowing developers to easily manage transactions across multiple engines without friction.
+
+Thank you for providing the introspection and query-building tools that make translating dynamic JSON expressions into complex SQL queries a reality! ✨
+
+### 📚 References
+
+* **The Specification Pattern:** [Specifications by Martin Fowler & Eric Evans (PDF)](https://martinfowler.com/apsupp/spec.pdf) - The foundational paper that inspired the core domain-driven architecture of this library.
+* **SQLAlchemy 2.0:** [Official Documentation](https://docs.sqlalchemy.org/en/20/) - The robust ORM and toolkit that powers the AxiomQuery engine.

{axiomquery-0.1.0 → axiomquery-0.3.0}/examples/example_async.py

@@ -5,7 +5,8 @@ methods.  Demonstrates the same domain styles:
   - Simple equality / comparison
   - AND, OR, NOT
   - Combined nested conditions
-  - Child-field EXISTS filtering
+  - Child-field EXISTS filtering (O2M)
+  - Many-to-One field filtering (M2O EXISTS subquery)
   - alist() options: limit, offset, order_by
   - aread_group() with domain, date granularity, child aggregate, HAVING
   - __domain drill-down with alist()
@@ -18,7 +19,7 @@ from __future__ import annotations
 
 import asyncio
 from datetime import datetime
-from typing import List
+from typing import List, Optional
 
 from sqlalchemy import DateTime, ForeignKey, String
 from sqlalchemy.ext.asyncio import AsyncSession, create_async_engine
@@ -34,12 +35,25 @@ class Base(DeclarativeBase):
     pass
 
 
+class Customer(Base):
+    __tablename__ = "customers"
+    id: Mapped[int] = mapped_column(primary_key=True)
+    name: Mapped[str] = mapped_column(String(100))
+
+    def __repr__(self) -> str:
+        return f"Customer(id={self.id}, name={self.name!r})"
+
+
 class Order(Base):
     __tablename__ = "orders"
     id: Mapped[int] = mapped_column(primary_key=True)
     status: Mapped[str] = mapped_column(String(20))
     total: Mapped[int] = mapped_column(default=0)
     created_at: Mapped[datetime] = mapped_column(DateTime)
+    customer_id: Mapped[Optional[int]] = mapped_column(
+        ForeignKey("customers.id"), nullable=True
+    )
+    customer: Mapped[Optional["Customer"]] = relationship()
     lines: Mapped[List["OrderLine"]] = relationship(back_populates="order")
 
     def __repr__(self) -> str:
@@ -62,14 +76,41 @@ class OrderLine(Base):
 async def seed(session: AsyncSession) -> None:
     session.add_all(
         [
+            Customer(id=1, name="Joy"),
+            Customer(id=2, name="Bob"),
+        ]
+    )
+    await session.flush()
+    session.add_all(
+        [
+            Order(
+                id=1,
+                status="CONFIRMED",
+                total=100,
+                created_at=datetime(2026, 1, 15),
+                customer_id=1,
+            ),
+            Order(
+                id=2,
+                status="CONFIRMED",
+                total=200,
+                created_at=datetime(2026, 2, 20),
+                customer_id=2,
+            ),
             Order(
-                id=1, status="CONFIRMED", total=100, created_at=datetime(2026, 1, 15)
+                id=3,
+                status="DRAFT",
+                total=50,
+                created_at=datetime(2026, 1, 25),
+                customer_id=1,
             ),
             Order(
-                id=2, status="CONFIRMED", total=200, created_at=datetime(2026, 2, 20)
+                id=4,
+                status="CANCELLED",
+                total=75,
+                created_at=datetime(2026, 3, 10),
+                customer_id=None,
             ),
-            Order(id=3, status="DRAFT", total=50, created_at=datetime(2026, 1, 25)),
-            Order(id=4, status="CANCELLED", total=75, created_at=datetime(2026, 3, 10)),
         ]
     )
     await session.flush()
@@ -302,9 +343,34 @@ async def main() -> None:
             ),
         )
 
-        # ── Section 8: alist() options ────────────────────────────────────
+        # ── Section 8: M2O field — EXISTS on referenced table ────────────
+
+        section("8. M2O field filtering (EXISTS on referenced table)")
+
+        show(
+            "orders where customer.name = 'Joy'",
+            await engine.alist(session, domain=[["customer.name", "=", "Joy"]]),
+        )
+
+        show(
+            "orders where customer.name ilike '%ob%'",
+            await engine.alist(session, domain=[["customer.name", "ilike", "%ob%"]]),
+        )
+
+        show(
+            "CONFIRMED orders for Joy (M2O + scalar)",
+            await engine.alist(
+                session,
+                domain=[
+                    ["customer.name", "=", "Joy"],
+                    ["status", "=", "CONFIRMED"],
+                ],
+            ),
+        )
+
+        # ── Section 9: alist() options ────────────────────────────────────
 
-        section("8. alist() — limit, offset, order_by")
+        section("9. alist() — limit, offset, order_by")
 
         show(
             "top 2 orders by total desc",
@@ -327,7 +393,7 @@ async def main() -> None:
 
         # ── Section 9: aread_group — basic ────────────────────────────────
 
-        section("9. aread_group — basic groupby + count")
+        section("10. aread_group — basic groupby + count")
 
         groups, total = await engine.aread_group(
             session,
@@ -339,7 +405,7 @@ async def main() -> None:
 
         # ── Section 10: aread_group with domain ───────────────────────────
 
-        section("10. aread_group with domain filter")
+        section("11. aread_group with domain filter")
 
         groups, total = await engine.aread_group(
             session,
@@ -351,7 +417,7 @@ async def main() -> None:
 
         # ── Section 11: aread_group — date granularity ────────────────────
 
-        section("11. aread_group — date granularity (month)")
+        section("12. aread_group — date granularity (month)")
 
         groups, total = await engine.aread_group(
             session,
@@ -363,7 +429,7 @@ async def main() -> None:
 
         # ── Section 12: aread_group — child aggregate (LEFT JOIN) ─────────
 
-        section("12. aread_group — child aggregate (LEFT JOIN)")
+        section("13. aread_group — child aggregate (LEFT JOIN)")
 
         groups, total = await engine.aread_group(
             session,
@@ -374,7 +440,7 @@ async def main() -> None:
 
         # ── Section 13: aread_group — HAVING ──────────────────────────────
 
-        section("13. aread_group — HAVING filter on aggregate")
+        section("14. aread_group — HAVING filter on aggregate")
 
         groups, total = await engine.aread_group(
             session,
@@ -386,7 +452,7 @@ async def main() -> None:
 
         # ── Section 14: __domain drill-down with alist() ──────────────────
 
-        section("14. __domain drill-down — group → records via alist()")
+        section("15. __domain drill-down — group → records via alist()")
 
         groups, _ = await engine.aread_group(
             session,

{axiomquery-0.1.0 → axiomquery-0.3.0}/examples/example_sync.py

@@ -6,7 +6,8 @@ Demonstrates all domain condition styles:
   - OR   — any condition must hold
   - NOT  — negation
   - Combined — nested AND / OR / NOT
-  - Child-field EXISTS filtering
+  - Child-field EXISTS filtering (O2M)
+  - Many-to-One field filtering (M2O EXISTS subquery)
   - list() options: limit, offset, order_by
   - read_group() with domain, date granularity, child aggregate, HAVING
   - __domain drill-down: group result → list of matching records
@@ -20,6 +21,8 @@ from __future__ import annotations
 from datetime import datetime
 from typing import List
 
+from typing import Optional
+
 from sqlalchemy import DateTime, ForeignKey, String, create_engine
 from sqlalchemy.orm import DeclarativeBase, Mapped, Session, mapped_column, relationship
 
@@ -33,12 +36,25 @@ class Base(DeclarativeBase):
     pass
 
 
+class Customer(Base):
+    __tablename__ = "customers"
+    id: Mapped[int] = mapped_column(primary_key=True)
+    name: Mapped[str] = mapped_column(String(100))
+
+    def __repr__(self) -> str:
+        return f"Customer(id={self.id}, name={self.name!r})"
+
+
 class Order(Base):
     __tablename__ = "orders"
     id: Mapped[int] = mapped_column(primary_key=True)
     status: Mapped[str] = mapped_column(String(20))
     total: Mapped[int] = mapped_column(default=0)
     created_at: Mapped[datetime] = mapped_column(DateTime)
+    customer_id: Mapped[Optional[int]] = mapped_column(
+        ForeignKey("customers.id"), nullable=True
+    )
+    customer: Mapped[Optional["Customer"]] = relationship()
     lines: Mapped[List["OrderLine"]] = relationship(back_populates="order")
 
     def __repr__(self) -> str:
@@ -61,14 +77,41 @@ class OrderLine(Base):
 def seed(session: Session) -> None:
     session.add_all(
         [
+            Customer(id=1, name="Joy"),
+            Customer(id=2, name="Bob"),
+        ]
+    )
+    session.flush()
+    session.add_all(
+        [
+            Order(
+                id=1,
+                status="CONFIRMED",
+                total=100,
+                created_at=datetime(2026, 1, 15),
+                customer_id=1,
+            ),
+            Order(
+                id=2,
+                status="CONFIRMED",
+                total=200,
+                created_at=datetime(2026, 2, 20),
+                customer_id=2,
+            ),
             Order(
-                id=1, status="CONFIRMED", total=100, created_at=datetime(2026, 1, 15)
+                id=3,
+                status="DRAFT",
+                total=50,
+                created_at=datetime(2026, 1, 25),
+                customer_id=1,
             ),
             Order(
-                id=2, status="CONFIRMED", total=200, created_at=datetime(2026, 2, 20)
+                id=4,
+                status="CANCELLED",
+                total=75,
+                created_at=datetime(2026, 3, 10),
+                customer_id=None,
             ),
-            Order(id=3, status="DRAFT", total=50, created_at=datetime(2026, 1, 25)),
-            Order(id=4, status="CANCELLED", total=75, created_at=datetime(2026, 3, 10)),
         ]
     )
     session.flush()
@@ -296,9 +339,34 @@ def main() -> None:
             ),
         )
 
-        # ── Section 8: list() options ─────────────────────────────────────
+        # ── Section 8: M2O field — EXISTS on referenced table ────────────
+
+        section("8. M2O field filtering (EXISTS on referenced table)")
+
+        show(
+            "orders where customer.name = 'Joy'",
+            engine.list(session, domain=[["customer.name", "=", "Joy"]]),
+        )
+
+        show(
+            "orders where customer.name ilike '%ob%'",
+            engine.list(session, domain=[["customer.name", "ilike", "%ob%"]]),
+        )
+
+        show(
+            "CONFIRMED orders for Joy (M2O + scalar)",
+            engine.list(
+                session,
+                domain=[
+                    ["customer.name", "=", "Joy"],
+                    ["status", "=", "CONFIRMED"],
+                ],
+            ),
+        )
+
+        # ── Section 9: list() options ─────────────────────────────────────
 
-        section("8. list() — limit, offset, order_by")
+        section("9. list() — limit, offset, order_by")
 
         show(
             "top 2 by total desc",
@@ -312,7 +380,7 @@ def main() -> None:
 
         # ── Section 9: read_group — basic ─────────────────────────────────
 
-        section("9. read_group — basic groupby + count")
+        section("10. read_group — basic groupby + count")
 
         groups, total = engine.read_group(
             session,
@@ -324,7 +392,7 @@ def main() -> None:
 
         # ── Section 10: read_group with domain ───────────────────────────
 
-        section("10. read_group with domain filter")
+        section("11. read_group with domain filter")
 
         groups, total = engine.read_group(
             session,
@@ -336,7 +404,7 @@ def main() -> None:
 
         # ── Section 11: read_group — date granularity ─────────────────────
 
-        section("11. read_group — date granularity (month)")
+        section("12. read_group — date granularity (month)")
 
         groups, total = engine.read_group(
             session,
@@ -348,7 +416,7 @@ def main() -> None:
 
         # ── Section 12: read_group — child aggregate (LEFT JOIN) ──────────
 
-        section("12. read_group — child aggregate (LEFT JOIN)")
+        section("13. read_group — child aggregate (LEFT JOIN)")
 
         groups, total = engine.read_group(
             session,
@@ -359,7 +427,7 @@ def main() -> None:
 
         # ── Section 13: read_group — HAVING ──────────────────────────────
 
-        section("13. read_group — HAVING filter on aggregate")
+        section("14. read_group — HAVING filter on aggregate")
 
         groups, total = engine.read_group(
             session,
@@ -371,7 +439,7 @@ def main() -> None:
 
         # ── Section 14: __domain drill-down ──────────────────────────────
 
-        section("14. __domain drill-down — group → records")
+        section("15. __domain drill-down — group → records")
 
         groups, _ = engine.read_group(
             session,

{axiomquery-0.1.0 → axiomquery-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "AxiomQuery"
-version = "0.1.0"
+version = "0.3.0"
 description = "Specification-based query and aggregation engine for SQLAlchemy 2.0 ORM models"
 readme = "README.md"
 license = { file = "LICENSE" }

{axiomquery-0.1.0 → axiomquery-0.3.0}/src/axiom_query/__init__.py

@@ -1,6 +1,6 @@
 """axiom_query — standalone specification-based query engine for SQLAlchemy ORM models."""
 
-__version__ = "0.1.0"
+__version__ = "0.3.0"
 
 from axiom_query.engine import QueryEngine
 from axiom_query.errors import QueryError

{axiomquery-0.1.0 → axiomquery-0.3.0}/src/axiom_query/compiler.py

@@ -94,22 +94,39 @@ def _make_table_resolver(schema: ModelSchema) -> SAResolver:
 
     def resolve(fp: str, op: Op, val: Any) -> ColumnElement:
         if "." in fp:
-            child_name, field_name = fp.split(".", 1)
+            rel_name, field_name = fp.split(".", 1)
             from axiom_query.errors import QueryError
 
-            child = schema.children.get(child_name)
-            if child is None:
-                raise QueryError(
-                    "INVALID_FILTER_FIELD",
-                    f"No child relation '{child_name}' on {schema.model_class.__name__}",
+            # O2M: FK is on the child table; use EXISTS over child rows
+            child = schema.children.get(rel_name)
+            if child is not None:
+                fk_col = child.table.c[child.fk_field]
+                field_col = child.table.c[field_name]
+                condition = _apply_operator(field_col, op, val)
+                return exists(
+                    select(1)
+                    .select_from(child.table)
+                    .where(and_(fk_col == schema.table.c.id, condition))
                 )
-            fk_col = child.table.c[child.fk_field]
-            field_col = child.table.c[field_name]
-            condition = _apply_operator(field_col, op, val)
-            return exists(
-                select(1)
-                .select_from(child.table)
-                .where(and_(fk_col == schema.table.c.id, condition))
+
+            # M2O: FK is on the current table; use EXISTS over the referenced table
+            related = schema.related.get(rel_name)
+            if related is not None:
+                local_fk_col = schema.table.c[related.fk_field]
+                ref_pk = next(iter(related.table.primary_key))
+                field_col = related.table.c[field_name]
+                condition = _apply_operator(field_col, op, val)
+                return exists(
+                    select(1)
+                    .select_from(related.table)
+                    .where(and_(ref_pk == local_fk_col, condition))
+                )
+
+            all_relations = list(schema.children.keys()) + list(schema.related.keys())
+            raise QueryError(
+                "INVALID_FILTER_FIELD",
+                f"No relation '{rel_name}' on {schema.model_class.__name__}. "
+                f"Available: {', '.join(all_relations) or 'none'}",
             )
         else:
             col = _resolve_column(schema, fp)

{axiomquery-0.1.0 → axiomquery-0.3.0}/src/axiom_query/engine.py

@@ -15,6 +15,9 @@ from axiom_query.parser import parse_domain
 from axiom_query.schema import ModelSchema, derive_schema
 
 
+DEFAULT_PREFETCH = 1000
+
+
 def _get_dialect_name(session) -> str:
     """Extract dialect name from a sync or async SQLAlchemy session."""
     # AsyncSession has a .bind attribute (AsyncEngine)
@@ -38,7 +41,14 @@ class QueryEngine:
     Usage::
 
         engine = QueryEngine(Order)
-        records = engine.list(session, domain=[["status", "=", "CONFIRMED"]])
+
+        # Materialised page
+        page = engine.list(session, domain=[["status", "=", "CONFIRMED"]], limit=20)
+
+        # Streaming iteration over every match (no len/indexing)
+        for order in engine.search(session, domain=[["status", "=", "CONFIRMED"]]):
+            process(order)
+
         groups, total = engine.read_group(session, groupby=["status"], aggregates=["__count"])
     """
 
@@ -46,6 +56,21 @@ class QueryEngine:
         self._model = model_class
         self._schema: ModelSchema = derive_schema(model_class)
 
+    # ── Statement builder ────────────────────────────────────────────────
+
+    def _build_stmt(self, domain, order_by, limit, offset):
+        stmt = select(self._model)
+        if domain is not None:
+            spec = parse_domain(domain)
+            stmt = stmt.where(compile_domain(spec, self._schema))
+        if order_by is not None:
+            stmt = self._apply_order_by(stmt, order_by)
+        if limit is not None:
+            stmt = stmt.limit(limit)
+        if offset is not None:
+            stmt = stmt.offset(offset)
+        return stmt
+
     # ── Sync API ─────────────────────────────────────────────────────────
 
     def list(
@@ -56,24 +81,36 @@ class QueryEngine:
         offset: int | None = None,
         order_by: list | None = None,
     ) -> list:
-        """Return all records matching the optional domain filter."""
-        stmt = select(self._model)
+        """Return all records matching the optional domain filter as a list.
 
-        if domain is not None:
-            spec = parse_domain(domain)
-            where = compile_domain(spec, self._schema)
-            stmt = stmt.where(where)
+        Materialises the full result. Use ``search()`` for streaming over large
+        result sets.
+        """
+        stmt = self._build_stmt(domain, order_by, limit, offset)
+        return list(session.execute(stmt).scalars().all())
 
-        if order_by is not None:
-            stmt = self._apply_order_by(stmt, order_by)
+    def search(
+        self,
+        session: Session,
+        domain: Any = None,
+        order_by: list | None = None,
+    ):
+        """Stream records for batch processing.
 
-        if limit is not None:
-            stmt = stmt.limit(limit)
-        if offset is not None:
-            stmt = stmt.offset(offset)
+        Returns an iterator yielding ORM instances from a server-side cursor,
+        fetched in batches of ``DEFAULT_PREFETCH`` (1000) rows. Single-pass —
+        iterate once and don't store the iterator for re-use.
 
-        result = session.execute(stmt)
-        return list(result.scalars().all())
+        No ``limit`` / ``offset``: this method is for processing every matching
+        row. Use ``list()`` if you need pagination, ``len()``, or indexing.
+
+        Driver note: true streaming requires a database driver with server-side
+        cursor support (psycopg2, asyncpg). SQLite degrades to client-side
+        iteration but remains correct.
+        """
+        stmt = self._build_stmt(domain, order_by, limit=None, offset=None)
+        streaming_stmt = stmt.execution_options(yield_per=DEFAULT_PREFETCH)
+        return iter(session.scalars(streaming_stmt))
 
     def read_group(
         self,
@@ -128,24 +165,34 @@ class QueryEngine:
         offset: int | None = None,
         order_by: list | None = None,
     ) -> list:
-        """Async variant of list()."""
-        stmt = select(self._model)
+        """Async variant of ``list()`` — returns a materialised list."""
+        stmt = self._build_stmt(domain, order_by, limit, offset)
+        result = await session.execute(stmt)
+        return list(result.scalars().all())
 
-        if domain is not None:
-            spec = parse_domain(domain)
-            where = compile_domain(spec, self._schema)
-            stmt = stmt.where(where)
+    async def asearch(
+        self,
+        session,
+        domain: Any = None,
+        order_by: list | None = None,
+    ):
+        """Async variant of ``search()`` — returns an async iterator.
 
-        if order_by is not None:
-            stmt = self._apply_order_by(stmt, order_by)
+        Consume with ``async for``::
 
-        if limit is not None:
-            stmt = stmt.limit(limit)
-        if offset is not None:
-            stmt = stmt.offset(offset)
+            async for record in await engine.asearch(session, domain=...):
+                process(record)
 
-        result = await session.execute(stmt)
-        return list(result.scalars().all())
+        Streams ORM instances in batches of ``DEFAULT_PREFETCH`` (1000) rows
+        from a server-side cursor. Single-pass; no ``limit`` / ``offset``.
+
+        Driver note: true streaming requires a server-side cursor capable
+        driver (asyncpg). aiosqlite iterates correctly but without driver-level
+        streaming.
+        """
+        stmt = self._build_stmt(domain, order_by, limit=None, offset=None)
+        streaming_stmt = stmt.execution_options(yield_per=DEFAULT_PREFETCH)
+        return await session.stream_scalars(streaming_stmt)
 
     async def aread_group(
         self,

{axiomquery-0.1.0 → axiomquery-0.3.0}/src/axiom_query/schema.py

@@ -17,12 +17,27 @@ class ChildSchema:
     columns: dict[str, Column]
 
 
+@dataclass
+class RelatedSchema:
+    """Represents a Many-to-One (M2O) relationship on the inspected model.
+
+    The FK column lives on the *current* table (e.g. orders.customer_id),
+    and the referenced table holds the PK that FK points to.
+    """
+
+    name: str
+    table: Table
+    fk_field: str  # FK column name on the current (owning) table
+    columns: dict[str, Column]
+
+
 @dataclass
 class ModelSchema:
     model_class: type
     table: Table
     columns: dict[str, Column]
     children: dict[str, ChildSchema] = field(default_factory=dict)
+    related: dict[str, RelatedSchema] = field(default_factory=dict)
 
 
 def derive_schema(model_class: type) -> ModelSchema:
@@ -32,24 +47,35 @@ def derive_schema(model_class: type) -> ModelSchema:
     columns = {col.key: col for col in mapper.columns}
 
     children: dict[str, ChildSchema] = {}
+    related: dict[str, RelatedSchema] = {}
     for rel_name, rel in mapper.relationships.items():
         if rel.direction == RelationshipDirection.ONETOMANY:
             child_table = rel.mapper.local_table
             child_columns = {col.key: col for col in rel.mapper.columns}
-            # Find the FK column on the child table via synchronize_pairs
             # synchronize_pairs: list of (parent_col, child_col) tuples
             _, child_fk_col = next(iter(rel.synchronize_pairs))
-            fk_field = child_fk_col.key
             children[rel_name] = ChildSchema(
                 name=rel_name,
                 table=child_table,
-                fk_field=fk_field,
+                fk_field=child_fk_col.key,
                 columns=child_columns,
             )
+        elif rel.direction == RelationshipDirection.MANYTOONE:
+            ref_table = rel.mapper.local_table
+            ref_columns = {col.key: col for col in rel.mapper.columns}
+            # synchronize_pairs for M2O: (referenced_pk_col, local_fk_col)
+            _, local_fk_col = next(iter(rel.synchronize_pairs))
+            related[rel_name] = RelatedSchema(
+                name=rel_name,
+                table=ref_table,
+                fk_field=local_fk_col.key,
+                columns=ref_columns,
+            )
 
     return ModelSchema(
         model_class=model_class,
         table=table,
         columns=columns,
         children=children,
+        related=related,
     )

{axiomquery-0.1.0 → axiomquery-0.3.0}/tests/conftest.py

@@ -16,12 +16,20 @@ class Base(DeclarativeBase):
     pass
 
 
+class Customer(Base):
+    __tablename__ = "customers"
+    id: Mapped[int] = mapped_column(primary_key=True)
+    name: Mapped[str] = mapped_column(String(100))
+
+
 class Order(Base):
     __tablename__ = "orders"
     id: Mapped[int] = mapped_column(primary_key=True)
     status: Mapped[str] = mapped_column(String(20))
     total: Mapped[int] = mapped_column(default=0)
     created_at: Mapped[datetime] = mapped_column(DateTime)
+    customer_id: Mapped[Optional[int]] = mapped_column(ForeignKey("customers.id"), nullable=True)
+    customer: Mapped[Optional["Customer"]] = relationship()
     lines: Mapped[List["OrderLine"]] = relationship(back_populates="order")
 
 
@@ -47,23 +55,31 @@ def db_engine():
 def seeded_engine(db_engine):
     """Seed test data once per session."""
     with Session(db_engine) as sess:
+        c1 = Customer(id=1, name="Alice")
+        c2 = Customer(id=2, name="Bob")
+        sess.add_all([c1, c2])
+        sess.flush()
+
         o1 = Order(
             id=1,
             status="CONFIRMED",
             total=100,
             created_at=datetime(2026, 1, 15),
+            customer_id=1,
         )
         o2 = Order(
             id=2,
             status="CONFIRMED",
             total=200,
             created_at=datetime(2026, 2, 20),
+            customer_id=2,
         )
         o3 = Order(
             id=3,
             status="DRAFT",
             total=50,
             created_at=datetime(2026, 1, 25),
+            customer_id=None,
         )
         sess.add_all([o1, o2, o3])
         sess.flush()
@@ -108,9 +124,14 @@ async def seeded_async_engine(async_db_engine):
     from sqlalchemy.ext.asyncio import AsyncSession
 
     async with AsyncSession(async_db_engine) as sess:
-        o1 = Order(id=1, status="CONFIRMED", total=100, created_at=datetime(2026, 1, 15))
-        o2 = Order(id=2, status="CONFIRMED", total=200, created_at=datetime(2026, 2, 20))
-        o3 = Order(id=3, status="DRAFT", total=50, created_at=datetime(2026, 1, 25))
+        c1 = Customer(id=1, name="Alice")
+        c2 = Customer(id=2, name="Bob")
+        sess.add_all([c1, c2])
+        await sess.flush()
+
+        o1 = Order(id=1, status="CONFIRMED", total=100, created_at=datetime(2026, 1, 15), customer_id=1)
+        o2 = Order(id=2, status="CONFIRMED", total=200, created_at=datetime(2026, 2, 20), customer_id=2)
+        o3 = Order(id=3, status="DRAFT", total=50, created_at=datetime(2026, 1, 25), customer_id=None)
         sess.add_all([o1, o2, o3])
         await sess.flush()
 

axiomquery-0.3.0/tests/test_asearch.py

@@ -0,0 +1,82 @@
+"""Tests for QueryEngine.asearch() — async streaming iteration."""
+
+from __future__ import annotations
+
+import pytest
+from sqlalchemy import event
+
+from axiom_query.engine import DEFAULT_PREFETCH
+from conftest import Order
+
+
+@pytest.mark.asyncio
+async def test_asearch_iterates_all_records(async_session, engine):
+    result = await engine.asearch(async_session)
+    records = [r async for r in result]
+    assert len(records) == 3
+    assert all(isinstance(r, Order) for r in records)
+
+
+@pytest.mark.asyncio
+async def test_asearch_with_domain(async_session, engine):
+    result = await engine.asearch(async_session, domain=[["status", "=", "CONFIRMED"]])
+    records = [r async for r in result]
+    assert len(records) == 2
+    assert all(r.status == "CONFIRMED" for r in records)
+
+
+@pytest.mark.asyncio
+async def test_asearch_with_m2o_domain(async_session, engine):
+    result = await engine.asearch(async_session, domain=[["customer.name", "=", "Alice"]])
+    records = [r async for r in result]
+    assert len(records) == 1
+    assert records[0].id == 1
+
+
+@pytest.mark.asyncio
+async def test_asearch_supports_order_by(async_session, engine):
+    result = await engine.asearch(async_session, order_by=[["total", "desc"]])
+    records = [r async for r in result]
+    assert [r.total for r in records] == [200, 100, 50]
+
+
+@pytest.mark.asyncio
+async def test_asearch_empty_result(async_session, engine):
+    result = await engine.asearch(async_session, domain=[["status", "=", "NONEXISTENT"]])
+    records = [r async for r in result]
+    assert records == []
+
+
+@pytest.mark.asyncio
+async def test_asearch_no_pagination_args(async_session, engine):
+    with pytest.raises(TypeError):
+        await engine.asearch(async_session, limit=10)
+    with pytest.raises(TypeError):
+        await engine.asearch(async_session, offset=5)
+
+
+@pytest.mark.asyncio
+async def test_asearch_uses_yield_per(async_session, engine, seeded_async_engine):
+    """Verify the SQL is issued with yield_per=DEFAULT_PREFETCH."""
+    captured = []
+
+    def listener(conn, cursor, statement, parameters, context, executemany):
+        captured.append(context.execution_options)
+
+    # AsyncEngine wraps a sync Engine; events attach to the sync engine
+    sync_engine = seeded_async_engine.sync_engine
+    event.listen(sync_engine, "before_cursor_execute", listener)
+    try:
+        result = await engine.asearch(async_session)
+        records = [r async for r in result]
+        assert len(records) == 3
+    finally:
+        event.remove(sync_engine, "before_cursor_execute", listener)
+
+    assert len(captured) >= 1, f"expected >=1 statement, got {len(captured)}"
+    # Find our SELECT statement (there may be other queries on the connection)
+    yield_per_stmts = [opts for opts in captured if opts.get("yield_per") == DEFAULT_PREFETCH]
+    assert len(yield_per_stmts) == 1, (
+        f"expected 1 statement with yield_per={DEFAULT_PREFETCH}, "
+        f"got {len(yield_per_stmts)}"
+    )

{axiomquery-0.1.0 → axiomquery-0.3.0}/tests/test_list.py

@@ -1,7 +1,9 @@
-"""Tests for QueryEngine.list() — slices 1-5."""
+"""Tests for QueryEngine.list() — slices 1-5 + M2O filtering."""
 
 from __future__ import annotations
 
+import pytest
+
 from conftest import Order
 
 
@@ -51,3 +53,39 @@ def test_list_with_order_by(session, engine):
     records = engine.list(session, order_by=[["total", "desc"]])
     assert records[0].total == 200
     assert records[1].total == 100
+
+
+# Slice 6 — M2O field filtering (EXISTS on referenced table)
+def test_list_filters_by_m2o_field(session, engine):
+    # Order 1 → customer Alice; Order 2 → customer Bob; Order 3 → no customer
+    records = engine.list(session, domain=[["customer.name", "=", "Alice"]])
+    assert len(records) == 1
+    assert records[0].id == 1
+
+
+def test_list_m2o_ilike(session, engine):
+    records = engine.list(session, domain=[["customer.name", "ilike", "%ob%"]])
+    assert len(records) == 1
+    assert records[0].id == 2
+
+
+def test_list_m2o_no_match(session, engine):
+    records = engine.list(session, domain=[["customer.name", "=", "Nobody"]])
+    assert records == []
+
+
+def test_list_m2o_combined_with_scalar(session, engine):
+    # Alice's order is CONFIRMED → should match
+    records = engine.list(
+        session,
+        domain=[["customer.name", "=", "Alice"], ["status", "=", "CONFIRMED"]],
+    )
+    assert len(records) == 1
+    assert records[0].id == 1
+
+
+def test_list_m2o_unknown_relation_raises(session, engine):
+    from axiom_query.errors import QueryError
+
+    with pytest.raises(QueryError):
+        engine.list(session, domain=[["nonexistent.name", "=", "x"]])

axiomquery-0.3.0/tests/test_search.py

@@ -0,0 +1,97 @@
+"""Tests for QueryEngine.search() — streaming iteration."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+
+import pytest
+from sqlalchemy import event
+
+from axiom_query.engine import DEFAULT_PREFETCH
+from conftest import Order
+
+
+def test_search_returns_iterator(session, engine):
+    result = engine.search(session)
+    assert isinstance(result, Iterator)
+
+
+def test_search_iterates_all_records(session, engine):
+    records = list(engine.search(session))
+    assert len(records) == 3
+    assert all(isinstance(r, Order) for r in records)
+
+
+def test_search_with_domain(session, engine):
+    records = list(engine.search(session, domain=[["status", "=", "CONFIRMED"]]))
+    assert len(records) == 2
+    assert all(r.status == "CONFIRMED" for r in records)
+
+
+def test_search_with_or_domain(session, engine):
+    records = list(
+        engine.search(
+            session,
+            domain={"or": [["status", "=", "CONFIRMED"], ["status", "=", "DRAFT"]]},
+        )
+    )
+    assert len(records) == 3
+
+
+def test_search_with_m2o_domain(session, engine):
+    records = list(engine.search(session, domain=[["customer.name", "=", "Alice"]]))
+    assert len(records) == 1
+    assert records[0].id == 1
+
+
+def test_search_supports_order_by(session, engine):
+    records = list(engine.search(session, order_by=[["total", "desc"]]))
+    assert [r.total for r in records] == [200, 100, 50]
+
+
+def test_search_empty_result(session, engine):
+    records = list(engine.search(session, domain=[["status", "=", "NONEXISTENT"]]))
+    assert records == []
+
+
+def test_search_no_pagination_args(session, engine):
+    with pytest.raises(TypeError):
+        engine.search(session, limit=10)
+    with pytest.raises(TypeError):
+        engine.search(session, offset=5)
+
+
+def test_search_uses_yield_per(session, engine, seeded_engine):
+    """Verify the SQL is issued with yield_per=DEFAULT_PREFETCH."""
+    captured = []
+
+    def listener(conn, cursor, statement, parameters, context, executemany):
+        captured.append(context.execution_options)
+
+    event.listen(seeded_engine, "before_cursor_execute", listener)
+    try:
+        list(engine.search(session))
+    finally:
+        event.remove(seeded_engine, "before_cursor_execute", listener)
+
+    assert len(captured) == 1, f"expected 1 statement, got {len(captured)}"
+    assert captured[0].get("yield_per") == DEFAULT_PREFETCH
+
+
+def test_search_is_single_pass(session, engine):
+    """Iterating the same result a second time yields nothing (iterator exhausted)."""
+    result = engine.search(session)
+    first_pass = list(result)
+    second_pass = list(result)
+    assert len(first_pass) == 3
+    assert second_pass == []
+
+
+def test_search_break_does_not_block_session(session, engine):
+    """Breaking out of iteration should not leave the session in a bad state."""
+    for record in engine.search(session):
+        if record.id == 1:
+            break
+    # Session should still be usable
+    records = engine.list(session)
+    assert len(records) == 3

axiomquery-0.1.0/CHANGELOG.md

@@ -1,29 +0,0 @@
-# Changelog
-
-All notable changes to `AxiomQuery` are documented here.
-
-Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
-Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
----
-
-## [0.1.0] — 2026-03-29
-
-Initial release.
-
-### Added
-
-- `QueryEngine` — specification-based query facade for any SQLAlchemy 2.0 ORM model
-- `list()` / `alist()` — filtered record retrieval with `limit`, `offset`, `order_by`
-- `read_group()` / `aread_group()` — grouped aggregation (GROUP BY + HAVING) with `__domain` drill-down per group
-- Domain filter DSL — composable JSON expressions: `[field, op, value]`, `{"and": [...]}`, `{"or": [...]}`, `{"not": ...}`
-- Full operator set: `=` `!=` `>` `<` `>=` `<=` `in` `not in` `like` `ilike` `is_null`
-- Child field filtering via EXISTS subquery (dot notation: `"lines.quantity"`)
-- Child field aggregation via LEFT JOIN (`"lines.quantity:sum"`)
-- Date granularity grouping: `day` `week` `month` `quarter` `year`
-- Aggregate functions: `count` `sum` `avg` `min` `max`
-- HAVING filter on aggregate aliases
-- Schema auto-derived from `inspect(model_class)` — O2M relationships are children by convention
-- Sync (`Session`) and async (`AsyncSession`) APIs
-- `QueryError` with `code` and `message` — field validation at compile time, before DB
-- `py.typed` marker — PEP 561 inline type annotations