feat: add lateral_load() for efficient Many:One eager loading via JOIN LATERAL

* feat: support relation tuples in order_fields for cross-table sorting

* docs: update crud module

.github/workflows/ci.yml

@@ -6,6 +6,9 @@ on:
   pull_request:
     branches: [main]
 
+permissions:
+  contents: read
+
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
   cancel-in-progress: true

docs/module/crud.md

@@ -324,6 +324,12 @@ result = await UserCrud.offset_paginate(
 )
 ```
 
+Or via the dependency to narrow which fields are exposed as query parameters:
+
+```python
+params = UserCrud.offset_paginate_params(search_fields=[Post.title])
+```
+
 This allows searching with both [`offset_paginate`](../reference/crud.md#fastapi_toolsets.crud.factory.AsyncCrud.offset_paginate) and [`cursor_paginate`](../reference/crud.md#fastapi_toolsets.crud.factory.AsyncCrud.cursor_paginate):
 
 ```python
@@ -344,13 +350,37 @@ async def get_users(
     return await UserCrud.cursor_paginate(session=session, **params, schema=UserRead)
 ```
 
+The dependency adds two query parameters to the endpoint:
+
+| Parameter       | Type          |
+| --------------- | ------------- |
+| `search`        | `str \| null` |
+| `search_column` | `str \| null` |
+
+```
+GET /posts?search=hello                        → search all configured columns
+GET /posts?search=hello&search_column=title    → search only Post.title
+```
+
+The available search column keys are returned in the `search_columns` field of [`PaginatedResponse`](../reference/schemas.md#fastapi_toolsets.schemas.PaginatedResponse). Use them to populate a column picker in the UI, or to validate `search_column` values on the client side:
+
+```json
+{
+  "status": "SUCCESS",
+  "data": ["..."],
+  "pagination": { "..." },
+  "search_columns": ["content", "author__username", "title"]
+}
+```
+
+!!! info "Key format uses `__` as a separator for relationship chains."
+    A direct column `Post.title` produces `"title"`. A relationship tuple `(Post.author, User.username)` produces `"author__username"`. An unknown `search_column` value raises [`InvalidSearchColumnError`](../reference/exceptions.md#fastapi_toolsets.exceptions.exceptions.InvalidSearchColumnError) (HTTP 422).
+
 ### Faceted search
 
 !!! info "Added in `v1.2`"
 
-Declare `facet_fields` on the CRUD class to return distinct column values alongside paginated results. This is useful for populating filter dropdowns or building faceted search UIs.
+Declare `facet_fields` on the CRUD class to return distinct column values alongside paginated results. This is useful for populating filter dropdowns or building faceted search UIs. Relationship traversal is supported via tuples, using the same syntax as `searchable_fields`:
-
-Facet fields use the same syntax as `searchable_fields` — direct columns or relationship tuples:
 
 ```python
 UserCrud = CrudFactory(
@@ -372,7 +402,47 @@ result = await UserCrud.offset_paginate(
 )
 ```
 
-The distinct values are returned in the `filter_attributes` field of [`PaginatedResponse`](../reference/schemas.md#fastapi_toolsets.schemas.PaginatedResponse):
+Or via the dependency to narrow which fields are exposed as query parameters:
+
+```python
+params = UserCrud.offset_paginate_params(facet_fields=[User.country])
+```
+
+Facet filtering is built into the consolidated params dependencies. When `filter=True` (the default), each facet field is exposed as a query parameter and values are collected into `filter_by` automatically:
+
+```python
+from typing import Annotated
+
+from fastapi import Depends
+
+@router.get("", response_model_exclude_none=True)
+async def list_users(
+    session: SessionDep,
+    params: Annotated[dict, Depends(UserCrud.offset_paginate_params())],
+) -> OffsetPaginatedResponse[UserRead]:
+    return await UserCrud.offset_paginate(session=session, **params, schema=UserRead)
+```
+
+```python
+@router.get("", response_model_exclude_none=True)
+async def list_users(
+    session: SessionDep,
+    params: Annotated[dict, Depends(UserCrud.cursor_paginate_params())],
+) -> CursorPaginatedResponse[UserRead]:
+    return await UserCrud.cursor_paginate(session=session, **params, schema=UserRead)
+```
+
+Both single-value and multi-value query parameters work:
+
+```
+GET /users?status=active                      → filter_by={"status": ["active"]}
+GET /users?status=active&country=FR           → filter_by={"status": ["active"], "country": ["FR"]}
+GET /users?role__name=admin&role__name=editor → filter_by={"role__name": ["admin", "editor"]}  (IN clause)
+```
+
+`filter_by` and `filters` can be combined — both are applied with AND logic.
+
+The distinct values for each facet field are returned in the `filter_attributes` field of [`PaginatedResponse`](../reference/schemas.md#fastapi_toolsets.schemas.PaginatedResponse). Use them to populate filter dropdowns in the UI, or to validate `filter_by` keys on the client side:
 
 ```json
 {
@@ -387,50 +457,14 @@ The distinct values are returned in the `filter_attributes` field of [`Paginated
 }
 ```
 
-Use `filter_by` to pass the client's chosen filter values directly — no need to build SQLAlchemy conditions by hand. Any unknown key raises [`InvalidFacetFilterError`](../reference/exceptions.md#fastapi_toolsets.exceptions.exceptions.InvalidFacetFilterError).
+!!! info "Key format uses `__` as a separator for relationship chains."
-
+    A direct column `User.status` produces `"status"`. A relationship tuple `(User.role, Role.name)` produces `"role__name"`. A deeper chain `(User.role, Role.permission, Permission.name)` produces `"role__permission__name"`. An unknown `filter_by` key raises [`InvalidFacetFilterError`](../reference/exceptions.md#fastapi_toolsets.exceptions.exceptions.InvalidFacetFilterError) (HTTP 422).
-!!! info "The keys in `filter_by` are the same keys the client received in `filter_attributes`."
-    Keys use `__` as a separator for the full relationship chain. A direct column `User.status` produces `"status"`. A relationship tuple `(User.role, Role.name)` produces `"role__name"`. A deeper chain `(User.role, Role.permission, Permission.name)` produces `"role__permission__name"`.
-
-`filter_by` and `filters` can be combined — both are applied with AND logic.
-
-Facet filtering is built into the consolidated params dependencies. When `filter=True` (the default), facet fields are exposed as query parameters and collected into `filter_by` automatically:
-
-```python
-from typing import Annotated
-
-from fastapi import Depends
-
-UserCrud = CrudFactory(
-    model=User,
-    facet_fields=[User.status, User.country, (User.role, Role.name)],
-)
-
-@router.get("", response_model_exclude_none=True)
-async def list_users(
-    session: SessionDep,
-    params: Annotated[dict, Depends(UserCrud.offset_paginate_params())],
-) -> OffsetPaginatedResponse[UserRead]:
-    return await UserCrud.offset_paginate(
-        session=session,
-        **params,
-        schema=UserRead,
-    )
-```
-
-Both single-value and multi-value query parameters work:
-
-```
-GET /users?status=active                      → filter_by={"status": ["active"]}
-GET /users?status=active&country=FR           → filter_by={"status": ["active"], "country": ["FR"]}
-GET /users?role__name=admin&role__name=editor → filter_by={"role__name": ["admin", "editor"]}  (IN clause)
-```
 
 ## Sorting
 
 !!! info "Added in `v1.3`"
 
-Declare `order_fields` on the CRUD class to expose client-driven column ordering via `order_by` and `order` query parameters.
+Declare `order_fields` on the CRUD class. Relationship traversal is supported via tuples, using the same syntax as `searchable_fields` and `facet_fields`:
 
 ```python
 UserCrud = CrudFactory(
@@ -438,11 +472,27 @@ UserCrud = CrudFactory(
     order_fields=[
         User.name,
         User.created_at,
+        (User.role, Role.name),  # sort by a related model column
     ],
 )
 ```
 
-Ordering is built into the consolidated params dependencies. When `order=True` (the default), `order_by` and `order` query parameters are exposed and resolved into an `OrderByClause` automatically:
+You can override `order_fields` per call:
+
+```python
+result = await UserCrud.offset_paginate(
+    session=session,
+    order_fields=[User.name],
+)
+```
+
+Or via the dependency to narrow which fields are exposed as query parameters:
+
+```python
+params = UserCrud.offset_paginate_params(order_fields=[User.name])
+```
+
+Sorting is built into the consolidated params dependencies. When `order=True` (the default), `order_by` and `order` query parameters are exposed and resolved into an `OrderByClause` automatically:
 
 ```python
 from typing import Annotated
@@ -452,33 +502,50 @@ from fastapi import Depends
 @router.get("")
 async def list_users(
     session: SessionDep,
-    params: Annotated[dict, Depends(UserCrud.offset_paginate_params(
+    params: Annotated[dict, Depends(UserCrud.offset_paginate_params())],
-        default_order_field=User.created_at,
-    ))],
 ) -> OffsetPaginatedResponse[UserRead]:
     return await UserCrud.offset_paginate(session=session, **params, schema=UserRead)
 ```
 
+```python
+@router.get("")
+async def list_users(
+    session: SessionDep,
+    params: Annotated[dict, Depends(UserCrud.cursor_paginate_params())],
+) -> CursorPaginatedResponse[UserRead]:
+    return await UserCrud.cursor_paginate(session=session, **params, schema=UserRead)
+```
+
 The dependency adds two query parameters to the endpoint:
 
 | Parameter  | Type            |
 | ---------- | --------------- |
-| `order_by` | `str | null`   |
+| `order_by` | `str \| null`  |
 | `order`    | `asc` or `desc` |
 
 ```
 GET /users?order_by=name&order=asc         → ORDER BY users.name ASC
-GET /users?order_by=name&order=desc  → ORDER BY users.name DESC
+GET /users?order_by=role__name&order=desc  → LEFT JOIN roles ON ... ORDER BY roles.name DESC
 ```
 
-An unknown `order_by` value raises [`InvalidOrderFieldError`](../reference/exceptions.md#fastapi_toolsets.exceptions.exceptions.InvalidOrderFieldError) (HTTP 422).
+!!! info "Relationship tuples are joined automatically."
+    When a relation field is selected, the related table is LEFT OUTER JOINed automatically. An unknown `order_by` value raises [`InvalidOrderFieldError`](../reference/exceptions.md#fastapi_toolsets.exceptions.exceptions.InvalidOrderFieldError) (HTTP 422).
 
-You can also pass `order_fields` directly to override the class-level defaults:
 
-```python
+The available sort keys are returned in the `order_columns` field of [`PaginatedResponse`](../reference/schemas.md#fastapi_toolsets.schemas.PaginatedResponse). Use them to populate a sort picker in the UI, or to validate `order_by` values on the client side:
-params = UserCrud.offset_paginate_params(order_fields=[User.name])
+
+```json
+{
+  "status": "SUCCESS",
+  "data": ["..."],
+  "pagination": { "..." },
+  "order_columns": ["created_at", "name", "role__name"]
+}
 ```
 
+!!! info "Key format uses `__` as a separator for relationship chains."
+    A direct column `User.name` produces `"name"`. A relationship tuple `(User.role, Role.name)` produces `"role__name"`.
+
 ## Relationship loading
 
 !!! info "Added in `v1.1`"

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "fastapi-toolsets"
-version = "3.0.1"
+version = "3.0.3"
 description = "Production-ready utilities for FastAPI applications"
 readme = "README.md"
 license = "MIT"

src/fastapi_toolsets/__init__.py

@@ -21,4 +21,4 @@ Example usage:
         return Response(data={"user": user.username}, message="Success")
 """
 
-__version__ = "3.0.1"
+__version__ = "3.0.3"

src/fastapi_toolsets/crud/__init__.py

@@ -12,14 +12,16 @@ from ..types import (
     JoinType,
     M2MFieldType,
     OrderByClause,
+    OrderFieldType,
     SearchFieldType,
 )
-from .factory import AsyncCrud, CrudFactory
+from .factory import AsyncCrud, CrudFactory, lateral_load
 from .search import SearchConfig, get_searchable_fields
 
 __all__ = [
     "AsyncCrud",
     "CrudFactory",
+    "lateral_load",
     "FacetFieldType",
     "get_searchable_fields",
     "InvalidFacetFilterError",
@@ -28,6 +30,7 @@ __all__ = [
     "M2MFieldType",
     "NoSearchableFieldsError",
     "OrderByClause",
+    "OrderFieldType",
     "PaginationType",
     "SearchConfig",
     "SearchFieldType",

src/fastapi_toolsets/crud/factory.py

@@ -10,15 +10,32 @@ from collections.abc import Awaitable, Callable, Sequence
 from datetime import date, datetime
 from decimal import Decimal
 from enum import Enum
-from typing import Any, ClassVar, Generic, Literal, Self, cast, overload
+from typing import Any, ClassVar, Generic, Literal, NamedTuple, Self, cast, overload
 
 from fastapi import Query
 from pydantic import BaseModel
-from sqlalchemy import Date, DateTime, Float, Integer, Numeric, Uuid, and_, func, select
+from sqlalchemy import (
+    Date,
+    DateTime,
+    Float,
+    Integer,
+    Numeric,
+    Uuid,
+    and_,
+    func,
+    select,
+    true,
+)
 from sqlalchemy.dialects.postgresql import insert
 from sqlalchemy.exc import NoResultFound
 from sqlalchemy.ext.asyncio import AsyncSession
-from sqlalchemy.orm import DeclarativeBase, QueryableAttribute, selectinload
+from sqlalchemy.orm import (
+    DeclarativeBase,
+    QueryableAttribute,
+    RelationshipProperty,
+    contains_eager,
+    selectinload,
+)
 from sqlalchemy.sql.base import ExecutableOption
 from sqlalchemy.sql.roles import WhereHavingRole
 
@@ -35,9 +52,11 @@ from ..schemas import (
 from ..types import (
     FacetFieldType,
     JoinType,
+    LateralJoinType,
     M2MFieldType,
     ModelType,
     OrderByClause,
+    OrderFieldType,
     SchemaType,
     SearchFieldType,
 )
@@ -114,6 +133,78 @@ def _apply_joins(q: Any, joins: JoinType | None, outer_join: bool) -> Any:
     return q
 
 
+class _ResolvedLateral(NamedTuple):
+    joins: LateralJoinType
+    eager: list[ExecutableOption]
+
+
+class _LateralLoad:
+    """Marker used inside ``default_load_options`` for lateral join loading.
+
+    Supports only Many:One and One:One relationships (single row per parent).
+    """
+
+    __slots__ = ("rel_attr",)
+
+    def __init__(self, rel_attr: QueryableAttribute) -> None:
+        prop = rel_attr.property
+        if not isinstance(prop, RelationshipProperty):
+            raise TypeError(
+                f"lateral_load() requires a relationship attribute, got {type(prop).__name__}. "
+                "Example: lateral_load(User.team)"
+            )
+        if prop.secondary is not None:
+            raise ValueError(
+                f"lateral_load({rel_attr}) does not support Many:Many relationships. "
+                "Use selectinload() instead."
+            )
+        if prop.uselist:
+            raise ValueError(
+                f"lateral_load({rel_attr}) does not support One:Many relationships. "
+                "Use selectinload() instead."
+            )
+        self.rel_attr = rel_attr
+
+
+def lateral_load(rel_attr: QueryableAttribute) -> _LateralLoad:
+    """Mark a Many:One or One:One relationship for lateral join loading.
+
+    Raises ``ValueError`` for One:Many or Many:Many relationships.
+    """
+    return _LateralLoad(rel_attr)
+
+
+def _build_lateral_from_relationship(
+    rel_attr: QueryableAttribute,
+) -> tuple[Any, Any, ExecutableOption]:
+    """Introspect a Many:One relationship and build (lateral_subquery, true(), contains_eager)."""
+    prop = rel_attr.property
+    target_class = prop.mapper.class_
+    parent_class = prop.parent.class_
+
+    conditions = [
+        getattr(target_class, remote_col.key) == getattr(parent_class, local_col.key)
+        for local_col, remote_col in prop.local_remote_pairs
+    ]
+
+    lateral_sub = (
+        select(target_class)
+        .where(and_(*conditions))
+        .correlate(parent_class)
+        .lateral(f"_lateral_{prop.key}")
+    )
+    return lateral_sub, true(), contains_eager(rel_attr, alias=lateral_sub)
+
+
+def _apply_lateral_joins(q: Any, lateral_joins: LateralJoinType | None) -> Any:
+    """Apply lateral subqueries as LEFT JOIN LATERAL to preserve all parent rows."""
+    if not lateral_joins:
+        return q
+    for subquery, condition in lateral_joins:
+        q = q.outerjoin(subquery, condition)
+    return q
+
+
 def _apply_search_joins(q: Any, search_joins: list[Any]) -> Any:
     """Apply relationship-based outer joins (from search/filter_by) to a query."""
     seen: set[str] = set()
@@ -131,12 +222,17 @@ class AsyncCrud(Generic[ModelType]):
     Subclass this and set the `model` class variable, or use `CrudFactory`.
     """
 
+    _resolved_lateral: ClassVar[_ResolvedLateral | None] = None
+
     model: ClassVar[type[DeclarativeBase]]
     searchable_fields: ClassVar[Sequence[SearchFieldType] | None] = None
     facet_fields: ClassVar[Sequence[FacetFieldType] | None] = None
-    order_fields: ClassVar[Sequence[QueryableAttribute[Any]] | None] = None
+    order_fields: ClassVar[Sequence[OrderFieldType] | None] = None
     m2m_fields: ClassVar[M2MFieldType | None] = None
-    default_load_options: ClassVar[Sequence[ExecutableOption] | None] = None
+    default_load_options: ClassVar[Sequence[ExecutableOption | _LateralLoad] | None] = (
+        None
+    )
+    lateral_joins: ClassVar[LateralJoinType | None] = None
     cursor_column: ClassVar[Any | None] = None
 
     @classmethod
@@ -160,14 +256,60 @@ class AsyncCrud(Generic[ModelType]):
             ):
                 cls.searchable_fields = [pk_col, *raw_fields]
 
+        raw_default_opts = cls.__dict__.get("default_load_options", None)
+        if raw_default_opts:
+            joins: LateralJoinType = []
+            eager: list[ExecutableOption] = []
+            clean: list[ExecutableOption] = []
+            for opt in raw_default_opts:
+                if isinstance(opt, _LateralLoad):
+                    lat_sub, condition, eager_opt = _build_lateral_from_relationship(
+                        opt.rel_attr
+                    )
+                    joins.append((lat_sub, condition))
+                    eager.append(eager_opt)
+                else:
+                    clean.append(opt)
+            if joins:
+                cls._resolved_lateral = _ResolvedLateral(joins=joins, eager=eager)
+                cls.default_load_options = clean or None
+
+    @classmethod
+    def _get_lateral_joins(cls) -> LateralJoinType | None:
+        """Merge manual lateral_joins with ones resolved from default_load_options."""
+        resolved = cls._resolved_lateral
+        all_lateral = [
+            *(cls.lateral_joins or []),
+            *(resolved.joins if resolved else []),
+        ]
+        return all_lateral or None
+
     @classmethod
     def _resolve_load_options(
         cls, load_options: Sequence[ExecutableOption] | None
     ) -> Sequence[ExecutableOption] | None:
-        """Return load_options if provided, else fall back to default_load_options."""
+        """Return merged load options."""
         if load_options is not None:
-            return load_options
+            return list(load_options) or None
-        return cls.default_load_options
+        resolved = cls._resolved_lateral
+        # default_load_options is cleaned of _LateralLoad markers in __init_subclass__,
+        # but its declared type still includes them — cast to reflect the runtime invariant.
+        base = cast(list[ExecutableOption], cls.default_load_options or [])
+        lateral = resolved.eager if resolved else []
+        merged = [*base, *lateral]
+        return merged or None
+
+    @classmethod
+    async def _reload_with_options(
+        cls: type[Self], session: AsyncSession, instance: ModelType
+    ) -> ModelType:
+        """Re-query instance by PK with default_load_options applied."""
+        mapper = cls.model.__mapper__
+        pk_filters = [
+            getattr(cls.model, col.key) == getattr(instance, col.key)
+            for col in mapper.primary_key
+        ]
+        return await cls.get(session, filters=pk_filters)
 
     @classmethod
     async def _resolve_m2m(
@@ -278,6 +420,17 @@ class AsyncCrud(Generic[ModelType]):
             return None
         return search_field_keys(fields)
 
+    @classmethod
+    def _resolve_order_columns(
+        cls: type[Self],
+        order_fields: Sequence[OrderFieldType] | None,
+    ) -> list[str] | None:
+        """Return sort column keys, or None if no order fields configured."""
+        fields = order_fields if order_fields is not None else cls.order_fields
+        if not fields:
+            return None
+        return sorted(facet_keys(fields))
+
     @classmethod
     def _build_paginate_params(
         cls: type[Self],
@@ -290,7 +443,7 @@ class AsyncCrud(Generic[ModelType]):
         order: bool,
         search_fields: Sequence[SearchFieldType] | None,
         facet_fields: Sequence[FacetFieldType] | None,
-        order_fields: Sequence[QueryableAttribute[Any]] | None,
+        order_fields: Sequence[OrderFieldType] | None,
         default_order_field: QueryableAttribute[Any] | None,
         default_order: Literal["asc", "desc"],
     ) -> Callable[..., Awaitable[dict[str, Any]]]:
@@ -349,14 +502,15 @@ class AsyncCrud(Generic[ModelType]):
                 )
                 reserved_names.update(filter_keys)
 
-        order_field_map: dict[str, QueryableAttribute[Any]] | None = None
+        order_field_map: dict[str, OrderFieldType] | None = None
         order_valid_keys: list[str] | None = None
         if order:
             resolved_order = (
                 order_fields if order_fields is not None else cls.order_fields
             )
             if resolved_order:
-                order_field_map = {f.key: f for f in resolved_order}
+                keys = facet_keys(resolved_order)
+                order_field_map = dict(zip(keys, resolved_order))
                 order_valid_keys = sorted(order_field_map.keys())
                 all_params.extend(
                     [
@@ -408,6 +562,13 @@ class AsyncCrud(Generic[ModelType]):
                 else:
                     field = order_field_map[order_by_val]
                 if field is not None:
+                    if isinstance(field, tuple):
+                        col = field[-1]
+                        result["order_by"] = (
+                            col.asc() if order_dir == "asc" else col.desc()
+                        )
+                        result["order_joins"] = list(field[:-1])
+                    else:
                         result["order_by"] = (
                             field.asc() if order_dir == "asc" else field.desc()
                         )
@@ -434,7 +595,7 @@ class AsyncCrud(Generic[ModelType]):
         order: bool = True,
         search_fields: Sequence[SearchFieldType] | None = None,
         facet_fields: Sequence[FacetFieldType] | None = None,
-        order_fields: Sequence[QueryableAttribute[Any]] | None = None,
+        order_fields: Sequence[OrderFieldType] | None = None,
         default_order_field: QueryableAttribute[Any] | None = None,
         default_order: Literal["asc", "desc"] = "asc",
     ) -> Callable[..., Awaitable[dict[str, Any]]]:
@@ -496,7 +657,7 @@ class AsyncCrud(Generic[ModelType]):
         order: bool = True,
         search_fields: Sequence[SearchFieldType] | None = None,
         facet_fields: Sequence[FacetFieldType] | None = None,
-        order_fields: Sequence[QueryableAttribute[Any]] | None = None,
+        order_fields: Sequence[OrderFieldType] | None = None,
         default_order_field: QueryableAttribute[Any] | None = None,
         default_order: Literal["asc", "desc"] = "asc",
     ) -> Callable[..., Awaitable[dict[str, Any]]]:
@@ -561,7 +722,7 @@ class AsyncCrud(Generic[ModelType]):
         order: bool = True,
         search_fields: Sequence[SearchFieldType] | None = None,
         facet_fields: Sequence[FacetFieldType] | None = None,
-        order_fields: Sequence[QueryableAttribute[Any]] | None = None,
+        order_fields: Sequence[OrderFieldType] | None = None,
         default_order_field: QueryableAttribute[Any] | None = None,
         default_order: Literal["asc", "desc"] = "asc",
     ) -> Callable[..., Awaitable[dict[str, Any]]]:
@@ -685,6 +846,8 @@ class AsyncCrud(Generic[ModelType]):
 
             session.add(db_model)
         await session.refresh(db_model)
+        if cls.default_load_options:
+            db_model = await cls._reload_with_options(session, db_model)
         result = cast(ModelType, db_model)
         if schema:
             return Response(data=schema.model_validate(result))
@@ -827,6 +990,8 @@ class AsyncCrud(Generic[ModelType]):
         """
         q = select(cls.model)
         q = _apply_joins(q, joins, outer_join)
+        if load_options is None:
+            q = _apply_lateral_joins(q, cls._get_lateral_joins())
         q = q.where(and_(*filters))
         if resolved := cls._resolve_load_options(load_options):
             q = q.options(*resolved)
@@ -899,6 +1064,8 @@ class AsyncCrud(Generic[ModelType]):
         """
         q = select(cls.model)
         q = _apply_joins(q, joins, outer_join)
+        if load_options is None:
+            q = _apply_lateral_joins(q, cls._get_lateral_joins())
         if filters:
             q = q.where(and_(*filters))
         if resolved := cls._resolve_load_options(load_options):
@@ -944,6 +1111,8 @@ class AsyncCrud(Generic[ModelType]):
         """
         q = select(cls.model)
         q = _apply_joins(q, joins, outer_join)
+        if load_options is None:
+            q = _apply_lateral_joins(q, cls._get_lateral_joins())
         if filters:
             q = q.where(and_(*filters))
         if resolved := cls._resolve_load_options(load_options):
@@ -1040,6 +1209,8 @@ class AsyncCrud(Generic[ModelType]):
                 for rel_attr, related_instances in m2m_resolved.items():
                     setattr(db_model, rel_attr, related_instances)
         await session.refresh(db_model)
+        if cls.default_load_options:
+            db_model = await cls._reload_with_options(session, db_model)
         if schema:
             return Response(data=schema.model_validate(db_model))
         return db_model
@@ -1202,12 +1373,14 @@ class AsyncCrud(Generic[ModelType]):
         outer_join: bool = False,
         load_options: Sequence[ExecutableOption] | None = None,
         order_by: OrderByClause | None = None,
+        order_joins: list[Any] | None = None,
         page: int = 1,
         items_per_page: int = 20,
         include_total: bool = True,
         search: str | SearchConfig | None = None,
         search_fields: Sequence[SearchFieldType] | None = None,
         search_column: str | None = None,
+        order_fields: Sequence[OrderFieldType] | None = None,
         facet_fields: Sequence[FacetFieldType] | None = None,
         filter_by: dict[str, Any] | BaseModel | None = None,
         schema: type[BaseModel],
@@ -1228,6 +1401,7 @@ class AsyncCrud(Generic[ModelType]):
             search: Search query string or SearchConfig object
             search_fields: Fields to search in (overrides class default)
             search_column: Restrict search to a single column key.
+            order_fields: Fields allowed for sorting (overrides class default).
             facet_fields: Columns to compute distinct values for (overrides class default)
             filter_by: Dict of {column_key: value} to filter by declared facet fields.
                 Keys must match the column.key of a facet field. Scalar → equality,
@@ -1261,9 +1435,17 @@ class AsyncCrud(Generic[ModelType]):
         # Apply explicit joins
         q = _apply_joins(q, joins, outer_join)
 
+        # Apply lateral joins (Many:One relationship loading, excluded from count query)
+        if load_options is None:
+            q = _apply_lateral_joins(q, cls._get_lateral_joins())
+
         # Apply search joins (always outer joins for search)
         q = _apply_search_joins(q, search_joins)
 
+        # Apply order joins (relation joins required for order_by field)
+        if order_joins:
+            q = _apply_search_joins(q, order_joins)
+
         if filters:
             q = q.where(and_(*filters))
         if resolved := cls._resolve_load_options(load_options):
@@ -1308,6 +1490,7 @@ class AsyncCrud(Generic[ModelType]):
             session, facet_fields, filters, search_joins
         )
         search_columns = cls._resolve_search_columns(search_fields)
+        order_columns = cls._resolve_order_columns(order_fields)
 
         return OffsetPaginatedResponse(
             data=items,
@@ -1319,6 +1502,7 @@ class AsyncCrud(Generic[ModelType]):
             ),
             filter_attributes=filter_attributes,
             search_columns=search_columns,
+            order_columns=order_columns,
         )
 
     @classmethod
@@ -1332,10 +1516,12 @@ class AsyncCrud(Generic[ModelType]):
         outer_join: bool = False,
         load_options: Sequence[ExecutableOption] | None = None,
         order_by: OrderByClause | None = None,
+        order_joins: list[Any] | None = None,
         items_per_page: int = 20,
         search: str | SearchConfig | None = None,
         search_fields: Sequence[SearchFieldType] | None = None,
         search_column: str | None = None,
+        order_fields: Sequence[OrderFieldType] | None = None,
         facet_fields: Sequence[FacetFieldType] | None = None,
         filter_by: dict[str, Any] | BaseModel | None = None,
         schema: type[BaseModel],
@@ -1351,12 +1537,15 @@ class AsyncCrud(Generic[ModelType]):
                 tables.
             outer_join: Use LEFT OUTER JOIN instead of INNER JOIN.
             load_options: SQLAlchemy loader options. Falls back to
-                ``default_load_options`` when not provided.
+                ``default_load_options`` (including any lateral joins) when not
+                provided. When explicitly supplied, the caller takes full control
+                and lateral joins are skipped.
             order_by: Additional ordering applied after the cursor column.
             items_per_page: Number of items per page (default 20).
             search: Search query string or SearchConfig object.
             search_fields: Fields to search in (overrides class default).
             search_column: Restrict search to a single column key.
+            order_fields: Fields allowed for sorting (overrides class default).
             facet_fields: Columns to compute distinct values for (overrides class default).
             filter_by: Dict of {column_key: value} to filter by declared facet fields.
                 Keys must match the column.key of a facet field. Scalar → equality,
@@ -1407,9 +1596,17 @@ class AsyncCrud(Generic[ModelType]):
         # Apply explicit joins
         q = _apply_joins(q, joins, outer_join)
 
+        # Apply lateral joins (Many:One relationship loading)
+        if load_options is None:
+            q = _apply_lateral_joins(q, cls._get_lateral_joins())
+
         # Apply search joins (always outer joins)
         q = _apply_search_joins(q, search_joins)
 
+        # Apply order joins (relation joins required for order_by field)
+        if order_joins:
+            q = _apply_search_joins(q, order_joins)
+
         if filters:
             q = q.where(and_(*filters))
         if resolved := cls._resolve_load_options(load_options):
@@ -1468,6 +1665,7 @@ class AsyncCrud(Generic[ModelType]):
             session, facet_fields, filters, search_joins
         )
         search_columns = cls._resolve_search_columns(search_fields)
+        order_columns = cls._resolve_order_columns(order_fields)
 
         return CursorPaginatedResponse(
             data=items,
@@ -1479,6 +1677,7 @@ class AsyncCrud(Generic[ModelType]):
             ),
             filter_attributes=filter_attributes,
             search_columns=search_columns,
+            order_columns=order_columns,
         )
 
     @overload
@@ -1493,6 +1692,7 @@ class AsyncCrud(Generic[ModelType]):
         outer_join: bool = ...,
         load_options: Sequence[ExecutableOption] | None = ...,
         order_by: OrderByClause | None = ...,
+        order_joins: list[Any] | None = ...,
         page: int = ...,
         cursor: str | None = ...,
         items_per_page: int = ...,
@@ -1500,6 +1700,7 @@ class AsyncCrud(Generic[ModelType]):
         search: str | SearchConfig | None = ...,
         search_fields: Sequence[SearchFieldType] | None = ...,
         search_column: str | None = ...,
+        order_fields: Sequence[OrderFieldType] | None = ...,
         facet_fields: Sequence[FacetFieldType] | None = ...,
         filter_by: dict[str, Any] | BaseModel | None = ...,
         schema: type[BaseModel],
@@ -1517,6 +1718,7 @@ class AsyncCrud(Generic[ModelType]):
         outer_join: bool = ...,
         load_options: Sequence[ExecutableOption] | None = ...,
         order_by: OrderByClause | None = ...,
+        order_joins: list[Any] | None = ...,
         page: int = ...,
         cursor: str | None = ...,
         items_per_page: int = ...,
@@ -1524,6 +1726,7 @@ class AsyncCrud(Generic[ModelType]):
         search: str | SearchConfig | None = ...,
         search_fields: Sequence[SearchFieldType] | None = ...,
         search_column: str | None = ...,
+        order_fields: Sequence[OrderFieldType] | None = ...,
         facet_fields: Sequence[FacetFieldType] | None = ...,
         filter_by: dict[str, Any] | BaseModel | None = ...,
         schema: type[BaseModel],
@@ -1540,6 +1743,7 @@ class AsyncCrud(Generic[ModelType]):
         outer_join: bool = False,
         load_options: Sequence[ExecutableOption] | None = None,
         order_by: OrderByClause | None = None,
+        order_joins: list[Any] | None = None,
         page: int = 1,
         cursor: str | None = None,
         items_per_page: int = 20,
@@ -1547,6 +1751,7 @@ class AsyncCrud(Generic[ModelType]):
         search: str | SearchConfig | None = None,
         search_fields: Sequence[SearchFieldType] | None = None,
         search_column: str | None = None,
+        order_fields: Sequence[OrderFieldType] | None = None,
         facet_fields: Sequence[FacetFieldType] | None = None,
         filter_by: dict[str, Any] | BaseModel | None = None,
         schema: type[BaseModel],
@@ -1575,6 +1780,7 @@ class AsyncCrud(Generic[ModelType]):
             search: Search query string or :class:`.SearchConfig` object.
             search_fields: Fields to search in (overrides class default).
             search_column: Restrict search to a single column key.
+            order_fields: Fields allowed for sorting (overrides class default).
             facet_fields: Columns to compute distinct values for (overrides
                 class default).
             filter_by: Dict of ``{column_key: value}`` to filter by declared
@@ -1600,10 +1806,12 @@ class AsyncCrud(Generic[ModelType]):
                     outer_join=outer_join,
                     load_options=load_options,
                     order_by=order_by,
+                    order_joins=order_joins,
                     items_per_page=items_per_page,
                     search=search,
                     search_fields=search_fields,
                     search_column=search_column,
+                    order_fields=order_fields,
                     facet_fields=facet_fields,
                     filter_by=filter_by,
                     schema=schema,
@@ -1618,12 +1826,14 @@ class AsyncCrud(Generic[ModelType]):
                     outer_join=outer_join,
                     load_options=load_options,
                     order_by=order_by,
+                    order_joins=order_joins,
                     page=page,
                     items_per_page=items_per_page,
                     include_total=include_total,
                     search=search,
                     search_fields=search_fields,
                     search_column=search_column,
+                    order_fields=order_fields,
                     facet_fields=facet_fields,
                     filter_by=filter_by,
                     schema=schema,
@@ -1638,7 +1848,7 @@ def CrudFactory(
     base_class: type[AsyncCrud[Any]] = AsyncCrud,
     searchable_fields: Sequence[SearchFieldType] | None = None,
     facet_fields: Sequence[FacetFieldType] | None = None,
-    order_fields: Sequence[QueryableAttribute[Any]] | None = None,
+    order_fields: Sequence[OrderFieldType] | None = None,
     m2m_fields: M2MFieldType | None = None,
     default_load_options: Sequence[ExecutableOption] | None = None,
     cursor_column: Any | None = None,

src/fastapi_toolsets/crud/search.py

@@ -265,7 +265,15 @@ async def build_facets(
         else:
             q = q.order_by(column)
         result = await session.execute(q)
-        values = [row[0] for row in result.all() if row[0] is not None]
+        col_type = column.property.columns[0].type
+        enum_class = getattr(col_type, "enum_class", None)
+        values = [
+            row[0].name
+            if (enum_class is not None and isinstance(row[0], enum_class))
+            else row[0]
+            for row in result.all()
+            if row[0] is not None
+        ]
         return key, values
 
     pairs = await asyncio.gather(
@@ -347,6 +355,24 @@ def build_filter_by(
                 filters.append(column.overlap(value))
             else:
                 filters.append(column.any(value))
+        elif isinstance(col_type, Enum):
+            enum_class = col_type.enum_class
+            if enum_class is not None:
+
+                def _coerce_enum(v: Any) -> Any:
+                    if isinstance(v, enum_class):
+                        return v
+                    return enum_class[v]  # lookup by name: "PENDING", "RED"
+
+                if isinstance(value, list):
+                    filters.append(column.in_([_coerce_enum(v) for v in value]))
+                else:
+                    filters.append(column == _coerce_enum(value))
+            else:  # pragma: no cover
+                if isinstance(value, list):
+                    filters.append(column.in_(value))
+                else:
+                    filters.append(column == value)
         elif isinstance(col_type, _EQUALITY_TYPES):
             if isinstance(value, list):
                 filters.append(column.in_(value))

src/fastapi_toolsets/schemas.py

@@ -163,6 +163,7 @@ class PaginatedResponse(BaseResponse, Generic[DataT]):
     pagination_type: PaginationType | None = None
     filter_attributes: dict[str, list[Any]] | None = None
     search_columns: list[str] | None = None
+    order_columns: list[str] | None = None
 
     _discriminated_union_cache: ClassVar[dict[Any, Any]] = {}
 

src/fastapi_toolsets/types.py

@@ -16,12 +16,14 @@ SchemaType = TypeVar("SchemaType", bound=BaseModel)
 
 # CRUD type aliases
 JoinType = list[tuple[type[DeclarativeBase] | Any, Any]]
+LateralJoinType = list[tuple[Any, Any]]
 M2MFieldType = Mapping[str, QueryableAttribute[Any]]
 OrderByClause = ColumnElement[Any] | QueryableAttribute[Any]
 
-# Search / facet type aliases
+# Search / facet / order type aliases
 SearchFieldType = InstrumentedAttribute[Any] | tuple[InstrumentedAttribute[Any], ...]
 FacetFieldType = SearchFieldType
+OrderFieldType = SearchFieldType
 
 # Dependency type aliases
 SessionDependency = Callable[[], AsyncGenerator[AsyncSession, None]] | Any

tests/conftest.py

@@ -2,6 +2,7 @@
 
 import os
 import uuid
+from enum import Enum
 
 import pytest
 from pydantic import BaseModel
@@ -12,6 +13,7 @@ from sqlalchemy import (
     Column,
     Date,
     DateTime,
+    Enum as SAEnum,
     ForeignKey,
     Integer,
     JSON,
@@ -139,6 +141,35 @@ class Post(Base):
     tags: Mapped[list[Tag]] = relationship(secondary=post_tags)
 
 
+class OrderStatus(int, Enum):
+    """Integer-backed enum for order status."""
+
+    PENDING = 1
+    PROCESSING = 2
+    SHIPPED = 3
+    CANCELLED = 4
+
+
+class Color(str, Enum):
+    """String-backed enum for color."""
+
+    RED = "red"
+    GREEN = "green"
+    BLUE = "blue"
+
+
+class Order(Base):
+    """Test model with an IntEnum column (Enum(int, Enum)) and a raw Integer column."""
+
+    __tablename__ = "orders"
+
+    id: Mapped[uuid.UUID] = mapped_column(Uuid, primary_key=True, default=uuid.uuid4)
+    name: Mapped[str] = mapped_column(String(100))
+    status: Mapped[OrderStatus] = mapped_column(SAEnum(OrderStatus))
+    priority: Mapped[int] = mapped_column(Integer)
+    color: Mapped[Color] = mapped_column(SAEnum(Color))
+
+
 class Transfer(Base):
     """Test model with two FKs to the same table (users)."""
 
@@ -311,6 +342,26 @@ class ArticleRead(PydanticBase):
     labels: list[str]
 
 
+class OrderCreate(BaseModel):
+    """Schema for creating an order."""
+
+    id: uuid.UUID | None = None
+    name: str
+    status: OrderStatus
+    priority: int = 0
+    color: Color = Color.RED
+
+
+class OrderRead(PydanticBase):
+    """Schema for reading an order."""
+
+    id: uuid.UUID
+    name: str
+    status: OrderStatus
+    priority: int
+    color: Color
+
+
 class TransferCreate(BaseModel):
     """Schema for creating a transfer."""
 
@@ -327,6 +378,7 @@ class TransferRead(PydanticBase):
     amount: str
 
 
+OrderCrud = CrudFactory(Order)
 TransferCrud = CrudFactory(Transfer)
 ArticleCrud = CrudFactory(Article)
 RoleCrud = CrudFactory(Role)

tests/test_crud.py

@@ -6,9 +6,15 @@ import pytest
 from sqlalchemy.ext.asyncio import AsyncSession
 from sqlalchemy.orm import selectinload
 
-from fastapi_toolsets.crud import CrudFactory, PaginationType
+from fastapi_toolsets.crud import CrudFactory, PaginationType, lateral_load
-from fastapi_toolsets.crud.factory import AsyncCrud, _CursorDirection
+from fastapi_toolsets.crud.factory import (
+    AsyncCrud,
+    _CursorDirection,
+    _LateralLoad,
+    _ResolvedLateral,
+)
 from fastapi_toolsets.exceptions import NotFoundError
+from fastapi_toolsets.schemas import PydanticBase
 
 from .conftest import (
     EventCreate,
@@ -51,6 +57,12 @@ from .conftest import (
 )
 
 
+class UserWithRoleRead(PydanticBase):
+    id: uuid.UUID
+    username: str
+    role: RoleRead | None = None
+
+
 class TestCrudFactory:
     """Tests for CrudFactory."""
 
@@ -208,11 +220,11 @@ class TestResolveLoadOptions:
         assert crud._resolve_load_options(None) is None
 
     def test_empty_list_overrides_default(self):
-        """An empty list is a valid override and disables default_load_options."""
+        """An explicit empty list disables default_load_options (no options applied)."""
         default = [selectinload(User.role)]
         crud = CrudFactory(User, default_load_options=default)
-        # Empty list is not None, so it should replace default
+        # Empty list replaces default; None and [] are both falsy → no options applied
-        assert crud._resolve_load_options([]) == []
+        assert not crud._resolve_load_options([])
 
 
 class TestResolveSearchColumns:
@@ -247,6 +259,60 @@ class TestResolveSearchColumns:
         assert "username" not in result
 
 
+class TestResolveOrderColumns:
+    """Tests for _resolve_order_columns logic."""
+
+    def test_returns_none_when_no_order_fields(self):
+        """Returns None when cls.order_fields is None and no order_fields passed."""
+
+        class AbstractCrud(AsyncCrud[User]):
+            pass
+
+        assert AbstractCrud._resolve_order_columns(None) is None
+
+    def test_returns_none_when_empty_order_fields_passed(self):
+        """Returns None when an empty list is passed explicitly."""
+        crud = CrudFactory(User)
+        assert crud._resolve_order_columns([]) is None
+
+    def test_returns_keys_from_class_order_fields(self):
+        """Returns sorted column keys from cls.order_fields when no override passed."""
+        crud = CrudFactory(User, order_fields=[User.username])
+        result = crud._resolve_order_columns(None)
+        assert result is not None
+        assert "username" in result
+
+    def test_order_fields_override_takes_priority(self):
+        """Explicit order_fields override cls.order_fields."""
+        crud = CrudFactory(User, order_fields=[User.username])
+        result = crud._resolve_order_columns([User.email])
+        assert result is not None
+        assert "email" in result
+        assert "username" not in result
+
+    def test_returns_sorted_keys(self):
+        """Keys are returned in sorted order."""
+        crud = CrudFactory(User, order_fields=[User.email, User.username])
+        result = crud._resolve_order_columns(None)
+        assert result is not None
+        assert result == sorted(result)
+
+    def test_relation_tuple_produces_dunder_key(self):
+        """A (rel, column) tuple produces a 'rel__column' key."""
+        crud = CrudFactory(User, order_fields=[(User.role, Role.name)])
+        result = crud._resolve_order_columns(None)
+        assert result == ["role__name"]
+
+    def test_mixed_flat_and_relation_fields(self):
+        """Flat and relation fields can be mixed; keys are sorted."""
+        crud = CrudFactory(User, order_fields=[User.username, (User.role, Role.name)])
+        result = crud._resolve_order_columns(None)
+        assert result is not None
+        assert "username" in result
+        assert "role__name" in result
+        assert result == sorted(result)
+
+
 class TestDefaultLoadOptionsIntegration:
     """Integration tests for default_load_options with real DB queries."""
 
@@ -305,13 +371,6 @@ class TestDefaultLoadOptionsIntegration:
         self, db_session: AsyncSession
     ):
         """default_load_options loads relationships automatically on offset_paginate()."""
-        from fastapi_toolsets.schemas import PydanticBase
-
-        class UserWithRoleRead(PydanticBase):
-            id: uuid.UUID
-            username: str
-            role: RoleRead | None = None
-
         UserWithDefaultLoad = CrudFactory(
             User, default_load_options=[selectinload(User.role)]
         )
@@ -326,6 +385,43 @@ class TestDefaultLoadOptionsIntegration:
         assert result.data[0].role is not None
         assert result.data[0].role.name == "admin"
 
+    @pytest.mark.anyio
+    async def test_default_load_options_applied_to_create(
+        self, db_session: AsyncSession
+    ):
+        """default_load_options loads relationships after create()."""
+        UserWithDefaultLoad = CrudFactory(
+            User, default_load_options=[selectinload(User.role)]
+        )
+        role = await RoleCrud.create(db_session, RoleCreate(name="admin"))
+        user = await UserWithDefaultLoad.create(
+            db_session,
+            UserCreate(username="alice", email="alice@test.com", role_id=role.id),
+        )
+        assert user.role is not None
+        assert user.role.name == "admin"
+
+    @pytest.mark.anyio
+    async def test_default_load_options_applied_to_update(
+        self, db_session: AsyncSession
+    ):
+        """default_load_options loads relationships after update()."""
+        UserWithDefaultLoad = CrudFactory(
+            User, default_load_options=[selectinload(User.role)]
+        )
+        role = await RoleCrud.create(db_session, RoleCreate(name="admin"))
+        user = await UserCrud.create(
+            db_session,
+            UserCreate(username="alice", email="alice@test.com"),
+        )
+        updated = await UserWithDefaultLoad.update(
+            db_session,
+            UserUpdate(role_id=role.id),
+            filters=[User.id == user.id],
+        )
+        assert updated.role is not None
+        assert updated.role.name == "admin"
+
     @pytest.mark.anyio
     async def test_load_options_overrides_default_load_options(
         self, db_session: AsyncSession
@@ -2371,12 +2467,7 @@ class TestCursorPaginateExtraOptions:
     @pytest.mark.anyio
     async def test_with_load_options(self, db_session: AsyncSession):
         """cursor_paginate passes load_options to the query."""
-        from fastapi_toolsets.schemas import CursorPagination, PydanticBase
+        from fastapi_toolsets.schemas import CursorPagination
-
-        class UserWithRoleRead(PydanticBase):
-            id: uuid.UUID
-            username: str
-            role: RoleRead | None = None
 
         role = await RoleCrud.create(db_session, RoleCreate(name="manager"))
         for i in range(3):
@@ -2742,3 +2833,445 @@ class TestPaginate:
 
         assert isinstance(result.pagination, OffsetPagination)
         assert result.pagination.total_count is None
+
+
+class TestLateralLoadValidation:
+    """lateral_load() raises immediately for bad relationship types."""
+
+    def test_valid_many_to_one_returns_marker(self):
+        """lateral_load() on a Many:One rel returns a _LateralLoad with rel_attr set."""
+        marker = lateral_load(User.role)
+        assert isinstance(marker, _LateralLoad)
+        assert marker.rel_attr is User.role
+
+    def test_raises_type_error_for_plain_column(self):
+        """lateral_load() raises TypeError when passed a plain column."""
+        with pytest.raises(TypeError, match="relationship attribute"):
+            lateral_load(User.username)
+
+    def test_raises_value_error_for_many_to_many(self):
+        """lateral_load() raises ValueError for Many:Many (secondary table)."""
+        with pytest.raises(ValueError, match="Many:Many"):
+            lateral_load(Post.tags)
+
+    def test_raises_value_error_for_one_to_many(self):
+        """lateral_load() raises ValueError for One:Many (uselist=True)."""
+        with pytest.raises(ValueError, match="One:Many"):
+            lateral_load(Role.users)
+
+
+class TestLateralLoadInSubclass:
+    """lateral_load() markers in default_load_options are processed at class definition."""
+
+    def test_marker_extracted_from_default_load_options(self):
+        """_LateralLoad is removed from default_load_options and stored in _resolved_lateral."""
+
+        class UserLateralCrud(AsyncCrud[User]):
+            model = User
+            default_load_options = [lateral_load(User.role)]
+
+        assert UserLateralCrud.default_load_options is None
+        assert UserLateralCrud._resolved_lateral is not None
+
+    def test_resolved_lateral_has_one_join_and_eager(self):
+        """_resolved_lateral contains exactly one join and one eager option."""
+
+        class UserLateralCrud(AsyncCrud[User]):
+            model = User
+            default_load_options = [lateral_load(User.role)]
+
+        resolved = UserLateralCrud._resolved_lateral
+        assert isinstance(resolved, _ResolvedLateral)
+        assert len(resolved.joins) == 1
+        assert len(resolved.eager) == 1
+
+    def test_regular_options_preserved_alongside_lateral(self):
+        """Non-lateral opts stay in default_load_options; lateral marker is extracted."""
+        regular = selectinload(User.role)
+
+        class UserMixedCrud(AsyncCrud[User]):
+            model = User
+            default_load_options = [lateral_load(User.role), regular]
+
+        assert UserMixedCrud._resolved_lateral is not None
+        assert UserMixedCrud.default_load_options == [regular]
+
+    def test_no_lateral_leaves_default_load_options_untouched(self):
+        """When no lateral marker is present, default_load_options is unchanged."""
+        opts = [selectinload(User.role)]
+
+        class UserNormalCrud(AsyncCrud[User]):
+            model = User
+            default_load_options = opts
+
+        assert UserNormalCrud.default_load_options is opts
+        assert UserNormalCrud._resolved_lateral is None
+
+    def test_no_default_load_options_leaves_resolved_lateral_none(self):
+        """_resolved_lateral stays None when default_load_options is not set."""
+
+        class UserPlainCrud(AsyncCrud[User]):
+            model = User
+
+        assert UserPlainCrud._resolved_lateral is None
+
+
+class TestResolveLoadOptionsWithLateral:
+    """_resolve_load_options always appends lateral eager options."""
+
+    def test_lateral_eager_included_when_no_call_site_opts(self):
+        """contains_eager from lateral_load is returned when load_options=None."""
+
+        class UserLateralCrud(AsyncCrud[User]):
+            model = User
+            default_load_options = [lateral_load(User.role)]
+
+        resolved = UserLateralCrud._resolve_load_options(None)
+        assert resolved is not None
+        assert len(resolved) == 1  # the contains_eager
+
+    def test_call_site_opts_bypass_lateral_eager(self):
+        """When call-site load_options are provided, lateral eager is NOT appended."""
+        extra = selectinload(User.role)
+
+        class UserLateralCrud(AsyncCrud[User]):
+            model = User
+            default_load_options = [lateral_load(User.role)]
+
+        resolved = UserLateralCrud._resolve_load_options([extra])
+        assert resolved is not None
+        assert len(resolved) == 1  # only the call-site option; lateral eager skipped
+
+    def test_lateral_eager_appended_to_default_load_options(self):
+        """default_load_options (regular) + lateral eager are both returned."""
+        regular = selectinload(User.role)
+
+        class UserMixedCrud(AsyncCrud[User]):
+            model = User
+            default_load_options = [lateral_load(User.role), regular]
+
+        resolved = UserMixedCrud._resolve_load_options(None)
+        assert resolved is not None
+        assert len(resolved) == 2
+
+
+class TestGetLateralJoins:
+    """_get_lateral_joins merges auto-resolved and manual lateral_joins."""
+
+    def test_returns_none_when_no_lateral_configured(self):
+        """Returns None when neither lateral_joins nor lateral_load is set."""
+
+        class UserPlainCrud(AsyncCrud[User]):
+            model = User
+
+        assert UserPlainCrud._get_lateral_joins() is None
+
+    def test_returns_resolved_lateral_joins(self):
+        """Returns the join tuple built from lateral_load()."""
+
+        class UserLateralCrud(AsyncCrud[User]):
+            model = User
+            default_load_options = [lateral_load(User.role)]
+
+        joins = UserLateralCrud._get_lateral_joins()
+        assert joins is not None
+        assert len(joins) == 1
+
+    def test_manual_lateral_joins_included(self):
+        """Manual lateral_joins class var is included in _get_lateral_joins."""
+        from sqlalchemy import select, true
+
+        manual_sub = select(Role).where(Role.id == User.role_id).lateral("_manual_role")
+
+        class UserManualCrud(AsyncCrud[User]):
+            model = User
+            lateral_joins = [(manual_sub, true())]
+
+        joins = UserManualCrud._get_lateral_joins()
+        assert joins is not None
+        assert len(joins) == 1
+
+    def test_manual_and_auto_lateral_joins_merged(self):
+        """Both manual lateral_joins and auto-resolved from lateral_load are combined."""
+        from sqlalchemy import select, true
+
+        manual_sub = select(Role).where(Role.id == User.role_id).lateral("_manual_role")
+
+        class UserBothCrud(AsyncCrud[User]):
+            model = User
+            lateral_joins = [(manual_sub, true())]
+            default_load_options = [lateral_load(User.role)]
+
+        joins = UserBothCrud._get_lateral_joins()
+        assert joins is not None
+        assert len(joins) == 2
+
+
+class TestLateralLoadIntegration:
+    """lateral_load() in real DB queries: relationship loaded, pagination correct."""
+
+    @pytest.mark.anyio
+    async def test_get_loads_relationship(self, db_session: AsyncSession):
+        """get() populates the relationship via lateral join."""
+
+        class UserLateralCrud(AsyncCrud[User]):
+            model = User
+            default_load_options = [lateral_load(User.role)]
+
+        role = await RoleCrud.create(db_session, RoleCreate(name="admin"))
+        user = await UserCrud.create(
+            db_session,
+            UserCreate(username="alice", email="alice@test.com", role_id=role.id),
+        )
+
+        fetched = await UserLateralCrud.get(db_session, [User.id == user.id])
+        assert fetched.role is not None
+        assert fetched.role.name == "admin"
+
+    @pytest.mark.anyio
+    async def test_get_null_fk_preserved(self, db_session: AsyncSession):
+        """User with null role_id still returned (LEFT JOIN behaviour)."""
+
+        class UserLateralCrud(AsyncCrud[User]):
+            model = User
+            default_load_options = [lateral_load(User.role)]
+
+        user = await UserCrud.create(
+            db_session, UserCreate(username="bob", email="bob@test.com")
+        )
+
+        fetched = await UserLateralCrud.get(db_session, [User.id == user.id])
+        assert fetched is not None
+        assert fetched.role is None
+
+    @pytest.mark.anyio
+    async def test_first_loads_relationship(self, db_session: AsyncSession):
+        """first() populates the relationship via lateral join."""
+
+        class UserLateralCrud(AsyncCrud[User]):
+            model = User
+            default_load_options = [lateral_load(User.role)]
+
+        role = await RoleCrud.create(db_session, RoleCreate(name="editor"))
+        await UserCrud.create(
+            db_session,
+            UserCreate(username="carol", email="carol@test.com", role_id=role.id),
+        )
+
+        user = await UserLateralCrud.first(db_session)
+        assert user is not None
+        assert user.role is not None
+        assert user.role.name == "editor"
+
+    @pytest.mark.anyio
+    async def test_get_multi_loads_relationship(self, db_session: AsyncSession):
+        """get_multi() populates the relationship via lateral join for all rows."""
+
+        class UserLateralCrud(AsyncCrud[User]):
+            model = User
+            default_load_options = [lateral_load(User.role)]
+
+        role = await RoleCrud.create(db_session, RoleCreate(name="member"))
+        for i in range(3):
+            await UserCrud.create(
+                db_session,
+                UserCreate(
+                    username=f"user{i}", email=f"u{i}@test.com", role_id=role.id
+                ),
+            )
+
+        users = await UserLateralCrud.get_multi(db_session)
+        assert len(users) == 3
+        assert all(u.role is not None and u.role.name == "member" for u in users)
+
+    @pytest.mark.anyio
+    async def test_offset_paginate_correct_count(self, db_session: AsyncSession):
+        """offset_paginate total_count is not inflated by the lateral join."""
+
+        class UserLateralCrud(AsyncCrud[User]):
+            model = User
+            default_load_options = [lateral_load(User.role)]
+
+        role = await RoleCrud.create(db_session, RoleCreate(name="admin"))
+        for i in range(5):
+            await UserCrud.create(
+                db_session,
+                UserCreate(
+                    username=f"user{i}", email=f"u{i}@test.com", role_id=role.id
+                ),
+            )
+
+        result = await UserLateralCrud.offset_paginate(
+            db_session, schema=UserWithRoleRead, items_per_page=10
+        )
+        assert result.pagination.total_count == 5
+        assert len(result.data) == 5
+
+    @pytest.mark.anyio
+    async def test_offset_paginate_loads_relationship(self, db_session: AsyncSession):
+        """offset_paginate serializes relationship data loaded via lateral."""
+
+        class UserLateralCrud(AsyncCrud[User]):
+            model = User
+            default_load_options = [lateral_load(User.role)]
+
+        role = await RoleCrud.create(db_session, RoleCreate(name="admin"))
+        await UserCrud.create(
+            db_session,
+            UserCreate(username="alice", email="alice@test.com", role_id=role.id),
+        )
+
+        result = await UserLateralCrud.offset_paginate(
+            db_session, schema=UserWithRoleRead, items_per_page=10
+        )
+        assert result.data[0].role is not None
+        assert result.data[0].role.name == "admin"
+
+    @pytest.mark.anyio
+    async def test_offset_paginate_mixed_null_fk(self, db_session: AsyncSession):
+        """offset_paginate returns all users including those with null role_id."""
+
+        class UserLateralCrud(AsyncCrud[User]):
+            model = User
+            default_load_options = [lateral_load(User.role)]
+
+        role = await RoleCrud.create(db_session, RoleCreate(name="admin"))
+        await UserCrud.create(
+            db_session,
+            UserCreate(username="with_role", email="a@test.com", role_id=role.id),
+        )
+        await UserCrud.create(
+            db_session, UserCreate(username="no_role", email="b@test.com")
+        )
+
+        result = await UserLateralCrud.offset_paginate(
+            db_session, schema=UserWithRoleRead, items_per_page=10
+        )
+        assert result.pagination.total_count == 2
+
+    @pytest.mark.anyio
+    async def test_cursor_paginate_loads_relationship(self, db_session: AsyncSession):
+        """cursor_paginate populates the relationship via lateral join."""
+
+        class UserLateralCursorCrud(AsyncCrud[User]):
+            model = User
+            cursor_column = User.id
+            default_load_options = [lateral_load(User.role)]
+
+        role = await RoleCrud.create(db_session, RoleCreate(name="admin"))
+        for i in range(3):
+            await UserCrud.create(
+                db_session,
+                UserCreate(
+                    username=f"user{i}", email=f"u{i}@test.com", role_id=role.id
+                ),
+            )
+
+        result = await UserLateralCursorCrud.cursor_paginate(
+            db_session, schema=UserWithRoleRead, items_per_page=10
+        )
+        assert len(result.data) == 3
+        assert all(item.role is not None for item in result.data)
+
+    @pytest.mark.anyio
+    async def test_offset_paginate_with_search_and_lateral(
+        self, db_session: AsyncSession
+    ):
+        """search filter works alongside lateral join."""
+
+        class UserLateralCrud(AsyncCrud[User]):
+            model = User
+            default_load_options = [lateral_load(User.role)]
+            searchable_fields = [User.username]
+
+        role = await RoleCrud.create(db_session, RoleCreate(name="admin"))
+        await UserCrud.create(
+            db_session,
+            UserCreate(username="alice", email="a@test.com", role_id=role.id),
+        )
+        await UserCrud.create(
+            db_session, UserCreate(username="bob", email="b@test.com", role_id=role.id)
+        )
+
+        result = await UserLateralCrud.offset_paginate(
+            db_session, schema=UserWithRoleRead, search="alice", items_per_page=10
+        )
+        assert result.pagination.total_count == 1
+        assert result.data[0].username == "alice"
+
+    @pytest.mark.anyio
+    async def test_first_call_site_load_options_bypasses_lateral(
+        self, db_session: AsyncSession
+    ):
+        """When load_options is provided, lateral join is skipped (no conflict)."""
+
+        class UserLateralCrud(AsyncCrud[User]):
+            model = User
+            default_load_options = [lateral_load(User.role)]
+
+        role = await RoleCrud.create(db_session, RoleCreate(name="admin"))
+        user = await UserCrud.create(
+            db_session,
+            UserCreate(username="alice", email="alice@test.com", role_id=role.id),
+        )
+
+        # Passing explicit load_options bypasses the lateral join — role loaded via selectinload
+        fetched = await UserLateralCrud.first(
+            db_session,
+            filters=[User.id == user.id],
+            load_options=[selectinload(User.role)],
+        )
+        assert fetched is not None
+        assert fetched.role is not None
+        assert fetched.role.name == "admin"
+
+    @pytest.mark.anyio
+    async def test_get_multi_call_site_load_options_bypasses_lateral(
+        self, db_session: AsyncSession
+    ):
+        """When load_options is provided, lateral join is skipped (no conflict)."""
+
+        class UserLateralCrud(AsyncCrud[User]):
+            model = User
+            default_load_options = [lateral_load(User.role)]
+
+        role = await RoleCrud.create(db_session, RoleCreate(name="viewer"))
+        for i in range(2):
+            await UserCrud.create(
+                db_session,
+                UserCreate(username=f"u{i}", email=f"u{i}@test.com", role_id=role.id),
+            )
+
+        # Passing explicit load_options bypasses the lateral join — role loaded via selectinload
+        users = await UserLateralCrud.get_multi(
+            db_session, load_options=[selectinload(User.role)]
+        )
+        assert len(users) == 2
+        assert all(u.role is not None and u.role.name == "viewer" for u in users)
+
+    @pytest.mark.anyio
+    async def test_offset_paginate_call_site_load_options_bypasses_lateral(
+        self, db_session: AsyncSession
+    ):
+        """When load_options is provided, lateral join is skipped (no conflict)."""
+
+        class UserLateralCrud(AsyncCrud[User]):
+            model = User
+            default_load_options = [lateral_load(User.role)]
+
+        role = await RoleCrud.create(db_session, RoleCreate(name="editor"))
+        for i in range(3):
+            await UserCrud.create(
+                db_session,
+                UserCreate(username=f"e{i}", email=f"e{i}@test.com", role_id=role.id),
+            )
+
+        # Passing explicit load_options bypasses the lateral join — role loaded via selectinload
+        result = await UserLateralCrud.offset_paginate(
+            db_session,
+            schema=UserWithRoleRead,
+            items_per_page=10,
+            load_options=[selectinload(User.role)],
+        )
+        assert result.pagination.total_count == 3
+        assert all(item.role is not None for item in result.data)

tests/test_crud_search.py

@@ -23,6 +23,12 @@ from .conftest import (
     ArticleCreate,
     ArticleCrud,
     ArticleRead,
+    Color,
+    Order,
+    OrderCreate,
+    OrderCrud,
+    OrderRead,
+    OrderStatus,
     Role,
     RoleCreate,
     RoleCrud,
@@ -1121,6 +1127,253 @@ class TestFilterBy:
         assert "JSON" in exc_info.value.col_type
 
 
+class TestFilterByIntEnum:
+    """Tests for filter_by on columns typed as (int, Enum) / IntEnum."""
+
+    @pytest.mark.anyio
+    async def test_filter_by_intenum_member(self, db_session: AsyncSession):
+        """filter_by with an IntEnum member value filters correctly."""
+        OrderFacetCrud = CrudFactory(Order, facet_fields=[Order.status])
+        await OrderCrud.create(
+            db_session, OrderCreate(name="order-1", status=OrderStatus.PENDING)
+        )
+        await OrderCrud.create(
+            db_session, OrderCreate(name="order-2", status=OrderStatus.SHIPPED)
+        )
+        await OrderCrud.create(
+            db_session, OrderCreate(name="order-3", status=OrderStatus.PENDING)
+        )
+
+        result = await OrderFacetCrud.offset_paginate(
+            db_session,
+            filter_by={"status": OrderStatus.PENDING},
+            schema=OrderRead,
+        )
+
+        assert isinstance(result.pagination, OffsetPagination)
+        assert result.pagination.total_count == 2
+        names = {o.name for o in result.data}
+        assert names == {"order-1", "order-3"}
+
+    @pytest.mark.anyio
+    async def test_filter_by_plain_int_value_raises(self, db_session: AsyncSession):
+        """filter_by with a plain int on an IntEnum column raises KeyError — use name or member."""
+        OrderFacetCrud = CrudFactory(Order, facet_fields=[Order.status])
+
+        with pytest.raises(KeyError):
+            await OrderFacetCrud.offset_paginate(
+                db_session,
+                filter_by={"status": 1},
+                schema=OrderRead,
+            )
+
+    @pytest.mark.anyio
+    async def test_filter_by_intenum_list(self, db_session: AsyncSession):
+        """filter_by with a list of IntEnum members produces an IN filter."""
+        OrderFacetCrud = CrudFactory(Order, facet_fields=[Order.status])
+        await OrderCrud.create(
+            db_session, OrderCreate(name="order-1", status=OrderStatus.PENDING)
+        )
+        await OrderCrud.create(
+            db_session, OrderCreate(name="order-2", status=OrderStatus.SHIPPED)
+        )
+        await OrderCrud.create(
+            db_session, OrderCreate(name="order-3", status=OrderStatus.CANCELLED)
+        )
+
+        result = await OrderFacetCrud.offset_paginate(
+            db_session,
+            filter_by={"status": [OrderStatus.PENDING, OrderStatus.SHIPPED]},
+            schema=OrderRead,
+        )
+
+        assert isinstance(result.pagination, OffsetPagination)
+        assert result.pagination.total_count == 2
+        names = {o.name for o in result.data}
+        assert names == {"order-1", "order-2"}
+
+    @pytest.mark.anyio
+    async def test_filter_by_plain_int_list_raises(self, db_session: AsyncSession):
+        """filter_by with a list of plain ints on an IntEnum column raises KeyError — use names or members."""
+        OrderFacetCrud = CrudFactory(Order, facet_fields=[Order.status])
+
+        with pytest.raises(KeyError):
+            await OrderFacetCrud.offset_paginate(
+                db_session,
+                filter_by={"status": [1, 3]},
+                schema=OrderRead,
+            )
+
+    @pytest.mark.anyio
+    async def test_filter_by_intenum_name_string(self, db_session: AsyncSession):
+        """filter_by with the enum member name as a string filters correctly."""
+        OrderFacetCrud = CrudFactory(Order, facet_fields=[Order.status])
+        await OrderCrud.create(
+            db_session, OrderCreate(name="order-1", status=OrderStatus.PENDING)
+        )
+        await OrderCrud.create(
+            db_session, OrderCreate(name="order-2", status=OrderStatus.SHIPPED)
+        )
+
+        result = await OrderFacetCrud.offset_paginate(
+            db_session,
+            filter_by={
+                "status": "PENDING"
+            },  # name as string, e.g. from HTTP query param
+            schema=OrderRead,
+        )
+
+        assert isinstance(result.pagination, OffsetPagination)
+        assert result.pagination.total_count == 1
+        assert result.data[0].name == "order-1"
+
+    @pytest.mark.anyio
+    async def test_filter_by_intenum_name_string_list(self, db_session: AsyncSession):
+        """filter_by with a list of enum name strings produces an IN filter."""
+        OrderFacetCrud = CrudFactory(Order, facet_fields=[Order.status])
+        await OrderCrud.create(
+            db_session, OrderCreate(name="order-1", status=OrderStatus.PENDING)
+        )
+        await OrderCrud.create(
+            db_session, OrderCreate(name="order-2", status=OrderStatus.SHIPPED)
+        )
+        await OrderCrud.create(
+            db_session, OrderCreate(name="order-3", status=OrderStatus.CANCELLED)
+        )
+
+        result = await OrderFacetCrud.offset_paginate(
+            db_session,
+            filter_by={"status": ["PENDING", "SHIPPED"]},
+            schema=OrderRead,
+        )
+
+        assert isinstance(result.pagination, OffsetPagination)
+        assert result.pagination.total_count == 2
+        names = {o.name for o in result.data}
+        assert names == {"order-1", "order-2"}
+
+
+class TestFilterByStrEnum:
+    """Tests for filter_by on columns typed as (str, Enum) / StrEnum (lines 364-367)."""
+
+    @pytest.mark.anyio
+    async def test_filter_by_strenum_member(self, db_session: AsyncSession):
+        """filter_by with a StrEnum member on a string Enum column filters correctly."""
+        OrderColorCrud = CrudFactory(Order, facet_fields=[Order.color])
+        await OrderCrud.create(
+            db_session,
+            OrderCreate(name="red-order", status=OrderStatus.PENDING, color=Color.RED),
+        )
+        await OrderCrud.create(
+            db_session,
+            OrderCreate(
+                name="blue-order", status=OrderStatus.PENDING, color=Color.BLUE
+            ),
+        )
+
+        result = await OrderColorCrud.offset_paginate(
+            db_session,
+            filter_by={"color": Color.RED},
+            schema=OrderRead,
+        )
+
+        assert isinstance(result.pagination, OffsetPagination)
+        assert result.pagination.total_count == 1
+        assert result.data[0].name == "red-order"
+
+    @pytest.mark.anyio
+    async def test_filter_by_strenum_list(self, db_session: AsyncSession):
+        """filter_by with a list of StrEnum members produces an IN filter."""
+        OrderColorCrud = CrudFactory(Order, facet_fields=[Order.color])
+        await OrderCrud.create(
+            db_session,
+            OrderCreate(name="red-order", status=OrderStatus.PENDING, color=Color.RED),
+        )
+        await OrderCrud.create(
+            db_session,
+            OrderCreate(
+                name="green-order", status=OrderStatus.PENDING, color=Color.GREEN
+            ),
+        )
+        await OrderCrud.create(
+            db_session,
+            OrderCreate(
+                name="blue-order", status=OrderStatus.PENDING, color=Color.BLUE
+            ),
+        )
+
+        result = await OrderColorCrud.offset_paginate(
+            db_session,
+            filter_by={"color": [Color.RED, Color.BLUE]},
+            schema=OrderRead,
+        )
+
+        assert isinstance(result.pagination, OffsetPagination)
+        assert result.pagination.total_count == 2
+        names = {o.name for o in result.data}
+        assert names == {"red-order", "blue-order"}
+
+
+class TestFilterByIntegerColumn:
+    """Tests for filter_by on plain Integer columns with IntEnum values."""
+
+    @pytest.mark.anyio
+    async def test_filter_by_integer_column_with_intenum_member(
+        self, db_session: AsyncSession
+    ):
+        """filter_by with an IntEnum member on an Integer column works correctly."""
+        OrderPriorityCrud = CrudFactory(Order, facet_fields=[Order.priority])
+        await OrderCrud.create(
+            db_session,
+            OrderCreate(
+                name="order-1", status=OrderStatus.PENDING, priority=OrderStatus.PENDING
+            ),
+        )
+        await OrderCrud.create(
+            db_session,
+            OrderCreate(
+                name="order-2", status=OrderStatus.SHIPPED, priority=OrderStatus.SHIPPED
+            ),
+        )
+
+        result = await OrderPriorityCrud.offset_paginate(
+            db_session,
+            filter_by={
+                "priority": OrderStatus.PENDING
+            },  # IntEnum member on Integer col
+            schema=OrderRead,
+        )
+
+        assert isinstance(result.pagination, OffsetPagination)
+        assert result.pagination.total_count == 1
+        assert result.data[0].name == "order-1"
+
+    @pytest.mark.anyio
+    async def test_filter_by_integer_column_with_plain_int(
+        self, db_session: AsyncSession
+    ):
+        """filter_by with a plain int on an Integer column works correctly."""
+        OrderPriorityCrud = CrudFactory(Order, facet_fields=[Order.priority])
+        await OrderCrud.create(
+            db_session,
+            OrderCreate(name="order-1", status=OrderStatus.PENDING, priority=1),
+        )
+        await OrderCrud.create(
+            db_session,
+            OrderCreate(name="order-2", status=OrderStatus.SHIPPED, priority=3),
+        )
+
+        result = await OrderPriorityCrud.offset_paginate(
+            db_session,
+            filter_by={"priority": 1},
+            schema=OrderRead,
+        )
+
+        assert isinstance(result.pagination, OffsetPagination)
+        assert result.pagination.total_count == 1
+        assert result.data[0].name == "order-1"
+
+
 class TestFilterParamsViaConsolidated:
     """Tests for filter params via consolidated offset_paginate_params()."""
 
@@ -1516,6 +1769,111 @@ class TestSearchColumns:
         assert result.data[0].username == "bob"
 
 
+class TestOrderColumns:
+    """Tests for order_columns in paginated responses."""
+
+    @pytest.mark.anyio
+    async def test_order_columns_returned_in_offset_paginate(
+        self, db_session: AsyncSession
+    ):
+        """offset_paginate response includes order_columns."""
+        UserSortCrud = CrudFactory(User, order_fields=[User.username, User.email])
+        await UserCrud.create(
+            db_session, UserCreate(username="alice", email="a@test.com")
+        )
+
+        result = await UserSortCrud.offset_paginate(db_session, schema=UserRead)
+
+        assert result.order_columns is not None
+        assert "username" in result.order_columns
+        assert "email" in result.order_columns
+
+    @pytest.mark.anyio
+    async def test_order_columns_returned_in_cursor_paginate(
+        self, db_session: AsyncSession
+    ):
+        """cursor_paginate response includes order_columns."""
+        UserSortCursorCrud = CrudFactory(
+            User,
+            cursor_column=User.id,
+            order_fields=[User.username, User.email],
+        )
+        await UserCrud.create(
+            db_session, UserCreate(username="alice", email="a@test.com")
+        )
+
+        result = await UserSortCursorCrud.cursor_paginate(db_session, schema=UserRead)
+
+        assert result.order_columns is not None
+        assert "username" in result.order_columns
+        assert "email" in result.order_columns
+
+    @pytest.mark.anyio
+    async def test_order_columns_none_when_no_order_fields(
+        self, db_session: AsyncSession
+    ):
+        """order_columns is None when no order_fields are configured."""
+        result = await UserCrud.offset_paginate(db_session, schema=UserRead)
+
+        assert result.order_columns is None
+
+    @pytest.mark.anyio
+    async def test_order_columns_override_in_offset_paginate(
+        self, db_session: AsyncSession
+    ):
+        """order_fields override in offset_paginate is reflected in order_columns."""
+        await UserCrud.create(
+            db_session, UserCreate(username="alice", email="a@test.com")
+        )
+
+        result = await UserCrud.offset_paginate(
+            db_session, order_fields=[User.email], schema=UserRead
+        )
+
+        assert result.order_columns == ["email"]
+
+    @pytest.mark.anyio
+    async def test_order_columns_override_in_cursor_paginate(
+        self, db_session: AsyncSession
+    ):
+        """order_fields override in cursor_paginate is reflected in order_columns."""
+        UserCursorCrud = CrudFactory(User, cursor_column=User.id)
+        await UserCrud.create(
+            db_session, UserCreate(username="alice", email="a@test.com")
+        )
+
+        result = await UserCursorCrud.cursor_paginate(
+            db_session, order_fields=[User.username], schema=UserRead
+        )
+
+        assert result.order_columns == ["username"]
+
+    @pytest.mark.anyio
+    async def test_order_columns_are_sorted_alphabetically(
+        self, db_session: AsyncSession
+    ):
+        """order_columns keys are returned in alphabetical order."""
+        UserSortCrud = CrudFactory(User, order_fields=[User.email, User.username])
+        await UserCrud.create(
+            db_session, UserCreate(username="alice", email="a@test.com")
+        )
+
+        result = await UserSortCrud.offset_paginate(db_session, schema=UserRead)
+
+        assert result.order_columns is not None
+        assert result.order_columns == sorted(result.order_columns)
+
+    @pytest.mark.anyio
+    async def test_relation_order_field_in_order_columns(
+        self, db_session: AsyncSession
+    ):
+        """A relation tuple order field produces 'rel__column' key in order_columns."""
+        UserSortCrud = CrudFactory(User, order_fields=[(User.role, Role.name)])
+        result = await UserSortCrud.offset_paginate(db_session, schema=UserRead)
+
+        assert result.order_columns == ["role__name"]
+
+
 class TestOrderParamsViaConsolidated:
     """Tests for order params via consolidated offset_paginate_params()."""
 
@@ -1670,6 +2028,92 @@ class TestOrderParamsViaConsolidated:
         assert result.data[0].username == "alice"
         assert result.data[1].username == "charlie"
 
+    def test_relation_order_field_key_in_enum(self):
+        """A relation tuple field produces a 'rel__column' key in the order_by enum."""
+        UserOrderCrud = CrudFactory(User, order_fields=[(User.role, Role.name)])
+        dep = UserOrderCrud.offset_paginate_params(search=False, filter=False)
+
+        sig = inspect.signature(dep)
+        description = sig.parameters["order_by"].default.description
+        assert "role__name" in description
+
+    @pytest.mark.anyio
+    async def test_relation_order_field_produces_order_joins(self):
+        """Selecting a relation order field emits order_by and order_joins."""
+        UserOrderCrud = CrudFactory(User, order_fields=[(User.role, Role.name)])
+        dep = UserOrderCrud.offset_paginate_params(search=False, filter=False)
+        result = await dep(
+            page=1, items_per_page=20, order_by="role__name", order="asc"
+        )
+
+        assert "order_by" in result
+        assert "order_joins" in result
+        assert result["order_joins"] == [User.role]
+
+    @pytest.mark.anyio
+    async def test_relation_order_integrates_with_offset_paginate(
+        self, db_session: AsyncSession
+    ):
+        """Relation order field joins the related table and sorts correctly."""
+        UserOrderCrud = CrudFactory(User, order_fields=[(User.role, Role.name)])
+        role_b = await RoleCrud.create(db_session, RoleCreate(name="beta"))
+        role_a = await RoleCrud.create(db_session, RoleCreate(name="alpha"))
+        await UserCrud.create(
+            db_session,
+            UserCreate(username="u1", email="u1@test.com", role_id=role_b.id),
+        )
+        await UserCrud.create(
+            db_session,
+            UserCreate(username="u2", email="u2@test.com", role_id=role_a.id),
+        )
+        await UserCrud.create(
+            db_session, UserCreate(username="u3", email="u3@test.com")
+        )
+
+        dep = UserOrderCrud.offset_paginate_params(search=False, filter=False)
+        params = await dep(
+            page=1, items_per_page=20, order_by="role__name", order="asc"
+        )
+        result = await UserOrderCrud.offset_paginate(
+            db_session, **params, schema=UserRead
+        )
+
+        usernames = [u.username for u in result.data]
+        # u2 (alpha) before u1 (beta); u3 (no role, NULL) comes last or first depending on DB
+        assert usernames.index("u2") < usernames.index("u1")
+
+    @pytest.mark.anyio
+    async def test_relation_order_integrates_with_cursor_paginate(
+        self, db_session: AsyncSession
+    ):
+        """Relation order field works with cursor_paginate (order_joins applied)."""
+        UserOrderCrud = CrudFactory(
+            User,
+            order_fields=[(User.role, Role.name)],
+            cursor_column=User.id,
+        )
+        role_b = await RoleCrud.create(db_session, RoleCreate(name="zeta"))
+        role_a = await RoleCrud.create(db_session, RoleCreate(name="alpha"))
+        await UserCrud.create(
+            db_session,
+            UserCreate(username="cx1", email="cx1@test.com", role_id=role_b.id),
+        )
+        await UserCrud.create(
+            db_session,
+            UserCreate(username="cx2", email="cx2@test.com", role_id=role_a.id),
+        )
+
+        dep = UserOrderCrud.cursor_paginate_params(search=False, filter=False)
+        params = await dep(
+            cursor=None, items_per_page=20, order_by="role__name", order="asc"
+        )
+        result = await UserOrderCrud.cursor_paginate(
+            db_session, **params, schema=UserRead
+        )
+
+        assert result.data is not None
+        assert len(result.data) == 2
+
 
 class TestOffsetPaginateParamsSchema:
     """Tests for AsyncCrud.offset_paginate_params()."""

uv.lock

@@ -251,7 +251,7 @@ wheels = [
 
 [[package]]
 name = "fastapi-toolsets"
-version = "3.0.1"
+version = "3.0.3"
 source = { editable = "." }
 dependencies = [
     { name = "asyncpg" },