14 KiB
relations.querysetproxy
QuerysetProxy Objects
class QuerysetProxy(ormar.QuerySetProtocol)
Exposes QuerySet methods on relations, but also handles creating and removing of through Models for m2m relations.
queryset
| @property
| queryset() -> "QuerySet"
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") -> None
Crete a through model instance in the database for m2m relations.
Arguments:
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
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:
keep_reversed (bool): flag if reverse models in reverse FK should be deleted or not, keep_reversed=False deletes them from database.
Returns:
(int): number of deleted models
first
| async first(**kwargs: Any) -> "Model"
Gets the first row from the db ordered by primary key column ascending.
Actual call delegated to QuerySet.
List of related models is cleared before the call.
Arguments:
kwargs ():
Returns:
(_asyncio.Future):
get
| async get(**kwargs: Any) -> "Model"
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 a criteria is actually calling filter(**kwargs) method described below.
Actual call delegated to QuerySet.
List of related models is cleared before the call.
Raises:
NoMatch: if no rows are returnedMultipleMatches: if more than 1 row is returned.
Arguments:
kwargs (Any): fields names and proper value types
Returns:
(Model): returned model
all
| async all(**kwargs: Any) -> Sequence[Optional["Model"]]
Returns all rows from a database for given model for set filter options.
Passing kwargs is a shortcut and equals to calling filter(**kwrags).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) -> "Model"
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
get_or_create
| async get_or_create(**kwargs: Any) -> "Model"
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) -> "Model"
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(**kwargs: Any) -> "QuerysetProxy"
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) - 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(**kwargs: Any) -> "QuerysetProxy"
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_related
| select_related(related: Union[List, str]) -> "QuerysetProxy"
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"
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
limit
| limit(limit_count: int) -> "QuerysetProxy"
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"
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"
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"
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]) -> "QuerysetProxy"
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