Django ORMクエリセット完全ガイド

By /

Django ORM クエリセット 完全ガイド

Djangoフレームワークの最も強力な機能の一つに、Object-Relational Mapper（ORM）があります。ORMは、Pythonコードを使ってデータベースと対話するための抽象化レイヤーを提供し、SQLを直接書くことなくデータベースのレコードを操作することを可能にします。そして、このORMの中心的な役割を担うのが「クエリセット（Queryset）」です。

クエリセットは、データベースから取得されるオブジェクトのコレクションを表します。しかし、単なるリストとは異なり、非常に柔軟で強力な機能を持っています。この記事では、Django ORMにおけるクエリセットのあらゆる側面を網羅的に解説し、その使い方、内部の仕組み、パフォーマンス最適化の方法まで、完全に理解することを目指します。

約5000語にわたる詳細な解説を通じて、あなたはDjangoアプリケーションにおけるデータベース操作のエキスパートとなるでしょう。

1. はじめに：Django ORMとクエリセットとは？

1.1 Django ORMの役割

Django ORMは、データベースのテーブルとPythonのクラス（モデル）をマッピングします。これにより、Pythonのオブジェクトの操作を通じてデータベースのデータを操作できるようになります。

  • 抽象化: データベースの種類（PostgreSQL, MySQL, SQLiteなど）の違いを吸収します。コードは特定のデータベースシステムに依存せず、データベースバックエンドを変更してもコードの大部分はそのまま利用できます。
  • セキュリティ: SQLインジェクションのような一般的なセキュリティリスクを軽減します。ORMは自動的にクエリをエスケープ処理します。
  • 生産性: Pythonのオブジェクト指向パラダイムでデータベースを操作できるため、開発速度が向上します。複雑なデータ取得や操作も、メソッドの呼び出しや属性へのアクセスとして記述できます。

1.2 クエリセットとは

クエリセットは、データベースから取得される（または取得される予定の）オブジェクトのコレクションです。Djangoモデルのマネージャー（通常は objects）を通じて取得されます。

例えば、Book.objects.all() は Book モデルのすべてのオブジェクトを表すクエリセットを返します。

クエリセットの重要な特徴は以下の2つです。

  • 遅延評価 (Laziness): クエリセットは、それが評価される（つまり、実際にデータベースにアクセスしてデータを取得する）まで、データベースクエリを実行しません。クエリセットを作成したり、フィルタリングや順序付けのメソッドをチェーンしたりするだけでは、データベースへのアクセスは発生しません。
  • キャッシュ (Caching): 一度評価されたクエリセットの結果はメモリにキャッシュされます。同じクエリセットインスタンスに対して繰り返しアクセスしても、データベースへのアクセスは一度だけになります。

この遅延評価とキャッシュの仕組みが、クエリセットを非常に効率的かつ柔軟なものにしています。

2. クエリセットの取得：最初のステップ

すべてのクエリセット操作は、通常、モデルのマネージャーから始まります。デフォルトのマネージャーは objects という名前で、すべてのDjangoモデルに自動的に追加されます。

例として、以下のようなシンプルな Book モデルを考えます。

“`python

models.py

from django.db import models

class Author(models.Model):
name = models.CharField(max_length=100)
birth_date = models.DateField(null=True, blank=True)

def __str__(self):
    return self.name

class Book(models.Model):
title = models.CharField(max_length=200)
author = models.ForeignKey(Author, on_delete=models.CASCADE)
publication_date = models.DateField()
price = models.DecimalField(max_digits=5, decimal_places=2)
is_published = models.BooleanField(default=False)

def __str__(self):
    return self.title

“`

2.1 all() メソッド

最も基本的なクエリセットの取得方法は all() です。モデルのすべてのオブジェクトを含むクエリセットを返します。

“`python

すべての本を取得

all_books = Book.objects.all()
print(all_books) # , \, …]>
“`

all() はクエリセットを返しますが、この時点ではまだデータベースへのアクセスは行われていません。アクセスが行われるのは、例えば以下のような操作時です。

  • クエリセットをイテレートする（for ループなど）。
  • クエリセットをスライスする（all_books[:10]）。
  • クエリセットを list() 関数に渡す。
  • クエリセットに対して len() 関数を呼び出す。
  • クエリセットに対して repr() または str() を呼び出す（例: Djangoシェルでクエリセットを表示する）。
  • クエリセットに対して特定のメソッド（first(), last(), get(), count(), exists(), update(), delete() など）を呼び出す。

2.2 filter() メソッド

特定の条件を満たすオブジェクトを絞り込むには filter() メソッドを使用します。これは最も頻繁に使用されるメソッドの一つです。

“`python

2023年以降に出版された本を取得

books_2023_onward = Book.objects.filter(publication_date__year__gte=2023)

特定の著者による本を取得 (仮にAuthor IDが1の著者)

author_1_books = Book.objects.filter(author__id=1) # リレーションシップを辿ることも可能
“`

filter() メソッドもクエリセットを返します。したがって、複数の filter() 呼び出しをチェーンさせることができます。チェーンされた filter() 呼び出しは、SQLの AND 条件として結合されます。

“`python

2023年以降に出版された、かつ価格が2000円以上の本を取得

expensive_books_2023_onward = Book.objects.filter(publication_date__year__gte=2023).filter(price__gte=20.00)

これは以下と同じ意味になります:

expensive_books_2023_onward = Book.objects.filter(publication_date__year__gte=2023, price__gte=20.00)

“`

2.3 exclude() メソッド

特定の条件を満たさないオブジェクトを除外するには exclude() メソッドを使用します。filter() と同様にチェーン可能です。

“`python

未出版の本を除外して取得

published_books = Book.objects.exclude(is_published=False)

特定の著者 (ID 1) の本を除外して、2023年以降の本を取得

other_authors_books_2023 = Book.objects.filter(publication_date__year__gte=2023).exclude(author__id=1)
“`

