Skip to content

Loaders

Loader options describe how relationship paths should be loaded.

Use these helpers in find_one(..., load=[...]) and find_many(..., load=[...]):

from ormdantic import joinedload, selectinload

await db[Flavor].find_many(load=[joinedload("supplier")])
await db[Supplier].find_many(
    load=[selectinload("flavors").sorted_by("name").batched(100)]
)

Use joinedload for small related row sets where one joined query is acceptable. Use selectinload for collections or larger graphs where batched secondary queries are easier to control.

ormdantic.loaders.LoaderStrategy module-attribute 

LoaderStrategy = Literal[
    "joined", "selectin", "lazy", "noload"
]

ormdantic.loaders.LoaderPath dataclass 

LoaderPath(parts)

A dotted relationship path built from model class attributes.

parts instance-attribute 

parts

path property 

path

Return the dotted path string.

ormdantic.loaders.LoaderOption dataclass 

LoaderOption(
    path,
    strategy,
    filter_by=None,
    order_by=(),
    batch_size=None,
)

Relationship loading strategy for a dotted model path.

path instance-attribute 

path

strategy instance-attribute 

strategy

filter_by class-attribute instance-attribute 

filter_by = None

order_by class-attribute instance-attribute 

order_by = ()

batch_size class-attribute instance-attribute 

batch_size = None

depth property 

depth

Return the relationship depth implied by the path.

filter 

filter(**criteria)

Return a copy with relationship-local filter criteria attached.

Source code in ormdantic/loaders.py 
def filter(self, **criteria: Any) -> "LoaderOption":
    """Return a copy with relationship-local filter criteria attached."""
    return LoaderOption(
        path=self.path,
        strategy=self.strategy,
        filter_by={**(self.filter_by or {}), **criteria},
        order_by=self.order_by,
        batch_size=self.batch_size,
    )

sorted_by 

sorted_by(*columns)

Return a copy with relationship-local ordering attached.

Source code in ormdantic/loaders.py 
def sorted_by(self, *columns: str) -> "LoaderOption":
    """Return a copy with relationship-local ordering attached."""
    return LoaderOption(
        path=self.path,
        strategy=self.strategy,
        filter_by=self.filter_by,
        order_by=tuple(columns),
        batch_size=self.batch_size,
    )

batched 

batched(size)

Return a copy with a select-in batch size for this relationship.

Source code in ormdantic/loaders.py 
def batched(self, size: int) -> "LoaderOption":
    """Return a copy with a select-in batch size for this relationship."""
    return LoaderOption(
        path=self.path,
        strategy=self.strategy,
        filter_by=self.filter_by,
        order_by=self.order_by,
        batch_size=size,
    )

ormdantic.loaders.load 

load(path, *, strategy='joined')

Load a relationship path with the requested strategy.

Source code in ormdantic/loaders.py 
def load(path: LoaderPathLike, *, strategy: LoaderStrategy = "joined") -> LoaderOption:
    """Load a relationship path with the requested strategy."""
    return LoaderOption(path=".".join(path_parts(path)), strategy=strategy)

ormdantic.loaders.joinedload 

joinedload(path)

Load a relationship path with the joined strategy.

Source code in ormdantic/loaders.py 
def joinedload(path: LoaderPathLike) -> LoaderOption:
    """Load a relationship path with the joined strategy."""
    return load(path, strategy="joined")

ormdantic.loaders.selectinload 

selectinload(path)

Load a relationship path with the select-in strategy.

Source code in ormdantic/loaders.py 
def selectinload(path: LoaderPathLike) -> LoaderOption:
    """Load a relationship path with the select-in strategy."""
    return load(path, strategy="selectin")

ormdantic.loaders.lazyload 

lazyload(path)

Mark a relationship path for explicit lazy loading.

Source code in ormdantic/loaders.py 
def lazyload(path: LoaderPathLike) -> LoaderOption:
    """Mark a relationship path for explicit lazy loading."""
    return load(path, strategy="lazy")

ormdantic.loaders.noload 

noload(path)

Prevent eager loading for a relationship path.

Source code in ormdantic/loaders.py 
def noload(path: LoaderPathLike) -> LoaderOption:
    """Prevent eager loading for a relationship path."""
    return load(path, strategy="noload")

ormdantic.loaders.joined 

joined(path)

Backward-compatible alias for :func:joinedload.

Source code in ormdantic/loaders.py 
def joined(path: LoaderPathLike) -> LoaderOption:
    """Backward-compatible alias for :func:`joinedload`."""
    return joinedload(path)

ormdantic.loaders.selectin 

selectin(path)

Backward-compatible alias for :func:selectinload.

Source code in ormdantic/loaders.py 
def selectin(path: LoaderPathLike) -> LoaderOption:
    """Backward-compatible alias for :func:`selectinload`."""
    return selectinload(path)

ormdantic.loaders.lazy 

lazy(path)

Backward-compatible alias for :func:lazyload.

Source code in ormdantic/loaders.py 
def lazy(path: LoaderPathLike) -> LoaderOption:
    """Backward-compatible alias for :func:`lazyload`."""
    return lazyload(path)

ormdantic.loaders.loader_depth 

loader_depth(load)

Return the maximum eager-loading depth from loader options.

Source code in ormdantic/loaders.py 
def loader_depth(load: list[LoaderOption] | None) -> int:
    """Return the maximum eager-loading depth from loader options."""
    if not load:
        return 0
    return max(
        (option.depth for option in load if option.strategy not in {"lazy", "noload"}),
        default=0,
    )