ormar/docs/api/relations/queryset-proxy.md

relations.querysetproxy

QuerysetProxy Objects

class QuerysetProxy(Generic[T])

Exposes QuerySet methods on relations, but also handles creating and removing of through Models for m2m relations.

queryset

 | @property
 | queryset() -> "QuerySet[T]"

Returns queryset if it's set, AttributeError otherwise.

Returns:

QuerySet: QuerySet

queryset

 | @queryset.setter
 | queryset(value: "QuerySet") -> None

Set's the queryset. Initialized in RelationProxy.

Arguments:

• value (QuerySet): QuerySet

_assign_child_to_parent

 | _assign_child_to_parent(child: Optional["T"]) -> None

Registers child in parents RelationManager.

Arguments:

• child (Model): child to register on parent side.

_register_related

 | _register_related(child: Union["T", Sequence[Optional["T"]]]) -> None

Registers child/ children in parents RelationManager.

Arguments:

• child (Union[Model,List[Model]]): child or list of children models to register.

_clean_items_on_load

 | _clean_items_on_load() -> None

Cleans the current list of the related models.

create_through_instance

 | async create_through_instance(child: "T", **kwargs: Any) -> None

Crete a through model instance in the database for m2m relations.

Arguments:

• kwargs (Any): dict of additional keyword arguments for through instance
• child (Model): child model instance

update_through_instance

 | async update_through_instance(child: "T", **kwargs: Any) -> None

Updates a through model instance in the database for m2m relations.

Arguments:

• kwargs (Any): dict of additional keyword arguments for through instance
• child (Model): child model instance

upsert_through_instance

 | async upsert_through_instance(child: "T", **kwargs: Any) -> None

Updates a through model instance in the database for m2m relations if it already exists, else creates one.

Arguments:

• kwargs (Any): dict of additional keyword arguments for through instance
• child (Model): child model instance

delete_through_instance

 | async delete_through_instance(child: "T") -> None

Removes through model instance from the database for m2m relations.

Arguments:

• child (Model): child model instance

exists

 | async exists() -> bool

Returns a bool value to confirm if there are rows matching the given criteria (applied with filter and exclude if set).

Actual call delegated to QuerySet.

Returns:

bool: result of the check

count

 | async count() -> int

Returns number of rows matching the given criteria (applied with filter and exclude if set before).

Actual call delegated to QuerySet.

Returns:

int: number of rows

max

 | async max(columns: Union[str, List[str]]) -> Any

Returns max value of columns for rows matching the given criteria (applied with filter and exclude if set before).

Returns:

Any: max value of column(s)

min

 | async min(columns: Union[str, List[str]]) -> Any

Returns min value of columns for rows matching the given criteria (applied with filter and exclude if set before).

Returns:

Any: min value of column(s)

sum

 | async sum(columns: Union[str, List[str]]) -> Any

Returns sum value of columns for rows matching the given criteria (applied with filter and exclude if set before).

Returns:

int: sum value of columns

avg

 | async avg(columns: Union[str, List[str]]) -> Any

Returns avg value of columns for rows matching the given criteria (applied with filter and exclude if set before).

Returns:

Union[int, float, List]: avg value of columns

clear

 | async clear(keep_reversed: bool = True) -> int

Removes all related models from given relation.

Removes all through models for m2m relation.

For reverse FK relations keep_reversed flag marks if the reversed models should be kept or deleted from the database too (False means that models will be deleted, and not only removed from relation).

Arguments:

or not, keep_reversed=False deletes them from database.

• keep_reversed (bool): flag if reverse models in reverse FK should be deleted

Returns:

int: number of deleted models

first

 | async first(*args: Any, **kwargs: Any) -> "T"

Gets the first row from the db ordered by primary key column ascending.

Actual call delegated to QuerySet.

Passing args and/or kwargs is a shortcut and equals to calling filter(*args, **kwargs).first().

List of related models is cleared before the call.

Arguments:

• kwargs:

Returns:

_asyncio.Future:

get_or_none

 | async get_or_none(*args: Any, **kwargs: Any) -> Optional["T"]

Get's the first row from the db meeting the criteria set by kwargs.

If no criteria set it will return the last row in db sorted by pk.

Passing args and/or kwargs is a shortcut and equals to calling filter(*args, **kwargs).get_or_none().

If not match is found None will be returned.

Arguments:

• kwargs (Any): fields names and proper value types

Returns:

Model: returned model

get

 | async get(*args: Any, **kwargs: Any) -> "T"

Get's the first row from the db meeting the criteria set by kwargs.

If no criteria set it will return the last row in db sorted by pk.

Passing args and/or kwargs is a shortcut and equals to calling filter(*args, **kwargs).get().

Actual call delegated to QuerySet.