exclude() もクエリセットを返します。複数の exclude() 呼び出しをチェーンさせることも、filter() と組み合わせてチェーンさせることも可能です。

3. クエリセットによる絞り込み：ルックアップの使い方

filter() や exclude() メソッドのキーワード引数は、フィールド名とルックアップタイプの組み合わせで構成されます。ルックアップタイプは、フィールド名の後にダブルアンダースコア (__) を付けて指定します。

基本的なフィールド名だけを指定した場合 (filter(field_name=value)) は、正確に一致 (exact) する条件とみなされます。

以下に、よく使われるルックアップタイプをいくつか紹介します。

  • exact: 正確な一致。デフォルト。Entry.objects.filter(headline__exact='Hello world') は Entry.objects.filter(headline='Hello world') と同じです。
  • iexact: 大文字・小文字を区別しない正確な一致。
    python
    # タイトルが 'django' (大文字小文字無視) の本を取得
    Book.objects.filter(title__iexact='django')
  • contains: 指定した文字列を含む。大文字・小文字を区別します。
    python
    # タイトルに 'Python' を含む本を取得
    Book.objects.filter(title__contains='Python')
  • icontains: 大文字・小文字を区別しない contains。
    python
    # タイトルに 'python' (大文字小文字無視) を含む本を取得
    Book.objects.filter(title__icontains='python')
  • startswith: 指定した文字列で始まる。大文字・小文字を区別します。
  • istartswith: 大文字・小文字を区別しない startswith。
  • endswith: 指定した文字列で終わる。大文字・小文字を区別します。
  • iendswith: 大文字・小文字を区別しない endswith。
  • gt: より大きい (Greater Than)。
  • gte: より大きいか等しい (Greater Than or Equal to)。
    python
    # 価格が3000円以上の本を取得
    Book.objects.filter(price__gte=30.00)
    # 2024年1月1日以降に出版された本を取得
    from datetime import date
    Book.objects.filter(publication_date__gte=date(2024, 1, 1))
  • lt: より小さい (Less Than)。
  • lte: より小さいか等しい (Less Than or Equal to)。
  • in: リスト、タプル、または他のクエリセットに含まれる値に一致する。
    python
    # タイトルが 'Book A' または 'Book C' の本を取得
    Book.objects.filter(title__in=['Book A', 'Book C'])
    # 特定の著者たち (ID 1または3) の本を取得
    Book.objects.filter(author__id__in=[1, 3])
    # 特定の条件を満たす著者たちの本を取得 (サブクエリのようなもの)
    popular_authors = Author.objects.filter(book__publication_date__year__gte=2020).distinct()
    Book.objects.filter(author__in=popular_authors)
  • range: 範囲内の値に一致する。2つの要素を持つリストまたはタプルを受け取ります（両端を含む）。日付や数値フィールドでよく使われます。
    python
    # 2023年中の本を取得
    Book.objects.filter(publication_date__range=('2023-01-01', '2023-12-31'))
  • isnull: IS NULL または IS NOT NULL に対応します。True または False を受け取ります。
    python
    # 著者情報が設定されていない本を取得
    # (このモデル定義ではForeignKeyはnull=Falseがデフォルトなので、ありえないケースですが例として)
    Book.objects.filter(author__isnull=True)
    # 出版日が設定されている本を取得
    Book.objects.filter(publication_date__isnull=False)
  • regex: 正規表現に一致する。大文字・小文字を区別します。
  • iregex: 大文字・小文字を区別しない正規表現に一致する。

3.1 リレーションシップを辿るルックアップ

外部キー (ForeignKey) や多対多 (ManyToManyField) フィールドを通じて、関連モデルのフィールドをルックアップ条件に使用できます。これを行うには、フィールド名をダブルアンダースコアで区切りながらリレーションシップを辿ります。

“`python

著者の名前が ‘Jane Austen’ の本を取得

Book.objects.filter(author__name=’Jane Austen’)

2023年以降に出版された本を書いた著者の名前を取得

まず該当する本を取得し、それぞれの著者にアクセス

books_2023 = Book.objects.filter(publication_date__year__gte=2023)
author_names = [book.author.name for book in books_2023] # これはN+1問題を引き起こす可能性あり (後述)

より効率的に著者オブジェクトを取得したい場合は distinct() を使う

authors_2023 = Author.objects.filter(book__publication_date__year__gte=2023).distinct()
“`

リレーションシップのルックアップは、filter() だけでなく、order_by() や annotate() など、他のクエリセットメソッドでも使用できます。

4. クエリセットの順序付け：order_by()

取得したオブジェクトの順序を指定するには order_by() メソッドを使用します。

“`python

タイトルで昇順に並べ替え

books_ordered_by_title = Book.objects.all().order_by(‘title’)

出版日で降順に並べ替え

books_ordered_by_date_desc = Book.objects.all().order_by(‘-publication_date’)
“`

フィールド名の前にハイフン (-) を付けると降順になります。複数のフィールドを指定して、プライマリソートキー、セカンダリソートキー…と指定することも可能です。

“`python

著者の名前で昇順、次にタイトルで昇順に並べ替え

books_ordered = Book.objects.all().order_by(‘author__name’, ‘title’)
“`

4.1 ランダムな順序

データベースバックエンドがサポートしている場合、ランダムな順序で取得するには order_by('?') を使用します。

“`python

ランダムな本を1冊取得したい場合など

random_book = Book.objects.order_by(‘?’).first()
“`

ただし、order_by('?') はデータベースによっては非常に効率が悪くなる可能性があるため、大量のデータを扱う際には注意が必要です。

4.2 デフォルトの順序とソートの解除

モデルのMetaクラスで ordering オプションを指定すると、そのモデルのデフォルトの順序を設定できます。

python
class Book(models.Model):
# ...
class Meta:
ordering = ['title'] # デフォルトでタイトル昇順

