Выполнение запросов

Сохранение полей ForeignKey и ManyToManyField

Обновление поля ForeignKey выполняется так же, как сохранение обычного поля: присвойте соответствующему полю объект нужного типа. В этом примере обновляется атрибут blog экземпляра Entry entry. Предполагается, что соответствующие экземпляры Entry и Blog уже сохранены в базе данных (чтобы их можно было получить ниже):

>>> from blog.models import Blog, Entry
>>> entry = Entry.objects.get(pk=1)
>>> cheese_blog = Blog.objects.get(name="Cheddar Talk")
>>> entry.blog = cheese_blog
>>> entry.save()

Обновление поля ManyToManyField работает немного иначе: чтобы добавить запись в связь, используйте метод add() этого поля. В этом примере экземпляр Author joe добавляется к объекту entry:

>>> from blog.models import Author
>>> joe = Author.objects.create(name="Joe")
>>> entry.authors.add(joe)

Чтобы сразу добавить несколько записей в поле ManyToManyField, передайте несколько аргументов при вызове add(), например:

>>> john = Author.objects.create(name="John")
>>> paul = Author.objects.create(name="Paul")
>>> george = Author.objects.create(name="George")
>>> ringo = Author.objects.create(name="Ringo")
>>> entry.authors.add(john, paul, george, ringo)

Django выдаст ошибку, если вы попытаетесь присвоить или добавить объект неподходящего типа.

Получение всех объектов

Самый простой способ получить объекты из таблицы — запросить их все. Для этого используйте метод all() у Manager:

>>> all_entries = Entry.objects.all()

Метод all() возвращает QuerySet со всеми объектами из базы данных.

Получение определённых объектов с помощью фильтров

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

Чтобы создать такое подмножество, уточните исходный QuerySet, добавив условия фильтрации. Два наиболее распространённых способа уточнить QuerySet:

filter(**kwargs)

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

exclude(**kwargs)

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

Параметры поиска (**kwargs в приведённых выше определениях функций) должны иметь формат, описанный ниже в разделе Поиск по полям.

Например, чтобы получить QuerySet записей блога за 2006 год, используйте filter() следующим образом:

Entry.objects.filter(pub_date__year=2006)

С классом менеджера по умолчанию это эквивалентно:

Entry.objects.all().filter(pub_date__year=2006)

>>> Entry.objects.filter(headline__startswith="What").exclude(
...     pub_date__gte=datetime.date.today()
... ).filter(pub_date__gte=datetime.date(2005, 1, 30))

>>> q1 = Entry.objects.filter(headline__startswith="What")
>>> q2 = q1.exclude(pub_date__gte=datetime.date.today())
>>> q3 = q1.filter(pub_date__gte=datetime.date.today())

>>> q = Entry.objects.filter(headline__startswith="What")
>>> q = q.filter(pub_date__lte=datetime.date.today())
>>> q = q.exclude(body_text__icontains="food")
>>> print(q)

Получение одного объекта с помощью get()

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

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

>>> one_entry = Entry.objects.get(pk=1)

С get() можно использовать любое выражение запроса, как и с filter(). Подробнее см. раздел Поиск по полям ниже.

Обратите внимание на разницу между использованием get() и использованием filter() среза [0]. Если запрос не вернёт результатов, get() вызовет исключение DoesNotExist. Это исключение является атрибутом класса модели, для которой выполняется запрос. Поэтому в приведённом выше коде, если объекта Entry с первичным ключом 1 не существует, Django вызовет Entry.DoesNotExist.

Аналогично, Django сообщит об ошибке, если запросу get() соответствует более одного элемента. В этом случае будет вызвано исключение MultipleObjectsReturned, которое также является атрибутом самого класса модели.

Другие методы QuerySet

Чаще всего для поиска объектов в базе данных используются методы all(), get(), filter() и exclude(). Но это далеко не всё; полный список различных методов QuerySet см. в справочнике по API QuerySet.

Ограничение QuerySets

Используйте часть синтаксиса срезов массивов Python, чтобы ограничить QuerySet заданным количеством результатов. Это эквивалент предложений SQL LIMIT и OFFSET.

Например, этот код возвращает первые 5 объектов (LIMIT 5):

