filter¶

filter(*args, **kwargs)¶

Возвращает новый QuerySet содержащий объекты отвечающие параметрам фильтрации.

Параметры фильтрации (**kwargs) должны отвечать формату описанному в соответствующем разделе. Несколько параметров объединяются оператором SQL AND.

Если вам нужно выполнить более сложные запросы (например, запросы с операторами OR), вы можете использовать объекты Q (*args).

exclude¶

exclude(*args, **kwargs)¶

Возвращает новый QuerySet содержащий объекты не отвечающие параметрам фильтрации.

Параметры фильтрации (**kwargs) должны отвечать формату описанному в соответствующем разделе. Несколько параметров объединяются оператором SQL AND и все это замыкается оператором NOT().

Этот пример исключает все записи с pub_date раньше 3.01.2005 И с headline равным «Hello»:

Entry.objects.exclude(pub_date__gt=datetime.date(2005, 1, 3), headline="Hello")

Это эквивалентно запросу SQL:

SELECT ...
WHERE NOT (pub_date > '2005-1-3' AND headline = 'Hello')

Этот пример исключает все записи с pub_date раньше 3.01.2005 ИЛИ с headline равным «Hello»:

Entry.objects.exclude(pub_date__gt=datetime.date(2005, 1, 3)).exclude(headline="Hello")

Это эквивалентно запросу SQL:

SELECT ...
WHERE NOT pub_date > '2005-1-3'
AND NOT headline = 'Hello'

Обратите внимание на второй пример, который больше ограничивает выборку.

Если вам нужно выполнить более сложные запросы (например, запросы с операторами OR), вы можете использовать объекты Q (*args).

annotate¶

annotate(*args, **kwargs)¶

Аннотирует каждый объект в QuerySet предоставленным списком выражений запроса или Q объектов. Каждый объект может быть аннотирован с помощью:

• простое значение через Value();

• ссылка на поле модели (или любых связанных моделей) через F();

• логическое значение через Q(); или

• результат совокупного выражения (средние значения, суммы и т. д.), вычисленного по объектам, связанным с объектами в QuerySet.

Каждый аргумент annotate() добавит аннотацию для каждого объекта, возвращаемого QuerySet.

Функции агрегации описаны в соответствующем разделе ниже.

Аннотация, определенная именованными аргументами, будет использовать имя аргумента, как название аннотации. Для позиционного аргумента будет использовано имя, созданное с названия функции агрегации и используемого поля модели. В позиционных аргументах можно указывать агрегирующее выражение, которое использует только одно поле. Все остальные должны передаваться через именованные аргументы.

Например, если вы манипулировали списком блогов, вам может потребоваться определить, сколько записей было сделано в каждом блоге:

>>> from django.db.models import Count
>>> q = Blog.objects.annotate(Count("entry"))
# The name of the first blog
>>> q[0].name
'Blogasaurus'
# The number of entries on the first blog
>>> q[0].entry__count
42

Модель «Блог» не определяет атрибут «entry__count» сам по себе, но используя аргумент ключевого слова для указания агрегатной функции, вы можете управлять именем аннотации:

>>> q = Blog.objects.annotate(number_of_entries=Count("entry"))
# The number of entries on the first blog, using the name provided
>>> q[0].number_of_entries
42

Для углубленного изучения агрегации смотрите раздел про агрегацию.

псевдоним()¶

alias(*args, **kwargs)¶

То же, что и annotate(), но вместо аннотирования объектов в QuerySet сохраняет выражение для последующего повторного использования с другими методами QuerySet. Это полезно, когда результат самого выражения не нужен, но используется для фильтрации, упорядочивания или как часть сложного выражения. Если не выбрать неиспользуемое значение, из базы данных будет удалена избыточная работа, что должно привести к повышению производительности.

Например, если вы хотите найти блоги с более чем 5 записями, но вас не интересует точное количество записей, вы можете сделать это:

>>> from django.db.models import Count
>>> blogs = Blog.objects.alias(entries=Count("entry")).filter(entries__gt=5)

alias() может использоваться в сочетании с annotate(), exclude(), filter(), order_by() и update(). Чтобы использовать выражение с псевдонимом с другими методами (например, aggregate()), вы должны преобразовать его в аннотацию:

Blog.objects.alias(entries=Count("entry")).annotate(
    entries=F("entries"),
).aggregate(Sum("entries"))

filter() и order_by() могут принимать выражения напрямую, но построение и использование выражений часто не происходят в одном и том же месте (например, метод QuerySet создает выражения для последующего использования в представлениях). alias() позволяет создавать сложные выражения постепенно, возможно, охватывая несколько методов и модулей, ссылаться на части выражения по их псевдонимам и использовать только annotate() для конечного результата.

order_by¶

order_by(*fields)¶

По-умолчанию, результат возвращаемый QuerySet, отсортирован по полям указанным в аргументе ordering класса Meta модели. Вы можете переопределить сортировку используя метод order_by.

Например:

Entry.objects.filter(pub_date__year=2005).order_by("-pub_date", "headline")

Результат выше будет отсортирован в обратном порядке по полю pub_date, далее по полю headline. Знак «минус» в "-pub_date" указывает на «нисходящую» сортировку. Сортировка по возрастанию подразумевается по-умолчанию. Чтобы отсортировать случайно используйте "?", например:

Entry.objects.order_by("?")

Заметка: запрос с order_by('?') может быть медленным и сильно нагружать базу данных, зависит от типа базы данных, которую вы используете.

Для сортировки по полю из другой модели, используйте синтаксис аналогичный тому, который используется при фильтрации по полям связанной модели. То есть, название поля, далее два нижних подчеркивания (__), и имя поля в новой модели, и так далее. Например:

Entry.objects.order_by("blog__name", "headline")

Если вы пытаетесь отсортировать по полю, которое является связью на другую модель, Django будет использовать сортировку по-умолчанию связанной модели (или же сортировку по первичному ключу связанной модели если Meta.ordering не указан). Например, так как в модели Blog не указана сортировка по умолчанию:

Entry.objects.order_by("blog")

…идентично:

Entry.objects.order_by("blog__id")

Если Blog содержит ordering = ['name'], первый запрос будет аналогичен:

Entry.objects.order_by("blog__name")

Вы можете также сортировать по выражению, вызвав asc() или desc() для выражения:

Entry.objects.order_by(Coalesce("summary", "headline").desc())

asc() и desc() имеют аргументы (nulls_first и nulls_last), которые управляют сортировкой нулевых значений.

Будьте осторожны при сортировке по полям в связанных моделях, если вы также используете distinct(). См. примечание в distinct() для объяснения того, как упорядочение связанных моделей может изменить ожидаемые результаты.

class Event(Model):
    parent = models.ForeignKey(
        "self",
        on_delete=models.CASCADE,
        related_name="children",
    )
    date = models.DateField()


Event.objects.order_by("children__date")

Нет способа указать должна ли сортировка учитывать регистр. Поэтому Django возвращает результат в таком порядке, в каком его вернула используемая база данных.

Вы можете отсортировать по полю преобразовав значение в нижний регистр, используя Lower:

Entry.objects.order_by(Lower("headline").desc())

Если вы не хотите, чтобы к запросу применялся какой-либо порядок, даже порядок по умолчанию, вызовите order_by() без параметров.

Вы можете определить используется сортировка или нет проверив атрибут QuerySet.ordered, который будет равен True, если сортировка была применена для QuerySet каким-либо образом.

Каждый последующий вызов order_by() сбросит предыдущую сортировку. Например, следующий запрос будет отсортирован по pub_date, а не headline:

Entry.objects.order_by("headline").order_by("pub_date")

reverse¶

reverse()¶

Используйте метод reverse(), чтобы изменить порядок сортировки на обратный. Вызов reverse() повторно восстановит изначальную сортировку.

Чтобы получить «последние» пять объектов выполните:

my_queryset.reverse()[:5]

Обратите внимание, что это не совсем аналог среза Python с конца. Этот пример вернет сначала последний элемент, потом предпоследний и так далее. Используя список Python и сделав срез seq[-5:], мы увидим пятый элемент с конца первым. Django не поддерживает подобное (срез с конца), т.к. нет способа интерпретировать это в эффективный SQL.

Также обратите внимание, что reverse() обычно следует вызывать только для QuerySet, который имеет определенный порядок (например, при запросе к модели, которая определяет порядок по умолчанию, или при использовании order_by()). Если такой порядок не определен для данного QuerySet, вызов reverse() не имеет реального эффекта (порядок был неопределенным до вызова reverse() и останется неопределенным впоследствии).

distinct¶

distinct(*fields)¶

Возвращает QuerySet с добавленным SELECT DISTINCT в SQL запрос. Повторяющиеся записи будут исключены из результатов запроса.

По-умолчанию, QuerySet не исключает повторяющиеся записи. На практике, это редко является проблемой, простые запросы вроде Blog.objects.all() не создают повторяющиеся записи. Однако, если запрос использует несколько таблиц, возможно что QuerySet вернет повторяющиеся записи. И здесь вам пригодится distinct().

Только для PostgreSQL можно указать позиционный аргумент (*fields) определяющий для каких полей применять DISTINCT. Они будут добавлены в SELECT DISTINCT ON часть SQL запроса. Вот в чем разница. При обычном вызове distinct(), база данных сравнивает каждое поле каждой строки для определения уникальности записи. При передаче полей в distinct(), база данных будет сравнивать только указанные поля.

