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

filter()¶

filter(**kwargs)¶

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

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

Если вам нужно выполнить более сложные запросы (например, запросы с помощью операторов OR), вы можете использовать Q objects.

exclude()¶

exclude(**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'

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

Если вам нужно выполнить более сложные запросы (например, запросы с помощью операторов OR), вы можете использовать Q objects.

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

Подробное обсуждение агрегации смотрите в руководство по агрегации.

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), которые управляют сортировкой нулевых значений.

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

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

• Объединение преобразований и агрегирования требует использования двух вызовов 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)¶

Возвращает 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.

none()¶

none()¶

Вызов none() создаст набор запросов, который никогда не вернет никаких объектов, и при доступе к результатам запрос не будет выполнен. Набор запросов qs.none() является экземпляром 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() и diff() возвращают экземпляры модели типа первого 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')

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

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.all().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-запроса. Всегда профилируйте то, что используете!

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

Вы можете использовать объект 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))
  

>>> 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. Так как select_params является последовательностью, а атрибут select является словарем, требуется некоторая осторожность, чтобы параметры были правильно сопоставлены с дополнительными частями select. В этой ситуации вы должны использовать collections.OrderedDict для значения select, а не просто обычный словарь Python.

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

  Blog.objects.extra(
      select=OrderedDict([('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.all().defer('f2')

only()¶

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 and body immediately (only() replaces any
# existing set of fields).
Entry.objects.defer("body").only("headline", "body")

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

Использование only() и пропуск поля, запрошенного с использованием select_related(), также является ошибкой.

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

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

Вы не можете использовать 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: ...)>, ...]>

В настоящее время бэкэнды баз данных postgresql, oracle и mysql поддерживают select_for_update(). Однако MySQL не поддерживает аргумент of, а аргументы nowait и skip_locked поддерживаются только в MySQL 8.0.1+.

Передача nowait=True, skip_locked=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=None, translations=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

get()¶

get(**kwargs)¶

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

get() вызовет MultipleObjectsReturned, если найдено более одного объекта. Исключение MultipleObjectsReturned является атрибутом класса модели.

get() вызывает исключение DoesNotExist, если объект не найден для заданных параметров. Это исключение является атрибутом класса модели. Пример:

Entry.objects.get(id='foo') # raises Entry.DoesNotExist

Исключение DoesNotExist наследуется от django.core.exceptions.ObjectDoesNotExist, поэтому вы можете указывать несколько объектов DoesNotExist исключений. Пример:

from django.core.exceptions import ObjectDoesNotExist
try:
    e = Entry.objects.get(id=3)
    b = Blog.objects.get(id=1)
except ObjectDoesNotExist:
    print("Either the entry or blog doesn't exist.")

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

entry = Entry.objects.filter(...).exclude(...).get()

create()¶

create(**kwargs)¶

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

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

Удобный метод для поиска объекта с указанным 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.

Наконец, слово об использовании 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, **kwargs)¶

Удобный метод для обновления объекта с указанным 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'},
)

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

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

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

bulk_create()¶

bulk_create(objs, batch_size=None, ignore_conflicts=False)¶

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

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

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

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

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

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

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

• Он бросает 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 переменных на запрос.

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

bulk_update()¶

bulk_update(objs, fields, batch_size=None)¶

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

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

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

• Вы не можете обновить первичный ключ модели.
• Метод save() каждой модели не вызывается, и сигналы pre_save и post_save не отправлено.
• При обновлении большого количества столбцов в большом количестве строк сгенерированный SQL может быть очень большим. Избегайте этого, указав подходящий batch_size.
• Обновление полей, определенных в предках наследования нескольких таблиц, повлечет за собой дополнительный запрос для предка.
• Если objs содержит дубликаты, обновляется только первый.

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

count()¶

count()¶

Возвращает целое число, представляющее количество объектов в базе данных, соответствующих 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().

in_bulk()¶

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

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

Если вы передадите in_bulk() пустой список, вы получите пустой словарь.

iterator()¶

iterator(chunk_size=2000)¶

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

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

Кроме того, использование iterator() приводит к игнорированию предыдущих вызовов prefetch_related(), поскольку эти две оптимизации не имеют смысла вместе.

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

latest()¶

latest(*fields)¶

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

Этот пример возвращает последний 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)¶