>>> Entry.objects.all()[:5]

Этот код возвращает объекты с шестого по десятый (OFFSET 5 LIMIT 5):

>>> Entry.objects.all()[5:10]

Отрицательная индексация (например, Entry.objects.all()[-1]) не поддерживается.

Как правило, срез QuerySet возвращает новый QuerySet — запрос при этом не вычисляется. Исключение составляет использование параметра «шага» в синтаксисе срезов Python. Например, следующий код действительно выполнит запрос, чтобы вернуть список каждого второго объекта из первых 10:

>>> Entry.objects.all()[:10:2]

Дальнейшая фильтрация или сортировка срезанного набора запросов запрещена из-за неоднозначности возможного поведения.

Чтобы получить один объект, а не список (например, SELECT foo FROM bar LIMIT 1), используйте индекс вместо среза. Например, этот код возвращает первую запись Entry в базе данных после сортировки записей по заголовку в алфавитном порядке:

>>> Entry.objects.order_by("headline")[0]

Это примерно эквивалентно следующему:

>>> Entry.objects.order_by("headline")[0:1].get()

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

Поиск по полям

Поиск по полям позволяет задать основную часть предложения SQL WHERE. Он задаётся в виде именованных аргументов методов QuerySet filter(), exclude() и get().

Именованные аргументы для базового поиска имеют вид field__lookuptype=value. (Это два символа подчёркивания.) Например:

>>> Entry.objects.filter(pub_date__lte="2006-01-01")

примерно соответствует следующему SQL:

SELECT * FROM blog_entry WHERE pub_date <= '2006-01-01';

Указанное в поисковом запросе поле должно быть именем поля модели. Однако есть одно исключение: для ForeignKey можно указать имя поля с суффиксом _id. В этом случае параметр значения должен содержать необработанное значение первичного ключа связанной модели. Например:

>>> Entry.objects.filter(blog_id=4)

Если передать недопустимый именованный аргумент, функция поиска вызовет TypeError.

API базы данных поддерживает около двух десятков типов поиска; полный справочник доступен в справочнике по поиску по полям. Чтобы получить представление о доступных возможностях, рассмотрим несколько наиболее распространённых типов поиска:

exact

Точное совпадение. Например:

>>> Entry.objects.get(headline__exact="Cat bites dog")

Будет сгенерирован примерно такой SQL:

SELECT ... WHERE headline = 'Cat bites dog';

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

Например, следующие два оператора эквивалентны:

>>> Blog.objects.get(id__exact=14)  # Explicit form
>>> Blog.objects.get(id=14)  # __exact is implied

Это сделано для удобства, поскольку поиск exact используется чаще всего.

iexact

Совпадение без учёта регистра. Так, запрос:

>>> Blog.objects.get(name__iexact="beatles blog")

Найдёт запись Blog с заголовком "Beatles Blog", "beatles blog" или даже "BeAtlES blOG".

contains

Проверка наличия подстроки с учётом регистра. Например:

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

Примерно соответствует следующему SQL:

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

Обратите внимание: этот поиск найдёт заголовок 'Today Lennon honored', но не 'today lennon honored'.

Существует также версия без учёта регистра: icontains.

startswith, endswith

Поиск по началу и концу строки соответственно. Существуют также версии без учёта регистра: istartswith и iendswith.

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

Поиск по связанным объектам

Django предлагает мощный и интуитивно понятный способ «переходить» по связям при поиске, автоматически формируя за кулисами необходимые SQL-соединения JOIN. Чтобы перейти по связи, используйте имена полей связанных моделей, разделяя их двумя символами подчёркивания, пока не дойдёте до нужного поля.

В этом примере извлекаются все объекты Entry, у которых есть Blog, чей name равен 'Beatles Blog':

>>> Entry.objects.filter(blog__name="Beatles Blog")

Такие переходы могут быть сколь угодно глубокими.

Это работает и в обратном направлении. Хотя can be customized, по умолчанию для обращения к «обратной» связи в запросе используется имя модели в нижнем регистре.

В этом примере извлекаются все объекты Blog, у которых есть хотя бы один Entry, чей headline содержит 'Lennon':

>>> Blog.objects.filter(entry__headline__contains="Lennon")

