Для чего используется атрибут related_query_name в моделях Django

Атрибут related_query_name в полях ForeignKey, OneToOneField и ManyToManyField в Django используется для кастомизации имени, по которому можно фильтровать объекты из связанной модели.

Он решает проблему неоднозначности и делает обратные запросы (reverse lookups) более читаемыми, особенно когда на одну модель есть несколько ссылок.

Ключевое отличие от related_name:

• related_name: Имя для доступа к связанным объектам от экземпляра. Например, author.books.all().
• related_query_name: Имя для использования в фильтрах (filter, exclude) на уровне QuerySet. Например, Author.objects.filter(book__title=...).

Если related_query_name не задан, Django по умолчанию использует значение related_name.

Пример:

Предположим, у пользователя есть два типа постов: созданные и отредактированные.

from django.db import models
from django.contrib.auth.models import User

class Post(models.Model):
    title = models.CharField(max_length=200)
    author = models.ForeignKey(
        User, 
        on_delete=models.CASCADE, 
        related_name='authored_posts',
        related_query_name='authored_post' # Имя для фильтрации
    )
    last_editor = models.ForeignKey(
        User, 
        on_delete=models.CASCADE, 
        related_name='edited_posts',
        related_query_name='edited_post' # Имя для фильтрации
    )

Теперь мы можем выполнять интуитивно понятные запросы:

# Найти всех пользователей, которые являются авторами постов с заголовком 'Django Intro'
User.objects.filter(authored_post__title='Django Intro')

# Найти всех пользователей, которые редактировали посты с заголовком 'Django Intro'
User.objects.filter(edited_post__title='Django Intro')

Без related_query_name пришлось бы использовать authored_posts__title и edited_posts__title, что может быть менее очевидно.