Работает также как и latest() за исключением изменения направления.

first()¶

first()¶

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

Пример:

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

last()¶

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

aggregate()¶

aggregate(*args, **kwargs)¶

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

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

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

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

>>> from django.db.models import Count
>>> q = Blog.objects.aggregate(Count('entry'))
{'entry__count': 16}

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

>>> q = Blog.objects.aggregate(number_of_entries=Count('entry'))
{'number_of_entries': 16}

Подробное обсуждение агрегации смотрите в руководство по агрегации.

exists()¶

exists()¶

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

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

Наиболее эффективный метод определения, является ли модель с уникальным полем (например, primary_key) членом QuerySet, это:

entry = Entry.objects.get(pk=123)
if some_queryset.filter(pk=entry.pk).exists():
    print("Entry contained in queryset")

Который будет быстрее, чем следующий, который требует оценки и итерации по всему набору запросов:

if entry in some_queryset:
   print("Entry contained in 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")

… но не в значительной степени (следовательно, для повышения эффективности требуется большой набор запросов).

Кроме того, если some_queryset еще не был проанализирован, но вы знаете, что это произойдет в какой-то момент, то использование some_queryset.exists() сделает более общую работу (один запрос для проверки существования плюс дополнительный для последующего извлечения результатов), а не просто bool(some_queryset), который извлекает результаты и затем проверяет, были ли какие-либо возвращены.

update()¶

update(**kwargs)¶

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

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

>>> Entry.objects.filter(pub_date__year=2010).update(comments_on=False)

(Предполагается, что ваша модель Entry имеет поля pub_date и comments_on.)

Вы можете обновить несколько полей - нет ограничений на их количество. Например, здесь мы обновляем поля comments_on и headline:

>>> Entry.objects.filter(pub_date__year=2010).update(comments_on=False, headline='This is old')

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

>>> Entry.objects.update(blog__name='foo') # Won't work!

Фильтрация на основе связанных полей все еще возможна, хотя:

>>> Entry.objects.filter(blog__id=1).update(comments_on=True)

Вы не можете вызвать update() для QuerySet, у которого был взят фрагмент или который больше не может быть отфильтрован.

Метод update() возвращает количество затронутых строк:

>>> Entry.objects.filter(id=64).update(comments_on=True)
1

>>> Entry.objects.filter(slug='nonexistent-slug').update(comments_on=True)
0

>>> Entry.objects.filter(pub_date__year=2010).update(comments_on=False)
132

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

e = Entry.objects.get(id=10)
e.comments_on = False
e.save()

…сделайте это:

Entry.objects.filter(id=10).update(comments_on=False)

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

Наконец, следует понимать, что update() выполняет обновление на уровне SQL и, таким образом, не вызывает никаких методов save() в ваших моделях и не генерирует pre_save или post_save (которые являются следствием вызова Model.save()). Если вы хотите обновить группу записей для модели, имеющей пользовательский метод save(), выполните их в цикле и вызовите save(), как тут:

for e in Entry.objects.filter(pub_date__year=2010):
    e.comments_on = False
    e.save()

delete()¶

delete()¶

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

delete() применяется мгновенно. Вы не можете вызвать delete() для QuerySet, у которого был взят фрагмент или который больше не может быть отфильтрован.

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

>>> b = Blog.objects.get(pk=1)

# Delete all the entries belonging to this Blog.
>>> Entry.objects.filter(blog=b).delete()
(4, {'weblog.Entry': 2, 'weblog.Entry_authors': 2})

По умолчанию класс Django ForeignKey эмулирует ограничение SQL ON DELETE CASCADE - другими словами, любые объекты с внешними ключами, указывающими на объекты, которые будут удалены, будут удалены вместе с ними. Например:

>>> blogs = Blog.objects.all()

# This will delete all Blogs and all of their Entry objects.
>>> blogs.delete()
(5, {'weblog.Blog': 1, 'weblog.Entry': 2, 'weblog.Entry_authors': 2})