デフォルトの順序を持つクエリセットに対して、order_by() を引数なしで呼び出すと、その順序を解除できます。

“`python

デフォルトの順序 (title) で取得

books_default_order = Book.objects.all()

デフォルトの順序を解除して、順序指定なしで取得 (通常はプライマリキーなどで順序付けされる)

books_no_order = Book.objects.all().order_by()
“`

5. クエリセットの絞り込みと単一オブジェクトの取得

取得するオブジェクトの数や、特定のオブジェクトを1つだけ取得したい場合に使うメソッドです。

5.1 スライシング

Pythonのスライシング構文を使って、クエリセットを制限できます。

“`python

最初の10冊の本を取得

first_10_books = Book.objects.all()[:10]

11冊目から20冊目までの本を取得

books_11_to_20 = Book.objects.all()[10:20]

最初の100冊だけを効率的に取得

first_100_books_list = list(Book.objects.all()[:100])
“`

スライシングは、SQLの LIMIT および OFFSET 句に変換されます。負のインデックス（例: qs[-1]）やステップ値（例: qs[::2]）はデータベースレベルではサポートされないため、クエリセット全体がまずフェッチされてからPython内で処理されます。これは非効率なので避けるべきです。

スライシングされたクエリセットは新しいクエリセットインスタンスを返します。これは遅延評価であり、例えば qs[:10] はすぐにデータベースにアクセスするわけではありません。

5.2 first() と last()

クエリセットの最初のオブジェクトまたは最後のオブジェクトを取得します。

“`python

最初の本を取得 (順序指定がない場合は不定)

first_book = Book.objects.first()

出版日が最も古い本を取得 (まず出版日で昇順に並べ替え)

oldest_book = Book.objects.order_by(‘publication_date’).first()

出版日が最も新しい本を取得 (まず出版日で降順に並べ替え)

latest_book = Book.objects.order_by(‘-publication_date’).first()

または

latest_book = Book.objects.order_by(‘publication_date’).last() # last() は内部的に降順にしてfirst()を取得する
“`

first() および last() は、クエリセットが空の場合は None を返します。

5.3 get()

特定の条件に厳密に一致する単一のオブジェクトを取得します。

“`python

IDが5の本を正確に1冊取得

book_with_id_5 = Book.objects.get(id=5)

タイトルが ‘The Hitchhiker\’s Guide to the Galaxy’ の本を正確に1冊取得

hitchhiker_book = Book.objects.get(title=’The Hitchhiker\’s Guide to the Galaxy’)
“`

get() メソッドは、以下のいずれかの場合に例外を発生させます。

  • 条件に一致するオブジェクトが見つからない場合 (Book.DoesNotExist 例外)。
  • 条件に一致するオブジェクトが複数見つかった場合 (Book.MultipleObjectsReturned 例外)。

したがって、get() は条件に一致するオブジェクトが必ず1つだけ存在すると分かっている場合に使用すべきです。そうでない場合は、filter() と first() を組み合わせる方が安全です (Book.objects.filter(...).first())。

5.4 get_or_create() および update_or_create()

これらのメソッドは、オブジェクトの取得と作成または更新をアトミックに行いたい場合に便利です。

  • get_or_create(defaults=None, **kwargs): 指定した kwargs に一致するオブジェクトがあれば取得し、なければ作成します。作成時には defaults 辞書の値を適用します。戻り値は (object, created) のタプルで、object は取得または作成されたオブジェクト、created は新しく作成された場合は True、取得された場合は False です。
    python
    # 名前が 'Leo Tolstoy' の著者を検索し、いなければ作成
    author, created = Author.objects.get_or_create(
    name='Leo Tolstoy',
    defaults={'birth_date': date(1828, 9, 9)}
    )
    if created:
    print("新しい著者を作成しました:", author.name)
    else:
    print("既存の著者を取得しました:", author.name)
  • update_or_create(defaults=None, **kwargs): 指定した kwargs に一致するオブジェクトがあれば更新し、なければ作成します。戻り値は (object, created) のタプルで、object は更新または作成されたオブジェクト、created は新しく作成された場合は True、既存オブジェクトが更新された場合は False です。
    python
    # タイトルが 'War and Peace' でレオ・トルストイの本を検索。
    # あれば価格を更新、なければ新しい本として作成。
    book, created = Book.objects.update_or_create(
    title='War and Peace',
    author=author, # 上で取得/作成したauthorオブジェクト
    defaults={'price': 25.50, 'publication_date': date(1869, 1, 1)}
    )
    if created:
    print("新しい本を作成しました:", book.title)
    else:
    print("既存の本を更新しました:", book.title)
    これらのメソッドは、データベースの制約（例: ユニーク制約）を活用して、競合状態を避けるように設計されていますが、完璧なアトミック性を保証するわけではありません。

6. クエリセットによるオブジェクトの作成、更新、削除

クエリセットは、複数のオブジェクトに対してまとめて作成、更新、削除を行うための効率的なメソッドも提供します。

6.1 オブジェクトの作成

個別のオブジェクトを作成する場合は、モデルクラスのインスタンスを作成し、save() メソッドを呼び出します。

“`python

新しい著者を作成

new_author = Author(name=’J.K. Rowling’)
new_author.save() # データベースに保存

新しい本を作成 (既存の著者が必要)

rowling_author = Author.objects.get(name=’J.K. Rowling’)
new_book = Book(
title=’Harry Potter and the Sorcerer\’s Stone’,
author=rowling_author,
publication_date=date(1997, 6, 26),
price=19.95,
is_published=True
)
new_book.save() # データベースに保存
“`

複数のオブジェクトを一度に作成したい場合は、bulk_create() メソッドが非常に効率的です。