List of related models is cleared before the call.

Raises:

• NoMatch: if no rows are returned
• MultipleMatches: if more than 1 row is returned.

Arguments:

• kwargs (Any): fields names and proper value types

Returns:

Model: returned model

all

 | async all(*args: Any, **kwargs: Any) -> List["T"]

Returns all rows from a database for given model for set filter options.

Passing args and/or kwargs is a shortcut and equals to calling filter(*args, **kwargs).all().

If there are no rows meeting the criteria an empty list is returned.

Actual call delegated to QuerySet.

List of related models is cleared before the call.

Arguments:

• kwargs (Any): fields names and proper value types

Returns:

List[Model]: list of returned models

create

 | async create(**kwargs: Any) -> "T"

Creates the model instance, saves it in a database and returns the updates model (with pk populated if not passed and autoincrement is set).

The allowed kwargs are Model fields names and proper value types.

For m2m relation the through model is created automatically.

Actual call delegated to QuerySet.

Arguments:

• kwargs (Any): fields names and proper value types

Returns:

Model: created model

update

 | async update(each: bool = False, **kwargs: Any) -> int

Updates the model table after applying the filters from kwargs.

You have to either pass a filter to narrow down a query or explicitly pass each=True flag to affect whole table.

Arguments:

• each (bool): flag if whole table should be affected if no filter is passed
• kwargs (Any): fields names and proper value types

Returns:

int: number of updated rows

get_or_create

 | async get_or_create(*args: Any, **kwargs: Any) -> "T"

Combination of create and get methods.

Tries to get a row meeting the criteria fro kwargs and if NoMatch exception is raised it creates a new one with given kwargs.

Arguments:

• kwargs (Any): fields names and proper value types

Returns:

Model: returned or created Model

update_or_create

 | async update_or_create(**kwargs: Any) -> "T"

Updates the model, or in case there is no match in database creates a new one.

Actual call delegated to QuerySet.

Arguments:

• kwargs (Any): fields names and proper value types

Returns:

Model: updated or created model

filter

 | filter(*args: Any, **kwargs: Any) -> "QuerysetProxy[T]"

Allows you to filter by any Model attribute/field as well as to fetch instances, with a filter across an FK relationship.

You can use special filter suffix to change the filter operands:

• exact - like album__name__exact='Malibu' (exact match)
• iexact - like album__name__iexact='malibu' (exact match case insensitive)
• contains - like album__name__contains='Mal' (sql like)
• icontains - like album__name__icontains='mal' (sql like case insensitive)
• in - like album__name__in=['Malibu', 'Barclay'] (sql in)
• isnull - like album__name__isnull=True (sql is null) (isnotnull album__name__isnull=False (sql is not null))
• gt - like position__gt=3 (sql >)
• gte - like position__gte=3 (sql >=)
• lt - like position__lt=3 (sql <)
• lte - like position__lte=3 (sql <=)
• startswith - like album__name__startswith='Mal' (exact start match)
• istartswith - like album__name__istartswith='mal' (case insensitive)
• endswith - like album__name__endswith='ibu' (exact end match)
• iendswith - like album__name__iendswith='IBU' (case insensitive)

Actual call delegated to QuerySet.

Arguments:

• kwargs (Any): fields names and proper value types

Returns:

QuerysetProxy: filtered QuerysetProxy

exclude

 | exclude(*args: Any, **kwargs: Any) -> "QuerysetProxy[T]"

Works exactly the same as filter and all modifiers (suffixes) are the same, but returns a not condition.

So if you use filter(name='John') which is where name = 'John' in SQL, the exclude(name='John') equals to where name <> 'John'

Note that all conditions are joined so if you pass multiple values it becomes a union of conditions.

exclude(name='John', age>=35) will become where not (name='John' and age>=35)

Actual call delegated to QuerySet.

Arguments:

• kwargs (Any): fields names and proper value types

Returns:

QuerysetProxy: filtered QuerysetProxy

select_all

 | select_all(follow: bool = False) -> "QuerysetProxy[T]"

By default adds only directly related models.

If follow=True is set it adds also related models of related models.

To not get stuck in an infinite loop as related models also keep a relation to parent model visited models set is kept.

That way already visited models that are nested are loaded, but the load do not follow them inside. So Model A -> Model B -> Model C -> Model A -> Model X will load second Model A but will never follow into Model X. Nested relations of those kind need to be loaded manually.

Arguments:

by default only directly related models are saved with follow=True also related models of related models are saved

• follow (bool): flag to trigger deep save -

Returns:

Model: reloaded Model

select_related

 | select_related(related: Union[List, str]) -> "QuerysetProxy[T]"

Allows to prefetch related models during the same query.

With select_related always only one query is run against the database, meaning that one (sometimes complicated) join is generated and later nested models are processed in python.

