Некоторые неочевидные особенности Django ORM (filter и exclude)

TLDR: В статье рассказывается о некоторых особенностях Django ORM, а именно, как при неправильном использовании некоторых встроенных методов (filter(), exclude()) можно незаметно, но очень больно, выстрелить себе в ногу при работе со связями many-to-many и one-to-many (связь, обратная к FK). Статья может быть полезной не слишком искушенному в тонкостях Django ORM разработчику.

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

Собственно вот эта часть документации: https://docs.djangoproject.com/en/5.2/topics/db/queries/#spanning-multi-valued-relationships Быстро посмотрим, что там:

class Blog(models.Model):     name = models.CharField(max_length=100)     tagline = models.TextField()  class Entry(models.Model):     blog = models.ForeignKey(Blog, on_delete=models.CASCADE)     headline = models.CharField(max_length=255)     body_text = models.TextField()     pub_date = models.DateField()

… Если нам нужно выбрать все блоги (Blog), содержащие хотя бы одну запись (Entry) от 2008 года, имеющую “Lennon” в своем заголовке, то запрос будет следующим.

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

Если же, нас интересуют такие блоги, в которых есть одновременно и записи от 2008 года, и записи, содержащие Lennon в своем заголовке, то нужно писать

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

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

Казалось бы, ну понятно же все, RTFM, но я пойду немного дальше и расскажу, какие последствия незнания мы поймали на практике, и что с этим делали. И на мой взгляд, гораздо нагляднее и гораздо ближе к реальности будет показать это на примере связи many-to-many Entry — Tag.

class Blog(models.Model):       name = models.CharField(max_length=100)    class Tag(models.Model):       name = models.CharField(max_length=100)        def __str__(self):           return self.name    class Entry(models.Model):       blog = models.ForeignKey(Blog, on_delete=models.CASCADE)       tags = models.ManyToManyField(Tag)        headline = models.CharField(max_length=255)       body_text = models.TextField()       is_hidden = models.BooleanField(default=False)

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

def get_tags(blog_id: int = None) -> QuerySet:       qs = Tag.objects.filter(entry__is_hidden=False)       if blog_id is not None:           qs = qs.filter(entry__blog_id=blog_id)        return qs.distinct()

Тут мы обращаемся к Entry в разных .filter(). Это конечно же ошибка (теперь-то мы знаем), и ниже посмотрим, как она проявляется на практике.

Заполним БД:

blog_beatles = Blog.objects.create(name="Beatles Blog")   blog_pop = Blog.objects.create(name="Pop Music Blog")   tag_lennon = Tag.objects.create(name="Lennon")   tag_beatles = Tag.objects.create(name="Beatles")   tag_biography = Tag.objects.create(name="Biography")   tag_hip_hop = Tag.objects.create(name="Hip-hop")    Entry.objects.create(       blog=blog_beatles,       headline="New Lennon Biography",       is_hidden=True,   ).tags.set([tag_lennon, tag_biography, ])    Entry.objects.create(       blog=blog_beatles,       headline="Full Beatles Discography",       is_hidden=False,   ).tags.set([tag_lennon, tag_beatles, ])    Entry.objects.create(       blog=blog_pop,       headline="Lennon Would Have Loved Hip Hop",       is_hidden=False,   ).tags.set([tag_lennon, tag_hip_hop, tag_biography, ])

Теперь, если вызвать get_tags(blog_id=blog_beatles.id), то среди тегов мы увидим тег Biography.

>>> get_tags(1) <QuerySet [<Tag: Lennon>, <Tag: Biography>, <Tag: Beatles>]>

Потому что есть нескрытая запись с таким тегом, и есть запись с таким тегом в целевом блоге. Да, это разные записи, но поскольку запрос составлен “более мягким“ образом, то этот тег мы увидим в ответе.

Вторая проблема становится отчетливо видна, если посмотреть на выполняемый SQL-запрос.

SELECT DISTINCT "example_tag"."id",        "example_tag"."name"   FROM "example_tag"  INNER JOIN "example_entry_tags"     ON ("example_tag"."id" = "example_entry_tags"."tag_id")  INNER JOIN "example_entry"     ON ("example_entry_tags"."entry_id" = "example_entry"."id")  INNER JOIN "example_entry_tags" T4     ON ("example_tag"."id" = T4."tag_id")  INNER JOIN "example_entry" T5     ON (T4."entry_id" = T5."id")  WHERE (NOT "example_entry"."is_hidden" AND T5."blog_id" = 1)  LIMIT 21