“`python

複数の著者オブジェクトをリストで作成

authors_to_create = [
Author(name=’George Orwell’),
Author(name=’Aldous Huxley’),
Author(name=’F. Scott Fitzgerald’),
]

bulk_create() を使って一度にデータベースに挿入

これはINSERT文を効率的に生成する

created_authors = Author.objects.bulk_create(authors_to_create)
print(f”{len(created_authors)} 人の著者が作成されました。”)
“`

bulk_create() は通常、個々のオブジェクトの save() メソッドを呼び出しません。また、post_save シグナルは送信されません。主キーの値は通常、メソッド呼び出し後にオブジェクトに設定されます（ただし、一部のデータベースバックエンドでは制限がある場合があります）。

6.2 オブジェクトの更新：update()

クエリセットに対して update() メソッドを呼び出すと、一致するすべてのオブジェクトを単一のSQLクエリで更新できます。

“`python

すべての未出版の本を出版済みにする

published_count = Book.objects.filter(is_published=False).update(is_published=True)
print(f”{published_count} 冊の本が出版されました。”)

特定の著者のすべての本の価格を10%値上げする

Fオブジェクトを使用すると、現在のフィールド値に基づいて更新できる (後述)

from django.db.models import F
Author.objects.filter(name=’J.K. Rowling’).update(price=F(‘price’) * 1.1)
“`

update() メソッドは、更新された行数を返します。
update() はクエリセットに対して直接作用するため、個々のモデルインスタンスを取得して save() を呼び出すよりもはるかに効率的です。例えば、1000冊の本の価格を更新する場合、ループして1000回の save() を行うよりも、単一の update() 呼び出しの方が圧倒的に高速です。

update() を呼び出した場合、個々のモデルの save() メソッドは呼ばれず、pre_save/post_save シグナルも送信されません。

6.3 オブジェクトの削除：delete()

クエリセットに対して delete() メソッドを呼び出すと、一致するすべてのオブジェクトをデータベースから削除できます。

“`python

2020年より前に出版されたすべての本を削除

deleted_count, _ = Book.objects.filter(publication_date__year__lt=2020).delete()
print(f”{deleted_count} 冊の本が削除されました。”)

特定の著者を削除（関連する本もForeignKeyのon_delete=models.CASCADEにより削除される）

author_to_delete = Author.objects.get(name=’Aldous Huxley’)
deleted_count, detailed_counts = author_to_delete.delete()
print(f”オブジェクト総数: {deleted_count}”)
print(f”詳細: {detailed_counts}”) # 削除されたオブジェクトの数と種類を示す辞書
“`

delete() メソッドは、削除されたオブジェクトの総数と、モデルごとの削除数を要素とするタプルを返します。
update() と同様に、delete() も個々のモデルインスタンスを取得して削除するより効率的です。また、モデルの delete() メソッドや pre_delete/post_delete シグナルは、関連オブジェクトのカスケード削除を含め、期待通りに機能します（update とは異なる挙動に注意）。

7. クエリセットの評価とキャッシュ

前述したように、クエリセットは「遅延評価」され、一度評価されるとその結果が「キャッシュ」されます。これを理解することは、効率的なコードを書く上で非常に重要です。

7.1 遅延評価 (Laziness)

クエリセットを作成したり、チェーンメソッドを呼び出したりするだけでは、データベースへのアクセスは発生しません。SQLクエリは、クエリセットが必要になったときに初めて実行されます。

“`python

この時点ではまだデータベースへのアクセスはなし

qs = Book.objects.filter(is_published=True).order_by(‘-publication_date’)

ここで初めてデータベースにアクセス

for book in qs:
print(book.title)

ここでもデータベースにアクセス (別の評価)

first_book = qs.first()

ここでもデータベースにアクセス (別の評価)

count = qs.count()
“`

この遅延評価のおかげで、あなたは必要なフィルタリング、順序付け、スライシングなどを組み合わせてクエリセットを構築し、必要な時に必要な形で評価させることができます。

7.2 キャッシュ (Caching)

一度評価されたクエリセットの結果は、そのクエリセットインスタンス内にキャッシュされます。同じインスタンスに対して後続の操作を行う際に、再度データベースにアクセスするのではなく、キャッシュされた結果が使用されます。

“`python

ここでクエリセットを評価し、結果がqsインスタンスにキャッシュされる

qs = Book.objects.all()
print(qs[0].title) # アクセス1回目、評価発生 -> キャッシュ

同じqsインスタンスからのアクセスなので、キャッシュされた結果が使用される

print(qs[1].title) # キャッシュから取得

スライシングは評価をトリガーするが、キャッシュも利用する

first_three = qs[:3] # qsのキャッシュから最初の3つを取得 (追加のDBアクセスなし)

count() も評価をトリガーするが、既にキャッシュがある場合はそれを利用

注意: evalされたキャッシュがあればlen(qs)と同じになるが、

count()は評価されていないクエリセットに対しても効率的なCOUNT(*)クエリを発行できる

count = qs.count() # キャッシュがあればそこからlen()を取得、なければCOUNT(*)クエリ

新しいクエリセットインスタンスを作成した場合、キャッシュは共有されない

qs2 = Book.objects.all() # 新しいインスタンス、キャッシュなし
print(qs2[0].title) # アクセス1回目、評価発生 -> qs2にキャッシュ
“`

重要な注意点: filter(), exclude(), order_by(), annotate() など、新しいクエリセットを返すメソッドは、元のクエリセットのキャッシュを引き継ぎません。

“`python
all_books = Book.objects.all() # キャッシュなし

all_booksをイテレート -> 評価発生 -> all_booksに結果がキャッシュされる

for book in all_books:
print(book.title)

新しいクエリセットが作成される (all_booksのキャッシュは引き継がれない)

published_books = all_books.filter(is_published=True) # キャッシュなし

published_booksをイテレート -> 評価発生 -> データベースアクセス -> published_booksに結果がキャッシュされる

for book in published_books:
print(book.title)
“`