To fetch related model use ForeignKey names.

To chain related Models relation use double underscores between names.

Actual call delegated to QuerySet.

Arguments:

• related (Union[List, str]): list of relation field names, can be linked by '__' to nest

Returns:

QuerysetProxy: QuerysetProxy

prefetch_related

 | prefetch_related(related: Union[List, str]) -> "QuerysetProxy[T]"

Allows to prefetch related models during query - but opposite to select_related each subsequent model is fetched in a separate database query.

With prefetch_related always one query per Model is run against the database, meaning that you will have multiple queries executed one after another.

To fetch related model use ForeignKey names.

To chain related Models relation use double underscores between names.

Actual call delegated to QuerySet.

Arguments:

• related (Union[List, str]): list of relation field names, can be linked by '__' to nest

Returns:

QuerysetProxy: QuerysetProxy

paginate

 | paginate(page: int, page_size: int = 20) -> "QuerysetProxy[T]"

You can paginate the result which is a combination of offset and limit clauses. Limit is set to page size and offset is set to (page-1) * page_size.

Actual call delegated to QuerySet.

Arguments:

• page_size (int): numbers of items per page
• page (int): page number

Returns:

QuerySet: QuerySet

limit

 | limit(limit_count: int) -> "QuerysetProxy[T]"

You can limit the results to desired number of parent models.

Actual call delegated to QuerySet.

Arguments:

• limit_count (int): number of models to limit

Returns:

QuerysetProxy: QuerysetProxy

offset

 | offset(offset: int) -> "QuerysetProxy[T]"

You can also offset the results by desired number of main models.

Actual call delegated to QuerySet.

Arguments:

• offset (int): numbers of models to offset

Returns:

QuerysetProxy: QuerysetProxy

fields

 | fields(columns: Union[List, str, Set, Dict]) -> "QuerysetProxy[T]"

With fields() you can select subset of model columns to limit the data load.

Note that fields() and exclude_fields() works both for main models (on normal queries like get, all etc.) as well as select_related and prefetch_related models (with nested notation).

You can select specified fields by passing a str, List[str], Set[str] or dict with nested definition.

To include related models use notation {related_name}__{column}[__{optional_next} etc.].

fields() can be called several times, building up the columns to select.

If you include related models into select_related() call but you won't specify columns for those models in fields - implies a list of all fields for those nested models.

Mandatory fields cannot be excluded as it will raise ValidationError, to exclude a field it has to be nullable.

Pk column cannot be excluded - it's always auto added even if not explicitly included.

You can also pass fields to include as dictionary or set.

To mark a field as included in a dictionary use it's name as key and ellipsis as value.

To traverse nested models use nested dictionaries.

To include fields at last level instead of nested dictionary a set can be used.

To include whole nested model specify model related field name and ellipsis.

Actual call delegated to QuerySet.

Arguments:

• columns (Union[List, str, Set, Dict]): columns to include

Returns:

QuerysetProxy: QuerysetProxy

exclude_fields

 | exclude_fields(columns: Union[List, str, Set, Dict]) -> "QuerysetProxy[T]"

With exclude_fields() you can select subset of model columns that will be excluded to limit the data load.

It's the opposite of fields() method so check documentation above to see what options are available.

Especially check above how you can pass also nested dictionaries and sets as a mask to exclude fields from whole hierarchy.

Note that fields() and exclude_fields() works both for main models (on normal queries like get, all etc.) as well as select_related and prefetch_related models (with nested notation).

Mandatory fields cannot be excluded as it will raise ValidationError, to exclude a field it has to be nullable.

Pk column cannot be excluded - it's always auto added even if explicitly excluded.

Actual call delegated to QuerySet.

Arguments:

• columns (Union[List, str, Set, Dict]): columns to exclude

Returns:

QuerysetProxy: QuerysetProxy

order_by

 | order_by(columns: Union[List, str, "OrderAction"]) -> "QuerysetProxy[T]"

With order_by() you can order the results from database based on your choice of fields.

You can provide a string with field name or list of strings with fields names.

Ordering in sql will be applied in order of names you provide in order_by.

By default if you do not provide ordering ormar explicitly orders by all primary keys

If you are sorting by nested models that causes that the result rows are unsorted by the main model ormar will combine those children rows into one main model.

The main model will never duplicate in the result

To order by main model field just provide a field name

To sort on nested models separate field names with dunder '__'.

You can sort this way across all relation types -> ForeignKey, reverse virtual FK and ManyToMany fields.

To sort in descending order provide a hyphen in front of the field name

Actual call delegated to QuerySet.

Arguments:

• columns (Union[List, str]): columns by which models should be sorted

Returns:

QuerysetProxy: QuerysetProxy