Справочник по API QuerySet¶

filter()¶

filter(*args, **kwargs)¶

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

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

If you need to execute more complex queries (for example, queries with OR statements), you can use Q objects (*args).

exclude()¶

exclude(*args, **kwargs)¶

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

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

Этот пример исключает все записи, чье pub_date позже, чем 2005-1-3 И чьи 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 позже, чем 2005-1-3 ИЛИ с заголовком «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'

Обратите внимание, что второй пример является более ограниченным.

If you need to execute more complex queries (for example, queries with OR statements), you can use Q objects (*args).

annotate()¶

annotate(*args, **kwargs)¶

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

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

Функции агрегации, предоставляемые Django, описаны в Функции агрегации ниже.

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

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

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

Модель Blog не определяет атрибут 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()¶

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 модели. Вы можете переопределить это для каждого QuerySet, используя метод 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), которые управляют сортировкой нулевых значений.

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

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. Это преобразуется в SQL-запрос SELECT DISTINCT ON. Вот в чем разница. Для обычного вызова 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() также принимает необязательные именованные аргументы, **expressions, которые передаются через 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() после вызова extra(), любые поля, определенные аргументом select в extra(), должны быть явно включены в вызов values(). При любом вызов extra() после вызова values() лишние выбранные поля будут игнорироваться.

• Calling only() and defer() after values() doesn’t make sense, so doing so will raise a 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(), за исключением того, что вместо возврата словарей он возвращает кортежи при повторении. Каждый кортеж содержит значение из соответствующего поля или выражения, переданное в вызов values_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, это будет означать, что возвращаемые результаты будут единичными значениями, а не кортежем. Пример должен прояснить разницу:

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

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

Аналогично, при запросе обратного внешнего ключа, 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", "week", либо "day". Каждый объект datetime.date в списке результатов «усекается» до заданного type.

• "year" возвращает список всех различных значений года.
• "month" возвращает список всех различных значений года/месяца.
• "week" возвращает список всех различных значений года/недели. Все даты будут понедельником.
• "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, is_dst=None)¶

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