Примеры (после первого будут работать только с PostgreSQL):

>>> Author.objects.distinct()
[...]

>>> Entry.objects.order_by("pub_date").distinct("pub_date")
[...]

>>> Entry.objects.order_by("blog").distinct("blog")
[...]

>>> Entry.objects.order_by("author", "pub_date").distinct("author", "pub_date")
[...]

>>> Entry.objects.order_by("blog__name", "mod_date").distinct("blog__name", "mod_date")
[...]

>>> Entry.objects.order_by("author", "pub_date").distinct("author")
[...]

Entry.objects.order_by("blog").distinct("blog")

values¶

values(*fields, **expressions)¶

Возвращает QuerySet , который возвращает словари с результатом вместо объектов моделей.

Каждый словарь представляет объект, ключи которого соответствуют полям модели.

В этом примере сравниваются словари values() с обычными объектами модели:

# This list contains a Blog object.
>>> Blog.objects.filter(name__startswith="Beatles")
<QuerySet [<Blog: Beatles Blog>]>

# This list contains a dictionary.
>>> Blog.objects.filter(name__startswith="Beatles").values()
<QuerySet [{'id': 1, 'name': 'Beatles Blog', 'tagline': 'All the latest Beatles news.'}]>

Метод values() принимает дополнительные позиционные аргументы, *fields, которые определяют какие поля будут получены через SELECT. Каждый словарь будет содержать только указанные поля. Если поля не указаны, каждый словарь будет содержать все данные из таблицы в базе данных.

Например:

>>> Blog.objects.values()
<QuerySet [{'id': 1, 'name': 'Beatles Blog', 'tagline': 'All the latest Beatles news.'}]>
>>> Blog.objects.values("id", "name")
<QuerySet [{'id': 1, 'name': 'Beatles Blog'}]>

Метод values() также принимает необязательные аргументы ключевых слов, **выражения, которые передаются в annotate():

>>> from django.db.models.functions import Lower
>>> Blog.objects.values(lower_name=Lower("name"))
<QuerySet [{'lower_name': 'beatles blog'}]>

Для упорядочивания вы можете использовать встроенные и настраиваемые поисковые запросы. Например:

>>> from django.db.models import CharField
>>> from django.db.models.functions import Lower
>>> CharField.register_lookup(Lower)
>>> Blog.objects.values("name__lower")
<QuerySet [{'name__lower': 'beatles blog'}]>

Агрегат в предложении Values() применяется перед другими аргументами в том же предложении Values(). Если вам нужно сгруппировать по другому значению, добавьте его в предыдущее предложение Values(). Например:

>>> from django.db.models import Count
>>> Blog.objects.values("entry__authors", entries=Count("entry"))
<QuerySet [{'entry__authors': 1, 'entries': 20}, {'entry__authors': 1, 'entries': 13}]>
>>> Blog.objects.values("entry__authors").annotate(entries=Count("entry"))
<QuerySet [{'entry__authors': 1, 'entries': 33}]>

Следует упомянуть несколько тонкостей:

• Если модель содержит поле foo типа ForeignKey, по-умолчанию values() вернет словарь с ключом foo_id, т.к. это названия скрытого поля, которое на самом деле хранит значение (атрибут foo отображает связанную модель). Вызывая values() вы можете передать foo или foo_id и получите тот же результат (ключ словаря будет равен переданному значению).

  Например:

  >>> Entry.objects.values()
  <QuerySet [{'blog_id': 1, 'headline': 'First Entry', ...}, ...]>
  
  >>> Entry.objects.values("blog")
  <QuerySet [{'blog': 1}, ...]>
  
  >>> Entry.objects.values("blog_id")
  <QuerySet [{'blog_id': 1}, ...]>
  

• При использовании values() вместе с distinct() имейте в виду, что порядок может повлиять на результаты. Подробности смотрите в примечании в distinct().

• Если вы используете предложение values() после вызова :meth:extra, любые поля, определенные аргументом select в :meth:extra, должны быть явно включены в вызовvalues(). Любой вызов extra(), сделанный после вызова values(), будет игнорировать дополнительные выбранные поля.

• Вызов only() и defer() после values() не имеет смысла, поэтому это вызовет TypeError.

• Объединение преобразований и агрегатов требует использования двух вызовов annotate(), либо явно, либо в качестве аргументов ключевого слова для values(). Как и выше, если преобразование было зарегистрировано для соответствующего типа поля, первое annotate() можно опустить, поэтому следующие примеры эквивалентны:

  >>> from django.db.models import CharField, Count
  >>> from django.db.models.functions import Lower
  >>> CharField.register_lookup(Lower)
  >>> Blog.objects.values("entry__authors__name__lower").annotate(entries=Count("entry"))
  <QuerySet [{'entry__authors__name__lower': 'test author', 'entries': 33}]>
  >>> Blog.objects.values(entry__authors__name__lower=Lower("entry__authors__name")).annotate(
  ...     entries=Count("entry")
  ... )
  <QuerySet [{'entry__authors__name__lower': 'test author', 'entries': 33}]>
  >>> Blog.objects.annotate(entry__authors__name__lower=Lower("entry__authors__name")).values(
  ...     "entry__authors__name__lower"
  ... ).annotate(entries=Count("entry"))
  <QuerySet [{'entry__authors__name__lower': 'test author', 'entries': 33}]>
  

Полезен, если вам нужны только данные некоторых полей и не нужен функционал объектов моделей. Более эффективно получить только необходимые данные.

Обратите внимание, при вызове filter(), order_by() и других методов после вызова values(), означает, что следующие объекты одинаковы:

Blog.objects.values().order_by("id")
Blog.objects.order_by("id").values()

Разработчики Django предпочитают использовать в первую очередь методы влияющие на SQL-запрос, далее методы влияющие на вывод данных (такие как values()), хотя это и не имеет значения. Это ваш шанс проявить индивидуальность.

Вы также можете ссылаться на поля в связанных моделях с обратными отношениями через атрибуты OneToOneField, ForeignKey и ManyToManyField:

>>> Blog.objects.values("name", "entry__headline")
<QuerySet [{'name': 'My blog', 'entry__headline': 'An entry'},
     {'name': 'My blog', 'entry__headline': 'Another entry'}, ...]>

values_list¶

values_list(*fields, flat=False, named=False)¶

Это похоже на values(), за исключением того, что вместо возврата словарей он возвращает кортежи при повторении. Каждый кортеж содержит значение из соответствующего поля или выражения, переданного в вызов value_list(), поэтому первый элемент является первым полем и т. д. Например:

>>> Entry.objects.values_list("id", "headline")
<QuerySet [(1, 'First entry'), ...]>
>>> from django.db.models.functions import Lower
>>> Entry.objects.values_list("id", Lower("headline"))
<QuerySet [(1, 'first entry'), ...]>

Если вы передаете только одно поле, вы также можете передать параметр Flat. Если True, это будет означать, что возвращаемые результаты представляют собой одиночные значения, а не кортежи из 1 единицы. Пример должен прояснить разницу:

>>> Entry.objects.values_list("id").order_by("id")
<QuerySet[(1,), (2,), (3,), ...]>

>>> Entry.objects.values_list("id", flat=True).order_by("id")
<QuerySet [1, 2, 3, ...]>

Если вы указали больше одного поля, использование flat будет ошибкой.

Вы можете передать named=True, чтобы получить результаты в виде namedtuple():

>>> Entry.objects.values_list("id", "headline", named=True)
<QuerySet [Row(id=1, headline='First entry'), ...]>

Использование именованного кортежа может сделать результаты более читаемыми за счет небольшого снижения производительности при преобразовании результатов в именованный кортеж.

Если поля не будут указаны при вызове values_list(), будут возвращены все поля модели в порядке, в котором они были объявлены.

Общей необходимостью является получение определенного значения поля определенного экземпляра модели. Для этого используйте values_list(), а затем вызов get():

>>> Entry.objects.values_list("headline", flat=True).get(pk=1)
'First entry'

values() и values_list() предназначены для оптимизации для конкретного варианта использования: получения подмножества данных без накладных расходов на создание экземпляра модели. Эта метафора не работает при работе с отношениями «многие-ко-многим» и другими многозначными отношениями (такими как отношение «один-ко-многим» обратного внешнего ключа), поскольку предположение «одна строка, один объект» не выполняется.

Например, обратите внимание на поведение при запросе через ManyToManyField:

>>> Author.objects.values_list("name", "entry__headline")
<QuerySet [('Noam Chomsky', 'Impressions of Gaza'),
 ('George Orwell', 'Why Socialists Do Not Believe in Fun'),
 ('George Orwell', 'In Defence of English Cooking'),
 ('Don Quixote', None)]>

Авторы с несколькими записями появляются несколько раз, а у авторов без записей в заголовке записи указано «Нет».

Аналогично, при запросе обратного внешнего ключа для записей, не имеющих автора, отображается «Нет»:

>>> Entry.objects.values_list("authors")
<QuerySet [('Noam Chomsky',), ('George Orwell',), (None,)]>

dates¶

dates(field, kind, order='ASC')¶

Возвращает QuerySet, который возвращает список объектов datetime.date, отображающих возможные даты в контексте QuerySet.

field должен быть названием поля DateField вашей модели. kind должен быть "year", "month" или "day". Каждый объект datetime.date - результат «урезания» данных в соответствии с указанным type.

• "year" возвращает список уникальных значений года из всех дат указанного поля.

