Skip to content

queryset.queryset

QuerySet Objects

1
class QuerySet(Generic[T])

Main class to perform database queries, exposed on each model as objects attribute.

model_meta

1
2
 | @property
 | model_meta() -> "ModelMeta"

Shortcut to model class Meta set on QuerySet model.

Returns:

Meta class of the model :rtype: model Meta class

model

1
2
 | @property
 | model() -> Type["T"]

Shortcut to model class set on QuerySet.

Returns:

model class :rtype: Type[Model]

rebuild_self

1
 | rebuild_self(filter_clauses: List = None, exclude_clauses: List = None, select_related: List = None, limit_count: int = None, offset: int = None, excludable: "ExcludableItems" = None, order_bys: List = None, prefetch_related: List = None, limit_raw_sql: bool = None, proxy_source_model: Optional[Type["Model"]] = None) -> "QuerySet"

Method that returns new instance of queryset based on passed params, all not passed params are taken from current values.

1
 | async _prefetch_related_models(models: List["T"], rows: List) -> List["T"]

Performs prefetch query for selected models names.

Arguments:

  • models: list of already parsed main Models from main query :type models: List[Model]
  • rows: database rows from main query :type rows: List[sqlalchemy.engine.result.RowProxy]

Returns:

list of models with prefetch models populated :rtype: List[Model]

_process_query_result_rows

1
 | _process_query_result_rows(rows: List) -> List["T"]

Process database rows and initialize ormar Model from each of the rows.

Arguments:

  • rows: list of database rows from query result :type rows: List[sqlalchemy.engine.result.RowProxy]

Returns:

list of models :rtype: List[Model]

_resolve_filter_groups

1
 | _resolve_filter_groups(groups: Any) -> Tuple[List[FilterGroup], List[str]]

Resolves filter groups to populate FilterAction params in group tree.

Arguments:

  • groups: tuple of FilterGroups :type groups: Any

Returns:

list of resolver groups :rtype: Tuple[List[FilterGroup], List[str]]

check_single_result_rows_count

1
2
 | @staticmethod
 | check_single_result_rows_count(rows: Sequence[Optional["T"]]) -> None

Verifies if the result has one and only one row.

Arguments:

  • rows: one element list of Models :type rows: List[Model]

database

1
2
 | @property
 | database() -> databases.Database

Shortcut to models database from Meta class.

Returns:

database :rtype: databases.Database

table

1
2
 | @property
 | table() -> sqlalchemy.Table

Shortcut to models table from Meta class.

Returns:

database table :rtype: sqlalchemy.Table

build_select_expression

1
 | build_select_expression(limit: int = None, offset: int = None, order_bys: List = None) -> sqlalchemy.sql.select

Constructs the actual database query used in the QuerySet. If any of the params is not passed the QuerySet own value is used.

Arguments:

  • limit: number to limit the query :type limit: int
  • offset: number to offset by :type offset: int
  • order_bys: list of order-by fields names :type order_bys: List

Returns:

built sqlalchemy select expression :rtype: sqlalchemy.sql.selectable.Select

filter

1
 | filter(*args: Any, *, _exclude: bool = False, **kwargs: Any) -> "QuerySet[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)

Note that you can also use python style filters - check the docs!

Arguments:

  • _exclude: flag if it should be exclude or filter :type _exclude: bool
  • kwargs: fields names and proper value types :type kwargs: Any

Returns:

filtered QuerySet :rtype: QuerySet

exclude

1
 | exclude(*args: Any, **kwargs: Any) -> "QuerySet[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)

Arguments:

  • kwargs: fields names and proper value types :type kwargs: Any

Returns:

filtered QuerySet :rtype: QuerySet

1
 | select_related(related: Union[List, str, FieldAccessor]) -> "QuerySet[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.

Arguments:

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

Returns:

QuerySet :rtype: QuerySet

select_all

1
 | select_all(follow: bool = False) -> "QuerySet[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:

  • follow: flag to trigger deep save - by default only directly related models are saved with follow=True also related models of related models are saved :type follow: bool

Returns:

reloaded Model :rtype: Model

1
 | prefetch_related(related: Union[List, str, FieldAccessor]) -> "QuerySet[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.

Arguments:

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

Returns:

QuerySet :rtype: QuerySet

fields

1
 | fields(columns: Union[List, str, Set, Dict], _is_exclude: bool = False) -> "QuerySet[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.

Arguments:

  • _is_exclude: flag if it's exclude or include operation :type _is_exclude: bool
  • columns: columns to include :type columns: Union[List, str, Set, Dict]

Returns:

QuerySet :rtype: QuerySet

exclude_fields

1
 | exclude_fields(columns: Union[List, str, Set, Dict]) -> "QuerySet[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.

Arguments:

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

Returns:

QuerySet :rtype: QuerySet

order_by

1
 | order_by(columns: Union[List, str, OrderAction]) -> "QuerySet[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

Arguments:

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

Returns:

QuerySet :rtype: QuerySet

values

1
 | async values(fields: Union[List, str, Set, Dict] = None, exclude_through: bool = False, _as_dict: bool = True, _flatten: bool = False) -> List