この挙動を理解していないと、意図せず繰り返しデータベースにアクセスしてしまう（N+1問題など）可能性があります。

8. パフォーマンス最適化

クエリセットの遅延評価とキャッシュの仕組みを理解した上で、パフォーマンスを最大化するためのテクニックをいくつか紹介します。

8.1 N+1問題とその解決策

最も一般的なパフォーマンス問題の一つが「N+1問題」です。これは、一つのクエリで親オブジェクトのリストを取得した後、子オブジェクトの情報を取得するために、リスト内の各親オブジェクトごとに個別のクエリが実行される場合に発生します。

例：すべての本のタイトルと著者の名前を表示したい場合。

“`python

非効率な例 (N+1問題)

books = Book.objects.all()
for book in books:
# book.author にアクセスするたびに、author_id に基づいてデータベースからAuthorオブジェクトを取得するクエリが実行される
# Bookが100冊あれば、100回のAuthorオブジェクト取得クエリが実行される可能性がある (合計1 + 100 = 101クエリ)
print(f”Title: {book.title}, Author: {book.author.name}”)
“`

これを解決するには、select_related() と prefetch_related() を使用します。

  • select_related(*fields): ForeignKey や OneToOneField のような「一対一」の関係にあるオブジェクトを、親オブジェクトを取得するクエリと同時に（SQLの JOIN を使って）取得します。これにより、関連オブジェクトへのアクセスに追加のクエリが発生しなくなります。

    “`python

    効率的な例 (select_relatedを使用)

    Bookオブジェクトを取得する際に、関連するAuthorオブジェクトもJOINで取得する

    books_with_author = Book.objects.select_related(‘author’).all()
    for book in books_with_author:
    # author オブジェクトは既に取得されているため、追加のクエリは発生しない
    print(f”Title: {book.title}, Author: {book.author.name}”)

    この操作全体で実行されるクエリはBookとAuthorをJOINした1つだけ

    “`

    複数のリレーションシップを辿ることも可能です (select_related('author__country', 'publisher'))。

  • prefetch_related(*lookups): ManyToManyField や、リバース ForeignKey のような「一対多」または「多対多」の関係にあるオブジェクトを、別途クエリを実行して取得し、Python内で関連付けを行います。

    例：すべての著者の名前と、その著者が書いた本のリストを表示したい場合。

    “`python

    非効率な例 (N+1問題)

    authors = Author.objects.all()
    for author in authors:
    # author.book_set.all() にアクセスするたびに、その著者の本を取得するクエリが実行される
    # Authorが10人いれば、10回のBookクエリが実行される (合計1 + 10 = 11クエリ)
    books = author.book_set.all()
    book_titles = “, “.join([book.title for book in books])
    print(f”Author: {author.name}, Books: {book_titles}”)
    “`

    “`python

    効率的な例 (prefetch_relatedを使用)

    Authorオブジェクトを取得するクエリ (1つ)

    関連するBookオブジェクトをすべて取得する別のクエリ (1つ)

    DjangoがPython内でこれらのオブジェクトを関連付ける

    authors_with_books = Author.objects.prefetch_related(‘book_set’).all()
    for author in authors_with_books:
    # author.book_set.all() はキャッシュされた結果から取得されるため、追加のクエリは発生しない
    books = author.book_set.all()
    book_titles = “, “.join([book.title for book in books])
    print(f”Author: {author.name}, Books: {book_titles}”)

    この操作全体で実行されるクエリはAuthor取得用とBook取得用の2つだけ

    “`

    prefetch_related は、リバース ForeignKey フィールド名（この例では book_set – デフォルト名は <related_model_name>_set）または ManyToManyField フィールド名を指定します。カスタムマネージャーやクエリセットを使ってプリフェッチするオブジェクトを絞り込むことも可能です。

select_related は単一のJOINクエリ、prefetch_related は複数の独立したクエリを実行します。どちらを使うかは、リレーションシップのタイプ（一対一/多対一 vs 一対多/多対多）によって決まります。両方を組み合わせて使用することもよくあります。

8.2 values() と values_list()

クエリセットは通常、完全なモデルインスタンスを返します。しかし、特定のフィールドの値だけが必要な場合、モデルインスタンスを生成するのはオーバーヘッドになります。values() や values_list() を使うと、必要なフィールドだけを取得できます。

  • values(*fields): 指定したフィールドの値を辞書のリストとして返します。
    python
    # すべての本のタイトルと価格を辞書のリストとして取得
    book_data = Book.objects.values('title', 'price')
    # 結果の例: [{'title': 'Book A', 'price': Decimal('10.00')}, ...]
    values() にフィールド名を指定しない場合、すべてのフィールドが取得されます。

  • values_list(*fields, flat=False, named=False): 指定したフィールドの値をタプルのリストとして返します。
    “`python
    # すべての本のタイトルと価格をタプルのリストとして取得
    book_data = Book.objects.values_list(‘title’, ‘price’)
    # 結果の例: [(‘Book A’, Decimal(‘10.00’)), …]

    単一のフィールドだけを取得し、結果をフラットなリストとして取得

    book_titles = Book.objects.values_list(‘title’, flat=True)

    結果の例: [‘Book A’, ‘Book B’, …]

    named=True を指定すると、フィールド名を属性として持つnamedtupleのリストとして取得

    book_data_named = Book.objects.values_list(‘title’, ‘price’, named=True)

    結果の例: [Row(title=’Book A’, price=Decimal(‘10.00’)), …]

    “`

values() や values_list() は、完全なモデルインスタンスを必要としない（例: シリアライズ、単純なデータ表示）場合に、メモリ使用量とクエリ実行時間を削減できます。

8.3 defer() と only()

