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

filter()¶

filter( ** kwargs ) ¶

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

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

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

exclude()¶

exclude( ** kwargs ) ¶

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

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

В этом примере исключаются все записи, которые pub_dateстарше 2005-1-3 И у которых headlineесть «Привет»:

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 ИЛИ с заголовком «Привет»:

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( * аргументы , ** 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( * аргументы , ** 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( * поля ) ¶

По умолчанию результаты, возвращаемые a 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( * поля ) ¶

Возвращает новый, QuerySetкоторый используется в своем SQL-запросе. Это исключает повторяющиеся строки из результатов запроса.SELECT DISTINCT

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

Только в PostgreSQL вы можете передавать позиционные аргументы ( *fields), чтобы указать имена полей, к которым DISTINCTдолжен применяться. Это переводится в SQL-запрос. Вот в чем разница. При обычном вызове база данных сравнивает каждое поле в каждой строке, чтобы определить, какие строки являются разными. Для вызова с указанными именами полей база данных будет сравнивать только указанные имена полей.SELECT DISTINCT ONdistinct()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( * поля , ** выражения ) ¶

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

Несколько тонкостей, о которых стоит упомянуть:

• Если у вас есть поле с именем fooa 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()не имеет смысла, так что это поднимет 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( поле , вид , порядок = '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( имя_поля , вид , порядок = 'ASC' , tzinfo = Нет , is_dst = Нет ) ¶

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

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

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

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

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

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

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подкласса). Это может быть полезно в ситуациях, когда вы, возможно, захотите передать либо менеджер модели, либо a QuerySetи выполнить дальнейшую фильтрацию результата. После вызова all()любого объекта вам определенно придется QuerySetпоработать.

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

union()¶

union( * Other_qs , все = False ) ¶

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

>>> qs1.union(qs2, qs3)

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

union(), intersection(), И difference()возвращение модель экземпляры типа первый , QuerySetдаже если аргументы QuerySets других моделей. Передача разных моделей работает до тех пор, пока SELECTсписок один и тот же во всех QuerySets (по крайней мере, типы, имена не имеют значения, если типы находятся в одном порядке). В таких случаях вы должны использовать имена столбцов из первых 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 BYcount()exists()order_by()values()values_list()QuerySetLIMITOFFSET

intersection()¶

intersection( * other_qs ) ¶

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

>>> qs1.intersection(qs2, qs3)

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

difference()¶

difference( * other_qs ) ¶

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

>>> qs1.difference(qs2, qs3)

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

select_related()¶

select_related( * поля ) ¶

Возвращает объект, 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().

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

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

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

>>> without_relations = queryset.select_related(None)

Объединение select_relatedвызовов работает аналогично другим методам, то есть эквивалентно .select_related('foo', 'bar')select_related('foo').select_related('bar')

prefetch_related()¶

prefetch_related( * поиск ) ¶

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

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

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

prefetch_related, с другой стороны, выполняет отдельный поиск для каждой связи и выполняет «соединение» в Python. Это позволяет выполнять предварительную выборку объектов типа «многие ко многим» и «многие к одному», что невозможно сделать с использованием select_related, помимо внешнего ключа и отношений «один к одному», которые поддерживаются select_related. Он также поддерживает предварительную выборку GenericRelationи GenericForeignKey, однако, должен ограничиваться однородным набором результатов. Например, предварительная выборка объектов, на которые ссылается a, 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')

Это подразумевает a 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')

Это принесет лучшую пиццу и все начинки для лучшей пиццы для каждого ресторана. Это будет сделано в трех запросах к базе данных - один для ресторанов, один для «лучшей пиццы» и один для начинки.

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

Поиски, созданные с помощью custom, по- 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()

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

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

• Вы хотите предварительно выбрать только подмножество связанных объектов.

• Вы хотите использовать такие методы оптимизации производительности, как :deferred fields

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

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

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

>>> prefetch_related('pizzas__toppings', 'pizzas')

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

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

extra()¶

extra( select = None , где = 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;
  

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

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

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

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

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

• where / tables

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

  whereи tablesоба берут список строк. Все where параметры объединяются «И» по отношению к любым другим критериям поиска.

  Пример:

  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( * поля ) ¶

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

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( псевдоним ) ¶

Этот метод предназначен для контроля, по какой базе данных 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()отношения, допускающие значение NULL:

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

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

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

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

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

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

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

raw()¶

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

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

Дополнительные сведения см. В разделе « Выполнение необработанных запросов SQL» .

И ( &) ¶

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

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

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

ИЛИ ( |) ¶

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

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

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

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

Entry.objects.get(id=1)
Entry.objects.get(blog=blog, 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 ) ¶

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

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(по умолчанию = Нет , ** kwargs ) ¶

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

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

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

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(по умолчанию = Нет , ** kwargs ) ¶

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

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

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 запрос, независимо от количества объектов) и возвращает созданные объекты в виде списка в том же порядке, как указано:

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

Однако здесь есть ряд предостережений:

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

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

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

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

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

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

bulk_update()¶

bulk_update( объекты , поля , batch_size = Нет ) ¶

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

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

В 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()вызов выполняет за кадром, так что вы всегда должны использовать вместо загрузки всех записей в Python объектов и вызов на результате (если вам не нужно загружать объекты в память в любом случае, в этом случай будет быстрее).SELECT COUNT(*)count()len()len()

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

in_bulk()¶

in_bulk( id_list = Нет , * , field_name = 'pk' ) ¶

Принимает список значений поля ( id_list) и field_nameдля этих значений и возвращает словарь, сопоставляющий каждое значение с экземпляром объекта с заданным значением поля. Если id_listне указан, возвращаются все объекты в наборе запросов. field_nameдолжно быть уникальным полем или отдельным полем (если в поле указано только одно поле distinct()). field_nameпо умолчанию используется первичный ключ.

Пример:

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

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

iterator()¶

iterator( chunk_size = 2000 ) ¶

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

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

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

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

latest()¶

latest( * поля ) ¶

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

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

Если мета вашей модели указывает 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( * поля ) ¶

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

Самый эффективный метод определения, является ли модель с уникальным полем (например primary_key) членом a 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")

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

Кроме того, если a 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()

Entry.objects.order_by('-number').update(number=F('number') + 1)

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

ForeignKeys, настроенные так, чтобы не препятствовать быстрому пути удаления.on_delete DO_NOTHING

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

as_manager()¶

classmethodas_manager () ¶

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

explain()¶

explain( формат = Нет , ** параметры ) ¶

Возвращает строку 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'форматы. Поддержка MariaDB и MySQL 'TEXT'(также называемых 'TRADITIONAL') и 'JSON'форматов. MySQL 8.0.16+ также поддерживает улучшенный 'TREE'формат, который похож на 'TEXT'вывод PostgreSQL и используется по умолчанию, если поддерживается.

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

>>> print(Blog.objects.filter(title='My Blog').explain(verbose=True, analyze=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флаг, поддерживаемый MariaDB, MySQL 8.0.18+ и 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')