Django FilteredRelationだけじゃない！relation_nameの代替手法を比較解説

2025-05-27

db.models.FilteredRelation は、DjangoのORM（Object-Relational Mapper）で、特定の条件に基づいて関連するオブジェクトをフィルタリングしてアノテーション（集計や追加の情報を付与すること）を行う際に使用されるクラスです。

この FilteredRelation クラスのコンストラクタ（初期化メソッド）に渡される引数の一つが relation_name です。

`relation_name` の役割

relation_name は、どの関連（リレーション）に対してフィルタリングを適用するかを指定する文字列です。

具体的には、Djangoモデル間で定義されたリレーションシップ（例: ForeignKey, ManyToManyField, OneToOneField など）のフィールド名、またはリレーションシップを辿るパス（例: related_model__field_name のようにダブルアンダースコア __ で連結されたパス）を指定します。

例

例えば、Book モデルと Author モデルがあり、Book モデルが author という ForeignKey で Author モデルを参照しているとします。

# models.py
from django.db import models

class Author(models.Model):
    name = models.CharField(max_length=100)

class Book(models.Model):
    title = models.CharField(max_length=200)
    author = models.ForeignKey(Author, on_delete=models.CASCADE)
    is_published = models.BooleanField(default=True)

ここで、特定の著者が書いた本の中で「出版済み」の本だけをカウントしたい場合を考えます。FilteredRelation を使うと、以下のように書けます。

from django.db.models import Count, FilteredRelation, Q

# Authorごとに、出版済みの本の数をカウントする
authors_with_published_book_count = Author.objects.annotate(
    published_books=FilteredRelation(
        'book',  # ここが relation_name。AuthorモデルからBookモデルへのリレーション名
        condition=Q(book__is_published=True) # Bookモデルのis_publishedがTrueのものをフィルタリング
    ),
    published_book_count=Count('published_books__id') # フィルタリングされたリレーションのIDをカウント
)

for author in authors_with_published_book_count:
    print(f"{author.name}: Published Books = {author.published_book_count}")

上記の例では、'book' が relation_name です。これは、Author モデルから Book モデルへの逆リレーション（Author のインスタンスからその著者に関連する Book の集合を参照する際にDjangoが自動的に生成するリレーション名、通常は小文字のモデル名）を指しています。

もし、Book モデルの author フィールドに related_name='books_by_author' のような related_name が設定されていれば、その related_name を relation_name として指定することもできます。

# models.py
class Book(models.Model):
    title = models.CharField(max_length=200)
    author = models.ForeignKey(Author, on_delete=models.CASCADE, related_name='books_by_author')
    is_published = models.BooleanField(default=True)

# クエリ
authors_with_published_book_count = Author.objects.annotate(
    published_books=FilteredRelation(
        'books_by_author', # related_name を指定
        condition=Q(books_by_author__is_published=True)
    ),
    published_book_count=Count('published_books__id')
)

注意点

relation_name には、ルックアップ（__ を使ったフィールドの検索）を含めることはできません。例えば、'comment__set' のような指定はできません。あくまで、FilteredRelation を適用したい直接のリレーションの名前（または related_name）を指定します。フィルタリング条件は condition 引数で指定します。
relation_name は、クエリを実行するモデルからの相対的なパスで指定します。

FilteredRelation は非常に強力な機能ですが、その relation_name の指定方法を誤ると、様々なエラーに遭遇する可能性があります。

FieldError: Cannot resolve keyword 'xxx' into field. Choices are ...

これは最も一般的なエラーの一つです。relation_name で指定した文字列が、クエリを実行しているモデルから辿れる有効なリレーション名ではない場合に発生します。

原因

relation_name にルックアップを含めている
relation_name には __ (ダブルアンダースコア) を使ったフィールドのルックアップ（例: 'author__name'）を含めることはできません。relation_name はあくまで直接のリレーション名を指定し、フィルタリング条件は condition 引数で指定します。
リレーションのパスの誤り
多段のリレーションを辿る際に、途中のリレーション名が間違っている。
リレーション名の誤解
- ForeignKey や OneToOneField のフィールド名を指定すべきなのに、間違った名前を指定している。
- 逆リレーション（_set が付くことが多い）の名前を間違って指定している。related_name を指定している場合は、その related_name を正確に指定する必要があります。
スペルミス
relation_name の文字列にスペルミスがある。

トラブルシューティング