Если при фильтрации по нескольким связям одна из промежуточных моделей не содержит значения, удовлетворяющего условию фильтрации, Django обработает её так, будто там находится пустой (все значения — NULL), но допустимый объект. Это означает, что ошибка не возникнет. Например, для такого фильтра:

Blog.objects.filter(entry__authors__name="Lennon")

(если бы существовала связанная модель Author), при отсутствии связанного с записью author Django обработал бы её так, будто к ней не прикреплён и name, вместо того чтобы вызывать ошибку из-за отсутствующего author. Обычно именно такого поведения и ожидают. Единственный случай, в котором оно может сбить с толку, — использование isnull. Например:

Blog.objects.filter(entry__authors__name__isnull=True)

вернёт объекты Blog, у которых name пусто в author, а также объекты, у которых author пусто в entry. Если вам не нужны последние объекты, можно написать:

Blog.objects.filter(entry__authors__isnull=False, entry__authors__name__isnull=True)

Blog.objects.filter(entry__headline__contains="Lennon", entry__pub_date__year=2008)

Blog.objects.filter(entry__headline__contains="Lennon").filter(
    entry__pub_date__year=2008
)

>>> from datetime import date
>>> beatles = Blog.objects.create(name="Beatles Blog")
>>> pop = Blog.objects.create(name="Pop Music Blog")
>>> Entry.objects.create(
...     blog=beatles,
...     headline="New Lennon Biography",
...     pub_date=date(2008, 6, 1),
... )
<Entry: New Lennon Biography>
>>> Entry.objects.create(
...     blog=beatles,
...     headline="New Lennon Biography in Paperback",
...     pub_date=date(2009, 6, 1),
... )
<Entry: New Lennon Biography in Paperback>
>>> Entry.objects.create(
...     blog=pop,
...     headline="Best Albums of 2008",
...     pub_date=date(2008, 12, 15),
... )
<Entry: Best Albums of 2008>
>>> Entry.objects.create(
...     blog=pop,
...     headline="Lennon Would Have Loved Hip Hop",
...     pub_date=date(2020, 4, 1),
... )
<Entry: Lennon Would Have Loved Hip Hop>
>>> Blog.objects.filter(
...     entry__headline__contains="Lennon",
...     entry__pub_date__year=2008,
... )
<QuerySet [<Blog: Beatles Blog>]>
>>> Blog.objects.filter(
...     entry__headline__contains="Lennon",
... ).filter(
...     entry__pub_date__year=2008,
... )
<QuerySet [<Blog: Beatles Blog>, <Blog: Beatles Blog>, <Blog: Pop Music Blog]>

Blog.objects.exclude(
    entry__headline__contains="Lennon",
    entry__pub_date__year=2008,
)

Blog.objects.exclude(
    entry__in=Entry.objects.filter(
        headline__contains="Lennon",
        pub_date__year=2008,
    ),
)

Фильтры могут ссылаться на поля модели

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

Django предоставляет F expressions, позволяющие выполнять такие сравнения. Экземпляры F() служат ссылками на поля модели внутри запроса. Эти ссылки можно использовать в фильтрах запросов для сравнения значений двух разных полей одного экземпляра модели.

Например, чтобы найти все записи блога, у которых комментариев больше, чем уведомлений о пингах, создадим объект F(), ссылающийся на количество уведомлений о пингах, и используем этот объект F() в запросе:

>>> from django.db.models import F
>>> Entry.objects.filter(number_of_comments__gt=F("number_of_pingbacks"))

Django поддерживает арифметические операции сложения, вычитания, умножения, деления, вычисления остатка и возведения в степень с объектами F() — как с константами, так и с другими объектами F(). Чтобы найти записи блога, в которых комментариев более чем вдвое больше, чем уведомлений о пингах, изменим запрос:

>>> Entry.objects.filter(number_of_comments__gt=F("number_of_pingbacks") * 2)

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

>>> Entry.objects.filter(rating__lt=F("number_of_comments") + F("number_of_pingbacks"))

Для перехода по связям в объекте F() также можно использовать запись с двумя символами подчёркивания. Объект F() с двумя символами подчёркивания добавит все необходимые соединения для доступа к связанному объекту. Например, чтобы получить все записи, в которых имя автора совпадает с названием блога, выполним запрос:

>>> Entry.objects.filter(authors__name=F("blog__name"))

Для полей даты и даты/времени можно прибавлять или вычитать объект timedelta. Следующий запрос вернёт все записи, изменённые более чем через 3 дня после публикации:

>>> from datetime import timedelta
>>> Entry.objects.filter(mod_date__gt=F("pub_date") + timedelta(days=3))

Объекты F() поддерживают побитовые операции .bitand(), .bitor(), .bitxor(), .bitrightshift() и .bitleftshift(). Например:

>>> F("somefield").bitand(16)

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

Django поддерживает использование преобразований в выражениях.

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

>>> from django.db.models import F
>>> Entry.objects.filter(pub_date__year=F("mod_date__year"))

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

>>> from django.db.models import Min
>>> Entry.objects.aggregate(first_published_year=Min("pub_date__year"))

Этот пример находит значение наибольшего рейтинга записи и общее количество комментариев ко всем записям для каждого года:

>>> from django.db.models import OuterRef, Subquery, Sum
>>> Entry.objects.values("pub_date__year").annotate(
...     top_rating=Subquery(
...         Entry.objects.filter(
...             pub_date__year=OuterRef("pub_date__year"),
...         )
...         .order_by("-rating")
...         .values("rating")[:1]
...     ),
...     total_comments=Sum("number_of_comments"),
... )

Сокращённая запись поиска pk

Для удобства Django предоставляет сокращённую запись поиска pk, которая означает «первичный ключ».

В модели Blog из примера первичным ключом является поле id, поэтому следующие три оператора эквивалентны:

>>> Blog.objects.get(id__exact=14)  # Explicit form
>>> Blog.objects.get(id=14)  # __exact is implied
>>> Blog.objects.get(pk=14)  # pk implies id__exact

Использование pk не ограничивается запросами к __exact — любой термин запроса можно объединить с pk, чтобы выполнить запрос по первичному ключу модели:

# Get blogs entries with id 1, 4 and 7
>>> Blog.objects.filter(pk__in=[1, 4, 7])

# Get all blog entries with id > 14
>>> Blog.objects.filter(pk__gt=14)

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

>>> Entry.objects.filter(blog__id__exact=3)  # Explicit form
>>> Entry.objects.filter(blog__id=3)  # __exact is implied
>>> Entry.objects.filter(blog__pk=3)  # __pk implies __id__exact

Экранирование знаков процента и подчёркиваний в операторах LIKE

Поиски по полям, соответствующие операторам SQL LIKE (iexact, contains, icontains, startswith, istartswith, endswith и iendswith), автоматически экранируют два специальных символа, используемых в операторах LIKE: знак процента и подчёркивание. (В операторе LIKE знак процента обозначает подстановочный знак для нескольких символов, а подчёркивание — для одного символа.)

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

>>> Entry.objects.filter(headline__contains="%")

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

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

То же самое относится к подчёркиваниям. Знаки процента и подчёркивания обрабатываются автоматически.

Кэширование и QuerySet

Каждый QuerySet содержит кэш для минимизации обращений к базе данных. Понимание его работы позволит писать максимально эффективный код.

У только что созданного QuerySet кэш пуст. При первой оценке QuerySet — и, следовательно, выполнении запроса к базе данных — Django сохраняет результаты запроса в кэше QuerySet и возвращает явно запрошенные результаты (например, следующий элемент, если выполняется итерация по QuerySet). При последующих оценках QuerySet используются кэшированные результаты.

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

>>> print([e.headline for e in Entry.objects.all()])
>>> print([e.pub_date for e in Entry.objects.all()])

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

Чтобы избежать этой проблемы, сохраните QuerySet и используйте его повторно:

>>> queryset = Entry.objects.all()
>>> print([p.headline for p in queryset])  # Evaluate the query set.
>>> print([p.pub_date for p in queryset])  # Reuse the cache from the evaluation.

>>> queryset = Entry.objects.all()
>>> print(queryset[5])  # Queries the database
>>> print(queryset[5])  # Queries the database again

>>> queryset = Entry.objects.all()
>>> [entry for entry in queryset]  # Queries the database
>>> print(queryset[5])  # Uses cache
>>> print(queryset[5])  # Uses cache