オブジェクトの中には、特定のフィールドが大きく（例: テキストフィールド、画像フィールド）、多くのオブジェクトを取得する際にそのフィールドを毎回取得したくない場合があります。defer() と only() を使うと、一部のフィールドの取得を遅延させることができます。

  • defer(*fields): 指定したフィールド以外のすべてのフィールドをすぐに取得し、指定したフィールドはそれらがアクセスされたときに別途取得します。

    “`python

    書籍の説明文 (仮にdescriptionフィールドがあるとして) の取得を遅延させる

    books = Book.objects.defer(‘description’)

    この時点では description 以外のフィールドが取得される

    for book in books:
    print(book.title) # title は取得済みなので速い
    # print(book.description) # ここで初めて description フィールドを取得するための追加クエリが発生
    “`

  • only(*fields): 指定したフィールドだけをすぐに取得し、それ以外のすべてのフィールドはそれらがアクセスされたときに別途取得します。

    “`python

    タイトルと著者だけをすぐに取得し、他のフィールドの取得を遅延させる

    books = Book.objects.only(‘title’, ‘author’)

    この時点では title と author_id (外部キーなので) だけが取得される

    for book in books:
    print(book.title) # title は取得済みなので速い
    # print(book.price) # ここで初めて price フィールドを取得するための追加クエリが発生
    “`

これらのメソッドは、特定の高価なフィールドへのアクセスが一部のシナリオでのみ必要な場合に有効です。ただし、後から遅延されたフィールドにアクセスすると追加のクエリが発生するため、そのフィールドが常に必要なら defer/only を使わない方が効率的です。

8.4 count() と exists()

クエリセット内のオブジェクト数を数えたい場合や、少なくとも1つのオブジェクトが存在するかどうかだけを知りたい場合、クエリセットを評価して len() を使うのは非効率な場合があります。

  • count(): クエリセット内のオブジェクト数を効率的に取得します。これはSQLの SELECT COUNT(*) クエリに変換されます。

    “`python

    2023年以降に出版された本の数を取得

    book_count_2023 = Book.objects.filter(publication_date__year__gte=2023).count()
    ``
    もしクエリセットが既に完全に評価されキャッシュされている場合は、    len(qs)はキャッシュを利用しますが、count()は評価されていないクエリセットに対しては常に効率的なCOUNT(*)クエリを発行します。多くの場合、明示的に数を数えたいときはcount()` を使うのが最善です。

  • exists(): クエリセットに少なくとも1つのオブジェクトが存在するかどうかを効率的にチェックします。これはSQLの SELECT 1 ... LIMIT 1 のようなクエリに変換されることが多いです。

    “`python

    2023年以降に出版された本が1冊でも存在するかチェック

    if Book.objects.filter(publication_date__year__gte=2023).exists():
    print(“2023年以降に出版された本があります。”)
    “`

    exists() は bool(qs) や if qs: よりも効率的です。これらはクエリセット全体または少なくとも一つを取得しようとするためです。存在チェックだけなら exists() が推奨されます。

9. クエリセットの集計とアノテーション

クエリセットは、データベースレベルでの集計演算（合計、平均、カウントなど）や、各オブジェクトに計算フィールドを追加する機能を提供します。これらはDjangoの django.db.models にある集計関数 (Avg, Count, Max, Min, Sum など) を使用します。

9.1 集計：aggregate()

aggregate() メソッドは、クエリセット全体に対して集計演算を実行し、結果を辞書として返します。

“`python
from django.db.models import Count, Sum, Avg, Max, Min

すべての本の総数、合計価格、平均価格を取得

agg_results = Book.objects.aggregate(
total_books=Count(‘id’),
total_price=Sum(‘price’),
average_price=Avg(‘price’),
max_price=Max(‘price’),
min_price=Min(‘price’)
)

print(agg_results)

例: {‘total_books’: 100, ‘total_price’: Decimal(‘1500.00’), ‘average_price’: Decimal(‘15.00’), ‘max_price’: Decimal(‘30.00’), ‘min_price’: Decimal(‘5.00’)}

“`

aggregate() はクエリセットを評価し、単一の辞書を返します。各キーは、キーワード引数として指定した集計関数の名前（またはデフォルト名）になります。

9.2 アノテーション：annotate()

annotate() メソッドは、クエリセット内の各オブジェクトに、計算された新しいフィールド（アノテーション）を追加します。これは、グループ化された結果や、各アイテムに関連する情報の集計値を取得したい場合に非常に便利です。

例1：各著者が書いた本の数を取得

“`python

各著者が書いた本の数を annotated_book_count フィールドとして追加

authors_with_book_count = Author.objects.annotate(
annotated_book_count=Count(‘book’) # ‘book’ は Authorモデルからの Bookモデルへのリバースリレーションシップ名
)

結果はAuthorオブジェクトのクエリセット。各オブジェクトに annotated_book_count 属性が追加されている。

for author in authors_with_book_count:
print(f”{author.name}: {author.annotated_book_count} 冊”)
``Count(‘book’)は、Authorごとに、関連するBookオブジェクトの数をカウントしています。これはSQLのGROUP BY` に対応します。

例2：各著者の本の平均価格を取得

“`python
authors_with_avg_price = Author.objects.annotate(
avg_book_price=Avg(‘book__price’) # リレーションシップを辿ってBookのpriceを集計
)

for author in authors_with_avg_price:
print(f”{author.name}: 平均価格 {author.avg_book_price}”)
“`

annotate() と filter()/order_by() を組み合わせることで、さらに複雑なクエリを作成できます。例えば、本の数が3冊以上の著者だけをフィルタリングしたり、本の数で並べ替えたりすることができます。

“`python

本の数が3冊以上の著者を、本の数が多い順に取得

prolific_authors = Author.objects.annotate(
book_count=Count(‘book’)
).filter(book_count__gte=3).order_by(‘-book_count’)

for author in prolific_authors:
print(f”{author.name}: {author.book_count} 冊”)
“`

9.3 values()/values_list() と集計/アノテーションの組み合わせ

values() または values_list() と annotate() を組み合わせると、特定のフィールドでグループ化して集計結果を得ることができます。