Здесь мы видим, что промежуточная таблица для M2M-связи example_entry_tags (и вслед за ней example_entry) джойнится дважды, а поскольку нет условия, которое бы связывало example_entry_tags и T4, то по факту к таблице example_tags мы джойним декартово произведение таблицы example_entry_tags саму на себя. И здесь проблема может быть незаметной (база все стерпит) до какого-то критического момента. Таковым может стать добавление еще одного .filter(), после чего таблица example_entry_tags будет джойниться трижды. Или например, если количество связей Entry — Tag превысит некоторое пороговое значения, когда объем данных (а он, я обращаю внимание, из-за декартова произведения будет расти “по параболе”) перестанет умещаться в память, и все это начнет выгружаться на диск…

Что делать? Конкретно в данном примере это правится довольно просто:

def get_tags_fixed(blog_id: int = None) -> QuerySet:       conditions = [Q(entry__is_hidden=False)]       if blog_id is not None:           conditions.append(Q(entry__blog_id=blog_id))        return Tag.objects.filter(*conditions).distinct()

… но с гораздо бОльшими проблемами мы столкнулись, когда это был разбросанный по разным методам код. Например, у нас были кастомные менеджеры моделей и новые фильтры добавлялись внутри них. Что-то типа

class TagManager(models.Manager):     def filter_by_visibility(self):         return self.filter(entry__is_hidden=False)      def filter_by_blog(self, entry_blog_id: int = None):         if entry_blog_id is not None:             return self.filter(entry__blog_id=entry_blog_id)         return self  class Tag(models.Model):     ...     objects = TagManager()

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

Добавлю здесь еще небольшой лайфхак, как это можно отловить (если есть подозрения, а кодовая база довольно крупная) — по запросам к БД. И на мой взгляд, лучше всего тут подойдут тестовые прогоны. Поскольку у нас код довольно неплохо был покрыт юнит-тестами, то мы их прогоняли с логированием запросов, которые потом проверяли по примерно такой регулярке (синтаксис Python для бэктрекинга в регулярках: https://www.regular-expressions.info/named.html ).

r'INNER JOIN (?P<linked_table>"\w+") ON \((?P<original_table_field>"\w+"\."\w+") = (?P=linked_table)\.(?P<linked_field>"\w+")\).*' r'INNER JOIN (?P=linked_table) (?P<linked_alias>\w+) ON \((?P=original_table_field) = (?P=linked_alias)\.(?P=linked_field)\)'

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

И еще немного про .exclude(). Если бы исходный хелпер был бы написан таким образом:

def get_tags_with_exclude(blog_id: int = None) -> QuerySet:       qs = Tag.objects.exclude(entry__is_hidden=True)       if blog_id is not None:           qs = qs.filter(entry__blog_id=blog_id)        return qs.distinct()

то вызов get_tags_with_exclude(blog_id=blog_beatles) вернул бы только

<QuerySet [<Tag: Beatles>]>

а под капотом породил бы следующий SQL-запрос с подзапросом с EXISTS

SELECT DISTINCT "example_tag"."id",        "example_tag"."name"   FROM "example_tag"  INNER JOIN "example_entry_tags"     ON ("example_tag"."id" = "example_entry_tags"."tag_id")  INNER JOIN "example_entry"     ON ("example_entry_tags"."entry_id" = "example_entry"."id")  WHERE (NOT (EXISTS(SELECT 1 AS "a" FROM "example_entry_tags" U1 INNER JOIN "example_entry" U2 ON (U1."entry_id" = U2."id") WHERE (U2."is_hidden" AND U1."tag_id" = ("example_tag"."id")) LIMIT 1)) AND "example_entry"."blog_id" = 1)

Я понимаю, почему тег Lennon не попал в выдачу — потому что он встречается в скрытой записи, а .exclude() работает именно таким образом (и это не баг, а фича, и ее всегда нужно держать в уме). Но в какой-то очередной раз, споткнувшись о такое поведение, я решил окончательно отказаться от .exclude() вообще. Неудобно же, и мне непонятна логика создателей Django, почему они не добавили lookup для “не равно” (но к счастью, описали прямо в документации, как это сделать https://docs.djangoproject.com/en/5.2/howto/custom-lookups/#a-lookup-example ), а вместо этого рекомендуют использовать или .filter(~Q()), или .exclude(), хотя первый вариант более громоздкий, а второй — работает не всегда точно так же, как простое “не равно”.

Собственно, это все, что хотел здесь рассказать. Возможно, кто-то это и так уже знал, но надеюсь, что найдутся и те, для кого эта статья станет откровением.
И в конце не могу не порекомендовать почаще смотреть в то, какие SQL-запросы генерирует Django ORM, слишком уж много сюрпризов она может прятать «под капотом». Доверяй но проверяй.