>>> [entry for entry in queryset]
>>> bool(queryset)
>>> entry in queryset
>>> list(queryset)

Итерация по запросам

При обычном способе перебора запроса с помощью for за кулисами выполняется блокирующий запрос к базе данных, поскольку Django загружает результаты во время итерации. Чтобы исправить это, используйте async for:

async for entry in Authors.objects.filter(name__startswith="A"):
    ...

Обратите внимание, что также нельзя выполнять другие действия, которые могут перебирать набор запросов, например оборачивать его в list(), чтобы принудительно выполнить его оценку (при необходимости можно использовать async for в выражении-генераторе).

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

Методы QuerySet и менеджеров

Некоторые методы менеджеров и наборов запросов, например get() и first(), принудительно выполняют набор запросов и блокируют выполнение. Другие, например filter() и exclude(), не принуждают к выполнению, поэтому их безопасно вызывать из асинхронного кода. Но как понять, чем они отличаются?

Можно поискать версию метода с префиксом a (например, у нас есть aget(), но нет afilter()), однако есть более логичный способ — посмотреть, к какому типу относится метод, в справочнике по QuerySet.

В нём методы QuerySet сгруппированы в два раздела:

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

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

user = await User.objects.filter(username=my_input).afirst()

filter() возвращает набор запросов, поэтому его можно продолжать объединять с другими вызовами в асинхронной среде, тогда как first() выполняет запрос и возвращает экземпляр модели. Поэтому мы заменяем его на afirst() и добавляем await в начало всего выражения, чтобы вызвать его безопасным для асинхронного кода способом.

Транзакции

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

Если вам нужна транзакция, рекомендуем поместить код ORM в отдельную синхронную функцию и вызвать её с помощью sync_to_async — подробнее см. раздел Асинхронная поддержка.

Сохранение и поиск None

Как и в случае с другими полями, сохранение None в качестве значения поля сохранит его как SQL NULL. Хотя это не рекомендуется, можно сохранить скалярное значение JSON null вместо SQL NULL, используя Value(None, JSONField()).

Какое бы значение ни было сохранено, при получении из базы данных представление скалярного значения JSON null в Python совпадает с представлением SQL NULL, то есть None. Поэтому их бывает трудно различить.

Это относится только к None в качестве верхнеуровневого значения поля. Если None находится внутри list или dict, оно всегда будет интерпретироваться как JSON null.

При выполнении запроса значение None всегда будет интерпретироваться как JSON null. Для поиска SQL NULL используйте isnull:

>>> Dog.objects.create(name="Max", data=None)  # SQL NULL.
<Dog: Max>
>>> Dog.objects.create(name="Archie", data=Value(None, JSONField()))  # JSON null.
<Dog: Archie>
>>> Dog.objects.filter(data=None)
<QuerySet [<Dog: Archie>]>
>>> Dog.objects.filter(data=Value(None, JSONField()))
<QuerySet [<Dog: Archie>]>
>>> Dog.objects.filter(data__isnull=True)
<QuerySet [<Dog: Max>]>
>>> Dog.objects.filter(data__isnull=False)
<QuerySet [<Dog: Archie>]>

Если вы не уверены, что хотите работать со значениями SQL NULL, рассмотрите возможность задать null=False и указать подходящее значение по умолчанию для пустых значений, например default=dict.

Преобразования ключей, индексов и путей

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

>>> Dog.objects.create(
...     name="Rufus",
...     data={
...         "breed": "labrador",
...         "owner": {
...             "name": "Bob",
...             "other_pets": [
...                 {
...                     "name": "Fishy",
...                 }
...             ],
...         },
...     },
... )
<Dog: Rufus>
>>> Dog.objects.create(name="Meg", data={"breed": "collie", "owner": None})
<Dog: Meg>
>>> Dog.objects.filter(data__breed="collie")
<QuerySet [<Dog: Meg>]>

Несколько ключей можно объединить в цепочку, сформировав поиск по пути:

>>> Dog.objects.filter(data__owner__name="Bob")
<QuerySet [<Dog: Rufus>]>

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

>>> Dog.objects.filter(data__owner__other_pets__0__name="Fishy")
<QuerySet [<Dog: Rufus>]>

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

