AxiomQuery 0.1.0__tar.gz → 0.2.0__tar.gz

{axiomquery-0.1.0 → axiomquery-0.2.0}/CHANGELOG.md

@@ -7,6 +7,24 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ---
 
+## [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.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: AxiomQuery
-Version: 0.1.0
+Version: 0.2.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.2.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.2.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.2.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.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "AxiomQuery"
-version = "0.1.0"
+version = "0.2.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.2.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.2.0"
 
 from axiom_query.engine import QueryEngine
 from axiom_query.errors import QueryError

{axiomquery-0.1.0 → axiomquery-0.2.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.2.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.2.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.1.0 → axiomquery-0.2.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"]])