Return a list of dictionaries with column values in order of the fields passed or all fields from queried models.

To filter for given row use filter/exclude methods before values, to limit number of rows use limit/offset or paginate before values.

Note that it always return a list even for one row from database.

Arguments:

  • exclude_through: flag if through models should be excluded :type exclude_through: bool
  • _flatten: internal parameter to flatten one element tuples :type _flatten: bool
  • _as_dict: internal parameter if return dict or tuples :type _as_dict: bool
  • fields: field name or list of field names to extract from db :type fields: Union[List, str, Set, Dict]

values_list

1
 | async values_list(fields: Union[List, str, Set, Dict] = None, flatten: bool = False, exclude_through: bool = False) -> List

Return a list of tuples with column values in order of the fields passed or all fields from queried models.

When one field is passed you can flatten the list of tuples into list of values of that single field.

To filter for given row use filter/exclude methods before values, to limit number of rows use limit/offset or paginate before values.

Note that it always return a list even for one row from database.

Arguments:

  • exclude_through: flag if through models should be excluded :type exclude_through: bool
  • fields: field name or list of field names to extract from db :type fields: Union[str, List[str]]
  • flatten: when one field is passed you can flatten the list of tuples :type flatten: bool

exists

1
 | async exists() -> bool

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

Returns:

result of the check :rtype: bool

count

1
 | async count() -> int

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

Returns:

number of rows :rtype: int

max

1
 | 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:

max value of column(s) :rtype: Any

min

1
 | 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:

min value of column(s) :rtype: Any

sum

1
 | 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:

sum value of columns :rtype: int

avg

1
 | 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:

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

update

1
 | 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: flag if whole table should be affected if no filter is passed :type each: bool
  • kwargs: fields names and proper value types :type kwargs: Any

Returns:

number of updated rows :rtype: int

delete

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

Deletes from 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: flag if whole table should be affected if no filter is passed :type each: bool
  • kwargs: fields names and proper value types :type kwargs: Any

Returns:

number of deleted rows :rtype:int

paginate

1
 | paginate(page: int, page_size: int = 20) -> "QuerySet[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.

Arguments:

  • page_size: numbers of items per page :type page_size: int
  • page: page number :type page: int

Returns:

QuerySet :rtype: QuerySet

limit

1
 | limit(limit_count: int, limit_raw_sql: bool = None) -> "QuerySet[T]"

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

To limit the actual number of database query rows instead of number of main models use the limit_raw_sql parameter flag, and set it to True.

Arguments:

  • limit_raw_sql: flag if raw sql should be limited :type limit_raw_sql: bool
  • limit_count: number of models to limit :type limit_count: int

Returns:

QuerySet :rtype: QuerySet

offset

1
 | offset(offset: int, limit_raw_sql: bool = None) -> "QuerySet[T]"

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

To offset the actual number of database query rows instead of number of main models use the limit_raw_sql parameter flag, and set it to True.

Arguments:

  • limit_raw_sql: flag if raw sql should be offset :type limit_raw_sql: bool
  • offset: numbers of models to offset :type offset: int

Returns:

QuerySet :rtype: QuerySet

first

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

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

Raises:

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

Arguments:

  • kwargs: fields names and proper value types :type kwargs: Any

Returns:

returned model :rtype: Model

get_or_none

1
 | 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 a criteria is actually calling filter(args, *kwargs) method described below.

If not match is found None will be returned.

Arguments:

  • kwargs: fields names and proper value types :type kwargs: Any

Returns:

returned model :rtype: Model

get

1
 | 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 a criteria is actually calling filter(args, *kwargs) method described below.

Raises:

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

Arguments:

  • kwargs: fields names and proper value types :type kwargs: Any

Returns:

returned model :rtype: Model

get_or_create

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

Combination of create and get methods.

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

Passing a criteria is actually calling filter(args, *kwargs) method described below.

Arguments:

  • kwargs: fields names and proper value types :type kwargs: Any

Returns:

returned or created Model :rtype: Model

update_or_create

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

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

Arguments:

  • kwargs: fields names and proper value types :type kwargs: Any

Returns:

updated or created model :rtype: Model

all

1
 | 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.

Arguments:

  • kwargs: fields names and proper value types :type kwargs: Any

Returns:

list of returned models :rtype: List[Model]

create

1
 | 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.

Arguments:

  • kwargs: fields names and proper value types :type kwargs: Any

Returns:

created model :rtype: Model

bulk_create

1
 | async bulk_create(objects: List["T"]) -> None

Performs a bulk update in one database session to speed up the process.

Allows you to create multiple objects at once.

A valid list of Model objects needs to be passed.

Bulk operations do not send signals.

Arguments:

  • objects: list of ormar models already initialized and ready to save. :type objects: List[Model]

bulk_update

1
 | async bulk_update(objects: List["T"], columns: List[str] = None) -> None

Performs bulk update in one database session to speed up the process.

Allows to update multiple instance at once.

All Models passed need to have primary key column populated.

You can also select which fields to update by passing columns list as a list of string names.

Bulk operations do not send signals.

Arguments:

  • objects: list of ormar models :type objects: List[Model]
  • columns: list of columns to update :type columns: List[str]