モデル定義の確認
relation_name が指しているモデルのリレーション定義（ForeignKey, ManyToManyField など）を再確認してください。
フィールド名の確認
- もし正方向のリレーション（例: Book から Author への author フィールド）であれば、そのフィールド名を正確に指定します。
- 逆方向のリレーション（例: Author から Book へのリレーション）であれば、デフォルトのリレーション名（通常は関連モデルの小文字名、例: book_set）または related_name で指定した名前を正確に指定します。

インタラクティブシェルで確認
Djangoのシェル（python manage.py shell）で、問題のモデルから _meta.get_fields() などを使って、利用可能なリレーション名を確認してみると良いでしょう。

# 例: AuthorモデルからBookモデルへのリレーションを確認
from myapp.models import Author
print([f.name for f in Author._meta.get_fields() if f.is_relation])
# ['book', 'books_by_author', ...] のように表示されるはず

relation_name と condition の分離
relation_name には単純なリレーション名のみを指定し、そのリレーション内のフィールドに対する条件は必ず condition=Q(...) の中に記述してください。

誤った例
```
FilteredRelation('book__is_published', condition=Q(book__is_published=True)) # relation_nameにルックアップを含めている
```
正しい例
```
FilteredRelation('book', condition=Q(book__is_published=True))
```

ValueError: QuerySet values after FilteredRelation must include 'xxx'

これは、FilteredRelation を使用してアノテーションを作成し、その後 values() や values_list() で特定のフィールドを選択しようとした際に、FilteredRelation で作成されたエイリアスが含まれていない場合に発生することがあります。

原因

FilteredRelation は内部的にSQLのLEFT JOINのような形で動作し、新しいエイリアス（一時的なテーブル名やカラム名）を生成します。values() や values_list() を使用して結果を整形する場合、このエイリアス名も結果に含める必要があります。

トラブルシューティング

FilteredRelation を使用して生成されたエイリアス名を values() または values_list() の引数に含めます。通常、FilteredRelation で指定したエイリアス名（上記の例では published_books）とそのエイリアスのフィールド（例: published_books__id）を指定します。

# エラーが発生する可能性のある例
authors_with_published_book_count = Author.objects.annotate(
    published_books=FilteredRelation(
        'book',
        condition=Q(book__is_published=True)
    ),
    published_book_count=Count('published_books__id')
).values('name', 'published_book_count') # ここでpublished_booksが含まれていない

# 修正例
authors_with_published_book_count = Author.objects.annotate(
    published_books=FilteredRelation(
        'book',
        condition=Q(book__is_published=True)
    ),
    published_book_count=Count('published_books__id')
).values('name', 'published_book_count', 'published_books') # published_booksを追加

ただし、通常 Count などの集計関数と FilteredRelation を組み合わせる場合は、values() や values_list() に集計結果のエイリアス（例: published_book_count）を含めるだけで十分なことが多いです。FilteredRelation 自体のエイリアス（published_books）は、そのエイリアスを直接参照する必要がある場合（例えば、そのエイリアス経由でさらに別のフィールドを抽出したい場合など）にのみ含めることが一般的です。

期待する結果が得られない（フィルタリングが効いていない、または結果が少ない/多い）

これはエラーメッセージが出ないため、デバッグが難しいケースです。

原因

結合の性質の理解不足
FilteredRelation は LEFT JOIN のように動作します。これにより、フィルタリング条件に一致する関連オブジェクトがない場合でも、元のクエリセットのオブジェクトは結果に含まれます（ただし、アノテーションされた値は None や 0 になります）。もし INNER JOIN のような動作を期待している（関連オブジェクトが存在しない行は除外したい）場合は、filter() メソッドを組み合わせる必要があります。
relation_name と condition の不一致
relation_name で指定したリレーションと、condition 内で参照しているフィールドのパスが一致していない。例えば、relation_name='book' なのに condition=Q(comment__text='...') のように全く異なるリレーションのフィールドを参照している場合など。
condition の誤り
FilteredRelation の condition 引数に渡す Q オブジェクトの条件が正しくない。
- フィールド名が間違っている。
- 比較演算子が間違っている。
- 論理演算子（&, |）の組み合わせが意図通りではない。

トラブルシューティング

condition のデバッグ
- Q オブジェクトの条件をシンプルにして、意図通りにフィルタリングされるかを確認します。
- 複雑な Q オブジェクトの場合、複数の Q オブジェクトに分割してテストします。
- Q オブジェクト内のフィールド名が、relation_name で指定したリレーションから辿れるパスになっていることを確認します。
SQLクエリの確認
queryset.query を出力して、Djangoが生成するSQLクエリを確認します。特に JOIN 句や WHERE 句が意図通りになっているかを確認します。
```
print(authors_with_published_book_count.query)
```
SQLクエリを見ることで、FilteredRelation がどのように JOIN を生成し、WHERE 句を適用しているか理解できます。