例：出版年ごとの本の数と平均価格を取得

“`python

出版年でグループ化し、各年の本の数と平均価格を集計

books_by_year = Book.objects.values(‘publication_date__year’).annotate(
count=Count(‘id’),
avg_price=Avg(‘price’)
).order_by(‘publication_date__year’)

for item in books_by_year:
print(f”年: {item[‘publication_date__year’]}, 冊数: {item[‘count’]}, 平均価格: {item[‘avg_price’]}”)
“`

values('publication_date__year') は、結果を出版年でグループ化する指示になります。その後の annotate() は、そのグループ内で集計を行います。

10. 複雑なクエリ条件：Q オブジェクト

filter() や exclude() のキーワード引数は、デフォルトでAND条件として結合されます。OR条件や複雑なAND/ORの組み合わせ、または条件の否定を使いたい場合は、Q オブジェクトを使用します。

Q オブジェクトは django.db.models からインポートします。

“`python
from django.db.models import Q

タイトルに ‘Harry Potter’ を含むか、著者が ‘J.K. Rowling’ の本を取得 (OR条件)

or_query = Book.objects.filter(
Q(title__icontains=’Harry Potter’) | Q(author__name=’J.K. Rowling’)
)

著者が ‘Jane Austen’ ではなく、かつ価格が3000円未満の本を取得 (NOT + AND条件)

not_and_query = Book.objects.filter(
~Q(author__name=’Jane Austen’) & Q(price__lt=30.00)
)

複雑な組み合わせ

(タイトルに ‘Lord’ を含む AND 価格が 2000円以上) OR (出版年が2020年以降) の本

complex_query = Book.objects.filter(
(Q(title__icontains=’Lord’) & Q(price__gte=20.00)) | Q(publication_date__year__gte=2020)
)
“`

Q オブジェクトは以下の演算子で結合できます。

  • &: AND
  • |: OR
  • ~: NOT

Q オブジェクトは、filter(), exclude(), get() などのメソッドに渡すことができます。また、キーワード引数と Q オブジェクトを組み合わせて使うこともできますが、Q オブジェクトはキーワード引数の前に置く必要があります。

“`python

出版済みの本のうち、(タイトルに ‘Django’ を含む OR タイトルに ‘Python’ を含む) ものを取得

combined_query = Book.objects.filter(
Q(title__icontains=’Django’) | Q(title__icontains=’Python’),
is_published=True # これはAND条件として結合される
)
“`

11. データベース関数と参照：F オブジェクト

F オブジェクト (django.db.models からインポート) を使うと、データベース内の他のフィールドの値を参照したり、データベース関数（数学関数、文字列関数など）を適用したりすることができます。これは、Pythonレベルではなくデータベースレベルで値を操作できるため、競合状態を避けたアトミックな更新などに非常に強力です。

“`python
from django.db.models import F

すべての本の価格を10%値上げする (Fオブジェクトを使用すると、現在の価格をデータベースレベルで参照して計算できる)

Book.objects.all().update(price=F(‘price’) * 1.1)

著者の生年月日が出版日よりも早い本を取得 (フィールド同士の比較)

Book.objects.filter(publication_date__gt=F(‘author__birth_date’))

タイトルフィールドと価格フィールドを結合した文字列で並べ替える (データベース関数の例 – サポートはデータベースに依存)

from django.db.models.functions import Concat, Cast

from django.db.models import CharField

Book.objects.annotate(

title_and_price=Concat(‘title’, Value(‘ ‘), Cast(‘price’, CharField()))

).order_by(‘title_and_price’)

“`

F オブジェクトは、filter(), exclude(), order_by(), update(), annotate() など、多くのクエリセットメソッドで使用できます。

12. カスタムマネージャー

繰り返し使用する複雑なクエリロジックがある場合や、モデルのデフォルトの objects マネージャーに独自のメソッドを追加したい場合は、カスタムマネージャーを作成するのが良い方法です。

カスタムマネージャーは django.db.models.Manager を継承するクラスとして定義します。

“`python

managers.py

from django.db import models

class PublishedBookManager(models.Manager):
def get_queryset(self):
# デフォルトのクエリセットをオーバーライドして、出版済みの本だけを返すようにする
return super().get_queryset().filter(is_published=True)

def young_authors_books(self):
    # カスタムメソッドの追加
    # 例: 著者の生年月日が20世紀以降の本 (適当な例)
    from datetime import date
    return self.filter(author__birth_date__year__gte=1900)

models.py

from django.db import models

from .managers import PublishedBookManager # managers.pyをインポート

class Book(models.Model):
# … フィールド定義 …
objects = models.Manager() # デフォルトマネージャー (常に必要ではないが、カスタムマネージャーと共存させたい場合)
published = PublishedBookManager() # カスタムマネージャーをアタッチ

def __str__(self):
    return self.title

“`

モデルにカスタムマネージャーをアタッチすると、その名前でアクセスできるようになります。

“`python

すべての本を取得 (デフォルトマネージャー)

all_books = Book.objects.all()

出版済みの本だけを取得 (カスタムマネージャー)

published_books = Book.published.all() # get_queryset() で定義されたフィルタリングが適用される

カスタムマネージャーのメソッドを呼び出し

young_books = Book.published.young_authors_books()
“`

カスタムマネージャーは、モデルに特定のドメインロジックに関連するクエリメソッドをカプセル化し、コードの再利用性と可読性を向上させるのに役立ちます。

13. クエリセットとイテレータ

クエリセットはイテレータでもあります。つまり、for ループなどで繰り返し処理できます。

python
qs = Book.objects.all()
for book in qs:
print(book.title)

大量のデータを扱う場合、クエリセットのキャッシュメカニズムがメモリを大量に消費する可能性があります。特に、一度にすべての結果が必要ない場合（例: データを1件ずつ処理してエクスポートする場合など）、キャッシュを無効にしたいことがあります。