• "month" возвращает список уникальных значений года/месяца из всех дат указанного поля.

• "year" возвращает список уникальных значений года из всех дат указанного поля.

• "day" возвращает список уникальных значений года/месяца/дня из всех дат указанного поля.

order – сортировка значений. По-умолчанию 'ASC', должна быть 'ASC' или 'DESC'.

Например:

>>> Entry.objects.dates("pub_date", "year")
[datetime.date(2005, 1, 1)]
>>> Entry.objects.dates("pub_date", "month")
[datetime.date(2005, 2, 1), datetime.date(2005, 3, 1)]
>>> Entry.objects.dates("pub_date", "week")
[datetime.date(2005, 2, 14), datetime.date(2005, 3, 14)]
>>> Entry.objects.dates("pub_date", "day")
[datetime.date(2005, 2, 20), datetime.date(2005, 3, 20)]
>>> Entry.objects.dates("pub_date", "day", order="DESC")
[datetime.date(2005, 3, 20), datetime.date(2005, 2, 20)]
>>> Entry.objects.filter(headline__contains="Lennon").dates("pub_date", "day")
[datetime.date(2005, 3, 20)]

datetimes¶

datetimes(field_name, kind, order='ASC', tzinfo=None)¶

Возвращает QuerySet, который возвращает список объектов datetime.datetime, отображающих возможные даты в контексте QuerySet.

field_name – название поля модели типа DateTimeField.

kind должен быть "year", "month", "day", "hour", "minute" или "second". Каждый объект datetime.datetime результат «урезания» данных в соответствии с указанным kind.

order – сортировка значений. По-умолчанию 'ASC', должна быть 'ASC' или 'DESC'.

tzinfo указывает часовой пояс используемый при создании объектов datetime. Принимает объект datetime.tzinfo. Если передать None, Django использует текущий часовой пояс. Не используется при USE_TZ равном False.

нет()¶

none()¶

Вызов none() создаст набор запросов, который никогда не возвращает никаких объектов, и при доступе к результатам не будет выполняться никакой запрос. Набор запросов qs.none() является экземпляром EmptyQuerySet.

Например:

>>> Entry.objects.none()
<QuerySet []>
>>> from django.db.models.query import EmptyQuerySet
>>> isinstance(Entry.objects.none(), EmptyQuerySet)
True

все()¶

all()¶

Возвращает копию текущего QuerySet (или подкласса QuerySet). Это может быть полезно в ситуациях, когда вам может потребоваться передать либо менеджер модели, либо QuerySet и выполнить дальнейшую фильтрацию результата. После вызова all() для любого объекта у вас обязательно будет QuerySet для работы.

Если QuerySet был выполнен, он кэширует результат. Если данные в базе данных поменялись после выполнения QuerySet, вы можете получить обновленный результат запроса, вызывав all() уже выполненного QuerySet.

using¶

union(*other_qs, all=False)¶

Использует оператор SQL UNION для объединения результатов двух или более наборов QuerySet. Например:

>>> qs1.union(qs2, qs3)

Оператор UNION по умолчанию выбирает только отдельные значения. Чтобы разрешить дублирование значений, используйте аргумент all=True.

union(), intersection() и difference() возвращают экземпляры модели типа первого QuerySet, даже если аргументами являются QuerySet других моделей. Передача разных моделей работает до тех пор, пока список SELECT одинаков во всех QuerySet (по крайней мере, типы, имена не имеют значения, пока типы расположены в одном и том же порядке). В таких случаях вы должны использовать имена столбцов из первого QuerySet в методах QuerySet, применяемых к результирующему QuerySet. Например:

>>> qs1 = Author.objects.values_list("name")
>>> qs2 = Entry.objects.values_list("headline")
>>> qs1.union(qs2).order_by("name")