>>> Dog.objects.filter(**{"data__owner__other_pets__-1__name": "Fishy"})
<QuerySet [<Dog: Rufus>]>

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

Для поиска отсутствующих ключей используйте поиск isnull:

>>> Dog.objects.create(name="Shep", data={"breed": "collie"})
<Dog: Shep>
>>> Dog.objects.filter(data__owner__isnull=True)
<QuerySet [<Dog: Shep>]>

Поиски по содержимому и ключам

>>> Dog.objects.create(name="Rufus", data={"breed": "labrador", "owner": "Bob"})
<Dog: Rufus>
>>> Dog.objects.create(name="Meg", data={"breed": "collie", "owner": "Bob"})
<Dog: Meg>
>>> Dog.objects.create(name="Fred", data={})
<Dog: Fred>
>>> Dog.objects.create(
...     name="Merry", data={"breed": "pekingese", "tricks": ["fetch", "dance"]}
... )
>>> Dog.objects.filter(data__contains={"owner": "Bob"})
<QuerySet [<Dog: Rufus>, <Dog: Meg>]>
>>> Dog.objects.filter(data__contains={"breed": "collie"})
<QuerySet [<Dog: Meg>]>
>>> Dog.objects.filter(data__contains={"tricks": ["dance"]})
<QuerySet [<Dog: Merry>]>

>>> Dog.objects.create(name="Rufus", data={"breed": "labrador", "owner": "Bob"})
<Dog: Rufus>
>>> Dog.objects.create(name="Meg", data={"breed": "collie", "owner": "Bob"})
<Dog: Meg>
>>> Dog.objects.create(name="Fred", data={})
<Dog: Fred>
>>> Dog.objects.create(
...     name="Merry", data={"breed": "pekingese", "tricks": ["fetch", "dance"]}
... )
>>> Dog.objects.filter(data__contained_by={"breed": "collie", "owner": "Bob"})
<QuerySet [<Dog: Meg>, <Dog: Fred>]>
>>> Dog.objects.filter(data__contained_by={"breed": "collie"})
<QuerySet [<Dog: Fred>]>
>>> Dog.objects.filter(
...     data__contained_by={"breed": "pekingese", "tricks": ["dance", "fetch", "hug"]}
... )
<QuerySet [<Dog: Merry>, <Dog: Fred>]>

>>> Dog.objects.create(name="Rufus", data={"breed": "labrador"})
<Dog: Rufus>
>>> Dog.objects.create(name="Meg", data={"breed": "collie", "owner": "Bob"})
<Dog: Meg>
>>> Dog.objects.filter(data__has_key="owner")
<QuerySet [<Dog: Meg>]>

>>> Dog.objects.create(name="Rufus", data={"breed": "labrador"})
<Dog: Rufus>
>>> Dog.objects.create(name="Meg", data={"breed": "collie", "owner": "Bob"})
<Dog: Meg>
>>> Dog.objects.filter(data__has_keys=["breed", "owner"])
<QuerySet [<Dog: Meg>]>

>>> Dog.objects.create(name="Rufus", data={"breed": "labrador"})
<Dog: Rufus>
>>> Dog.objects.create(name="Meg", data={"owner": "Bob"})
<Dog: Meg>
>>> Dog.objects.filter(data__has_any_keys=["owner", "breed"])
<QuerySet [<Dog: Rufus>, <Dog: Meg>]>

Связи «один ко многим»

>>> e = Entry.objects.get(id=2)
>>> e.blog  # Returns the related Blog object.

>>> e = Entry.objects.get(id=2)
>>> e.blog = some_blog
>>> e.save()

>>> e = Entry.objects.get(id=2)
>>> e.blog = None
>>> e.save()  # "UPDATE blog_entry SET blog_id = NULL ...;"

>>> e = Entry.objects.get(id=2)
>>> print(e.blog)  # Hits the database to retrieve the associated Blog.
>>> print(e.blog)  # Doesn't hit the database; uses cached version.

>>> e = Entry.objects.select_related().get(id=2)
>>> print(e.blog)  # Doesn't hit the database; uses cached version.
>>> print(e.blog)  # Doesn't hit the database; uses cached version.