filter() との組み合わせ
もし LEFT JOIN ではなく、関連オブジェクトが存在しない親オブジェクトを除外したい場合は、FilteredRelation でアノテーションした後、そのアノテーションされたフィールドに対して filter() を適用します。

# 出版済みの本がある著者のみを対象とする場合
authors_with_published_book_count = Author.objects.annotate(
    published_books=FilteredRelation(
        'book',
        condition=Q(book__is_published=True)
    ),
    published_book_count=Count('published_books__id')
).filter(published_book_count__gt=0) # published_book_countが0より大きいもののみフィルタ

FilteredRelation は、特定の条件に基づいて関連オブジェクトをフィルタリングし、それを元のクエリセットにアノテーション（追加情報として付与）する際に非常に役立ちます。relation_name は、このフィルタリングをどのリレーションシップに対して行うかを指定します。

以下の例では、ブログアプリケーションを想定し、Author (著者)、Article (記事)、Comment (コメント) の3つのモデルを使用します。

モデルの定義

まず、models.py に以下のモデルを定義します。

# myapp/models.py
from django.db import models

class Author(models.Model):
    name = models.CharField(max_length=100)
    email = models.EmailField(unique=True)

    def __str__(self):
        return self.name

class Article(models.Model):
    title = models.CharField(max_length=200)
    content = models.TextField()
    pub_date = models.DateTimeField(auto_now_add=True)
    author = models.ForeignKey(Author, on_delete=models.CASCADE, related_name='articles')
    is_published = models.BooleanField(default=False) # 公開済みか否か

    def __str__(self):
        return self.title

class Comment(models.Model):
    article = models.ForeignKey(Article, on_delete=models.CASCADE, related_name='comments')
    author_name = models.CharField(max_length=100)
    text = models.TextField()
    created_at = models.DateTimeField(auto_now_add=True)
    is_approved = models.BooleanField(default=False) # 承認済みか否か

    def __str__(self):
        return f"Comment by {self.author_name} on {self.article.title[:20]}..."

例1: 各著者の公開済み記事数をカウントする

この例では、各著者について、is_published=True の記事の数をカウントします。

from django.db.models import Count, FilteredRelation, Q
from myapp.models import Author, Article

# 各著者の公開済み記事数をアノテーション
authors_with_published_article_count = Author.objects.annotate(
    # 'articles' は Author モデルから Article モデルへの related_name
    published_articles_relation=FilteredRelation(
        'articles',
        condition=Q(articles__is_published=True)
    ),
    published_article_count=Count('published_articles_relation__id')
)

# 結果の表示
for author in authors_with_published_article_count:
    print(f"著者: {author.name}, 公開済み記事数: {author.published_article_count}")

"""
出力例 (データによる):
著者: Alice, 公開済み記事数: 2
著者: Bob, 公開済み記事数: 1
著者: Charlie, 公開済み記事数: 0
"""

relation_name の説明

published_articles_relation は FilteredRelation によって作成される一時的なエイリアス名です。このエイリアスを通して、フィルタリングされた記事の id をカウントしています。
condition=Q(articles__is_published=True) で、この 'articles' リレーションの中から is_published が True の記事のみを対象とするフィルタリング条件を定義しています。
ここでは 'articles' を relation_name として指定しています。これは Author モデルの articles という related_name を指しており、Author から Article へ逆方向にリレーションを辿ることを示しています。

例2: 各記事の承認済みコメント数をカウントする

この例では、各記事について、is_approved=True のコメントの数をカウントします。

from django.db.models import Count, FilteredRelation, Q
from myapp.models import Article, Comment

# 各記事の承認済みコメント数をアノテーション
articles_with_approved_comment_count = Article.objects.annotate(
    # 'comments' は Article モデルから Comment モデルへの related_name
    approved_comments_relation=FilteredRelation(
        'comments',
        condition=Q(comments__is_approved=True)
    ),
    approved_comment_count=Count('approved_comments_relation__id')
)

# 結果の表示
for article in articles_with_approved_comment_count:
    print(f"記事: {article.title}, 承認済みコメント数: {article.approved_comment_count}")

"""
出力例 (データによる):
記事: Django の基本, 承認済みコメント数: 3
記事: Python の新しい機能, 承認済みコメント数: 1
記事: 未公開の記事, 承認済みコメント数: 0
"""

relation_name の説明

