ormar/docs/api/query-set/query-set.md

queryset.queryset

QuerySet Objects

class QuerySet()

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

__init__

 | __init__(model_cls: Type["Model"] = None, filter_clauses: List = None, exclude_clauses: List = None, select_related: List = None, limit_count: int = None, offset: int = None, columns: Dict = None, exclude_columns: Dict = None, order_bys: List = None, prefetch_related: List = None, limit_raw_sql: bool = False) -> None

__get__

 | __get__(instance: Optional[Union["QuerySet", "QuerysetProxy"]], owner: Union[Type["Model"], Type["QuerysetProxy"]]) -> "QuerySet"

model_meta

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

Shortcut to model class Meta set on QuerySet model.

Returns:

(model Meta class): Meta class of the model

model

 | @property
 | model() -> Type["Model"]

Shortcut to model class set on QuerySet.

Returns:

(Type[Model]): model class

_prefetch_related_models

 | async _prefetch_related_models(models: Sequence[Optional["Model"]], rows: List) -> Sequence[Optional["Model"]]

Performs prefetch query for selected models names.

Arguments:

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

Returns:

(List[Model]): list of models with prefetch models populated

_process_query_result_rows

 | _process_query_result_rows(rows: List) -> Sequence[Optional["Model"]]

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

Arguments:

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

Returns:

(List[Model]): list of models

check_single_result_rows_count

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

Verifies if the result has one and only one row.

Arguments:

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

database

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

Shortcut to models database from Meta class.

Returns:

(databases.Database): database

table

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

Shortcut to models table from Meta class.

Returns:

(sqlalchemy.Table): database table

build_select_expression

 | 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 (int): number to limit the query
• offset (int): number to offset by
• order_bys (List): list of order-by fields names

Returns:

(sqlalchemy.sql.selectable.Select): built sqlalchemy select expression

filter

 | filter(_exclude: bool = False, **kwargs: Any) -> "QuerySet"

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)

Arguments:

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

Returns:

(QuerySet): filtered QuerySet

exclude

 | exclude(**kwargs: Any) -> "QuerySet"

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 (Any): fields names and proper value types

Returns:

(QuerySet): filtered QuerySet

select_related

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

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 (Union[List, str]): list of relation field names, can be linked by '__' to nest

Returns:

(QuerySet): QuerySet

prefetch_related

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

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 (Union[List, str]): list of relation field names, can be linked by '__' to nest

Returns:

(QuerySet): QuerySet

fields

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

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:

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

Returns:

(QuerySet): QuerySet

exclude_fields

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

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 (Union[List, str, Set, Dict]): columns to exclude

Returns:

(QuerySet): QuerySet

order_by

 | order_by(columns: Union[List, str]) -> "QuerySet"

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 (Union[List, str]): columns by which models should be sorted

Returns:

(QuerySet): QuerySet

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

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

Returns:

(int): number of rows

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

delete

 | async delete(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 (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 deleted rows

limit

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

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 (bool): flag if raw sql should be limited
• limit_count (int): number of models to limit

Returns:

(QuerySet): QuerySet

offset

 | offset(offset: int, limit_raw_sql: bool = None) -> "QuerySet"

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 (bool): flag if raw sql should be offset
• offset (int): numbers of models to offset

Returns:

(QuerySet): QuerySet

first

 | async first(**kwargs: Any) -> "Model"

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 (Any): fields names and proper value types

Returns:

(Model): returned model

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.

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

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.

Arguments:

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

Returns:

(Model): updated or created 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.

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.

Arguments:

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

Returns:

(Model): created model

bulk_create

 | async bulk_create(objects: List["Model"]) -> 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[Model]): list of ormar models already initialized and ready to save.

bulk_update

 | async bulk_update(objects: List["Model"], 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[Model]): list of ormar models
• columns (List[str]): list of columns to update