Это каскадное поведение настраивается с помощью аргумента on_delete для ForeignKey.

Метод delete() выполняет массовое удаление и не вызывает никаких методов delete() в ваших моделях. Однако он генерирует сигналы pre_delete и post_delete для всех удаленных объектов (включая каскадные удаления).

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

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

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

as_manager()¶

classmethod as_manager()¶

Метод класса, который возвращает экземпляр Manager с копией методов QuerySet. Смотрите Создание менеджера с помощью методов QuerySet для более подробной информации.

explain()¶

explain(format=None, **options)¶

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

Например, при использовании PostgreSQL:

>>> print(Blog.objects.filter(title='My Blog').explain())
Seq Scan on blog  (cost=0.00..35.50 rows=10 width=12)
  Filter: (title = 'My Blog'::bpchar)

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

explain() поддерживается всеми встроенными базами данных базы данных, кроме Oracle, потому что реализация там не проста.

Параметр format изменяет формат вывода по умолчанию для баз данных, обычно на основе текста. PostgreSQL поддерживает 'TEXT', 'JSON', 'YAML' и 'XML'. MySQL поддерживает 'TEXT' (также называемый 'TRADITIONAL') и 'JSON'.

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

>>> print(Blog.objects.filter(title='My Blog').explain(verbose=True))
Seq Scan on public.blog  (cost=0.00..35.50 rows=10 width=12) (actual time=0.004..0.004 rows=10 loops=1)
  Output: id, title
  Filter: (blog.title = 'My Blog'::bpchar)
Planning time: 0.064 ms
Execution time: 0.058 ms

В некоторых базах данных флаги могут привести к выполнению запроса, что может отрицательно повлиять на вашу базу данных. Например, флаг ANALYZE в PostgreSQL может привести к изменению данных, если есть триггеры или если вызывается функция, даже для запроса SELECT.

exact¶

Точное совпадение. Если значение, предоставленное для сравнения, равно None, оно будет интерпретировано как SQL NULL (подробнее см. isnull).

Примеры:

Entry.objects.get(id__exact=14)
Entry.objects.get(id__exact=None)

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

SELECT ... WHERE id = 14;
SELECT ... WHERE id IS NULL;

iexact¶

Точное совпадение без учета регистра. Если значение, предоставленное для сравнения, равно None, оно будет интерпретировано как SQL NULL (подробнее смотрите isnull).

Пример:

Blog.objects.get(name__iexact='beatles blog')
Blog.objects.get(name__iexact=None)

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

SELECT ... WHERE name ILIKE 'beatles blog';
SELECT ... WHERE name IS NULL;

Обратите внимание, что первый запрос будет соответствовать 'Beatles Blog', 'beatles blog', 'BeAtLes BLoG' и т.д.

contains¶

Чувствительная к регистру проверка вхождения.

Пример:

Entry.objects.get(headline__contains='Lennon')

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

SELECT ... WHERE headline LIKE '%Lennon%';

Обратите внимание, что это будет соответствовать заголовку 'Lennon honored today' но не 'lennon honored today'.

icontains¶

Нечувствительное к регистру проверка вхождения.

Пример:

Entry.objects.get(headline__icontains='Lennon')

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

SELECT ... WHERE headline ILIKE '%Lennon%';

in¶

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

Примеры:

Entry.objects.filter(id__in=[1, 3, 4])
Entry.objects.filter(headline__in='abc')

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

SELECT ... WHERE id IN (1, 3, 4);
SELECT ... WHERE headline IN ('a', 'b', 'c');

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

inner_qs = Blog.objects.filter(name__contains='Cheddar')
entries = Entry.objects.filter(blog__in=inner_qs)

Этот набор запросов будет оцениваться как оператор подвыбора:

SELECT ... WHERE blog.id IN (SELECT id FROM ... WHERE NAME LIKE '%Cheddar%')

Если вы передаете QuerySet, полученный в результате values() или values_list(), в качестве значения для поиска __in, вам нужно убедиться, что вы извлекаете только одно поле в результат. Например, это будет работать (фильтрация по именам блогов):