iterator() メソッドを使うと、クエリセットのキャッシュをバイパスし、データベースから一度に少ない数の行（通常はバックエンドが決定）を取得しながらイテレートできます。

“`python

キャッシュを無効にしてイテレート

for book in Book.objects.all().iterator():
print(book.title)
# ここで各bookオブジェクトは個別に取得されるか、バックエンドのバッチで取得される
# クエリセット全体の結果はメモリにキャッシュされない
“`

iterator() は、非常に大きなクエリセットを扱う際にメモリ使用量を抑えるのに役立ちます。ただし、一度イテレートを開始すると、逆方向へのイテレートや、後からスライスや他のクエリセットメソッド（filter() など）を適用することはできません。また、iterator() を使用すると select_related は無効になる場合があります（Django 4.2以降では一部改善）。prefetch_related は iterator() と一緒に使用できます。

14. Raw SQLクエリ

ほとんどの場合、Django ORMのクエリセットで必要なデータベース操作は実現できます。しかし、ORMでは表現が難しい非常に複雑なクエリや、データベース固有の高度な機能を使用したい場合があります。そのような場合は、Raw SQLクエリを実行することができます。

Raw SQLクエリの結果も、モデルインスタンスとして取得したり、タプルや辞書のリストとして取得したりできます。

“`python

モデルインスタンスとして取得

SELECT b.id, b.title, b.publication_date, b.price, b.is_published, b.author_id, a.name AS author_name

FROM book b JOIN author a ON b.author_id = a.id

WHERE a.name = %s

for book in Book.objects.raw(‘SELECT * FROM myapp_book WHERE author_id = %s’, [author_id]):
print(book.title, book.author.name) # 注意: raw()で取得したオブジェクトは関連オブジェクトが自動でフェッチされない場合がある

任意のSQLを実行し、タプルまたは辞書のリストとして結果を取得

from django.db import connection

with connection.cursor() as cursor:
cursor.execute(“SELECT author_id, COUNT(*) FROM myapp_book GROUP BY author_id”)
row = cursor.fetchone() # 結果を1行取得
rows = cursor.fetchall() # 残りのすべての行を取得

# 結果を辞書として取得したい場合
# cursor.execute("SELECT * FROM myapp_book LIMIT 10")
# from django.db.models.sql.query import Query
# cols = [col[0] for col in cursor.description]
# rows = [dict(zip(cols, row)) for row in cursor.fetchall()]

“`

Raw SQLは強力ですが、ORMの利点（データベースの抽象化、セキュリティ、オブジェクト指向インターフェース）を失うことに注意が必要です。可能な限りORMを使用することを強く推奨します。

15. まとめとベストプラクティス

この記事では、Django ORMのクエリセットについて、その基本的な取得、フィルタリング、順序付け、集計、パフォーマンス最適化、そしてより高度なトピックまで、幅広く詳細に解説しました。

クエリセットを効果的に使うためのベストプラクティスをまとめます。

  • ORMを最大限に活用する: ほとんどのデータベース操作はクエリセットで可能です。Raw SQLは最後の手段と考えましょう。
  • 遅延評価とキャッシュを理解する: これらはクエリセットの挙動の根幹です。意図しないデータベースアクセスを避けるために、いつクエリが評価されるのかを常に意識しましょう。
  • N+1問題を回避する: select_related() と prefetch_related() を適切に使用して、関連オブジェクトの取得効率を大幅に改善しましょう。プロファイリングツール（Django Debug Toolbarなど）を使ってクエリ数を確認するのが効果的です。
  • 必要なデータだけを取得する:
    • 単一オブジェクトなら get() (例外処理を忘れずに)、または filter().first() を使う。
    • 特定のフィールドだけなら values() や values_list() を使う。
    • 大きなフィールドの取得を遅延させるなら defer() や only() を検討する。
  • バッチ操作を活用する: 複数のオブジェクトの作成、更新、削除は、bulk_create(), update(), delete() を使って単一のクエリで行いましょう。ループ内で個別に save() や delete() を呼び出すのは避けましょう。
  • count() と exists() を適切に使う: オブジェクトの数や存在チェックだけが必要なら、これらの効率的なメソッドを使用し、クエリセット全体を評価したり len() を使ったりするのは避けましょう。
  • 複雑な条件には Q オブジェクトを使う: OR条件やNOT条件には Q オブジェクトが必須です。
  • データベースレベルの操作には F オブジェクトを使う: フィールド間の比較やアトミックな更新には F オブジェクトを活用しましょう。
  • 再利用可能なロジックはカスタムマネージャーにまとめる: モデル固有の複雑なクエリや、特定のサブセットを取得するロジックは、カスタムマネージャーとして定義することで、コードの重複を減らし、可読性を高めることができます。
  • 大規模データには iterator() を検討する: 大量のデータを処理する際には、メモリ使用量を抑えるために iterator() が役立つことがあります。
  • SQLクエリを確認する: 開発中は print(qs.query) や Django Debug Toolbar を使って、実際にどのようなSQLクエリが実行されているかを確認し、非効率なクエリがないかをチェックする習慣をつけましょう。

クエリセットは、Djangoアプリケーション開発におけるデータベースとの主要なインターフェースです。その豊富な機能と効率的な仕組みを深く理解することは、高性能でスケーラブルなアプリケーションを構築する上で不可欠です。この記事で解説した内容が、あなたのDjango開発の一助となれば幸いです。

Djangoの公式ドキュメントはクエリセットに関する最も権威ある情報源です。疑問点やさらに詳細を知りたい場合は、ぜひ参照してください。

これで、Django ORMクエリセットの旅は一旦終わりです。実際にコードを書き、様々なクエリを試すことで、あなたの理解はさらに深まるでしょう。

コメントする

メールアドレスが公開されることはありません。 ※ が付いている欄は必須項目です

上部へスクロール