Кроме того, в результирующем наборе QuerySet разрешены только LIMIT, OFFSET, COUNT(*), ORDER BY и указание столбцов (т. е. нарезка, count(), exists(), order_by() и values()/values_list`(). Кроме того, базы данных накладывают ограничения на то, какие операции разрешены в комбинированных запросах. Например, большинство баз данных не допускают использования LIMIT или OFFSET в комбинированных запросах.

iterator¶

intersection(*other_qs)¶

Использует оператор SQL INTERSECT для возврата общих элементов двух или более наборов QuerySet. Например:

>>> qs1.intersection(qs2, qs3)

См. некоторые ограничения в union().

defer¶

difference(*other_qs)¶

Использует оператор SQL EXCEPT, чтобы сохранять только элементы, присутствующие в QuerySet, но не в каких-либо других QuerySet. Например:

>>> qs1.difference(qs2, qs3)

См. некоторые ограничения в union().

select_related¶

select_related(*fields)¶

Возвращает QuerySet который автоматически включает в выборку данные связанных объектов при выполнении запроса. Повышает производительность, т.к. при доступе к связанным объектам через модель не потребуются дополнительные запросы в базу данных.

Этот пример отображает разницу между обычной выборкой и с select_related(). Обычная выборка:

# Hits the database.
e = Entry.objects.get(id=5)

# Hits the database again to get the related Blog object.
b = e.blog

И с select_related:

# Hits the database.
e = Entry.objects.select_related("blog").get(id=5)

# Doesn't hit the database, because e.blog has been prepopulated
# in the previous query.
b = e.blog

Вы можете использовать select_related() с любым «queryset»:

from django.utils import timezone

# Find all the blogs with entries scheduled to be published in the future.
blogs = set()

for e in Entry.objects.filter(pub_date__gt=timezone.now()).select_related("blog"):
    # Without select_related(), this would make a database query for each
    # loop iteration in order to fetch the related blog for each entry.
    blogs.add(e.blog)

Порядок использования filter() и select_related() не важен. Эти экземпляры QuerySet одинаковы:

Entry.objects.filter(pub_date__gt=timezone.now()).select_related("blog")
Entry.objects.select_related("blog").filter(pub_date__gt=timezone.now())

Можно указывать поля связанных моделей как и при запросе. Например, у нас есть такие модели:

from django.db import models


class City(models.Model):
    # ...
    pass


class Person(models.Model):
    # ...
    hometown = models.ForeignKey(
        City,
        on_delete=models.SET_NULL,
        blank=True,
        null=True,
    )


class Book(models.Model):
    # ...
    author = models.ForeignKey(Person, on_delete=models.CASCADE)

Затем вызов Book.objects.select_related('author__hometown').get(id=4) будет кэшировать связанный Person и связанный City:

# Hits the database with joins to the author and hometown tables.
b = Book.objects.select_related("author__hometown").get(id=4)
p = b.author  # Doesn't hit the database.
c = p.hometown  # Doesn't hit the database.

# Without select_related()...
b = Book.objects.get(id=4)  # Hits the database.
p = b.author  # Hits the database.
c = p.hometown  # Hits the database.

Вы можете указать любое ForeignKey или OneToOneField поле в select_related().

Вы можете указать обратную связь для OneToOneField в списке полей — то есть, вы можете получить объект в котором определено поле OneToOneField. Вместо названия поля используйте значение параметра related_name.

В некоторых ситуациях вам может понадобится указать большое количество полей в select_related(), или вы просто не знаете всех связей. В таком случае можно использовать select_related() без аргументов. Будут использовать все связи кроме связей с null=True, такие связи необходимо указывать явно. Такой способ не рекомендуется т.к. может привести к очень сложному запросу и получению большого количества ненужных данных.

Если вам нужно очистить список связанных полей, добавленных предыдущими вызовами select_related в QuerySet, вы можете передать None в качестве параметра:

>>> without_relations = queryset.select_related(None)

Несколько вызовов select_related теперь работает как и для других методов – то есть select_related('foo', 'bar') аналогично select_related('foo').select_related('bar').

prefetch_related¶

prefetch_related(*lookups)¶

Возвращает QuerySet, который получает «за один подход» связанные объекты для каждого из указанных параметров поиска.

Смысл такой же, как и у select_related, избежать нарастающего количества запросов при обращении к связанным объектам, но принцип работы немного другой.

select_related создает запрос SQL, объединяющий связанные таблицы и включающий дополнительные поля в SELECT. По этой причине, select_related получает связанные объекты в том же запросе. Однако, чтобы избежать большого количества возвращаемых данных при обработке «множественных» связей, select_related работает только со связями возвращающими один объект - внешний ключ и связь один-к-одному.

С другой стороны, prefetch_related выполняет отдельный поиск для каждого отношения и выполняет «объединение» в Python. Это позволяет ему предварительно выбирать объекты «многие-ко-многим», «многие-к-одному» и GenericRelation, что невозможно сделать с помощью select_related, в дополнение к отношениям внешнего ключа и один-к-одному, которые поддерживаются select_related. Он также поддерживает предварительную выборку GenericForeignKey, однако набор запросов для каждого ContentType должен быть указан в параметре querysets GenericPrefetch.

Например, у вас есть две модели:

from django.db import models


class Topping(models.Model):
    name = models.CharField(max_length=30)


class Pizza(models.Model):
    name = models.CharField(max_length=50)
    toppings = models.ManyToManyField(Topping)

    def __str__(self):
        return "%s (%s)" % (
            self.name,
            ", ".join(topping.name for topping in self.toppings.all()),
        )

и запустите:

>>> Pizza.objects.all()
["Hawaiian (ham, pineapple)", "Seafood (prawns, smoked salmon)"...

Проблема в том, что Pizza.__str__(), вызывая self.toppings.all() выполняет запрос к базе данных, и Pizza.objects.all() выполнит запрос к таблице Topping для каждого объекта Pizza в QuerySet.

Мы можем уменьшить количество запросов до двух, используя prefetch_related:

>>> Pizza.objects.prefetch_related("toppings")

Этот код аналогичен выполнению self.toppings.all() для каждого объекта Pizza . При вызове self.toppings.all() будут использоваться подгруженные данные, вместо запроса к БД. Django найдет их в кэше QuerySet, который был заполнен одним запросом.

То есть все соответствующие начинки будут получены в одном запросе и использованы для создания экземпляров QuerySet, имеющих предварительно заполненный кеш соответствующих результатов; затем они используются в вызовах self.toppings.all().

Запрос для загрузки данных, указанных в prefetch_related() будет выполнен после выполнения основного запроса.

Обратите внимание, что не существует механизма, предотвращающего изменение элементов другим запросом к базе данных между выполнением основного запроса и дополнительных запросов, что может привести к противоречивому результату. Например, если пицца будет удалена после выполнения основного запроса, ее начинка не будет возвращена в дополнительном запросе, и будет казаться, что у пиццы нет начинки:

>>> Pizza.objects.prefetch_related("toppings")
#  "Hawaiian" Pizza was deleted in another shell.
<QuerySet [<Pizza: Hawaiian ()>, <Pizza: Seafood (prawns, smoked salmon)>]>

Если у вас есть итерация экземпляров модели, вы можете предварительно загрузить связанные атрибуты этих экземпляров, используя функцию prefetch_related_objects().

Обратите внимание, что кэш результатов основного QuerySet и всех указанных связанных объектов будет затем полностью загружен в память. Это меняет типичное поведение QuerySet, который обычно пытается избежать загрузки всех объектов в память до того, как они потребуются, даже после того, как запрос был выполнен в базе данных.

>>> pizzas = Pizza.objects.prefetch_related("toppings")
>>> [list(pizza.toppings.filter(spicy=True)) for pizza in pizzas]

Вы можете использовать стандартный синтаксис для обращения к связанным моделям. Например, добавим еще одну модель в пример выше:

class Restaurant(models.Model):
    pizzas = models.ManyToManyField(Pizza, related_name="restaurants")
    best_pizza = models.ForeignKey(
        Pizza, related_name="championed_by", on_delete=models.CASCADE
    )

Можно использовать такой запрос:

>>> Restaurant.objects.prefetch_related("pizzas__toppings")

Этот запрос выполнит предварительную загрузку всех пицц(Pizza) для ресторанов(Restaurant) и всех ингредиентов(Topping) для пицц. В результате будет выполнено 3 запроса - один для Restaurant, один для Pizza, и один для Topping.

>>> Restaurant.objects.prefetch_related("best_pizza__toppings")

Это вернет «best pizza» и все «toppings» для них для каждого ресторана. Будет выполнено 3 запроса.

Отношения «best_pizza» также можно получить с помощью select_related, чтобы уменьшить количество запросов до 2:

>>> Restaurant.objects.select_related("best_pizza").prefetch_related("best_pizza__toppings")

Так как предварительная загрузка выполняется после основного запроса (который включает все необходимые объединения таблиц для обработки select_related), она способна определить что объекты best_pizza уже получены и не выполнит их загрузку снова.

Использование нескольких вызовов prefetch_related соберет вместе все предварительно загружаемые поля. Чтобы их обнулить, вызовите метод prefetch_related с аргументом None:

>>> non_prefetched = qs.prefetch_related(None)

Одна особенность вызова prefetch_related, про которую следует упомянуть: объекты созданные в результате выполнения запроса могут быть использованы различными связанными объектами, то есть один экземпляр модели может оказаться более чем в одной точке в дереве возвращенных объектов. Это обычно случается с внешними ключами. Скорее всего это не вызовет никаких проблем, и даже сохранит память и время CPU.

Так как prefetch_related поддерживает предварительную загрузку GenericForeignKey, количество запросов зависит от данных. Так как GenericForeignKey может ссылаться на данные из разных таблиц, необходим один запрос на одну таблицу, вместо одного запроса для всех данных. Также может понадобится дополнительный запрос к таблице ContentType, если соответствующие данные еще не загружены.

prefetch_related в основном использует оператор „IN“ SQL запроса. Это означает, что для больших QuerySet может быть создано сложное условие „IN“, что, в зависимости от базы данных, может привести к проблемам с производительностью при разборе и выполнении SQL запроса. Всегда анализируйте(profile) ваш запрос!

Если вы используете iterator() для выполнения запроса, вызовы prefetch_related() будут наблюдаться только в том случае, если указано значение chunk_size.

Вы можете использовать объект Prefetch для большего контроля предварительной загрузкой.

В самом простом варианте Prefetch аналогичен обычному строковому аргументу:

>>> from django.db.models import Prefetch
>>> Restaurant.objects.prefetch_related(Prefetch("pizzas__toppings"))

Вы можете указать свой QuerySet в необязательном аргументе queryset. Это позволяет переопределить сортировку по умолчанию:

>>> Restaurant.objects.prefetch_related(
...     Prefetch("pizzas__toppings", queryset=Toppings.objects.order_by("name"))
... )

Или вызвать select_lated(), если это применимо, чтобы еще больше сократить количество запросов:

>>> Pizza.objects.prefetch_related(
...     Prefetch("restaurants", queryset=Restaurant.objects.select_related("best_pizza"))
... )

Можно также результат сохранить другом атрибуте, указав название в аргументе to_attr. Результат будет сохранен непосредственно в списке.

Это позволяет выполнить предварительную загрузку несколько раз для одной связи, используя разные QuerySet. Например:

>>> vegetarian_pizzas = Pizza.objects.filter(vegetarian=True)
>>> Restaurant.objects.prefetch_related(
...     Prefetch("pizzas", to_attr="menu"),
...     Prefetch("pizzas", queryset=vegetarian_pizzas, to_attr="vegetarian_menu"),
... )

Результат с собственным to_attr может использоваться в аргументах запроса:

>>> vegetarian_pizzas = Pizza.objects.filter(vegetarian=True)
>>> Restaurant.objects.prefetch_related(
...     Prefetch("pizzas", queryset=vegetarian_pizzas, to_attr="vegetarian_menu"),
...     "vegetarian_menu__toppings",
... )

Использование to_attr рекомендуется при фильтрации результата предварительной загрузки т.к. это менее двусмысленно, чем сохранение результата фильтрации в кэше связывающего менеджера:

>>> queryset = Pizza.objects.filter(vegetarian=True)
>>>
>>> # Recommended:
>>> restaurants = Restaurant.objects.prefetch_related(
...     Prefetch("pizzas", queryset=queryset, to_attr="vegetarian_pizzas")
... )
>>> vegetarian_pizzas = restaurants[0].vegetarian_pizzas
>>>
>>> # Not recommended:
>>> restaurants = Restaurant.objects.prefetch_related(
...     Prefetch("pizzas", queryset=queryset),
... )
>>> vegetarian_pizzas = restaurants[0].pizzas.all()

Пользовательская предварительная выборка также работает с отдельными связанными отношениями, такими как ForeignKey или OneToOneField. Обычно для этих отношений лучше использовать select_related(), но есть ряд случаев, когда предварительная выборка с помощью специального QuerySet полезна:

• Вы хотите использовать QuerySet, который выполняет предварительную загрузку для связанной модели.

• Вы хотите загрузить только часть связанных объектов.

• Вы хотите оптимизировать запрос, отфильтровав часть полей:

  >>> queryset = Pizza.objects.only("name")
  >>>
  >>> restaurants = Restaurant.objects.prefetch_related(
  ...     Prefetch("best_pizza", queryset=queryset)
  ... )
  

При использовании нескольких баз данных функция Prefetch будет учитывать ваш выбор базы данных. Если внутренний запрос не указывает базу данных, он будет использовать базу данных, выбранную внешним запросом. Все следующее действительно:

>>> # Both inner and outer queries will use the 'replica' database
>>> Restaurant.objects.prefetch_related("pizzas__toppings").using("replica")
>>> Restaurant.objects.prefetch_related(
...     Prefetch("pizzas__toppings"),
... ).using("replica")
>>>
>>> # Inner will use the 'replica' database; outer will use 'default' database
>>> Restaurant.objects.prefetch_related(
...     Prefetch("pizzas__toppings", queryset=Toppings.objects.using("replica")),
... )
>>>
>>> # Inner will use 'replica' database; outer will use 'cold-storage' database
>>> Restaurant.objects.prefetch_related(
...     Prefetch("pizzas__toppings", queryset=Toppings.objects.using("replica")),
... ).using("cold-storage")

>>> prefetch_related("pizzas__toppings", "pizzas")

>>> prefetch_related("pizzas__toppings", Prefetch("pizzas", queryset=Pizza.objects.all()))

>>> prefetch_related("pizza_list__toppings", Prefetch("pizzas", to_attr="pizza_list"))

**extra¶

extra(select=None, where=None, params=None, tables=None, order_by=None, select_params=None)¶

Иногда, стандартных возможностей Django не хватает для создания сложного условия WHERE запроса. Для таких случаев, Django предоставляет метод extra() QuerySet — метод позволяющий изменять SQL сгенерированный QuerySet.

>>> qs.extra(
...     select={"val": "select col from sometable where othercol = %s"},
...     select_params=(someparam,),
... )

>>> qs.annotate(val=RawSQL("select col from sometable where othercol = %s", (someparam,)))

SELECT col FROM sometable WHERE othercol = '%s'  # unsafe!

По определению, дополнительные параметры поиска определенные в extra() не переносимы между различными типами данных(потому что вы используете непосредственно SQL) и нарушает принцип DRY, поэтому вы должны избегать использование этого метода.

Укажите одни или несколько параметров params, select, where или tables. Ни один из аргументов не обязателен, но вы должны указать хотя бы один.

• select

  Аргумент select позволяет вам добавить дополнительные поля в предложение SELECT. Это должен быть словарь, сопоставляющий имена атрибутов с предложениями SQL, которые будут использоваться для вычисления этого атрибута.

  Например:

  Entry.objects.extra(select={"is_recent": "pub_date > '2006-01-01'"})
  

  В результате, каждый объект Entry будет содержать дополнительный атрибут, is_recent, булево значение определяющее больше ли значение pub_date чем 1 января 2006.

  Django вставит добавленный кусок SQL непосредственно в оператор SELECT, полученный SQL выглядит таким образом:

  SELECT blog_entry.*, (pub_date > '2006-01-01') AS is_recent
  FROM blog_entry;
  

  Следующий пример сложнее. Он добавляет подзапрос, чтобы добавить каждому объекту Blog атрибут entry_count, который равен количеству связанных объектов Entry:

  Blog.objects.extra(
      select={
          "entry_count": "SELECT COUNT(*) FROM blog_entry WHERE blog_entry.blog_id = blog_blog.id"
      },
  )
  

  В это примере, мы используем тот факт, что запрос уже будет содержать таблицу blog_blog в операторе FROM.

  Полученный SQL запрос выглядит таким образом:

  SELECT blog_blog.*, (SELECT COUNT(*) FROM blog_entry WHERE blog_entry.blog_id = blog_blog.id) AS entry_count
  FROM blog_blog;
  

  Обратите внимание, что круглые скобки, необходимые для большинства СУБД вокруг подзапросов, не требуются в предложениях Django select.

  В некоторых редких случаях вам может потребоваться передать параметры фрагментам SQL в extra(select=...). Для этой цели используйте параметр select_params.

  Например:

  Blog.objects.extra(
      select={"a": "%s", "b": "%s"},
      select_params=("one", "two"),
  )
  

  Если вам необходимо использовать %s в запрашиваемой строке, используйте %%s.

• where / tables

  Вы можете добавить оператор SQL WHERE — возможно для выполнения не явного объединения таблиц — by using where. Используя параметр tables можно добавить таблицы в оператор SQL FROM.

  where и tables принимают список строк. Все параметры where будут добавлены к остальным критериям через оператор «AND» .

  Например:

  Entry.objects.extra(where=["foo='a' OR bar = 'a'", "baz = 'a'"])
  

  …будет переведено (примерно) в следующий SQL:

  SELECT * FROM blog_entry WHERE (foo='a' OR bar='a') AND (baz='a')
  

  Будьте внимательны при добавлении в параметр tables таблиц, которые уже используются запросом. В таком случае Django предполагает, что вы хотите добавить их повторно. Это создает проблему, т.к. таблица будет добавлена с псевдонимом(an alias). Если таблица несколько раз используется в запросе, второй и последующие вхождения должны использовать псевдонимы, чтобы база данных могла различить их. При обращении к добавленной таблице в параметре where вы получите ошибку.

  Скорее всего вы будете использовать дополнительные таблицы, которые еще не добавлены в запрос. Однако, если все таки возникнет описанная выше ситуация, существует несколько способов ее решить. Первый, посмотрите возможно ли использовать уже добавленную в запрос таблицу. Если это не возможно, используйте вызов extra() в начале конструкции запроса, чтобы ваша таблица использовалась первой. В конце концов, если каким-то образом все остальное вам не помогло, посмотрите на созданный запрос и перепишите параметр where таким образом, чтобы использовался псевдоним назначенный дополнительной таблице. При одинаковом способе создать запрос псевдоним будет всегда не измененным.

• order_by

  Если вам нужно упорядочить результирующий набор запросов с использованием некоторых новых полей или таблиц, которые вы включили с помощью extra(), используйте параметр order_by для extra() и передайте последовательность строк. Эти строки должны быть либо полями модели (как в обычном методе order_by() для наборов запросов) в форме имя_таблицы.имя_столбца, либо псевдонимом столбца, который вы указали в параметре select для extra().

  Например:

  q = Entry.objects.extra(select={"is_recent": "pub_date > '2006-01-01'"})
  q = q.extra(order_by=["-is_recent"])
  

  Это запрос должен отсортировать все записи, у которых is_recent равен True, перед остальными записями (True следует перед False при ниспадающей сортировке).

  Вы можете заметить, между прочим, что можно выполнить несколько вызовов extra() (добавляя новые параметры каждый раз).

• params

  Параметр where описанный выше может использовать стандартный синтаксис Python подстановки параметров в строку — '%s', чтобы указать какие параметры должны быть экранированы базой данных. Аргумент params это список дополнительных параметров, которые будут подставлены в условие where.

  Например:

  Entry.objects.extra(where=["headline=%s"], params=["Lennon"])
  

  Всегда используйте params вместо добавления значений непосредственно в where т.к. params гарантирует, что все значения будут экранированы в соответствиями с синтаксисом используемой базы данных. Например, кавычки будут экранированы правильно.

  Не верно:

  Entry.objects.extra(where=["headline='Lennon'"])
  

  Верно:

  Entry.objects.extra(where=["headline=%s"], params=["Lennon"])
  

defer¶

defer(*fields)¶

При сложной структуре данных модели могут содержать большое количество полей, некоторые из которых могут содержать большие объемы данных(например, текстовые поля), или использовать ресурсоемкий процесс преобразования данных в объекты Python. Если вы точно знаете, что данные этих полей не будут использоваться при работе с результатами запроса, вы можете указать Django не выбирать эти поля из базы данных.

Это делается передачей названия полей, которые не должны быть загружены, в метод defer():

Entry.objects.defer("headline", "body")

Результат все также будет содержать объекты модели. Каждое не выбранное поле будет получено из базы данных при обращении к нему (одна за раз, не все «отложенные» поля сразу).

Вы можете выполнить несколько вызовов defer(). Каждый вызов добавит новые поля в список «отложенных»:

# Defers both the body and headline fields.
Entry.objects.defer("body").filter(rating=5).defer("headline")

Порядок добавления полей не имеет значения. Вызов defer() с полем, которое уже было добавлено в список «отложенных», ничего не изменит (поле все также не будет выбираться из базы данных).

Вы можете отложить загрузку полей в связанных моделях (если связанные модели загружаются через select_related()), используя стандартную нотацию двойного подчеркивания для разделения связанных полей:

Blog.objects.select_related().defer("entry__headline", "entry__body")

Если вы хотите очистить список «отложенных» полей, передайте None как параметр для defer():

# Load all fields immediately.
my_queryset.defer(None)

Некоторые поля в модели не будут отложены, даже если вы запросите их. Вы никогда не сможете отложить загрузку первичного ключа. Если вы используете select_related() для получения связанных моделей, вам не следует откладывать загрузку поля, которое подключается от основной модели к связанной, это приведет к ошибке.

Аналогично, вызов defer() (или его аналога only()), включающий аргумент из агрегации (например, использование результата annotate()), не имеет смысла: это вызовет исключение. Агрегированные значения всегда будут извлекаться в результирующий набор запросов.

class CommonlyUsedModel(models.Model):
    f1 = models.CharField(max_length=10)

    class Meta:
        managed = False
        db_table = "app_largetable"


class ManagedModel(models.Model):
    f1 = models.CharField(max_length=10)
    f2 = models.CharField(max_length=10)

    class Meta:
        db_table = "app_largetable"


# Two equivalent QuerySets:
CommonlyUsedModel.objects.all()
ManagedModel.objects.defer("f2")

только()¶

only(*fields)¶

Метод only() по сути является противоположностью defer(). Только поля, переданные в этот метод и которые не еще указаны как отложенные, загружаются немедленно при оценке набора запросов.

Если у вас есть модель, в которой почти все поля необходимо отложить, использование only() для указания дополнительного набора полей может привести к упрощению кода.

Например, у вас есть модель с полями name, age и biography. Эти два запроса идентичны в плане полученных полей:

Person.objects.defer("age", "biography")
Person.objects.only("name")

При вызове only() будет заменено множество загружаемых полей. Название метода говорит само за себя: только эти поля должны быть загружены; все остальные – «отложены». Таким образом при последовательном вызове only() несколько раз, только поля из последнего вызова будут загружены:

# This will defer all fields except the headline.
Entry.objects.only("body", "rating").only("headline")

Так как defer() добавляет поля в список «отложенных» при множественном вызове, вы можете совмещать вызовы only() и defer(), что будет работать вполне логично:

# Final result is that everything except "headline" is deferred.
Entry.objects.only("headline", "body").defer("body")

# Final result loads headline immediately.
Entry.objects.defer("body").only("headline", "body")

Все замечания описанные для метода defer() применимы и к методу only(). Используйте его с осторожностью и только в отсутствии других вариантов.

Использование only() и пропуск поля, запрошенного с помощью select_related(), также является ошибкой. С другой стороны, вызов only() без каких-либо аргументов вернет все поля (включая аннотации), полученные набором запросов.

Как и в случае с defer(), вы не можете получить доступ к незагруженным полям из асинхронного кода и ожидать их загрузки. Вместо этого вы получите исключение SynchronousOnlyOperation. Убедитесь, что все поля, к которым вы можете получить доступ, находятся в вашем вызове only().

using¶

using(alias)¶

Этот метод предназначен для управления базой данных, по которой будет оцениваться QuerySet, если вы используете более одной базы данных. Единственный аргумент, который принимает этот метод, — это псевдоним базы данных, определенный в DATABASES.

Например:

# queries the database with the 'default' alias.
>>> Entry.objects.all()

# queries the database with the 'backup' alias
>>> Entry.objects.using("backup")

select_for_update¶

select_for_update(nowait=False, skip_locked=False, of=(), no_key=False)¶

Возвращает QuerySet, блокирующий записи до завершения транзакции, используя оператор SQL SELECT ... FOR UPDATE используемой базы данных.

Например:

from django.db import transaction

entries = Entry.objects.select_for_update().filter(author=request.user)
with transaction.atomic():
    for entry in entries:
        ...

Все, удовлетворяющие фильтрам, строки будут заблокированы до завершения транзакции, то есть другие транзакции не смогут изменить или заблокировать это строки.

Обычно, если другая транзакция заблокировала одну из выбранных записей, запрос будет заблокирован до снятия блокировки. Если вы не желаете этого, используйте select_for_update(nowait=True). Вызов будет не блокированным, если записи уже заблокированы, будет вызвано исключение DatabaseError при вычислении QuerySet.

По умолчанию select_for_update() блокирует все строки, выбранные запросом. Например, строки связанных объектов, указанные в select_related(), блокируются в дополнение к строкам модели набора запросов. Если это нежелательно, укажите связанные объекты, которые вы хотите заблокировать, в select_for_update(of=(...)), используя тот же синтаксис полей, что и select_based(). Используйте значение self для ссылки на модель набора запросов.

Restaurant.objects.select_for_update(of=("self", "place_ptr"))

Только в PostgreSQL вы можете передать no_key=True, чтобы получить более слабую блокировку, которая по-прежнему позволяет создавать строки, которые просто ссылаются на заблокированные строки (например, через внешний ключ), пока блокировка действует. В документации PostgreSQL есть более подробная информация о режимах блокировки на уровне строк.

Вы не можете использовать select_for_update() для отношений, допускающих значение NULL:

>>> Person.objects.select_related("hometown").select_for_update()
Traceback (most recent call last):
...
django.db.utils.NotSupportedError: FOR UPDATE cannot be applied to the nullable side of an outer join

Чтобы избежать этого ограничения, вы можете исключить нулевые объекты, если они вам не нужны:

>>> Person.objects.select_related("hometown").select_for_update().exclude(hometown=None)
<QuerySet [<Person: ...)>, ...]>

Базы данных postgresql, oracle и mysql поддерживают select_for_update(). Однако MariaDB поддерживает только аргумент nowait, MariaDB 10.6+ также поддерживает аргументskip_locked, а MySQL поддерживает аргументы nowait,skip_locked и of. Аргумент no_key поддерживается только в PostgreSQL.

Передача nowait=True, skip_locked=True, no_key=True или of в select_for_update() с использованием баз данных, которые не поддерживают эти параметры, таких как MySQL, вызывает ошибку NotSupportedError. Это предотвращает неожиданную блокировку кода.

Выполнение выборки с select_for_update() в autocommit режиме для бэкенда, который поддерживает SELECT ... FOR UPDATE, вызовет TransactionManagementError т.к. строки не будут заблокированы в этом случае. Если разрешить такое выполнение, это может привести к повреждению данных т.к. код рассчитывает, что будет выполнен в транзакции, хотя это не так.

Использование select_for_update() с базой данных, которая не поддерживает SELECT ... FOR UPDATE (например, SQLite) не будет иметь никакого эффекта. SELECT ... FOR UPDATE не будет добавлено к запросу, и ошибка не будет вызвана, если select_for_update() используется в autocommit режиме.

сырой()¶

raw(raw_query, params=(), translations=None, using=None)¶

Принимает SQL запрос, выполняет его и возвращает объект django.db.models.query.RawQuerySet. Этот объект RawQuerySet может быть проитерирован как и обычный QuerySet для получения объектов результата.

Смотрите Использование чистого SQL.

И (&)¶

Объединяет два набора QuerySet с помощью оператора SQL AND аналогично объединению фильтров.

Можно использовать такой запрос:

Model.objects.filter(x=1) & Model.objects.filter(y=2)
Model.objects.filter(x=1).filter(y=2)

Аналог SQL:

SELECT ... WHERE x=1 AND y=2

ИЛИ (|)¶

Объединяет два набора QuerySet с помощью оператора SQL OR.

Можно использовать такой запрос:

Model.objects.filter(x=1) | Model.objects.filter(y=2)
from django.db.models import Q

Model.objects.filter(Q(x=1) | Q(y=2))

Аналог SQL:

SELECT ... WHERE x=1 OR y=2

| не является коммутативной операцией, поскольку могут быть сгенерированы разные (хотя и эквивалентные) запросы.

Исключающее ИЛИ (^)¶

Объединяет два набора QuerySet с помощью оператора SQL XOR. Выражение XOR соответствует строкам, которым соответствует нечетное количество операндов.

Можно использовать такой запрос:

Model.objects.filter(x=1) ^ Model.objects.filter(y=2)
from django.db.models import Q

Model.objects.filter(Q(x=1) ^ Q(y=2))

Аналог SQL:

SELECT ... WHERE x=1 XOR y=2

(x OR y OR ... OR z) AND
1=MOD(
    (CASE WHEN x THEN 1 ELSE 0 END) +
    (CASE WHEN y THEN 1 ELSE 0 END) +
    ...
    (CASE WHEN z THEN 1 ELSE 0 END),
    2
)

get()¶

get(*args, **kwargs)¶

aget(*args, **kwargs)¶

Асинхронная версия: aget()

Возвращает объект, соответствующий заданным параметрам поиска, который должен быть в формате, описанном в разделе Поиск полей. Вам следует использовать поиски, которые гарантированно уникальны, например, первичный ключ или поля в ограничении уникальности. Например:

Entry.objects.get(id=1)
Entry.objects.get(Q(blog=blog) & Q(entry_number=1))

Если вы ожидаете, что набор запросов уже вернет одну строку, вы можете использовать get() без каких-либо аргументов, чтобы вернуть объект для этой строки:

Entry.objects.filter(pk=1).get()

Если get() не находит ни одного объекта, он вызывает исключение Model.DoesNotExist:

Entry.objects.get(id=-999)  # raises Entry.DoesNotExist

Если get() находит более одного объекта, он вызывает исключение Model.MultipleObjectsReturned:

Entry.objects.get(name="A Duplicated Name")  # raises Entry.MultipleObjectsReturned

Оба этих класса исключений являются атрибутами класса модели и специфичны для этой модели. Если вы хотите обрабатывать такие исключения из нескольких вызовов get() для разных моделей, вы можете использовать их общие базовые классы. Например, вы можете использовать django.core.Exceptions.ObjectDoesNotExist для обработки исключений DoesNotExist из нескольких моделей:

from django.core.exceptions import ObjectDoesNotExist

try:
    blog = Blog.objects.get(id=1)
    entry = Entry.objects.get(blog=blog, entry_number=1)
except ObjectDoesNotExist:
    print("Either the blog or entry doesn't exist.")

create¶

create(**kwargs)¶

acreate(**kwargs)¶

Асинхронная версия: acreate()

Удобный метод создания объекта и сохранения его всего за один шаг. Таким образом:

p = Person.objects.create(first_name="Bruce", last_name="Springsteen")

и:

p = Person(first_name="Bruce", last_name="Springsteen")
p.save(force_insert=True)

эквивалентны.

Параметр force_insert описан в другом разделе, он означает, что всегда будет создаваться новый объект. Обычно вам не нужно беспокоиться об этом. Однако, если ваш объект содержит значение первичного ключа и этот ключ уже существует в базе данных, метод create() вызовет исключение IntegrityError т.к. первичный ключ должен быть уникальным. Будьте готовы обработать исключение, если вы самостоятельно указываете первичный ключ.

get_or_create¶

get_or_create(defaults=None, **kwargs)¶

aget_or_create(defaults=None, **kwargs)¶

Асинхронная версия: aget_or_create()

Удобный метод для поиска объекта по заданным параметрам поиска kwargs (может быть пустым, если все поля содержат значения по умолчанию), и создания нового при необходимости.

Возвращает кортеж (object, created), где object полученный или созданный объект и created – булево значение, указывающее был ли создан объект.

Это предназначено для предотвращения создания дублирующихся объектов при параллельных запросах и в качестве ярлыка для шаблонного кода. Например:

try:
    obj = Person.objects.get(first_name="John", last_name="Lennon")
except Person.DoesNotExist:
    obj = Person(first_name="John", last_name="Lennon", birthday=date(1940, 10, 9))
    obj.save()

Такой способ становится весьма громоздким при увеличении количества полей модели. Пример выше может быть переписан с использованием метода get_or_create():

obj, created = Person.objects.get_or_create(
    first_name="John",
    last_name="Lennon",
    defaults={"birthday": date(1940, 10, 9)},
)

Любые аргументы ключевого слова, переданные в get_or_create() — кроме необязательного аргумента, называемого defaults, - будут использоваться в вызове get(). Если объект найден, get_or_create() возвращает кортеж этого объекта и False.

Вы можете указать более сложные условия для полученного объекта, связав get_or_create() с filter() и используя Q объекты. Например, чтобы получить Роберта или Боба Марли, если они существуют, и создать последнего в противном случае:

from django.db.models import Q

obj, created = Person.objects.filter(
    Q(first_name="Bob") | Q(first_name="Robert"),
).get_or_create(last_name="Marley", defaults={"first_name": "Bob"})

Все именованные аргументы переданные в get_or_create() — кроме одного не обязательного defaults — будут использованы при вызове get(). Если объект найден, get_or_create() вернет этот объект и False. Если найдено несколько объектов - будет вызвано исключение MultipleObjectsReturned. Если объект не найден, get_or_create() создаст и сохранит новый объект, возвращая новый объект и True. Новый объект будет создан примерно за таким алгоритмом:

params = {k: v for k, v in kwargs.items() if "__" not in k}
params.update({k: v() if callable(v) else v for k, v in defaults.items()})
obj = self.model(**params)
obj.save()

Это означает, что будут выбраны именованные аргументы кроме 'defaults' и не содержащие двойное подчеркивание (которые указывают на не-точный поиск). Затем добавляются значения из defaults, перезаписывая ключи при необходимости, полученные данные используются как аргументы для конструктора класса модели. Как уже указывалось выше, это упрощенный алгоритм, но все важные детали указаны. Внутренняя реализация одержит больше проверок ошибок и различных условий; если вам интересно, можете посмотреть исходный код.

Если модель содержит поле defaults и вы хотите использовать его в параметрах поиска в get_or_create(), просто используйте 'defaults__exact':

Foo.objects.get_or_create(defaults__exact="bar", defaults={"defaults": "baz"})

Метод get_or_create() имеет поведение ошибок, аналогичное методу create(), когда вы используете указанные вручную первичные ключи. Если необходимо создать объект и ключ уже существует в базе данных, будет выдано сообщение IntegrityError.

Наконец, несколько слов об использовании get_or_create() в представлениях Django. Обязательно используйте его только в запросах POST, если у вас нет веских причин не делать этого. Запросы GET не должны оказывать никакого влияния на данные. Вместо этого используйте POST всякий раз, когда запрос к странице оказывает побочный эффект на ваши данные. Дополнительную информацию см. в разделе Безопасные методы в спецификации HTTP.

class Chapter(models.Model):
    title = models.CharField(max_length=255, unique=True)


class Book(models.Model):
    title = models.CharField(max_length=256)
    chapters = models.ManyToManyField(Chapter)

>>> book = Book.objects.create(title="Ulysses")
>>> book.chapters.get_or_create(title="Telemachus")
(<Chapter: Telemachus>, True)
>>> book.chapters.get_or_create(title="Telemachus")
(<Chapter: Telemachus>, False)
>>> Chapter.objects.create(title="Chapter 1")
<Chapter: Chapter 1>
>>> book.chapters.get_or_create(title="Chapter 1")
# Raises IntegrityError

update_or_create¶

update_or_create(defaults=None, create_defaults=None, **kwargs)¶

aupdate_or_create(defaults=None, create_defaults=None, **kwargs)¶

Асинхронная версия: aupdate_or_create()

Удобный метод обновления объекта с заданными «кваргами» и создания нового при необходимости. Оба create_defaults и defaults являются словарями пар (поле, значение). Значения в create_defaults и defaults могут быть вызываемыми. defaults используется для обновления объекта, а create_defaults используется для операции создания. Если create_defaults не указан, defaults будет использоваться для операции создания.

Возвращает кортеж (object, created), где object полученный или обновленный объект и created – булево значение, указывающее был ли создан объект.

Метод update_or_create пытается получить объект из базы данных, используя kwargs. Если объект найден, он обновляет поля указанные в defaults.

Этот метод удобно использовать для скриптов импорта данных. Например:

defaults = {"first_name": "Bob"}
create_defaults = {"first_name": "Bob", "birthday": date(1940, 10, 9)}
try:
    obj = Person.objects.get(first_name="John", last_name="Lennon")
    for key, value in defaults.items():
        setattr(obj, key, value)
    obj.save()
except Person.DoesNotExist:
    new_values = {"first_name": "John", "last_name": "Lennon"}
    new_values.update(create_defaults)
    obj = Person(**new_values)
    obj.save()

Такой способ становится весьма громоздким при увеличении количества полей модели. Пример выше может быть переписан с использованием метода update_or_create():

obj, created = Person.objects.update_or_create(
    first_name="John",
    last_name="Lennon",
    defaults={"first_name": "Bob"},
    create_defaults={"first_name": "Bob", "birthday": date(1940, 10, 9)},
)

Подробное описание того, как разрешаются имена, передаваемые в kwargs, см. в get_or_create().

Как описано выше в get_or_create(), этот метод подвержен состоянию гонки, что может привести к созданию одинаковых строк в базе данных, если уникальность полей не контролируется на уровне базы данных.

Метод get_or_create() использует аналогичное поведение с ошибками что и метод create(), если вы самостоятельно определяете значение первичного ключа. Если объект должен быть создан и значение первичного ключа уже существует в базе данных, будет вызвано исключение IntegrityError.

bulk_create¶

bulk_create(objs, batch_size=None, ignore_conflicts=False, update_conflicts=False, update_fields=None, unique_fields=None)¶

abulk_create(objs, batch_size=None, ignore_conflicts=False, update_conflicts=False, update_fields=None, unique_fields=None)¶

Асинхронная версия: abulk_create()

Этот метод эффективно вставляет предоставленный список объектов в базу данных (обычно только 1 запрос, независимо от того, сколько объектов) и возвращает созданные объекты в виде списка в том же порядке, что и указано:

>>> objs = Entry.objects.bulk_create(
...     [
...         Entry(headline="This is a test"),
...         Entry(headline="This is only a test"),
...     ]
... )

Следует упомянуть ряд оговорок:

• Метод модели save() не будет вызван, и сигналы pre_save и post_save не будут вызваны.

• Не работает с дочерними моделями при multi-table наследовании.

• Если первичный ключ модели представляет собой AutoField или имеет значение db_default, а ignore_conflicts имеет значение False, атрибут первичного ключа можно получить только в определенных базах данных (в настоящее время PostgreSQL, MariaDB и SQLite 3.35+). В других базах данных он не будет установлен.

• Не работает со связями многое-ко-многим.

• Он преобразует objs в список, который полностью оценивает objs, если это генератор. Приведение позволяет проверять все объекты, чтобы в первую очередь можно было вставить любые объекты с первичным ключом, установленным вручную. Если вы хотите вставлять объекты пакетами, не оценивая весь генератор сразу, вы можете использовать этот метод, если у объектов нет первичных ключей, установленных вручную:

  from itertools import islice
  
  batch_size = 100
  objs = (Entry(headline="Test %s" % i) for i in range(1000))
  while True:
      batch = list(islice(objs, batch_size))
      if not batch:
          break
      Entry.objects.bulk_create(batch, batch_size)
  

Параметр batch_size контролирует, сколько объектов создается в одном запросе. По умолчанию создается столько объектов в одном пакете, сколько позволяет база данных. (SQLite и Oracle ограничивают количество параметров в запросе.)

В базах данных, которые его поддерживают (все, кроме Oracle), установка для параметра ignore_conflicts значения True указывает базе данных игнорировать неудачи при вставке любых строк, которые не соответствуют ограничениям, таким как повторяющиеся уникальные значения.

В базах данных, которые его поддерживают (все, кроме Oracle), установка параметра update_conflicts в значение True сообщает базе данных обновлять update_fields, когда вставка строки не удалась из-за конфликтов. В PostgreSQL и SQLite, помимо update_fields, необходимо предоставить список unique_fields, которые могут конфликтовать.

Включение параметра ignore_conflicts отключает установку первичного ключа для каждого экземпляра модели (если база данных обычно его поддерживает).

update¶

bulk_update(objs, fields, batch_size=None)¶

abulk_update(objs, fields, batch_size=None)¶

Асинхронная версия: abulk_update()

Этот метод эффективно обновляет данные поля в предоставленных экземплярах модели, обычно с помощью одного запроса, и возвращает количество обновленных объектов:

>>> objs = [
...     Entry.objects.create(headline="Entry 1"),
...     Entry.objects.create(headline="Entry 2"),
... ]
>>> objs[0].headline = "This is entry 1"
>>> objs[1].headline = "This is entry 2"
>>> Entry.objects.bulk_update(objs, ["headline"])
2

QuerySet.update() используется для сохранения изменений, поэтому это более эффективно, чем перебор списка моделей и вызов save() для каждой из них, но здесь есть несколько предостережений:

• Вы не можете обновить первичный ключ модели.

• Метод модели save() не будет вызван, и сигналы pre_save и post_save не будут вызваны.

• При обновлении большого количества столбцов в большом количестве строк сгенерированный SQL может быть очень большим. Избегайте этого, указав подходящий batch_size.

• При обновлении большого количества объектов имейте в виду, что Bulk_update() подготавливает все предложения WHEN для каждого объекта во всех пакетах перед выполнением каких-либо запросов. Это может потребовать больше памяти, чем ожидалось. Чтобы уменьшить использование памяти, вы можете использовать такой подход:

  from itertools import islice
  
  batch_size = 100
  ids_iter = range(1000)
  while ids := list(islice(ids_iter, batch_size)):
      batch = Entry.objects.filter(ids__in=ids)
      for entry in batch:
          entry.headline = f"Updated headline {entry.pk}"
      Entry.objects.bulk_update(batch, ["headline"], batch_size=batch_size)
  

• Обновление полей, определенных в предках многотабличного наследования, потребует дополнительного запроса для каждого предка.

• Если отдельный пакет содержит дубликаты, только первый экземпляр в этом пакете приведет к обновлению.

• Количество обновленных объектов, возвращаемых функцией, может быть меньше количества переданных объектов. Это может быть связано с дублированием переданных объектов, которые обновляются в одном и том же пакетном режиме, или в условиях гонки, в результате чего объекты больше не присутствуют в базе данных.

Параметр batch_size указывает количество объектов, которые будут созданы за один запрос. По умолчанию все объекты создаются одним запросом, кроме SQLite, где есть ограничение на количество переменных в запросе равное 999.

count¶

count()¶

acount()¶

Асинхронная версия: acount()

Возвращает количество записей в базе данных отвечающем запросу QuerySet. Метод count() никогда не вызывает исключение.

Например:

# Returns the total number of entries in the database.
Entry.objects.count()

# Returns the number of entries whose headline contains 'Lennon'
Entry.objects.filter(headline__contains="Lennon").count()

Метод count() использует SELECT COUNT(*), так что всегда используйте метод count() вместо загрузки всех записей в объекты Python и вызов len() над результатом (если вам кончено в любом случае не понадобится загружать их далее, в таком случае len() будет быстрее).

Обратите внимание, если вам необходимо количество объектов в QuerySet и сами объекты (например, цикл по ним), возможно эффективнее использовать len(queryset), чтобы избежать дополнительного запроса при выполнении count().

Если набор запросов уже полностью получен, функция count() будет использовать эту длину, а не выполнять дополнительный запрос к базе данных.

in_bulk¶

in_bulk(id_list=None, *, field_name='pk')¶

ain_bulk(id_list=None, *, field_name='pk')¶

Асинхронная версия: ain_bulk()

Принимает список значений полей («id_list») и «field_name» для этих значений и возвращает словарь, сопоставляющий каждое значение с экземпляром объекта с заданным значением поля. Никакие исключения django.core.Exceptions.ObjectDoesNotExist никогда не будут создаваться in_bulk; то есть любое значение id_list, не соответствующее ни одному экземпляру, будет просто игнорироваться. Если id_list не указан, возвращаются все объекты в наборе запросов. field_name должно быть уникальным полем или отдельным полем (если в distinct() указано только одно поле). field_name по умолчанию использует первичный ключ.

Например:

>>> Blog.objects.in_bulk([1])
{1: <Blog: Beatles Blog>}
>>> Blog.objects.in_bulk([1, 2])
{1: <Blog: Beatles Blog>, 2: <Blog: Cheddar Talk>}
>>> Blog.objects.in_bulk([])
{}
>>> Blog.objects.in_bulk()
{1: <Blog: Beatles Blog>, 2: <Blog: Cheddar Talk>, 3: <Blog: Django Weblog>}
>>> Blog.objects.in_bulk(["beatles_blog"], field_name="slug")
{'beatles_blog': <Blog: Beatles Blog>}
>>> Blog.objects.distinct("name").in_bulk(field_name="name")
{'Beatles Blog': <Blog: Beatles Blog>, 'Cheddar Talk': <Blog: Cheddar Talk>, 'Django Weblog': <Blog: Django Weblog>}

При передаче в in_bulk() пустого списка будет получен пустой словарь.

iterator¶

iterator(chunk_size=None)¶

aiterator(chunk_size=None)¶

Асинхронная версия: aiterator()

Оценивает QuerySet (выполняя запрос) и возвращает итератор (см. PEP 234) по результатам или асинхронный итератор (см. PEP 492), если вы вызываете его асинхронную версию aiterator.

QuerySet обычно кэширует свои результаты внутри себя, чтобы повторные вычисления не приводили к дополнительным запросам. Напротив, iterator() будет читать результаты напрямую, без какого-либо кэширования на уровне QuerySet (внутренне итератор по умолчанию вызывает iterator() и кэширует возвращаемое значение). Для QuerySet, который возвращает большое количество объектов, к которым вам нужно получить доступ только один раз, это может привести к повышению производительности и значительному сокращению памяти.

Заметим, что использование iterator() для QuerySet, который уже был вычислен, приведет к повторному вычислению и выполнению запроса к базе данных.

iterator() совместим с предыдущими вызовами prefetch_related(), если задан chunk_size. Большие значения потребуют меньшего количества запросов для выполнения предварительной выборки за счет большего использования памяти.

В некоторых базах данных (например, Oracle, SQLite <https://www.sqlite.org/limits.html#max_variable_number>`_) максимальное количество терминов в предложении SQL ``IN может быть ограничено. Следовательно, следует использовать значения ниже этого предела. (В частности, при предварительной выборке по двум или более отношениям размер фрагмента должен быть достаточно мал, чтобы ожидаемое количество результатов для каждого предварительно выбранного отношения все еще оставалось ниже предела.)