condition=Q(comments__is_approved=True) で、この 'comments' リレーションの中から is_approved が True のコメントのみを対象とするフィルタリング条件を定義しています。
ここでは 'comments' を relation_name として指定しています。これは Article モデルの comments という related_name を指しており、Article から Comment へ逆方向にリレーションを辿ることを示しています。

例3: 特定の条件を満たすコメントを持つ記事とそのコメント数を取得する

この例では、特定のキーワード（例: "素晴らしい"）を含む承認済みコメントを持つ記事を抽出し、そのコメント数をカウントします。

from django.db.models import Count, FilteredRelation, Q
from myapp.models import Article, Comment

# "素晴らしい"というキーワードを含む承認済みコメントを持つ記事と、そのコメント数を取得
articles_with_specific_approved_comments = Article.objects.annotate(
    specific_approved_comments=FilteredRelation(
        'comments',
        condition=Q(comments__is_approved=True, comments__text__icontains="素晴らしい")
    ),
    specific_approved_comment_count=Count('specific_approved_comments__id')
).filter(specific_approved_comment_count__gt=0) # 少なくとも1つ該当コメントがある記事のみ

# 結果の表示
for article in articles_with_specific_approved_comments:
    print(f"記事: {article.title}, 特定の承認済みコメント数: {article.specific_approved_comment_count}")

"""
出力例 (データによる):
記事: Django の基本, 特定の承認済みコメント数: 1
"""

relation_name の説明

condition=Q(comments__is_approved=True, comments__text__icontains="素晴らしい") は、comments リレーション内のコメントが「承認済み」であり、かつ「テキストに"素晴らしい"を含む」という複合条件を指定しています。
この場合も 'comments' が relation_name です。

FilteredRelation は、以下のような場合に特に有効です。

LEFT JOIN のように、関連オブジェクトが存在しない場合でも、元のモデルのレコードを結果に含めたいが、関連オブジェクトには特定の条件を適用したい場合。
関連オブジェクトを特定の条件でフィルタリングし、そのフィルタリングされた結果に基づいて集計（カウント、合計など）を行いたい場合。

`db.models.FilteredRelation` の代替手段

Count (または他の集計関数) の filter 引数を使う (Django 2.0 以降)

これは FilteredRelation の最も一般的な代替手段であり、Django 2.0 以降で導入された強力な機能です。Count や Sum などの集計関数に直接 filter 引数を渡すことで、条件付き集計を行うことができます。これにより、FilteredRelation を使うよりも簡潔に書けることが多いです。

特徴

多くの場合、これで十分な要件を満たせます。
FilteredRelation と同様に、内部的に CASE 文または FILTER WHERE 句（PostgreSQLなど）に変換され、効率的なSQLが生成されます。
最も簡潔な記述方法。

例 (各著者の公開済み記事数をカウント)

from django.db.models import Count, Q
from myapp.models import Author, Article

authors_with_published_article_count = Author.objects.annotate(
    # related_name 'articles' を使用し、そのリレーション内の is_published=True でフィルタリング
    published_article_count=Count('articles', filter=Q(articles__is_published=True))
)

for author in authors_with_published_article_count:
    print(f"著者: {author.name}, 公開済み記事数: {author.published_article_count}")

Case と When を使った条件付きアノテーション

Case と When を組み合わせることで、SQLの CASE 文を模倣し、条件に応じて異なる値をアノテーションできます。これを集計関数と組み合わせることで、FilteredRelation と同じような条件付き集計を実現できます。

特徴

FilteredRelation より冗長になることがある。
集計だけでなく、条件に基づいてフィールドの値を変更するなど、様々なアノテーションに応用可能。
より柔軟な条件付きアノテーションが可能。特定の条件で値を設定し、それ以外の場合は別の値を設定するといった複雑なロジックに対応できる。

例 (各著者の公開済み記事数をカウント)

from django.db.models import Count, Case, When, Value, IntegerField, Q
from myapp.models import Author, Article

authors_with_published_article_count = Author.objects.annotate(
    # articles リレーションの各記事について、is_published=True なら 1、そうでなければ 0 を返す
    # その後、それらの値を合計してカウントとする
    published_article_count=Count(
        Case(
            When(articles__is_published=True, then=Value(1)),
            default=Value(0),
            output_field=IntegerField()
        )
    )
)

for author in authors_with_published_article_count:
    print(f"著者: {author.name}, 公開済み記事数: {author.published_article_count}")

