Создание запросов

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

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

Используйте подмножество синтаксиса срезов массивов 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, то это будет обработано как отсутствие и 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"),
... )

Сокращение поиска по первичному ключу

Для удобства Django предоставляет сокращение поиска по первичному ключу.

В примере 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)

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

>>> 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 повторно используют кэшированные результаты.

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

>>> 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"):
    ...

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

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

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

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

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

Там вы найдете методы QuerySets, сгруппированные в две секции:

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

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

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

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

Транзакции

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

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

Хранение и поиск по значению None

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

Какой бы из значений ни был сохранён, при извлечении из базы данных, представление Python скалярного значения JSON null будет таким же, как 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>]>

Если ключ, по которому вы хотите выполнить запрос, совпадает с именем другого поиска, используйте вместо него поиск 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.filter(data__contains={"owner": "Bob"})
<QuerySet [<Dog: Rufus>, <Dog: Meg>]>
>>> Dog.objects.filter(data__contains={"breed": "collie"})
<QuerySet [<Dog: Meg>]>

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