Пока QuerySet не выполняет предварительную выборку каких-либо связанных объектов, отсутствие значения для chunk_size приведет к тому, что Django будет использовать неявное значение по умолчанию 2000.

В зависимости от серверной части базы данных результаты запроса будут либо загружены все сразу, либо переданы из базы данных с помощью курсоров на стороне сервера.

latest¶

latest(*fields)¶

alatest(*fields)¶

Асинхронная версия: alatest()

Возвращает последний объект, используя значение из поля даты указанного параметром field_name.

Этот пример возвращает последний объект Entry в таблице по полю pub_date:

Entry.objects.latest("pub_date")

Вы также можете выбрать последнюю версию на основе нескольких полей. Например, чтобы выбрать Запись с самой ранней expire_date, когда две записи имеют одинаковую pub_date:

Entry.objects.latest("pub_date", "-expire_date")

Знак минус в '-expire_date' означает сортировку expire_date в нисходящем порядке. Поскольку latest() получает последний результат, выбирается Entry с самой ранней expire_date.

Если в Meta модели определен get_latest_by, вы можете не указывать аргумент field_name при вызове earliest() или latest(). Django будет использовать поле указанное в get_latest_by как значение по-умолчанию.

Подобно get(), earliest() и latest(), поднимают DoesNotExist, если нет объекта с заданными параметрами.