解説
この方法では、Case 式を使って各 Article が公開済みであれば 1 を、そうでなければ 0 を返します。Count 関数は NULL 値を無視するため、default=Value(0) を指定することで、非公開記事も 0 としてカウントに含まれ、合計で記事数として数えられてしまいます。 Count が NULL 以外の値をカウントする性質を利用する場合は、default=None にするか、else=None のように明示的に NULL を返すようにします。

より正確なカウントの例 (Count は NULL を無視するため)

from django.db.models import Count, Case, When, Value, IntegerField
from myapp.models import Author, Article

authors_with_published_article_count = Author.objects.annotate(
    # articles リレーションの各記事について、is_published=True なら記事のIDを、そうでなければ None を返す
    # Count は None を無視するため、公開済み記事のIDのみをカウントする
    published_article_count=Count(
        Case(
            When(articles__is_published=True, then='articles__id'), # 公開済みならIDを返す
            default=Value(None), # 公開済みでなければ None を返す
            output_field=IntegerField() # 出力は整数型
        )
    )
)

for author in authors_with_published_article_count:
    print(f"著者: {author.name}, 公開済み記事数: {author.published_article_count}")

この修正により、Count は NULL を無視するため、公開済みの記事のIDのみをカウントし、正しい結果が得られます。

サブクエリ (Subquery) と OuterRef

より複雑なケースや、Django ORM の通常の annotate では対応できないようなアノテーションを行う場合、サブクエリを使用することができます。Subquery と OuterRef を組み合わせることで、外側のクエリの値をサブクエリに渡して、行ごとに計算を行うことができます。

特徴

パフォーマンス面で注意が必要な場合がある（サブクエリの実行計画による）。
コードが複雑になりがちで、デバッグが難しい場合がある。
最も柔軟性が高く、複雑なデータベース操作に対応できる。

例 (各著者の公開済み記事数をカウント)

from django.db.models import Count, OuterRef, Subquery
from myapp.models import Author, Article

# サブクエリ: 特定の著者の公開済み記事の数をカウント
# OuterRef('pk') で外側のクエリ (Author) のプライマリキーを参照
published_articles_subquery = Article.objects.filter(
    author=OuterRef('pk'), # 外側のクエリの Author のIDと一致する記事をフィルタ
    is_published=True
).order_by().values('author').annotate(
    count=Count('pk')
).values('count') # count の値のみを取得

# Author クエリセットにサブクエリの結果をアノテーション
authors_with_published_article_count = Author.objects.annotate(
    published_article_count=Subquery(published_articles_subquery, output_field=IntegerField())
)

for author in authors_with_published_article_count:
    # サブクエリで該当するデータがない場合、None が返されるため、0 に変換
    count = author.published_article_count if author.published_article_count is not None else 0
    print(f"著者: {author.name}, 公開済み記事数: {count}")

Subquery は、このサブクエリの結果を Author クエリセットの各行にアノテーションします。
order_by().values('author').annotate(count=Count('pk')).values('count') は、サブクエリが単一のカウント値を返すように整形しています。
OuterRef('pk') は、サブクエリが外側のクエリの現在の行の pk フィールドを参照できるようにします。
published_articles_subquery は、Article モデルに対して、外側の Author の pk（プライマリキー）と一致し、かつ is_published=True な記事の数をカウントするサブクエリです。

上記の方法では実現できない、非常に特殊で複雑なクエリ が必要な場合は、Subquery と OuterRef を検討します。ただし、パフォーマンスと複雑さのトレードオフを理解しておく必要があります。
より複雑な条件や、集計以外の条件付きアノテーションが必要な場合 は、Case と When が強力な選択肢となります。
Django 2.0 以降を使用している場合、ほとんどの条件付き集計のケースでは、Count の filter 引数を使うのが最も推奨される方法です。 最も簡潔で読みやすく、効率的なSQLを生成します。

Django FilteredRelationだけじゃない！relation_nameの代替手法を比較解説

relation_name の役割

注意点

FieldError: Cannot resolve keyword 'xxx' into field. Choices are ...

ValueError: QuerySet values after FilteredRelation must include 'xxx'

期待する結果が得られない（フィルタリングが効いていない、または結果が少ない/多い）

モデルの定義

例1: 各著者の公開済み記事数をカウントする

例2: 各記事の承認済みコメント数をカウントする

例3: 特定の条件を満たすコメントを持つ記事とそのコメント数を取得する

db.models.FilteredRelation の代替手段

Count (または他の集計関数) の filter 引数を使う (Django 2.0 以降)

Case と When を使った条件付きアノテーション

サブクエリ (Subquery) と OuterRef

`relation_name` の役割

`db.models.FilteredRelation` の代替手段