>>> b = Blog.objects.get(id=1)
>>> b.entry_set.all()  # Returns all Entry objects related to Blog.

# b.entry_set is a Manager that returns QuerySets.
>>> b.entry_set.filter(headline__contains="Lennon")
>>> b.entry_set.count()

>>> b = Blog.objects.get(id=1)
>>> b.entries.all()  # Returns all Entry objects related to Blog.

# b.entries is a Manager that returns ``QuerySet`` instances.
>>> b.entries.filter(headline__contains="Lennon")
>>> b.entries.count()

from django.db import models


class Entry(models.Model):
    # ...
    objects = models.Manager()  # Default Manager
    entries = EntryManager()  # Custom Manager


b = Blog.objects.get(id=1)
b.entry_set(manager="entries").all()

b.entry_set(manager="entries").is_published()

from django.db.models import Prefetch

prefetch_manager = Prefetch("entry_set", queryset=Entry.entries.all())
Blog.objects.prefetch_related(prefetch_manager)

b = Blog.objects.get(id=1)
b.entry_set.set([e1, e2])

Связи «многие ко многим»

Оба конца связи «многие ко многим» автоматически получают доступ через API к другому концу. API работает аналогично описанной выше обратной связи «один ко многим».

Одно отличие заключается в именовании атрибутов: модель, в которой определено поле ManyToManyField, использует имя самого этого поля, а «обратная» модель — имя исходной модели в нижнем регистре с добавлением '_set' (как и для обратных связей «один ко многим»).

Пример поможет разобраться:

e = Entry.objects.get(id=3)
e.authors.all()  # Returns all Author objects for this Entry.
e.authors.count()
e.authors.filter(name__contains="John")

a = Author.objects.get(id=5)
a.entry_set.all()  # Returns all Entry objects for this Author.

Как и ForeignKey, поле ManyToManyField может задавать параметр related_name. В приведённом выше примере, если бы поле ManyToManyField в Entry было задано как related_name='entries', каждый экземпляр Author имел бы атрибут entries вместо entry_set.

Ещё одно отличие от связей «один ко многим»: методы add(), set() и remove() для связей «многие ко многим» принимают не только экземпляры моделей, но и значения первичных ключей. Например, если e1 и e2 — экземпляры Entry, следующие вызовы set() выполняют одно и то же:

a = Author.objects.get(id=5)
a.entry_set.set([e1, e2])
a.entry_set.set([e1.pk, e2.pk])

Связи «один к одному»

Связи «один к одному» очень похожи на связи «многие к одному». Если в модели определить поле OneToOneField, экземпляры этой модели получат доступ к связанному объекту через атрибут модели.

Например:

class EntryDetail(models.Model):
    entry = models.OneToOneField(Entry, on_delete=models.CASCADE)
    details = models.TextField()


ed = EntryDetail.objects.get(id=2)
ed.entry  # Returns the related Entry object.

Различие проявляется при обратных запросах. Связанная модель в отношениях «один к одному» тоже имеет доступ к объекту Manager, но этот Manager представляет один объект, а не коллекцию объектов:

e = Entry.objects.get(id=2)
e.entrydetail  # returns the related EntryDetail object

Если объект для этой связи не назначен, Django вызовет исключение DoesNotExist.

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

e.entrydetail = ed

Как работают обратные связи?

В других объектно-реляционных преобразователях связи нужно определять с обеих сторон. Разработчики Django считают, что это нарушает принцип DRY (Don’t Repeat Yourself — «не повторяйся»), поэтому в Django достаточно определить связь только с одной стороны.

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

Ответ кроется в app registry. При запуске Django импортирует каждое приложение, указанное в INSTALLED_APPS, а затем модуль models внутри каждого приложения. При создании нового класса модели Django добавляет обратные связи во все связанные модели. Если связанные модели ещё не импортированы, Django отслеживает эти связи и добавляет их, когда связанные модели будут импортированы.

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

Запросы к связанным объектам

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

Например, если у вас есть объект Blog b с id=5, следующие три запроса будут идентичны:

Entry.objects.filter(blog=b)  # Query using object instance
Entry.objects.filter(blog=b.id)  # Query using id from instance
Entry.objects.filter(blog=5)  # Query using id directly