field_name` должно быть именем ``DateTimeField вашей модели.

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

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

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

is_dst указывает, должен ли pytz интерпретировать несуществующие и неоднозначные даты в летнее время. По умолчанию (когда is_dst=None), pytz выдает исключение для таких datetime.

none()¶

none()¶

Calling none() will create a queryset that never returns any objects and no query will be executed when accessing the results. A qs.none() queryset is an instance of EmptyQuerySet.

Примеры:

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

all()¶

all()¶

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

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

union()¶

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

In addition, only LIMIT, OFFSET, COUNT(*), ORDER BY, and specifying columns (i.e. slicing, count(), exists(), order_by(), and values()/values_list()) are allowed on the resulting QuerySet. Further, databases place restrictions on what operations are allowed in the combined queries. For example, most databases don’t allow LIMIT or OFFSET in the combined queries.

intersection()¶

intersection(*other_qs)¶

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

>>> qs1.intersection(qs2, qs3)

Смотрите union() для некоторых ограничений.

difference()¶

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() с любым набором запросов объектов:

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() не важен. Эти наборы запросов эквивалентны:

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 в списке полей, переданных select_related - то есть вы можете пройти в OneToOneField и вернуться к объекту, для которого определено поле. Вместо указания имени поля используйте related_name для поля в связанном объекте.

Могут быть ситуации, когда вы хотите вызвать select_related() с большим количеством связанных объектов, или когда вы не знаете всех отношений. В этих случаях можно вызывать select_related() без аргументов. Он будет следовать за всеми ненулевыми внешними ключами, которые он может найти - должны быть указаны внешние ключи, которые могут иметь значение null. Это не рекомендуется в большинстве случаев, так как это может сделать базовый запрос более сложным и вернуть больше данных, чем фактически необходимо.

Если вам нужно очистить список связанных полей, добавленных прошлыми вызовами 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 работает путем создания соединения (join) SQL и включения полей связанного объекта в оператор SELECT. По этой причине select_related получает связанные объекты в одном запросе к базе данных. Тем не менее, чтобы избежать гораздо большего результирующего набора, который мог бы возникнуть в результате объединения через отношение „many“, select_related ограничен однозначными отношениями - внешним ключом и один-к-одному.

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

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

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() выполнит запрос к таблице Toppings для каждого элемента в Pizza QuerySet.

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

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

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

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

Дополнительные запросы в prefetch_related() выполняются после того, как QuerySet начал оцениваться и был выполнен первичный запрос.

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

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

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

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

>>> Restaurant.objects.prefetch_related('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 следует отметить одно отличие, заключающееся в том, что объекты, созданные с помощью запроса, могут совместно использоваться различными объектами, с которыми они связаны, т.е. один экземпляр модели Python может появляться в нескольких точках дерева объектов, которые вернулись. Это обычно происходит с отношениями внешних ключей. Как правило, такое поведение не будет проблемой, и фактически сэкономит как память, так и время процессора.

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

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

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

В своей простейшей форме Prefetch эквивалентен традиционным поискам на основе строк:

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

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

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

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

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

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

>>> # 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!

По определению, эти дополнительные поиски могут не переноситься на разные механизмы баз данных (потому что вы явно пишете код 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;
  

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

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

  Это будет работать, например:

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

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

• where / tables

  Вы можете определить явные выражения SQL WHERE - возможно, для выполнения неявных объединений - используя where. Вы можете вручную добавить таблицы в предложение SQL FROM, используя tables.

  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, если вы указываете таблицы, которые уже используются в запросе. Когда вы добавляете дополнительные таблицы с помощью параметра tables, Django предполагает, что вы хотите, чтобы таблица включала дополнительное время, если оно уже включено. Это создает проблему, так как имя таблицы будет иметь псевдоним. Если таблица появляется в операторе SQL несколько раз, второе и последующие вхождения должны использовать псевдонимы, чтобы база данных могла различать их. Если вы ссылаетесь на дополнительную таблицу, которую вы добавили в дополнительный параметр where, это приведет к ошибкам.

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

• order_by

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

  Например:

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

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

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

• params

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

  Пример:

  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() для извлечения связанных моделей, вы не должны откладывать загрузку поля, соединяющего основную модель с связанной, это приведет к ошибке.

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()¶

only(*fields)¶

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

If you have a model where almost all the fields need to be deferred, using only() to specify the complementary set of fields can result in simpler code.

Предположим, у вас есть модель с полями 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(), также является ошибкой.

Как и в случае с 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)¶

Возвращает набор запросов, который блокирует строки до конца транзакции, генерируя оператор 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:
        ...

Когда набор запросов выполняется (в данном случае for entry in entries), все совпадающие записи будут заблокированы до конца блока транзакции, что означает, что другие транзакции не смогут изменить или получить блокировки для них.

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

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

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

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

Вы не можете использовать select_for_update() для обнуляемых отношений:

>>> 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: ...)>, ...]>

The postgresql, oracle, and mysql database backends support select_for_update(). However, MariaDB only supports the nowait argument, MariaDB 10.6+ also supports the skip_locked argument, and MySQL 8.0.1+ supports the nowait, skip_locked, and of arguments. The no_key argument is only supported on PostgreSQL.

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

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

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

raw()¶

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

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

Смотрите Выполнение необработанных SQL-запросов для получения дополнительной информации.

AND (&)¶

Объединяет два QuerySet’а, используя оператор SQL AND.

Следующее эквивалентно:

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

SQL-эквивалент:

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

OR (|)¶

Объединяет два 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

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

XOR (^)¶

Combines two QuerySets using the SQL XOR operator.

Следующее эквивалентно:

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=(
    (CASE WHEN x THEN 1 ELSE 0 END) +
    (CASE WHEN y THEN 1 ELSE 0 END) +
    ...
    (CASE WHEN z THEN 1 ELSE 0 END) +
)

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(*args, **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)¶

Asynchronous version: 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()

Здесь, при одновременных запросах, могут быть сделаны многочисленные попытки сохранить Person с одинаковыми параметрами. Чтобы избежать этого состояния гонки, приведенный выше пример можно переписать с помощью 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 objects. Например, чтобы получить Роберта или Боба Марли, если таковой существует, и создать последний в противном случае:

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() вызовет 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 есть какие-либо вызываемые элементы, выполните их. Как уже упоминалось выше, это упрощение алгоритма, который используется, но он содержит все соответствующие детали. Внутренняя реализация имеет больше проверок ошибок, чем эта, и обрабатывает некоторые дополнительные граничные условия; если вам интересно, прочитайте код.

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

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

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

Finally, a word on using get_or_create() in Django views. Please make sure to use it only in POST requests unless you have a good reason not to. GET requests shouldn’t have any effect on data. Instead, use POST whenever a request to a page has a side effect on your data. For more, see Safe methods in the HTTP spec.

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, **kwargs)¶

aupdate_or_create(defaults=None, **kwargs)¶

Asynchronous version: aupdate_or_create()

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

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

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

Это просто сокращение для упрощенного кода. Например:

defaults = {'first_name': 'Bob'}
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(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'},
)

For a detailed description of how names passed in kwargs are resolved, see 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()

This method inserts the provided list of objects into the database in an efficient manner (generally only 1 query, no matter how many objects there are), and returns created objects as a list, in the same order as provided:

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

Это имеет ряд предостережений, хотя:

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

• Он не работает с дочерними моделями в сценарии наследования нескольких таблиц.

• If the model’s primary key is an AutoField, the primary key attribute can only be retrieved on certain databases (currently PostgreSQL, MariaDB 10.5+, and SQLite 3.35+). On other databases, it will not be set.

• Это не работает с отношениями «многие ко многим».

• Он бросает 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, где по умолчанию используется не более 999 переменных на запрос.

On databases that support it (all but Oracle), setting the ignore_conflicts parameter to True tells the database to ignore failure to insert any rows that fail constraints such as duplicate unique values.

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

Enabling the ignore_conflicts or update_conflicts parameter disable setting the primary key on each model instance (if the database normally support it).

bulk_update()¶

bulk_update(objs, fields, batch_size=None)¶

abulk_update(objs, fields, batch_size=None)¶

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

This method efficiently updates the given fields on the provided model instances, generally with one query, and returns the number of objects updated:

>>> 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.
• Обновление полей, определенных в предках наследования нескольких таблиц, повлечет за собой дополнительный запрос для предка.
• When an individual batch contains duplicates, only the first instance in that batch will result in an update.
• Количество обновленных объектов, возвращаемых функцией, может быть меньше, чем количество переданных объектов. Это может быть вызвано дублированием переданных объектов, которые обновляются в одной и той же партии, или условиями гонки, когда объекты больше не присутствуют в базе данных.

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

count()¶

count()¶

acount()¶

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

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

Пример:

# 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()

Takes a list of field values (id_list) and the field_name for those values, and returns a dictionary mapping each value to an instance of the object with the given field value. No django.core.exceptions.ObjectDoesNotExist exceptions will ever be raised by in_bulk; that is, any id_list value not matching any instance will simply be ignored. If id_list isn’t provided, all objects in the queryset are returned. field_name must be a unique field or a distinct field (if there’s only one field specified in distinct()). field_name defaults to the primary key.

Пример:

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

A QuerySet typically caches its results internally so that repeated evaluations do not result in additional queries. In contrast, iterator() will read results directly, without doing any caching at the QuerySet level (internally, the default iterator calls iterator() and caches the return value). For a QuerySet which returns a large number of objects that you only need to access once, this can result in better performance and a significant reduction in memory.

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

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

В некоторых базах данных (например, Oracle, SQLite) максимальное количество терминов в предложении SQL IN может быть ограничено. Поэтому следует использовать значения ниже этого предела. (В частности, при предварительной выборке по двум или более отношениям, chunk_size должно быть достаточно маленьким, чтобы ожидаемое количество результатов для каждого предварительно выбранного отношения все еще было ниже предела).

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

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

latest()¶

latest(*fields)¶

alatest(*fields)¶

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

Возвращает последний объект в таблице на основе заданных полей.

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

Entry.objects.latest('pub_date')

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

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

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

Если ваша модель Meta указывает get_latest_by, вы можете опустить любые аргументы для earliest() или latest(). Поля, указанные в 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()¶