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

Сохранение полей 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() для поля. В данном примере к объекту entry добавляется экземпляр Author joe:

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

Джанго сообщит, если вы попытаетесь назначить или добавить объект неправильного типа.

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

Самый простой способ извлечь объекты из таблицы - получить их все. Для этого следует использовать метод 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 - он не оценивает запрос. Исключением является использование параметра «step» в синтаксисе Python slice. Например, в этом случае будет фактически выполнен запрос, чтобы вернуть список каждого второго объекта из первых 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. Они указываются в качестве аргументов ключевых слов для методов filter(), exclude() и get() класса QuerySet.

Основные аргументы ключевого слова lookups имеют вид 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. В этом случае ожидается, что параметр value будет содержать необработанное значение первичного ключа внешней модели. Например:

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

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

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

exact

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

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

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

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

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

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

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

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

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

Этот охват может быть настолько глубоким, насколько вы захотите.

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

В данном примере извлекаются все объекты 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 выражения, чтобы разрешить такие сравнения. Экземпляры 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¶

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

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

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

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

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

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

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

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

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

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

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

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

Чтобы избежать этой проблемы, сохраните 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 в comprehension, если вам это нужно).

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

QuerySet и методы менеджера¶

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

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

В нем вы найдете методы по QuerySets, сгруппированные в два раздела:

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

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

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

Ответ лежит в реестре приложений. Когда запускается 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