Заметим что earliest() и latest() существует исключительно для удобства и читаемости.

Entry.objects.filter(pub_date__isnull=False).latest("pub_date")

earliest¶

earliest(*fields)¶

aearliest(*fields)¶

Асинхронная версия: aearliest()

Работает как и latest() только наоборот.

first¶

first()¶

afirst()¶

Асинхронная версия: afirst()

Возвращает первый объект из выборки, или None если ничего не найдено. Если для QuerySet не указана сортировка, он будет отсортирован по первичному ключу.

Например:

p = Article.objects.order_by("title", "pub_date").first()

first() создан просто для удобства и аналогичен следующему коду:

try:
    p = Article.objects.order_by("title", "pub_date")[0]
except IndexError:
    p = None

последний()¶

last()¶

alast()¶

Асинхронная версия: alast()

Работает как first(), но возвращает последний объект в наборе запросов.

aggregate¶

aggregate(*args, **kwargs)¶

aaggregate(*args, **kwargs)¶

Асинхронная версия: aaggregate()

Возвращает словарь агрегированных значений (среднее значение, сума и др.) вычисленных для QuerySet. Каждый аргумент aggregate() определяет значение, которые будет включено в возвращаемый словарь.

Функции агрегации Django описаны в Функции агрегации. Так как они являются выражениями запроса, вы можете комбинировать функции агрегации друг с другом или значениями, чтобы создать сложные агрегации.

Агрегация, указанная с помощью именованного аргумента, использует имя аргумента как название ключа в возвращаемом словаре. Для анонимных аргументов названия ключей будут созданы из названия функции агрегации и названия поля модели используемого в агрегации данных. Сложные агрегации не могут использовать анонимные аргументы и вы должны указать именованные.

Например, когда вы работаете с записями в блоге, вам может потребоваться узнать количество авторов, разместивших записи в блоге:

>>> from django.db.models import Count
>>> Blog.objects.aggregate(Count("entry__authors"))
{'entry__authors__count': 16}

Используя аргумент ключевого слова для указания агрегатной функции, вы можете управлять именем возвращаемого агрегатного значения:

>>> Blog.objects.aggregate(number_of_authors=Count("entry__authors"))
{'number_of_authors': 16}

Для углубленного изучения агрегации смотрите раздел про агрегацию.

exists¶

exists()¶

aexists()¶

Асинхронная версия: aexists()

Возвращает True если QuerySet содержит какой-либо результат, иначе - False. Выполняет на столько простой и быстрый запрос, на сколько это возможно, почти идентичный обычному запросу QuerySet.

exists() полезен для поиска, связанного с существованием любых объектов в QuerySet, особенно в контексте большого QuerySet.

Чтобы узнать, содержит ли набор запросов какие-либо элементы:

if some_queryset.exists():
    print("There is at least one object in some_queryset")

Это будет быстрее чем:

if some_queryset:
    print("There is at least one object in some_queryset")