QuerySet API リファレンス

このドキュメントでは、QuerySet API の詳細を説明しています。モデル と データベースクエリ ガイドにある説明を前提としていますので、このドキュメントを読む前にこの 2 つを読んでおいた方がよいでしょう。

このリファレンスでは、 データベースクエリガイド で提供された Blogモデルの例 を使用します。

QuerySet が評価されるタイミング

内部的には、 QuerySet は実際にデータベースにアクセスすることなく、構築、フィルタリング、スライス、受け渡しを行うことができます。クエリセットを評価するための操作が行われない限り、実際のデータベースへのアクセスは発生しません。

あなたは次のような方法で QuerySet を評価することができます:

• イテレーション。 QuerySet はイテラブルで、初めてイテレートした時にデータベースのクエリを実行します。たとえば、これはデータベースにある全エントリのheadline属性を出力するプログラムです:

  for e in Entry.objects.all():
      print(e.headline)
  

  メモ: 1つ以上の結果が存在するかどうかを判定したいだけなら、これは使わないでください。 exists() を使った方が効率的です。

• 非同期イテレーション. QuerySet は async for を使ってイテレートすることもできます:

  async for e in Entry.objects.all():
      results.append(e)
  

  クエリセットの同期的・非同期的イテレータは、同じキャッシュを共有します。

• スライス。 QuerySet の要素数を制限する で説明されているとおり、 QuerySet はPythonのリストスライスを用いてスライスできます。未評価の QuerySet をスライスすると、通常は新たな未評価の QuerySet が返されます。しかし、スライスの "step" パラメータを使用した場合、Djangoはデータベースクエリを実行し、リストを返します。評価された QuerySet をスライスした場合も同様にリストが返されます。

  未評価の QuerySet をスライスして別の未評価の QuerySet が返されても、それをさらに変更すること(たとえば、さらにフィルタを追加したり、順序を変更したりすること)は許されていないことに気を付けてください。これは、その操作がSQLに正しく変換されず、明確な意味を持たないためです。

• Pickle 化/キャッシュ化。 詳細については、後述の pickling QuerySets を参照してください。結果がデータベースから読み出されることが、このセクションの目的として重要なことです。

• repr()。 QuerySet は repr() が呼び出された時点で評価されます。これはPythonの対話型インタプリタでの利便性を図るためで、APIを対話的に使用する際にクエリの結果をすぐに確認できます。

• len()。 QuerySet は len() を呼び出した時点で評価されます。想像される通り、この操作は結果のリストの長さを返します。

  メモ: セット内のレコード数を決定したいだけであれば(そして実際のオブジェクトが必要ないのであれば)、SQLの SELECT COUNT(*) を使ってデータベースレベルでハンドルする方がより効率的です。Djangoはまさにこの理由から count() メソッドを提供しています。

• list()。 list() を呼び出すことで、 QuerySet の評価を強制します。たとえば:

  entry_list = list(Entry.objects.all())
  

• bool()。 bool(), or, and または if 文を使用してブール値として QuerySet をテストすると、クエリが実行されます。 QuerySet も少なくとも1つ以上の結果が含まれれば True となり、そうでなければ False になります。例えば:

  if Entry.objects.filter(headline="Test"):
      print("There is at least one Entry with the headline Test")
  

  注意: もしクエリの結果が少なくとも1つ存在するかどうかを確認したいだけであれば(そして実際のオブジェクトを必要としないのであれば)、 exists() を使うべきです。

QuerySet の Pickle 化

QuerySet を pickle 化するとき、pickle化の前にすべての結果がメモリにロードされるように強制されます。キャッシュされたクエリセットがリロードされた時、結果がすでに存在し、使用できる状態になっていることが望ましいからです(データベースからの読み込みには時間がかかるので、キャッシュとしての目的を達成できません)。つまり、 QuerySet のpickle化を解除すると、解除した時点でデータベースにある結果ではなく、pickle化した時点での結果が出力されることになります。

もし、後でデータベースから QuerySet を再生成するために必要な情報だけを取り出したい場合は、 QuerySet の query を属性を取り出してください。そうすることで、以下のようなコードで本来の QuerySet (結果を読み込む前の状態)を再現できます:

>>> import pickle
>>> query = pickle.loads(s)  # Assuming 's' is the pickled string.
>>> qs = MyModel.objects.all()
>>> qs.query = query  # Restore the original 'query'.

query 属性は不透明なオブジェクトです。これは内側でのクエリ構築を表すもので、公開APIの一部ではありません。しかし、ここで説明しているように、この属性の内容のpickle化・pickle化の解除は安全に行うことができます(完全にサポートもされています)。

QuerySet.values_list() における制限

pickle化された query 属性を使って QuerySet.values_list() を再生成すると、返り値は QuerySet.values() に置き換えられます:

>>> import pickle
>>> qs = Blog.objects.values_list("id", "name")
>>> qs
<QuerySet [(1, 'Beatles Blog')]>
>>> reloaded_qs = Blog.objects.all()
>>> reloaded_qs.query = pickle.loads(pickle.dumps(qs.query))
>>> reloaded_qs
<QuerySet [{'id': 1, 'name': 'Beatles Blog'}]>

バージョン間でpickle化されたデータを共有することはできません

QuerySets をpickle化したデータは、生成したDjangoの同一バージョンでのみ有効です。DjangoのバージョンNで生成したデータをバージョンN+1でも正常に読み込める保証はありません。Pickle化は長期的なアーカイブ戦略の手段として用いるべきではありません。

pickle の互換性エラーは、静的に衝突したオブジェクトのように判定が難しいことがあるので、モデルをpickle化したデータを別のバージョンで復元しようとすると RuntimeWarning が送出されます。

QuerySet API

これが QuerySet の正式な宣言です:

class QuerySet(model=None, query=None, using=None, hints=None)

通常、 QuerySet を操作する際には フィルタの連結 を使用します。これを実現するために、ほとんどの QuerySet のメソッドは新たなクエリセットを返します。これらのメソッドについては、このセクションで後ほど詳しく説明します。

QuerySet クラスは、イントロスペクションのために以下のパブリックな属性を持っています:

ordered

QuerySet が order_by() やモデルのデフォルトの順序指定によって並び替えられた場合に True となります。それ以外のときは False になります。

db

このクエリが実行されるデータベースを示します。

注釈

QuerySet の query パラメータは、特殊なクエリのサブクラスが内部のクエリ状態を再構築できるようにするために存在します。このパラメータの値はクエリの状態の不透明な表現であり、パブリックAPIの一部ではありません。

新しい QuerySets を返すメソッド

QuerySet が返す結果の種類や、SQLクエリの実行方法を変更するための、さまざまな QuerySet の改良メソッドをDjangoは提供します。

注釈

これらのメソッドはデータベースクエリを実行しないので、非同期コードで実行しても 安全 であり、非同期処理専用のメソッドは存在しません。

filter()

filter(*args, **kwargs)

与えられたルックアップパラメータにマッチする新しい QuerySet を返します。

ルックアップパラメータ (**kwargs) は以下の Field lookups で説明されているフォーマットに従わなければなりません。複数のパラメータは、元となるSQLステートメントでは AND によって結合されます。

より複雑なクエリを実行したい場合(たとえば OR ステートメントを含むクエリ)は、 Q オブジェクト (*args) を使用してください。

exclude()

exclude(*args, **kwargs)

与えられたルックアップパラメータにマッチ しない 新しい QuerySet を返します。

ルックアップパラメータ (**kwargs) は下記の Field lookups で説明されているフォーマットに従わなければなりません。複数のパラメータは、元となるSQLステートメントでは AND によって結合され、全体が NOT() によって囲まれます。

この例では pub_date が 2005-1-3より新しく、 headline が "Hello" であるようなエントリーを除外しています:

Entry.objects.exclude(pub_date__gt=datetime.date(2005, 1, 3), headline="Hello")

SQL文では、次のように評価されます:

SELECT ...
WHERE NOT (pub_date > '2005-1-3' AND headline = 'Hello')

この例では pub_date が 2005-1-3より新しいか、 headline が "Hello" であるようなエントリーを除外しています:

Entry.objects.exclude(pub_date__gt=datetime.date(2005, 1, 3)).exclude(headline="Hello")

SQL文では、次のように評価されます:

SELECT ...
WHERE NOT pub_date > '2005-1-3'
AND NOT headline = 'Hello'

2つ目の例の方が、制約がより強いことに留意してください。

より複雑なクエリを実行したい場合(たとえば OR ステートメントを含むクエリ)は、 Q オブジェクト (*args) を使用してください。

annotate()

annotate(*args, **kwargs)

指定された クエリ式 のリストで QuerySet の各オブジェクトにアノテーションを付けます。式は単純な値、モデル（または関連する任意のモデル）上のフィールドへの参照、または QuerySet のオブジェクトのリレーション先オブジェクトに対して計算された集計式（平均、合計など）を指定できます。

annotate() の引数は、それぞれが返り値となる QuerySet 内の各オブジェクトに追加される集計情報となります。

Djangoが提供する集計関数については、下記の Aggregation Functions で説明されています。

キーワード引数を用いて集計情報を定義した場合、キーワードが集計情報のエイリアスとして用いられます。位置引数を用いた場合、使用した集計関数と集計されるモデルフィールドの名前に基づいてエイリアスが生成されます。単一のフィールドを参照する集計式であれば位置引数を利用できます。それ以外のすべての集計式は、キーワード引数を用いなくてはなりません。

たとえば、ブログのリストを操作しているときに、ブログごとのエントリー数を決定したいとします:

>>> from django.db.models import Count
>>> q = Blog.objects.annotate(Count("entry"))
# The name of the first blog
>>> q[0].name
'Blogasaurus'
# The number of entries on the first blog
>>> q[0].entry__count
42

Blog モデル自体は entry__count 属性を定義しませんが、集計式を指定したキーワード引数を用いることで、集計情報の名前を制御できます:

>>> q = Blog.objects.annotate(number_of_entries=Count("entry"))
# The number of entries on the first blog, using the name provided
>>> q[0].number_of_entries
42

集計処理についての深い議論については、 アグリゲーションについてのトピックガイド を確認してください。

alias()

alias(*args, **kwargs)

annotate() と同じですが、 QuerySet にオブジェクトをアノテーションするかわりに、後で他の QuerySet メソッドで再利用できるように式を保存します。これは式の結果自体は必要ないが、フィルタリングやソート、あるいは複雑な式の一部として利用する場合に便利です。未使用の値を選択しないことで、データベースで冗長な処理を行わずに済み、結果的にパフォーマンスを向上させることができます。

例えば、5エントリ以上のブログを探したいが、エントリ数自体に興味がない場合は、以下のようにできます:

>>> from django.db.models import Count
>>> blogs = Blog.objects.alias(entries=Count("entry")).filter(entries__gt=5)

alias() は annotate(), exclude(), filter(), order_by(), update() と組み合わせて使用できます。エイリアス式をその他のメソッド(aggregate() など)と組み合わせるためには、アノテーションを用いる必要があります

Blog.objects.alias(entries=Count("entry")).annotate(
    entries=F("entries"),
).aggregate(Sum("entries"))

filter() と order_by() は式を直接受け取ることができますが、式の構築と評価は同じ場所では行われないことが多いです(例えば、 QuerySet メソッドは式を作成し、後からビューを表示するときに使用されるため)。 alias() は、複数のメソッドやモジュールにまたがる複雑な式を段階的に構築することができ、式の部分をエイリアスで参照し、最終結果に対してのみ annotate() を使用する、といった使い方ができます。

order_by()

order_by(*fields)

デフォルトでは、 QuerySet の返り値はモデルの Meta 内の ordering オプションで指定されたタプルに基づいて並び替えられます。 order_by メソッドを使うことで、 QuerySet ごとにこれをオーバーライドできます。

実装例:

Entry.objects.filter(pub_date__year=2005).order_by("-pub_date", "headline")

上のコードの結果は pub_date の降順、次に headline の昇順で並び替えられます。 "-pub_date" のように、前にマイナス符号をつけることで降順を表現します。昇順は暗黙的に表現されます。ランダムに並び替えたい場合、次のように "?" を使います:

Entry.objects.order_by("?")

メモ: order_by('?') クエリは、使用するデータベースバックエンドによっては高負荷で遅くなる可能性があります。

異なるモデルのフィールドで並び替えたい場合、モデル間を横断して参照するクエリを発行するときと同じ構文を使用します。すなわち、フィールド名の後にダブルアンダースコア(__)を続けて、その後に新たなモデルのフィールド名を続けます。そして、それを結合したいモデルの数だけ繰り返します。例えば:

Entry.objects.order_by("blog__name", "headline")

異なるモデルを参照するフィールドで並び替えるとき、Djangoは参照先のモデルのデフォルトの順序を用いますが、 Meta.ordering が設定されていなければ参照先のモデルのプライマリーキーで並び替えます。たとえば、 Blog モデルにはデフォルトで設定された順序がないとき:

Entry.objects.order_by("blog")

...は以下と同じです:

Entry.objects.order_by("blog__id")

Blog が ordering = ['name'] を保持している場合、最初のクエリセットは以下と同じになります:

Entry.objects.order_by("blog__name")

asc() か desc() を式の中で呼び出すことで、 クエリ式 を使うこともできます:

Entry.objects.order_by(Coalesce("summary", "headline").desc())

asc() と desc() は、null値をどのようにソートするかを制御する引数 (nulls_first と nulls_last)をとります。

モデル参照フィールドによる並び替えと同時に distinct() を使用する際は注意してください。参照先のモデルの順序によって、期待される結果がどのように変化するかについては、 distinct() の注記を確認してください。

注釈

複数の値をとりうるフィールドを指定し、結果を並び替えることは許されています(たとえば、 ManyToManyField フィールド、もしくは ForeignKey フィールドの逆参照など)。

このケースを考えます:

class Event(Model):
    parent = models.ForeignKey(
        "self",
        on_delete=models.CASCADE,
        related_name="children",
    )
    date = models.DateField()


Event.objects.order_by("children__date")

ここで、それぞれの Event に対して、複数の並べ替えデータが存在する可能性があります; 複数の children を伴う Event は、order_by() が作る新たな QuerySet においてそれぞれ複数回返されることになります。言い換えれば、 QuerySet で order_by() を使うことで、もともと作業していたよりも多くの項目を返してしまう可能性があります。これはおそらく予期されることはなく、有用でもないでしょう。

従って、複数の値をとりうるフィールドを結果の並び替えに用いる際は気を付けてください。 もし仮に 並び替える項目ごとに1つのデータしか存在しないのであれば、この方法でも問題はないでしょう。そうでなければ、結果が期待通りになることを確認してください。

大文字と小文字を区別して並べ替えるかどうかを指定することはできません。Djangoは使用するデータベースバックエンドが通常このCase-sensitiveをどのように扱うかに従って結果を並び替えます。

Lower によって小文字に変換したフィールドで並び替えることで、一貫したルールでの並び替えを実現できます:

Entry.objects.order_by(Lower("headline").desc())

クエリに対し、デフォルトの順序付けも含めて並び替えを適用したくない場合、パラメータを指定せずに order_by() を呼び出してください。

クエリに並び替えが適用されたかどうかは、 QuerySet.ordered 属性を確認することで知ることができます。 QuerySet がなんらかの方法で並び替えられれば、この属性の値は True となります。

order_by() の呼び出しごとに、過去の並び替えは解除されます。たとえば、以下のクエリでは並び替えに pub_date が使われ、 headline は使われません:

Entry.objects.order_by("headline").order_by("pub_date")

警告

ソートには計算コストがかかります。ソート条件に追加した各フィールドに、データベースへのコストが発生します。追加する各外部キーには、暗黙的にすべてのデフォルトのソート条件が含まれます。

クエリでソートが指定されていない場合、データベースから返される結果の順序は指定されません。特定の順序が保証されるのは、結果内の各オブジェクトを一意に識別するフィールドの組み合わせでソートした場合だけです。例えば、 name フィールドが一意でない場合、そのフィールドでソートしても、同じ名前のオブジェクトが常に同じ順序で表示されるとは限りません。

reverse()

reverse()

reverse() メソッドを使用すると、クエリセットの要素を返す順序を逆にすることができます。再度 reverse() を呼び出すと、順序が元に戻ります。

クエリセットの「最後の」5つの項目を取り出すには、次のようにします:

my_queryset.reverse()[:5]

この処理がPythonでシーケンスの最後からスライスするのとは全く違うことに注意してください。上記の例では、まず最後の項目が返され、次に最後から5番目の項目が返されます。Python のシーケンスに対して seq[-5:] を参照すると、最後の 5 番目の項目が最初に表示されるはずです。そのようなアクセスモード (末尾からのスライス) は、SQL で効率的に行うことができないため、Django ではサポートされていません。

また、通常 reverse() は、順序が定義されている QuerySet に対してしか呼び出せないことに注意してください（例えば、デフォルトの順序を定義しているモデルに対するクエリや、 order_by() を使用する場合など）。 QuerySet に順序が定義されていなかったら、 reverse() を呼び出しても何の効果もありません（順序は reverse() を呼び出す前から未定義であり、その後も未定義のままです）。

distinct()

distinct(*fields)

SQL クエリで SELECT DISTINCT を使用した新しい QuerySet を返します。これにより、クエリ結果から重複した行を取り除くことができます。

デフォルトでは、 QuerySet は重複した行を削除しません。なぜなら、 Blog.objects.all() のような単純なクエリでは、結果の行が重複する可能性はないからです。しかし、クエリが複数のテーブルにまたがっている場合、 QuerySet が評価されたときに重複した結果を得る可能性があります。このような場合は distinct() を使用します。

注釈

order_by() の呼び出しで使用されるフィールドはすべて、SQL の SELECT 列に含まれます。これは distinct() と組み合わせて使用すると、時に予期せぬ結果をもたらすことがあります。リレーション先モデルのフィールドでソートした場合、それらのフィールドが SELECT の対象に追加され、重複した行が重複していないように出力されるかもしれません。余分なカラムは返される結果には現れないので (カラムは順序付けをサポートするためだけに存在するため)、重複した結果が返されているように見えることがあります。

同様に、 values() クエリを使用して選択するカラムを制限した場合、 order_by() （またはデフォルトのモデルの順序付け）で使用したカラムが残存し、結果の一意性に影響する可能性があります。

この問題の解決策は、 distinct() を使用する場合、リレーション先のモデルによるソートに注意することです。同様に、 distinct() と values() を一緒に使う場合、 values() の呼び出しに含まれないフィールドによるソートに注意する必要があります。

PostgreSQL のみ、位置引数 (*fields) を渡して、 DISTINCT を適用するフィールドの名前を指定できます。これは SELECT DISTINCT ON というSQLクエリに相当します。通常の distinct() 呼び出しでは、データベースはどの行が区別されるかを判断する際に、各行の each フィールドを比較しますが、フィールド名を指定した distinct() の呼び出しでは、データベースは指定されたフィールド名のみを比較できます。

注釈

フィールド名を指定する場合、QuerySet に order_by() を指定する必要があり、 order_by() のフィールドは distinct() のフィールドと同じ順序で始まる必要があります。

例えば、SELECT DISTINCT ON (a) とすると、列 a の各値の最初の行が得られます。もし順序を指定しなければ、任意の行を得ることができます。

例 (2つ目以降のコードは、PostgreSQL上でのみ動作します):

>>> Author.objects.distinct()
[...]

>>> Entry.objects.order_by("pub_date").distinct("pub_date")
[...]

>>> Entry.objects.order_by("blog").distinct("blog")
[...]

>>> Entry.objects.order_by("author", "pub_date").distinct("author", "pub_date")
[...]

>>> Entry.objects.order_by("blog__name", "mod_date").distinct("blog__name", "mod_date")
[...]

>>> Entry.objects.order_by("author", "pub_date").distinct("author")
[...]

注釈

order_by() はデフォルトで定義されているリレーション先モデルのソートを使用することに注意してください。 ORDER BY 句の先頭にある DISTINCT ON 式が一致するように、明示的に _id やフィールド参照によるソートをする必要があるかもしれません。例えば、 Blog モデルが name による ordering を定義していた場合、:

Entry.objects.order_by("blog").distinct("blog")

このコードは、クエリが blog__name によってソートされるため DISTINCT ON 式と食い違ってしまい、正しい結果を得られないでしょう。2つの式が一致するように、リレーションの _id フィールド（この場合は blog_id ）またはフィールド参照（ blog__pk ）によって明示的にソートする必要があります。

values()

values(*fields, **expressions)

イテラブルオブジェクトとして使用するとき、モデルインスタンスではなく辞書を返す QuerySet を返します。

これらの辞書はそれぞれオブジェクトを表し、キーはモデルオブジェクトの属性名に対応しています。

この例では、values() によって得られる辞書と通常のモデルのオブジェクトを比較しています:

# This list contains a Blog object.
>>> Blog.objects.filter(name__startswith="Beatles")
<QuerySet [<Blog: Beatles Blog>]>

# This list contains a dictionary.
>>> Blog.objects.filter(name__startswith="Beatles").values()
<QuerySet [{'id': 1, 'name': 'Beatles Blog', 'tagline': 'All the latest Beatles news.'}]>

values() メソッドはオプションの位置引数 *fields を取り、 SELECT で絞り込むフィールド名を指定します。フィールドを指定した場合、それぞれの辞書は指定したフィールドのキー/値のみを保有します。フィールドを指定しない場合、各辞書は、データベーステーブルのすべてのフィールドのキーと値を保有します。

例:

>>> Blog.objects.values()
<QuerySet [{'id': 1, 'name': 'Beatles Blog', 'tagline': 'All the latest Beatles news.'}]>
>>> Blog.objects.values("id", "name")
<QuerySet [{'id': 1, 'name': 'Beatles Blog'}]>

values() メソッドはオプションでキーワード引数 **expressions を受け取り、 annotate() に渡すこともできます:

>>> from django.db.models.functions import Lower
>>> Blog.objects.values(lower_name=Lower("name"))
<QuerySet [{'lower_name': 'beatles blog'}]>

ソートには、組み込みのルックアップまたは カスタムルックアップ が使用できます。例えば、次のようになります:

>>> from django.db.models import CharField
>>> from django.db.models.functions import Lower
>>> CharField.register_lookup(Lower)
>>> Blog.objects.values("name__lower")
<QuerySet [{'name__lower': 'beatles blog'}]>

values() 句内の集計処理は、同じ values() 句内の他の引数の前に適用されます。別の値でグループ化する必要がある場合は、その値を先の values() 句に追加してください。例えば:

>>> from django.db.models import Count
>>> Blog.objects.values("entry__authors", entries=Count("entry"))
<QuerySet [{'entry__authors': 1, 'entries': 20}, {'entry__authors': 1, 'entries': 13}]>
>>> Blog.objects.values("entry__authors").annotate(entries=Count("entry"))
<QuerySet [{'entry__authors': 1, 'entries': 33}]>

いくつかの際どいポイントについて言及しておきます:

• もし foo というフィールドが ForeignKey である場合、デフォルトの values() は foo_id という辞書キーを返します。それが実際の値を格納するモデルの隠し属性名だからです (foo 属性はリレーション先モデルを指します)。 value() を呼び出してフィールド名を渡す場合、foo と foo_id のどちらを渡しても、同じものが返ってきます（辞書のキーは渡したフィールド名と一致します）。

  例:

  >>> Entry.objects.values()
  <QuerySet [{'blog_id': 1, 'headline': 'First Entry', ...}, ...]>
  
  >>> Entry.objects.values("blog")
  <QuerySet [{'blog': 1}, ...]>
  
  >>> Entry.objects.values("blog_id")
  <QuerySet [{'blog_id': 1}, ...]>
  

• values() と distinct() を一緒に使う場合、呼び出す順番が結果に影響する場合があるので注意してください。 詳細は distinct() のノートを参照してください。

• extra() 呼び出しの後に values() 句を使用する場合、 extra() の select 引数で定義したフィールドは、明示的に values() 呼び出しに含めなければなりません。 values() 呼び出しの後に extra() を呼び出しても、後から追加した選択フィールドは返り値に含まれません。

• values() の後に only() と defer() を呼び出すのは意味がなく、 TypeError が発生します。

• トランスフォームと集計の処理を組み合わせるには、2つの annotate() 呼び出しを、明示的にまたは values() へのキーワード引数として使用する必要があります。上記の例のように、リレーション先のフィールドタイプにトランスフォームが登録されていれば、最初の annotate() は省略できます。よって以下の例はすべて等価です:

  >>> from django.db.models import CharField, Count
  >>> from django.db.models.functions import Lower
  >>> CharField.register_lookup(Lower)
  >>> Blog.objects.values("entry__authors__name__lower").annotate(entries=Count("entry"))
  <QuerySet [{'entry__authors__name__lower': 'test author', 'entries': 33}]>
  >>> Blog.objects.values(entry__authors__name__lower=Lower("entry__authors__name")).annotate(
  ...     entries=Count("entry")
  ... )
  <QuerySet [{'entry__authors__name__lower': 'test author', 'entries': 33}]>
  >>> Blog.objects.annotate(entry__authors__name__lower=Lower("entry__authors__name")).values(
  ...     "entry__authors__name__lower"
  ... ).annotate(entries=Count("entry"))
  <QuerySet [{'entry__authors__name__lower': 'test author', 'entries': 33}]>
  

これは、値が欲しい利用可能フィールドが少なく、モデルインスタンスオブジェクトの機能が必要ないことが分かっている場合に便利です。使用する必要のあるフィールドだけを選択する方がより効率的です。

最後に、values() の後に filter() や order_by() などを呼び出すことができますが、これはこの2つの呼び出しが同じであることを意味しています:

Blog.objects.values().order_by("id")
Blog.objects.order_by("id").values()

Django を作った人たちは、SQL に影響するメソッドを最初に置き、その後に出力に影響するメソッド (values() など) を (オプションで) 置くことを好みますが、それは本当に重要ではありません。しかし、そんなことはどうでもいいのです。この機会に、あなたの個性を存分に発揮してください。

リレーション先モデルのフィールドには、 OneToOneField 、 ForeignKey 、 ManyToManyField 属性を使用して逆リレーションで参照することもできます。

>>> Blog.objects.values("name", "entry__headline")
<QuerySet [{'name': 'My blog', 'entry__headline': 'An entry'},
     {'name': 'My blog', 'entry__headline': 'Another entry'}, ...]>

警告

ManyToManyField 属性と逆リレーションは複数の関連行を持つので、これらを含めると結果のサイズが数倍になることがあります。これは、 values() クエリに複数のフィールドを含めると特に顕著で、その場合、考えられるすべての組み合わせが返されることになります。

SQLiteにおける JSONField の特殊な値

SQLiteでは、 JSON_EXTRACT と JSON_TYPE は実装されていますが、 BOOLEAN データ型がないため、 values() は JSONField のキーを変換する際に true, False, None の代わりに "true", "false", "null" の代わりに True, False, None を返します。

values_list()

values_list(*fields, flat=False, named=False)

この関数は values() と似ていますが、イテレートしたときに辞書の代わりにタプルを返します。それぞれのタプルには、 values_list() に渡された各フィールドまたは式の値が、渡された順番で含まれます。例えば:

>>> Entry.objects.values_list("id", "headline")
<QuerySet [(1, 'First entry'), ...]>
>>> from django.db.models.functions import Lower
>>> Entry.objects.values_list("id", Lower("headline"))
<QuerySet [(1, 'first entry'), ...]>

フィールドを1つだけ渡す場合は、 flat パラメータを渡すことができます。これに True を渡すと、返り値はタプルではなく単一の値になります。この違いは例を見て理解してください。

>>> Entry.objects.values_list("id").order_by("id")
<QuerySet[(1,), (2,), (3,), ...]>

>>> Entry.objects.values_list("id", flat=True).order_by("id")
<QuerySet [1, 2, 3, ...]>

複数のフィールドがある場合に flat を渡すとエラーになります。

namedtuple(): として結果を得るには、named=True を渡します:

>>> Entry.objects.values_list("id", "headline", named=True)
<QuerySet [Row(id=1, headline='First entry'), ...]>

名前付きタプルを使用することで、名前付きタプルに変換するためのわずかなパフォーマンスの低下を犠牲にして、クエリの実行結果の可読性を高めることができます。

もし values_list() に何も値を渡さなければ、モデル内のすべてのフィールドを宣言された順に返します。

よくあるニーズは、特定のモデルインスタンスの特定のフィールドの値を取得することです。これを実現するには、 values_list() の後に get() を呼び出します:

>>> Entry.objects.values_list("headline", flat=True).get(pk=1)
'First entry'

values() と values_list() はいずれも、モデルインスタンスを作成するオーバーヘッドなしにデータのサブセットを取得するという、特定のユースケースに対する最適化を意図したものです。このメタファーは、多対多の関係やその他の多値の関係（逆引き外部キーの1対多の関係など）を扱うときには、「1行に1オブジェクト」の前提が成り立たないために崩れてしまいます。

例えば、 ManyToManyField: を通してクエリを実行したときの挙動に注目してみましょう:

>>> Author.objects.values_list("name", "entry__headline")
<QuerySet [('Noam Chomsky', 'Impressions of Gaza'),
 ('George Orwell', 'Why Socialists Do Not Believe in Fun'),
 ('George Orwell', 'In Defence of English Cooking'),
 ('Don Quixote', None)]>

複数のエントリを持つ著者は複数回表示され、エントリのない著者のエントリとして None と表示されます。

同様に、外部キーを逆引きするクエリでは、著者が設定されていないエントリに対して None が表示されます。

>>> Entry.objects.values_list("authors")
<QuerySet [('Noam Chomsky',), ('George Orwell',), (None,)]>

SQLiteにおける JSONField の特殊な値

SQLiteでは、 JSON_EXTRACT と JSON_TYPE は実装されていますが、 BOOLEAN データ型がないため、 values_list() は JSONField のキーを変換する際に "true", "false", and "null" の代わりに True, False, None の文字列を返します。

dates()

dates(field, kind, order='ASC')

この QuerySet は datetime.date オブジェクトのリストとして評価され、QuerySet の内容から指定された種類の日付を返します。

field にはモデルの DateField の名前を指定します。 kind には "year", "month", "week", "day" のいずれかを指定します。結果のリストに含まれる datetime.date オブジェクトは、指定された type に "切り捨て" られます。

• "year" は、そのフィールドのすべての年の値のリストを重複なしで返します。
• "month" はそのフィールドの年/月の値のリストを重複なしで返します。
• "week" はそのフィールドの年/週の値のリストを重複なしで返します。すべての date は月曜日になります。
• "day" はそのフィールドの年/月/日の値のリストを重複なしで返します。

order のデフォルトは 'ASC' で、 'ASC' または 'DESC' のいずれかを指定します。これは結果のソート方法を指定します。

例:

>>> Entry.objects.dates("pub_date", "year")
[datetime.date(2005, 1, 1)]
>>> Entry.objects.dates("pub_date", "month")
[datetime.date(2005, 2, 1), datetime.date(2005, 3, 1)]
>>> Entry.objects.dates("pub_date", "week")
[datetime.date(2005, 2, 14), datetime.date(2005, 3, 14)]
>>> Entry.objects.dates("pub_date", "day")
[datetime.date(2005, 2, 20), datetime.date(2005, 3, 20)]
>>> Entry.objects.dates("pub_date", "day", order="DESC")
[datetime.date(2005, 3, 20), datetime.date(2005, 2, 20)]
>>> Entry.objects.filter(headline__contains="Lennon").dates("pub_date", "day")
[datetime.date(2005, 3, 20)]

datetimes()

datetimes(field_name, kind, order='ASC', tzinfo=None)

これは、QuerySet 内の指定した種類の有効な日付を表す datetime.datetime オブジェクトのリストとして評価される QuerySet を返します。

field_name にはモデルの DateTimeField の名前を指定します。

kind には "year", "month", "week", "day", "hour", "minute", "second" のいずれかを指定します。結果のリストに含まれる datetime.datetime オブジェクトは、指定された type に " 切り捨て" られます。

order のデフォルトは 'ASC' で、 'ASC' または 'DESC' のいずれかを指定します。これは結果のソート方法を指定します。

tzinfo は、日時が切り捨てられる前に変換されるタイムゾーンを定義します。実際、与えられた日時は使用されるタイムゾーンによって異なる表現を持ちます。このパラメータは datetime.tzinfo オブジェクトでなければなりません。None の場合、Djangoは カレントタイムゾーン を使用します。USE_TZ が False の場合には効果がありません。

注釈

この関数はデータベース内で直接タイムゾーンの変換を行います。そのため、データベースは tzinfo.tzname(None) の値を解釈できなければなりません。これは以下の要件になります:

• SQLite: 要件はありません。変換はPythonで行われます。
• PostgreSQL: 要件はありません（ Time Zones を参照）。
• Oracle: 要件はありません（ Choosing a Time Zone File を参照）。
• MySQL: mysql_tzinfo_to_sql でタイムゾーンテーブルをロードすること。

none()

none()

none() を呼び出すと、オブジェクトを返さないクエリセットが作成され、結果にアクセスする際にクエリが実行されることはありません。 qs.none() のクエリセットは EmptyQuerySet のインスタンスです。

例:

>>> Entry.objects.none()
<QuerySet []>
>>> from django.db.models.query import EmptyQuerySet
>>> isinstance(Entry.objects.none(), EmptyQuerySet)
True

all()

all()

現在の QuerySet (または QuerySet サブクラス)の コピー を返します。これは、モデルマネージャまたは QuerySet のどちらかを渡して、その結果に対してさらにフィルタリングを行いたいときに便利です。いずれかのオブジェクトに対して all() を呼び出すと、動作する QuerySet が必ず作成されます。

QuerySet が 評価される とき、通常その結果はキャッシュされます。もし QuerySet が評価された後にデータベースのデータが更新された場合、以前に評価された QuerySet に対して all() を呼び出すことで、同じクエリの最新の結果を取得できます。

union()

union(*other_qs, all=False)

SQLの UNION コマンドを使用して、2つ以上の QuerySet の結果を結合します。例えば:

>>> qs1.union(qs2, qs3)

UNION 演算子は、デフォルトでは明確な値のみを選択します。重複した値を取得するには、 all=True 引数を使用します。

union(), intersection(), difference() は、引数が他のモデルの QuerySet であっても、最初の QuerySet の型のモデルインスタンスを返します。すべての QuerySet で SELECT リストが同じであれば、異なるモデルを渡すことができます（少なくとも型と、型の順番が同じであれば名前は関係ありません）。 このような場合、結果の QuerySet に適用される QuerySet メソッドでは、最初の QuerySet のカラム名を使用する必要があります。たとえば、次のようになります:

>>> qs1 = Author.objects.values_list("name")
>>> qs2 = Entry.objects.values_list("headline")
>>> qs1.union(qs2).order_by("name")

結果として得られる QuerySet では、LIMIT、OFFSET、COUNT(*)、ORDER BY、およびカラムの指定（すなわち、スライス、 count() 、 exists() 、 order_by() 、 values() / values_list() ）のみが許可されます。さらに、データベースによっては、組み合わせたクエリで許可される操作に制限があります。例えば、ほとんどのデータベースでは組み合わせたクエリで「LIMIT」や「OFFSET」は許可されていません。

intersection()

intersection(*other_qs)

SQL の INTERSECT 演算子を使用して、2つ以上の QuerySet の全てに含まれる共有要素を返します。例:

>>> qs1.intersection(qs2, qs3)

制限については union() を参照してください。

difference()

difference(*other_qs)

SQL の EXCEPT 演算子を使用して、 QuerySet には存在するが、他の QuerySet には存在しない要素のみを保持します。例:

>>> qs1.difference(qs2, qs3)

制限については union() を参照してください。

select_related()

select_related(*fields)

クエリを実行する際に、追加で関連オブジェクトのデータを選択し、外部キーのリレーションシップを "辿る" QuerySet を返します。発行されるクエリはより複雑になりますが、後で外部リレーションシップを使用する際に追加のデータベースクエリが不要になるので、パフォーマンスを向上させることができます。

以下の例は、通常のルックアップと select_related() を用いたルックアップの違いを示しています。まず、これが通常のルックアップです。

# Hits the database.
e = Entry.objects.get(id=5)

# Hits the database again to get the related Blog object.
b = e.blog

そしてこれが select_related を用いたルックアップです。

# Hits the database.
e = Entry.objects.select_related("blog").get(id=5)

# Doesn't hit the database, because e.blog has been prepopulated
# in the previous query.
b = e.blog

select_related() はどんなオブジェクトのクエリセットにも使うことができます。

from django.utils import timezone

# Find all the blogs with entries scheduled to be published in the future.
blogs = set()

for e in Entry.objects.filter(pub_date__gt=timezone.now()).select_related("blog"):
    # Without select_related(), this would make a database query for each
    # loop iteration in order to fetch the related blog for each entry.
    blogs.add(e.blog)

filter() と select_related() を連続させるときの順序は重要ではありません。これらのクエリセットは等価です:

Entry.objects.filter(pub_date__gt=timezone.now()).select_related("blog")
Entry.objects.select_related("blog").filter(pub_date__gt=timezone.now())

外部キーのクエリと同様の方法で、外部キーをたどることができます。次のようなモデルがあるとします:

from django.db import models


class City(models.Model):
    # ...
    pass


class Person(models.Model):
    # ...
    hometown = models.ForeignKey(
        City,
        on_delete=models.SET_NULL,
        blank=True,
        null=True,
    )


class Book(models.Model):
    # ...
    author = models.ForeignKey(Person, on_delete=models.CASCADE)

... そして、 Book.objects.select_related('author__hometown').get(id=4) を呼び出すと、関連する Person と City がキャッシュされます:

# Hits the database with joins to the author and hometown tables.
b = Book.objects.select_related("author__hometown").get(id=4)
p = b.author  # Doesn't hit the database.
c = p.hometown  # Doesn't hit the database.

# Without select_related()...
b = Book.objects.get(id=4)  # Hits the database.
p = b.author  # Hits the database.
c = p.hometown  # Hits the database.

select_related() にフィールドのリストを渡すことで、任意の ForeignKey または OneToOneField リレーションを参照できます。

select_related に渡すフィールドのリストには、 OneToOneField の逆方向の参照を含めることもできます。つまり、 OneToOneField を辿って、フィールドが定義されているオブジェクトに戻ることができます。このとき、フィールド名を指定する代わりに、 related_name を関連オブジェクトのフィールドに使用してください。

多くの関連オブジェクトを含む select_related() を呼び出したい場合や、すべての関連オブジェク トを把握していないケースもあるでしょう。このようなときは、引数なしで select_related() を呼び出すこともできます。この場合、NULLでない外部キーはすべて追いかけることになります。ただし、NULL可能な外部キーは明示的に指定する必要があります。クエリが複雑になり、実際に必要とされるよりも多くのデータを返す可能性があるため、ほとんどの場合、この方法は推奨されません。

過去に QuerySet で select_related を呼び出したときに追加した関連フィールドのリストを消去したい場合は、パラメータとして None を渡すことができます:

>>> without_relations = queryset.select_related(None)

select_related の呼び出しを連鎖させると、他のメソッドと同様に機能します。すなわち、 select_related('foo', 'bar') は select_related('foo').select_related('bar') と等価です。

prefetch_related()

prefetch_related(*lookups)

指定のルックアップに対してそれぞれのリレーション先のオブジェクトを一括で自動的に取得する QuerySet を返します。

目的は select_related と似ていて、関連オブジェクトにアクセスすることで多量のデータベースクエリが発生してしまうのを防ぐために作られていますが、その手段が異なります。

select_related はSQLで結合操作を行い、関連オブジェクトのフィールドを SELECT 文に含めることで動作します。そのため、 select_related は関連オブジェクトを同一のデータベースクエリで取得します。ただし、 '大量の' のリレーションを結合することで、膨大な結果になってしまうのを避けるため、 select_related を適用できるのは単一値のリレーション、つまり外部キーと一対一の関係に制限されています。

一方、 prefetch_related はリレーションごとに個別のルックアップを行い、Pythonで「結合」を行います。これにより、 select_related でサポートされている外部キーと一対一のリレーションに加えて、 select_related ではできない多対多、多対一、および GenericRelation オブジェクトの事前読み込みが可能になります。 GenericForeignKey の事前読み込みもサポートしていますが、各 ContentType のクエリセットを GenericPrefetch の querysets パラメータで指定する必要があります。

Changed in Django 5.0:

均質でない結果セットを持つ GenericForeignKey のプリフェッチをサポートしました。

例えば、以下のようなモデルがあると考えます:

from django.db import models


class Topping(models.Model):
    name = models.CharField(max_length=30)


class Pizza(models.Model):
    name = models.CharField(max_length=50)
    toppings = models.ManyToManyField(Topping)

    def __str__(self):
        return "%s (%s)" % (
            self.name,
            ", ".join(topping.name for topping in self.toppings.all()),
        )

そしてこれを実行します:

>>> Pizza.objects.all()
["Hawaiian (ham, pineapple)", "Seafood (prawns, smoked salmon)"...

問題は、 Pizza.__str__() が self.toppings.all() を要求するたびにデータベースにクエリを送信する必要があることです。これにより、 Pizza.objects.all() では Pizza QuerySet の すべての アイテムに対して Toppings テーブルでのクエリを実行することになります。

prefetch_related を使えば、クエリをたった2つに削減できます。

>>> Pizza.objects.prefetch_related("toppings")

上記は、それぞれの Pizza に対する self.toppings.all() を意味しています。これにより、 self.toppings.all() が呼び出されるたびにデータベースにアイテムを取得しに行くのではなく、単一のクエリで事前に読み込まれた QuerySet のキャッシュを利用するようになります。

すなわち、 対象の Pizza に関連するすべてのトッピングが単一のクエリで取得され、関連する結果が事前にキャッシュされた QuerySets を生成するのに使用されます。この QuerySets は self.toppings.all() の呼び出しで使用されることになります。

prefetch_related() の追加クエリは、 QuerySet の評価が開始され、主クエリが実行された後に実行されます。

主クエリが実行されてから追加クエリが実行されるまでの間に、別のデータベースクエリによってアイテムが変更されるのを防ぐ仕組みがないため、矛盾した結果が出力される可能性に留意してください。例えば、主クエリが実行された後に Pizza が削除された場合、追加クエリではトッピングが返されず、ピザにトッピングがないように見えます。

>>> Pizza.objects.prefetch_related("toppings")
#  "Hawaiian" Pizza was deleted in another shell.
<QuerySet [<Pizza: Hawaiian ()>, <Pizza: Seafood (prawns, smoked salmon)>]>

モデルインスタンスのイテラブルを保持する場合は、 prefetch_related_objects() 関数を使ってこれらインスタンスに関連する属性を事前読み込みしておくことができます。

主 QuerySet の結果のキャッシュと指定されたすべての関連オブジェクトは、メモリ上に完全にロードされますが、これは一般的な QuerySet の挙動と異なる点に注意してください。通常、クエリがデータベースで実行された後であっても、 オブジェクトは必要になるまでメモリに呼び出されません。

注釈

いつもの QuerySets がそうであるように、異なるデータベースクエリを意味するチェーンメソッドを連続させると、過去にキャッシュした結果は無視され、新たなデータベースクエリを発行してデータが取得されます。つまり、以下のように実装すると:

>>> pizzas = Pizza.objects.prefetch_related("toppings")
>>> [list(pizza.toppings.filter(spicy=True)) for pizza in pizzas]

... pizza.toppings.all() で事前読み込みしたことが役に立ちません。 prefetch_related('toppings') は pizza.toppings.all() を意味しますが、 pizza.toppings.filter() は別の新しいクエリを発行しており、事前に読み込まれたキャッシュは利用されません。それどころか、不要なデータベースクエリを実行したことで、パフォーマンスが低下します。ですから、この機能は注意深く利用してください！

また、 関係マネージャ で add() 、 remove() 、 clear() 、 set() といったデータベース互換のメソッドを呼び出した場合、リレーション用の事前呼び出しキャッシュはすべてクリアされます。

通常の結合構文を使って、リレーション先のフィールドのさらにリレーション先のフィールドも参照できます。上記の例に以下のモデルを追加したとして考えましょう:

class Restaurant(models.Model):
    pizzas = models.ManyToManyField(Pizza, related_name="restaurants")
    best_pizza = models.ForeignKey(
        Pizza, related_name="championed_by", on_delete=models.CASCADE
    )

以下は適切です:

>>> Restaurant.objects.prefetch_related("pizzas__toppings")

これはレストランに所属するすべてのピザと、これらのピザに所属するすべてのトッピングを事前読み込みします。これにより、3 つのデータベースクエリが発行されます - 一つはレストランのため、一つはピザのため、そしてもう一つはトッピングのためです。

>>> Restaurant.objects.prefetch_related("best_pizza__toppings")

これは、各レストランのベストピザとベストピザのトッピングすべてを取得します。これは3つのデータベースクエリで行われます。1つはレストラン、1つは "ベストピザ" 、1つはトッピングです。

best_pizza のリレーションシップも select_related を使って取得することで、クエリを2回に減らすことができます:

>>> Restaurant.objects.select_related("best_pizza").prefetch_related("best_pizza__toppings")

事前読み込みはメインクエリ ( select_related が必要とする結合を含む) の後に実行されるので、 best_pizza がすでに読み込まれたことを検出でき、再読み込みをスキップできます。

prefetch_related を連結して呼び出すと、事前読み込みのルックアップを蓄積します。すべての prefetch_related 動作をクリアするには None パラメータを渡してください。

>>> non_prefetched = qs.prefetch_related(None)

prefetch_related を使う際の違いの一つは、一つのクエリで生成されたオブジェクトは関連した異なるオブジェクト間で共有できることです。例えば、単一の Python モデルインスタンスは、返されたオブジェクトのツリー内で複数現れることができます。これは通常、外部キーで発生します。通常、この動作は問題とはならず、むしろメモリと CPU の両方を節約します。

prefetch_related は GenericForeignKey リレーションシップの事前読み込みをサポートしますが、クエリ数はデータに依存します。GenericForeignKey は複数のテーブルでデータを参照できるので、すべてのアイテムに対する単一のクエリではなく各テーブルを参照するクエリが必要となります。関連する行がまだ取得されていない場合、ContentType テーブルで追加的なクエリが必要となります。

ほとんどの場合、prefetch_related は 'IN' 演算子を使った SQL クエリで実装されます。つまり、大きな QuerySet の場合は大きな 'IN' 句が生成される可能性があり、データベースによっては SQL クエリのパースや実行時にパフォーマンス上の問題が発生する可能性があります。使用するケースに応じて、常にプロファイルを分析してください！

クエリの実行に iterator() を使用した場合、 prefetch_related() は chunk_size の値が指定されたときのみ呼び出されます。

Prefetch オブジェクトを使って、事前呼び出しの操作をより細かくコントロールできます。

Prefetch の最もシンプルな形では、従来の文字列ベースのルックアップと同等になります:

>>> from django.db.models import Prefetch
>>> Restaurant.objects.prefetch_related(Prefetch("pizzas__toppings"))

オプションの queryset 引数を使って、独自のクエリセットを指定できます。これは、クエリセットのデフォルトの並び順を変更するために使用できます:

>>> Restaurant.objects.prefetch_related(
...     Prefetch("pizzas__toppings", queryset=Toppings.objects.order_by("name"))
... )

もしくは、さらにクエリ数を減らすために、可能なときは select_related() を呼び出します:

>>> Pizza.objects.prefetch_related(
...     Prefetch("restaurants", queryset=Restaurant.objects.select_related("best_pizza"))
... )

また、オプションの to_attr で、事前読み込みの結果を独自の属性に割り当てることもできます。結果はリストに直接格納されます。

これにより、異なる QuerySet で同じリレーションを複数回事前読み込みできるようになります; 例えば:

>>> vegetarian_pizzas = Pizza.objects.filter(vegetarian=True)
>>> Restaurant.objects.prefetch_related(
...     Prefetch("pizzas", to_attr="menu"),
...     Prefetch("pizzas", queryset=vegetarian_pizzas, to_attr="vegetarian_menu"),
... )

独自の to_attr で生成したルックアップはいつも通り他のルックアップでも使用可能です:

>>> vegetarian_pizzas = Pizza.objects.filter(vegetarian=True)
>>> Restaurant.objects.prefetch_related(
...     Prefetch("pizzas", queryset=vegetarian_pizzas, to_attr="vegetarian_menu"),
...     "vegetarian_menu__toppings",
... )

to_attr の使用は、関係するマネージャのキャッシュにフィルタした結果を格納するよりも明確になるよう、事前読み込みした結果をフィルタする際に推奨されます:

>>> queryset = Pizza.objects.filter(vegetarian=True)
>>>
>>> # Recommended:
>>> restaurants = Restaurant.objects.prefetch_related(
...     Prefetch("pizzas", queryset=queryset, to_attr="vegetarian_pizzas")
... )
>>> vegetarian_pizzas = restaurants[0].vegetarian_pizzas
>>>
>>> # Not recommended:
>>> restaurants = Restaurant.objects.prefetch_related(
...     Prefetch("pizzas", queryset=queryset),
... )
>>> vegetarian_pizzas = restaurants[0].pizzas.all()

独自の事前読み込みは、 ForeignKey や OneToOneField のような単一の関連リレーションでも機能します。一般的にはこういう場合 select_related() を使いたくなるでしょうが、 QuerySet が役立つ場面も多くあります:

• 関連モデルに対してさらに事前読み込みを行う QuerySet を使用したい。

• 関連オブジェクトのサブセットのみを事前読み込みしたい。

• 遅延読み込みフィールド のようなパフォーマンス最適化のテクニックを使用したい。

  >>> queryset = Pizza.objects.only("name")
  >>>
  >>> restaurants = Restaurant.objects.prefetch_related(
  ...     Prefetch("best_pizza", queryset=queryset)
  ... )
  

複数のデータベースを使っている場合、Prefetch はデータベースの選択を尊重します。内側のクエリがデータベースを指定していない場合、外側のクエリで指定されたデータベースを使用します。以下はすべて正しいコードです:

>>> # Both inner and outer queries will use the 'replica' database
>>> Restaurant.objects.prefetch_related("pizzas__toppings").using("replica")
>>> Restaurant.objects.prefetch_related(
...     Prefetch("pizzas__toppings"),
... ).using("replica")
>>>
>>> # Inner will use the 'replica' database; outer will use 'default' database
>>> Restaurant.objects.prefetch_related(
...     Prefetch("pizzas__toppings", queryset=Toppings.objects.using("replica")),
... )
>>>
>>> # Inner will use 'replica' database; outer will use 'cold-storage' database
>>> Restaurant.objects.prefetch_related(
...     Prefetch("pizzas__toppings", queryset=Toppings.objects.using("replica")),
... ).using("cold-storage")

注釈

ルックアップの順番は重要です。

以下の例を見てみましょう:

>>> prefetch_related("pizzas__toppings", "pizzas")

'pizzas__toppings' がすでに必要な情報を含んでいるので、並び替えしていないにもかかわらずこれは機能します。したがって 2 番目の引数 'pizzas' は実際には不要です。

>>> prefetch_related("pizzas__toppings", Prefetch("pizzas", queryset=Pizza.objects.all()))

事前に見たルックアップクエリを再定義しようとしているため、これは ValueError を発生させます。 'pizzas' を横切るために 'pizzas__toppings' の一部として暗黙的なクエリセットが生成される点に留意してください。

>>> prefetch_related("pizza_list__toppings", Prefetch("pizzas", to_attr="pizza_list"))

'pizza_list__toppings' が実行される際にまだ 'pizza_list' が存在していないため、これは AttributeError を引き起こします。

この注意事項は、Prefetch の使用に限りません。高度なテクニックのいくつかでは、余計なクエリの生成を防止するため、特定の順序でルックアップを実施する必要があるかもしれません。したがって、prefetch_related の引数には常に注意を払うことを推奨します。

extra()

extra(select=None, where=None, params=None, tables=None, order_by=None, select_params=None)

Django のクエリ構文だけでは、複雑な WHERE 節を簡単に表現できないことがあります。このようなエッジケースのために、 Django は extra() QuerySet 修飾子、つまり QuerySet が生成する SQL に特定の句を注入するフックを提供します。

このやり方は最後の手段として使ってください。

これは古い API で、将来的には非推奨とする予定です。他の QuerySet メソッドでクエリを表現できない場合にのみ使用してください。もしあなたがこのメソッドを必要とするのであれば、私たちが QuerySet APIを拡張して extra() を削除できるように、 QuerySet.extra キーワード とあなたの使用例を添えて チケットを提出 してください (ただしその前に既存のチケットのリストを確認してください)。このメソッドの改善やバグの修正はもう行っていません。

例えば、 extra() を使った下記のコードは:

>>> qs.extra(
...     select={"val": "select col from sometable where othercol = %s"},
...     select_params=(someparam,),
... )

下記と等価です:

>>> qs.annotate(val=RawSQL("select col from sometable where othercol = %s", (someparam,)))

RawSQL を使う主な利点は、必要に応じて output_field を指定できることです。主な欠点は、生の SQL でクエリセットのテーブルエイリアスを参照すると、Django がそのエイリアスを変更する可能性があることです (たとえば、クエリセットが別のクエリのサブクエリとして使われる場合など)。

警告

extra() を使うときは常に細心の注意を払ってください。SQL インジェクション攻撃から守るために、使うときは常に params を使用して、ユーザが制御できるパラメータをエスケープする必要があります。

また、SQL文字列のプレースホルダを引用符で囲んではいけません。この例では %s を引用符で囲んでいるため、SQLインジェクションに対して脆弱です:

SELECT col FROM sometable WHERE othercol = '%s'  # unsafe!

Django が SQL インジェクションを防ぐ 仕組みの説明があります。

定義上、これらの extra ルックアップは異なるデータベースエンジンに移植できない可能性があり（明示的にSQLコードを記述しているため）、DRY原則に違反するため、可能であれば避けるべきです。

params、select、where、tables のうち、少なくとも1つを指定します。どの引数も必須ではありませんが、少なくとも1つは指定する必要があります。

• select

  select 引数を使用すると、SELECT 句に追加のフィールドを配置できます。属性名を SQL 句にマッピングした辞書を使用して、その属性を計算するために使用します。

  実装例:

  Entry.objects.extra(select={"is_recent": "pub_date > '2006-01-01'"})
  

  その結果、各 Entry オブジェクトには、追加の属性である is_recent が付与されます。これは、エントリーの pub_date が2006年1月1日よりも後の日付であるかどうかを表す真偽値です。

  Django は指定された SQL スニペットを SELECT 文に直接挿入するので、上の例の SQL は次のようになります:

  SELECT blog_entry.*, (pub_date > '2006-01-01') AS is_recent
  FROM blog_entry;
  

  次の例はもっと高度です。サブクエリを使って、各結果の Blog オブジェクトに、関連する Entry オブジェクトの整数カウントである entry_count 属性を付与します。

  Blog.objects.extra(
      select={
          "entry_count": "SELECT COUNT(*) FROM blog_entry WHERE blog_entry.blog_id = blog_blog.id"
      },
  )
  

  この特別なケースでは、クエリの FROM 句に既に blog_blog テーブルが含まれていることを利用している。

  上記の例の結果として得られる SQL は次のとおりです:

  SELECT blog_blog.*, (SELECT COUNT(*) FROM blog_entry WHERE blog_entry.blog_id = blog_blog.id) AS entry_count
  FROM blog_blog;
  

  ほとんどのデータベースエンジンで、サブクエリを囲む必要のある括弧は、Django の "select" 句では不要です。また、一部のデータベースバックエンド（一部のMySQLバージョンなど）はサブクエリをサポートしていないことに注意してください。

  まれに、extra(select=...) でSQLフラグメントにパラメータを渡したい場合があります。その場合は、select_params パラメータを使用してください。

  これは、次のように動作します:

  Blog.objects.extra(
      select={"a": "%s", "b": "%s"},
      select_params=("one", "two"),
  )
  

  select 文内で文字列 %s をそのまま使いたい場合は、 %%s というシーケンスを使用してください。

• where / tables

  SQLの明示的な WHERE 句を定義できます。たとえば、明示的でない結合を実行するために where を使用できます。また、SQLの FROM 句に手動でテーブルを追加できます。これには tables を使用します。

  where と tables は、どちらも文字列のリストを取ります。全ての where パラメーターは、他の検索条件と "AND" 演算されます。

  実装例:

  Entry.objects.extra(where=["foo='a' OR bar = 'a'", "baz = 'a'"])
  

  ...これは大まかに次の SQL に翻訳されます:

  SELECT * FROM blog_entry WHERE (foo='a' OR bar='a') AND (baz='a')
  

  すでにクエリで使われているテーブルを指定する場合、 tables パラメータを使うときには注意してください。テーブル tables パラメータを使ってテーブルを追加すると、 Django はそのテーブルが既に含まれている場合、そのテーブルをもう一回追加したいと仮定します。この場合、テーブル名にエイリアスが付けられるので、問題が生じます。テーブルが SQL 文の中で複数回出現する場合、データベースが区別できるように、2 回目以降の出現にはエイリアスを使う必要があります。追加の where パラメータで追加したテーブルを参照している場合、これはエラーの原因になります。

  通常は、クエリに既に表示されていない追加のテーブルのみを追加します。しかし、上記の場合が発生した場合は、いくつかの解決策があります。まず、追加のテーブルを含めずに、すでにクエリにあるテーブルを使用できるかどうかを確認してください。それが不可能な場合は、extra() メソッドをクエリセットの構築の最初に配置して、そのテーブルが最初に使用されるようにします。最後に、すべてが失敗した場合は、生成されたクエリを確認し、 where 句への追加をエイリアスの利用に書き直します。エイリアスは、同じ方法でクエリセットを構築するたびに同じであるため、エイリアス名は変わらないことを信頼できます。

• order_by

  extra() で追加した新しいフィールドやテーブルを使用してクエリセットを並べ替える必要がある場合は、extra() の order_by パラメータを使用し、文字列のシーケンスを渡します。 これらの文字列は、通常の querysets の order_by() メソッドのようなモデルフィールド、table_name.column_name の形式、または extra() の select パラメータで指定した列のエイリアスである必要があります。

  例:

  q = Entry.objects.extra(select={"is_recent": "pub_date > '2006-01-01'"})
  q = q.extra(order_by=["-is_recent"])
  

  これにより、is_recent が true であるすべてのアイテムが結果セットの先頭に並べ替えられます (降順では True が False よりも先に並びます)。

  ちなみに、これは extra() を複数回呼び出しても期待通りに動作する（つまり、毎回新しい制約を追加する）ことを示しています。

• params

  上記の where パラメータは、標準のPythonデータベース文字列プレースホルダー、 '%s' を使用して、データベースエンジンが自動的に引用符で囲むべきパラメータを示すことができます。 params 引数は、代入される追加のパラメータのリストです。

  実装例:

  Entry.objects.extra(where=["headline=%s"], params=["Lennon"])
  

  常に params を使用し、値を直接 where に埋め込まないでください。なぜなら params を使用することで、値が特定のバックエンドに応じて正しく引用符で囲まれることが保証されるからです。例えば、引用符は正しくエスケープされます。

  悪い例:

  Entry.objects.extra(where=["headline='Lennon'"])
  

  良い例:

  Entry.objects.extra(where=["headline=%s"], params=["Lennon"])
  

警告

もしあなたが MySQL でクエリを処理する場合は、複数の型を扱う際に MySQL の暗黙的な型変換が予期しない結果をもたらす場合がある事に注意してください。もし文字列型で定義したカラムに対し、数値型の値で問い合わせた場合、MySQL は比較処理を行う前にテーブル上の全ての値の型を数値型に変換します。例えば 'abc'、 'def' といった値が含まれているテーブルに対して WHERE mycolumn=0 という条件での問い合わせを行うと、両方の行がマッチします。これを防ぐため、クエリの値を利用する前に適切な型キャストを行ってください。

defer()

defer(*fields)

複雑なデータモデリングの場面では、モデルにはたくさんのフィールドが含まれるかもしれません。その中には、大量のデータを含むフィールド (たとえばテキストフィールド) や、Python オブジェクトに変換するために高コストな処理を必要とするフィールドがあるかもしれません。QuerySet の結果を、最初にデータを取得するときにはまだそのフィールドが必要かどうかわからないような状況で使う場合、まだデータベースからは読み込まないように Django に指示できます。

読み込ませたくないフィールドの名前を defer() に渡すことで、それを実現できます:

Entry.objects.defer("headline", "body")

Defer（遅延読み込み）されたフィールドを持つ QuerySet はモデルインスタンスを返します。それぞれの遅延読み込みフィールドは、そのフィールドにアクセスしたときにデータベースから取得されます (すべての遅延読み込みフィールドを一度に取得するのではなく、1つずつ取得します)。

注釈

遅延読み込みに指定されたフィールドは非同期コードからはこのように遅延ロードすることはできません。代わりに SynchronousOnlyOperation 例外が発生します。もし非同期コードを書いているのであれば、defer() されたフィールドにアクセスしようとしてはいけません。

defer() を複数回呼び出すこともできます。それぞれの呼び出しは新しいフィールドを遅延読み込みリストに追加します:

# Defers both the body and headline fields.
Entry.objects.defer("body").filter(rating=5).defer("headline")

フィールドが遅延読み込みリストに追加される順番は重要ではありません。すでに遅延読み込みに指定されているフィールド名で defer() を呼び出しても意味はありません（フィールドは遅延読み込みに指定されたままです）。

標準的な2重アンダースコア記法を用いてリレーション先のフィールドを区切ることで、(リレーション先のモデルが select_related() によって読み込まれる場合) リレーション先のモデルのフィールドの読み込みを遅延させることもできます:

Blog.objects.select_related().defer("entry__headline", "entry__body")

遅延読み込みフィールドの指定を消去したい場合は、 defer() のパラメータとして None を渡します:

# Load all fields immediately.
my_queryset.defer(None)

モデル内のいくつかのフィールドは、指定しても遅延読み込みされません。主キーの読み込みは決して遅延できません。リレーション先のモデルを取得するために select_related() を使っている場合、最初のモデルからリレーション先のモデルに接続するフィールドの読み込みを遅延すべきではありません。

同様に、 defer() (またはそれに対応する only()) を集計関数の引数を含めて (例えば annotate() の結果を使って) 呼び出しても意味はありません。集計された値は常に結果の QuerySet に取り込まれます。

注釈

defer() メソッド（およびその同類である only() 、以下同様）は高度なユースケースのためのものです。クエリを詳細に分析し、どのような情報が必要かを 正確に 理解し、必要なフィールドを返すこととモデルの全フィールドを返すことの差が大きいと判断した場合の最適化を提供するものです。

高度なユースケースだと思う場合でも、 defer() を使用するのは、 QuerySetのロード時に、余分なフィールドが必要かどうかを判断 できない場合だけ にしてください。データの特定のサブセットを頻繁に読み込んで使うなら、モデルを正規化し、ロードしないデータを別のモデル（とデータベーステーブル）に置くのが最善の選択です。もしカラムを一つのテーブル内に どうしても保持する必要がある 場合は、 Meta.managed = False (managed 属性 のドキュメントを参照) に設定されたモデルを作成し、通常必要なフィールドのみを含めます。これは、通常 defer() を呼び出す場合に使用します。これにより、コードは読み手に対してより明示的になり、わずかに速くなり、Pythonプロセスで消費するメモリも少し減ります。

たとえば、これらのモデルはどちらも同じデータベーステーブルを使用しています:

class CommonlyUsedModel(models.Model):
    f1 = models.CharField(max_length=10)

    class Meta:
        managed = False
        db_table = "app_largetable"


class ManagedModel(models.Model):
    f1 = models.CharField(max_length=10)
    f2 = models.CharField(max_length=10)

    class Meta:
        db_table = "app_largetable"


# Two equivalent QuerySets:
CommonlyUsedModel.objects.all()
ManagedModel.objects.defer("f2")

非マネージドモデルと多くのフィールドを重複させる必要がある場合、共有フィールドを持つ抽象モデルを作成し、非マネージドモデルとマネージドモデルに抽象モデルを継承させるのが最善でしょう。

注釈

defer されたフィールドを持つインスタンスに対して save() を呼び出すと、読み込まれたフィールドだけが保存されます。詳細は save() を参照してください。

only()

only(*fields)

only() メソッドは本質的に defer() の逆です。このメソッドに渡されたフィールドのうち、既に遅延読み込みフィールドに指定されていないものだけが、 QuerySet が評価されたときに直ちにロードされます。

ほとんどのフィールドが遅延読み込みされる必要があるようなモデルの場合、only() を使って補完的なフィールドセットを指定すると、よりシンプルなコードになります。

name, age, biography という3つのフィールドを持つモデルがあるとします。次の2つのQuerySetは、どのフィールドが遅延読み込みされるかという点では同じです:

Person.objects.defer("age", "biography")
Person.objects.only("name")

only() を呼び出すと、読み込むフィールドの設定を即座に置き換えます。このメソッドは名前の通り、指定したフィールド だけ を読み込み、残りのフィールドの読み込みを先送りします。その結果、連続して only() を呼び出すと、最後に指定したフィールドだけが考慮されることになります:

# This will defer all fields except the headline.
Entry.objects.only("body", "rating").only("headline")

defer() は段階的に（遅延読み込みリストにフィールドを追加しながら）動作するので、 only() と defer() の呼び出しは組み合わせることができ、ロジカルに動作します:

# Final result is that everything except "headline" is deferred.
Entry.objects.only("headline", "body").defer("body")

# Final result loads headline immediately.
Entry.objects.defer("body").only("headline", "body")

defer() のドキュメントにある注意事項はすべて only() にも当てはまります。 only() は慎重に、そして他のオプションを使い果たした後にだけ使用してください。

only() を使って select_related() で要求したフィールドを省略した場合もエラーになります。 一方、引数なしで only() を呼び出すと、queryset によって取得された全てのフィールド (アノテーションを含む) が返されます。

defer() と同様に、非同期コードからは、まだ読み込まれていないフィールドにアクセスすることはできません。その場合、SynchronousOnlyOperation 例外が発生します。アクセスする可能性のあるすべてのフィールドが only() 呼び出し内に含まれていることを確認してください。

注釈

defer されたフィールドを持つインスタンスに対して save() を呼び出すと、読み込まれたフィールドだけが保存されます。詳細は save() を参照してください。

注釈

only() の後に defer() を使用すると、 defer() のフィールドが only() を上書きします。

using()

using(alias)

このメソッドは、複数のデータベースを使用している場合に QuerySet がどのデータベースに対して評価されるかを制御するためのものです。 このメソッドが受け取る唯一の引数は DATABASES で定義されているデータベースのエイリアスです。

例:

# queries the database with the 'default' alias.
>>> Entry.objects.all()

# queries the database with the 'backup' alias
>>> Entry.objects.using("backup")

select_for_update()

select_for_update(nowait=False, skip_locked=False, of=(), no_key=False)

トランザクションが終了するまで行をロックし、サポートされているデータベース上で SELECT ... FOR UPDATE SQL 文を生成する QuerySet を返します。

例:

from django.db import transaction

entries = Entry.objects.select_for_update().filter(author=request.user)
with transaction.atomic():
    for entry in entries:
        ...

クエリセットが評価されるとき（この場合、 for entry in entries ）、マッチしたすべてのエントリは、トランザクションブロックが終了するまでロックされます。つまり、他のトランザクションがそれらのエントリを変更したりロックを取得したりするのを防ぐことができます。

通常、他のトランザクションが既に選択行の1つをロックしている場合、ロックが解除されるまでクエリはブロックされます。このような動作が望ましくない場合は、 select_for_update(nowait=True) を呼び出してください。これにより、呼び出しがノンブロッキングになります。競合するロックが既に他のトランザクションによって取得されている場合は、クエリセットが評価される際に DatabaseError が発生します。代わりに select_for_update(skip_locked=True) を使用すれば、ロックされた行を無視することもできます。 nowait と skip_locked は互いに排他的であり、両方のオプションを有効にして select_for_update() を呼び出そうとすると ValueError が発生します。

デフォルトでは、 select_for_update() はクエリによって選択された全ての行をロックします。たとえば、クエリセットのモデルの行に加えて、 select_related() で指定したリレーション先のオブジェクトの行もロックされます。この動作が望ましくない場合は、 select_related() と同じフィールド構文を使って select_for_update(of=(...)) でロックしたいリレーション先のオブジェクトを指定してください。クエリセットのモデルを参照するには 'self' という値を使用します。

親モデルを select_for_update(of=(...)) でロックする

複数テーブルの継承 を使用する際に親モデルをロックしたい場合は、 of 引数に親リンクフィールド (デフォルトでは <parent_model_name>_ptr) を指定する必要があります。たとえば次のようになります:

Restaurant.objects.select_for_update(of=("self", "place_ptr"))

フィールドを指定して select_for_update(of=(...)) を使う

例えば values() を使ってモデルをロックし、選択されたフィールドを指定したい場合、 of 引数で各モデルから少なくとも1つのフィールドを選択する必要があります。フィールドが選択されていないモデルはロックされません。

PostgreSQLの場合のみ、no_key=True を渡すことで、ロックがかかっている間、（たとえば外部キーによって）ロックされた行を参照するだけの行を作成できる、より弱いロックを取得できます。PostgreSQLのドキュメントに row-level lock modes についての詳細があります。

null 可能なリレーションでは select_for_update() は使用できません:

>>> Person.objects.select_related("hometown").select_for_update()
Traceback (most recent call last):
...
django.db.utils.NotSupportedError: FOR UPDATE cannot be applied to the nullable side of an outer join

この制限を回避するために、nullオブジェクトを気にしない場合は除外できます:

>>> Person.objects.select_related("hometown").select_for_update().exclude(hometown=None)
<QuerySet [<Person: ...)>, ...]>

データベースバックエンドの postgresql 、 oracle 、 mysql は select_for_update() をサポートしています。ただし、MariaDB は nowait 引数のみをサポートしており、MariaDB 10.6+ は skip_locked 引数もサポートしています。 no_key 引数は PostgreSQL のみでサポートされています。

nowait=True 、 skip_locked=True 、 no_key=True 、または of を select_for_update() に渡すと、MySQL のようなこれらのオプションをサポートしていないデータベースバックエンドでは NotSupportedError が発生します。これはコードが予期せずブロックされるのを防ぎます。

SELECT ... FOR UPDATE をサポートしているバックエンドで select_for_update() をオートコミットモードでクエリセットを評価すると TransactionManagementError エラーになります。もしこれが許される場合、これはデータを用意に破壊します。たとえばトランザクショ ン外のトランザクションで実行されることを期待するコードを呼び出すことで簡単に破壊が起こります。

SELECT ... FOR UPDATE をサポートしていないバックエンド (SQLite など) で select_for_update() を使用しても意味はありません。 SELECT ... FOR UPDATE はクエリに追加されず、 select_for_update() がオートコミットモードで使用されてもエラーは発生しません。

警告

自動コミットモードでは select_for_update() は通常失敗しますが、 TestCase は自動的に各テストをトランザクションでラップするので、 atomic() ブロックの外でも TestCase の中で select_for_update() を呼び出すと、(おそらく予期せず) TransactionManagementError を発生させずに通過します。正しく select_for_update() をテストするには TransactionTestCase を使うべきです。

一部の式はサポートされていません

PostgreSQL は select_for_update() を Window 式でサポートしていません。

raw()

raw(raw_query, params=(), translations=None, using=None)

素の SQL クエリを受け取って実行し、 django.db.models.query.RawQuerySet インスタンスを返します。この RawQuerySet インスタンスは、通常の QuerySet と同様にイテレートすることで、オブジェクトインスタンスを生成できます。

詳細は 素の SQL 文の実行 を参照してください。

警告

raw() は常に新しいクエリをトリガーし、以前のフィルタリングを考慮しません。そのため、通常は Manager から呼び出すか、新しい QuerySet インスタンスから呼び出す必要があります。

新しい QuerySet を返す演算子

結合したクエリセットは同じモデルを使用しなければなりません。

AND (&)

SQL の AND 演算子を使い、フィルタを連結するのと同じように、2つの QuerySet を結合します。

以下のコードは同等です:

Model.objects.filter(x=1) & Model.objects.filter(y=2)
Model.objects.filter(x=1).filter(y=2)

これらは SQL で言う下記と同等です:

SELECT ... WHERE x=1 AND y=2

OR (|)

SQL の OR 演算子を使用して、2つの QuerySet を結合します。

以下のコードは同等です:

Model.objects.filter(x=1) | Model.objects.filter(y=2)
from django.db.models import Q

Model.objects.filter(Q(x=1) | Q(y=2))

これらは SQL で言う下記と同等です:

SELECT ... WHERE x=1 OR y=2

| は可換演算ではないので、（等価ではあるが）異なるクエリが生成される可能性があります。

XOR (^)

SQLの XOR 演算子を使用して、2つの QuerySet を結合します。XOR 式は、奇数個の条件が真である行にマッチします。

以下のコードは同等です:

Model.objects.filter(x=1) ^ Model.objects.filter(y=2)
from django.db.models import Q

Model.objects.filter(Q(x=1) ^ Q(y=2))

これらは SQL で言う下記と同等です:

SELECT ... WHERE x=1 XOR y=2

注釈

XOR は MariaDB と MySQL ではネイティブでサポートされています。 他のデータベースでは、 x ^ y ^ .... z は下記と等価な式に変換されます:

(x OR y OR ... OR z) AND
1=MOD(
    (CASE WHEN x THEN 1 ELSE 0 END) +
    (CASE WHEN y THEN 1 ELSE 0 END) +
    ...
    (CASE WHEN z THEN 1 ELSE 0 END),
    2
)

Changed in Django 5.0:

古いバージョンでは、SQL の XOR 演算子をネイティブにサポートしていないデータベースでは、 XOR はただ1つの演算子でマッチする行だけを返していました。 以前の動作は MySQL、MariaDB、Python の動作と一致していませんでした。

QuerySet を返さないメソッド

以下の QuerySet メソッドは QuerySet を評価し、 QuerySet 以外のものを返します。

これらのメソッドはキャッシュを使用しません ( キャッシュと QuerySet を参照してください)。むしろ、呼び出されるたびにデータベースにクエリを行います。

これらのメソッドは QuerySet を評価するので、ブロッキング呼び出しとなり、そのため主な（同期）バージョンは非同期コードから呼び出すことはできません。このため、それぞれに対応する非同期バージョンがあり、 a 接頭辞が付いています。例えば、 get(…) の代わりに await aget(…) が使用できます。

これらのメソッドの挙動には、通常その非同期性以外に違いはありませんが、各メソッドの具体的な違いは、それぞれのメソッドの説明のすぐそばに記載されています。

get()

get(*args, **kwargs)

aget(*args, **kwargs)

非同期バージョン: aget()

指定されたルックアップパラメータに一致するオブジェクトを返します。これらのパラメータは、 Field lookups で説明されている形式に従うべきです。主キーやユニーク制約のあるフィールドのように、一意性が保証されるルックアップを使うべきです。例えば下記のようにします:

Entry.objects.get(id=1)
Entry.objects.get(Q(blog=blog) & Q(entry_number=1))

クエリセットがすでに1行だけを返すことがわかっている場合、引数なしで get() を使うことでその行のオブジェクトを取得できます。

Entry.objects.filter(pk=1).get()

もし``get()`` がオブジェクトを見つけられなかった場合は、 Model.DoesNotExist 例外が発生します。

Entry.objects.get(id=-999)  # raises Entry.DoesNotExist

もし get() が複数のオブジェクトを見つけた場合は、 Model.MultipleObjectsReturned 例外が発生します。

Entry.objects.get(name="A Duplicated Name")  # raises Entry.MultipleObjectsReturned

これらの例外クラスはモデルクラスの属性であり、そのモデルに特有のものです。複数のモデルに対する get() 呼び出しでこのような例外を処理したい場合、一般的な基底クラスを使用できます。たとえば下記のように、 django.core.exceptions.ObjectDoesNotExist を使って、複数のモデルからの DoesNotExist 例外をできます:

from django.core.exceptions import ObjectDoesNotExist

try:
    blog = Blog.objects.get(id=1)
    entry = Entry.objects.get(blog=blog, entry_number=1)
except ObjectDoesNotExist:
    print("Either the blog or entry doesn't exist.")

create()

create(**kwargs)

acreate(**kwargs)

非同期バージョン: acreate()

1ステップでオブジェクトを作成して保存するための便利なメソッドす。たとえばこのようにします:

p = Person.objects.create(first_name="Bruce", last_name="Springsteen")

そして、:

p = Person(first_name="Bruce", last_name="Springsteen")
p.save(force_insert=True)

これらは同等です。

別の場所で force_insert パラメータについても説明していますが、それは新しいオブジェクトを常に作成するよう強制するものです。普通はこれを気にする必要はありません。しかし、モデルが手動で指定した主キー値を含み、その値が既にデータベースに存在する場合、 create() の呼び出しは IntegrityError で失敗します。これは、主キーは一意である必要があるためです。手動の主キーを使用している場合は、例外処理に備える必要があります。

get_or_create()

get_or_create(defaults=None, **kwargs)

aget_or_create(defaults=None, **kwargs)

非同期バージョン: aget_or_create()

与えられた kwargs を持つオブジェクトを検索するための便利なメソッドです (モデルがすべてのフィールドをデフォルトで持っている場合は空でもかまいません)。

(Object, created) のタプルを返します。"Object"は受け取ったものか作られたものです。そして"created"はそのObjectが作られたものかどうかのBooleanです。

これは、リクエストが並列処理されたときに、重複したオブジェクトが生成されるのを防ぐため、また、定型的なコードへのショートカットのためです。たとえば次のような場合、:

try:
    obj = Person.objects.get(first_name="John", last_name="Lennon")
except Person.DoesNotExist:
    obj = Person(first_name="John", last_name="Lennon", birthday=date(1940, 10, 9))
    obj.save()

ここで、同時リクエストにより、同じパラメータで Person を保存しようとする試みが複数回行われる可能性があります。この競合状態を回避するために、上記の例は get_or_create() を使って次のように書き換えることができます:

obj, created = Person.objects.get_or_create(
    first_name="John",
    last_name="Lennon",
    defaults={"birthday": date(1940, 10, 9)},
)

get_or_create() に渡されたキーワード引数（オプションの defaults を除く）は get() 呼び出しで使用されます。オブジェクトが見つかった場合、 get_or_create() はそのオブジェクトと False のタプルを返します。

警告

このメソッドはデータベースがキーワード引数の一意性を強制していると仮定してアトミックに動作します (unique または unique_together を参照してください)。キーワード引数で使用されるフィールドにユニーク制約がない場合、このメソッドを同時に呼び出すと、同じパラメータを持つ複数の行が挿入される可能性があります。

get_or_create() と filter() を連結し、 Q オブジェクト を使用することで、取得するオブジェクトに対してより複雑な条件を指定できます。たとえば次のコードは、Robert と Bob Marley のどちらかが存在すればそれを取得し、そうでなければ後者（Bob Marley）を作成します:

from django.db.models import Q

obj, created = Person.objects.filter(
    Q(first_name="Bob") | Q(first_name="Robert"),
).get_or_create(last_name="Marley", defaults={"first_name": "Bob"})

複数のオブジェクトが見つかった場合、 get_or_create() は MultipleObjectsReturned を発生させます。オブジェクトが ** 見つからなかった** 場合、 get_or_create() は新しいオブジェクトをインスタンス化して保存し、新しいオブジェクトと True のタプルを返します。新しいオブジェクトはおおよそ以下のアルゴリズムに従って作成されます:

params = {k: v for k, v in kwargs.items() if "__" not in k}
params.update({k: v() if callable(v) else v for k, v in defaults.items()})
obj = self.model(**params)
obj.save()

英語では、defaults' 以外のキーワード引数で、2重アンダースコア（これはexact以外のルックアップを意味します）を含まないものから始めることを意味します。次に defaults の内容を追加し、必要であればキーを上書きして、その結果をモデルクラスのキーワード引数として使用します。もし defaults に呼び出し可能オブジェクトがあれば、それを評価します。上記のように、これは使用されるアルゴリズムを簡略化したものですが、適切な詳細はすべて含まれています。内部実装では、これよりもさらに多くのエラーチェックが行われ、エッジ条件も処理されます。興味があれば、コードを読んでください。

もし defaults という名前のフィールドがあり、それを get_or_create() で正確にルックアップしたい場合は、次のように 'defaults__exact' を使用します：

Foo.objects.get_or_create(defaults__exact="bar", defaults={"defaults": "baz"})

get_or_create() メソッドは create() と同様のエラー動作をします。オブジェクトを作成する必要があり、そのキーが既にデータベースに存在する場合、 IntegrityError が発生します。

最後に、Djangoビューで``get_or_create()``を使用する際の注意点について説明します。よほどの理由がない限り、 POST リクエスト以外では使用しないようにしてください。 GET リクエストはデータに影響を与えるべきではありません。代わりに、データに副作用がある場合は常に``POST``を使用してください。詳細については、HTTP仕様の 安全なメソッド を参照してください。

警告

ManyToManyField 属性と逆リレーションを通じて get_or_create() を使うことができます。この場合、クエリはリレーションのコンテキスト内で制限されます。一貫して使用しないと、整合性の問題が発生する可能性があります。

下記のモデルでは、:

class Chapter(models.Model):
    title = models.CharField(max_length=255, unique=True)


class Book(models.Model):
    title = models.CharField(max_length=256)
    chapters = models.ManyToManyField(Chapter)

get_or_create() は Book の chapters フィールドを通して使うことができますが、その本のコンテキスト内でしか取得できません:

>>> book = Book.objects.create(title="Ulysses")
>>> book.chapters.get_or_create(title="Telemachus")
(<Chapter: Telemachus>, True)
>>> book.chapters.get_or_create(title="Telemachus")
(<Chapter: Telemachus>, False)
>>> Chapter.objects.create(title="Chapter 1")
<Chapter: Chapter 1>
>>> book.chapters.get_or_create(title="Chapter 1")
# Raises IntegrityError

この現象は、"Ulysses "という本を通して "Chapter 1" を取得、または作成しようとしているために起こっています。しかし、そのいずれもできません。リレーションはその章を取得できません。なぜなら、その章はその本に関連していないからです。また、 title フィールドは一意でなければならないので、作成することもできません。

update_or_create()

update_or_create(defaults=None, create_defaults=None, **kwargs)

aupdate_or_create(defaults=None, create_defaults=None, **kwargs)

非同期バージョン: aupdate_or_create()

与えられた kwargs でオブジェクトを更新し、必要に応じて新しいオブジェクトを作成する便利なメソッドです。 create_defaults と defaults はどちらも (field, value) のペアの辞書です。 create_defaults と defaults の値はどちらも呼び出し可能オブジェクトです。 defaults はオブジェクトを更新する際に使用され、create_defaults はオブジェクトを作成する際に使用されます。もし create_defaults が指定されなかった場合、 defaults が作成操作に使用されます。

(Object, created) のタプルを返します。"Object"は受け取ったものか更新したものです。そして"created"はそのObjectが更新されたものかどうかのBooleanです。

update_or_create メソッドは、与えられた kwargs に基づいてデータベースからオブジェクトを取得しようとします。一致するオブジェクトが見つかった場合、 defaults 辞書に渡されたフィールドを更新します。

これは定型的なコードへのショートカットです。たとえば次のようなものです:

defaults = {"first_name": "Bob"}
create_defaults = {"first_name": "Bob", "birthday": date(1940, 10, 9)}
try:
    obj = Person.objects.get(first_name="John", last_name="Lennon")
    for key, value in defaults.items():
        setattr(obj, key, value)
    obj.save()
except Person.DoesNotExist:
    new_values = {"first_name": "John", "last_name": "Lennon"}
    new_values.update(create_defaults)
    obj = Person(**new_values)
    obj.save()

モデル内のフィールドの数が増えるにつれて、このパターンはかなり扱いにくくなります。上記の例は、 update_or_create() を使って次のように書き換えることができます:

obj, created = Person.objects.update_or_create(
    first_name="John",
    last_name="Lennon",
    defaults={"first_name": "Bob"},
    create_defaults={"first_name": "Bob", "birthday": date(1940, 10, 9)},
)

kwargs で渡された名前がどのように解決されるかについては get_or_create() を参照してください。

上記の get_or_create() で説明したように、このメソッドは、データベースレベルで一意性が強制されていない場合、複数の行が同時に挿入される競合状態に陥りがちです。

get_or_create() や create() と同様に、手動で指定した主キーを使用していて、オブジェクトを作成する必要があるが、そのキーが既にデータベースに存在する場合、 IntegrityError が発生します。

Changed in Django 4.2:

古いバージョンでは Model.save() の呼び出し時に update_or_create() が update_fields を指定していませんでした。

Changed in Django 5.0:

create_defaults 引数が追加されました。

bulk_create()

bulk_create(objs, batch_size=None, ignore_conflicts=False, update_conflicts=False, update_fields=None, unique_fields=None)

abulk_create(objs, batch_size=None, ignore_conflicts=False, update_conflicts=False, update_fields=None, unique_fields=None)

非同期バージョン: abulk_create()

このメソッドは、指定されたオブジェクトのリストを効率的な方法でデータベースに挿入し (通常、オブジェクトの数にかかわらずクエリは 1 回だけです)、作成されたオブジェクトを指定された順序でリストとして返します:

>>> objs = Entry.objects.bulk_create(
...     [
...         Entry(headline="This is a test"),
...         Entry(headline="This is only a test"),
...     ]
... )

しかし、これにはいくつかの注意点があります:

• モデルの save() メソッドは呼び出されず、 pre_save と post_save シグナルは送信されません。

• 複数テーブル継承シナリオの子モデルでは動作しません。

• モデルの主キーが AutoField で、 ignore_conflicts が False の場合、主キー属性は特定のデータベース (現在のところ PostgreSQL, MariaDB 10.5+, SQLite 3.35+) でしか取得できません。他のデータベースではセットされません。

• 多対多のリレーションシップでは動作しません。

• これは objs をリストにキャストし、それがジェネレータであれば objs を完全に評価します。このキャストにより、手動で主キーを指定したオブジェクトを最初に挿入できるように、すべてのオブジェクトを検査できます。ジェネレータ全体を一度に評価することなく、オブジェクトを一括して挿入したい場合は、オブジェクトに手動で指定した主キーがない限り、このテクニックを使用できます:

  from itertools import islice
  
  batch_size = 100
  objs = (Entry(headline="Test %s" % i) for i in range(1000))
  while True:
      batch = list(islice(objs, batch_size))
      if not batch:
          break
      Entry.objects.bulk_create(batch, batch_size)
  

batch_size パラメータは、1回のクエリでいくつのオブジェクトを作成するかを制御します。デフォルトでは、すべてのオブジェクトを 1 回のクエリで作成します。ただし、SQLite ではクエリごとに最大 999 個の変数が使用されます。

これをサポートしているデータベース（Oracleを除くすべてのデータベース）では、 ignore_conflicts パラメータを True に設定すると、一意な値の重複などの制約に違反する行の挿入の失敗を無視するようになります。

これをサポートしているデータベース（Oracleを除くすべてのデータベース）では、 update_conflicts パラメータを True に設定すると、行の挿入が競合して失敗したときに update_fields を更新するようになります。PostgreSQL と SQLite では、 update_fields に加えて、競合する可能性のある unique_fields のリストを指定する必要があります。

パラメータ ignore_conflicts を有効にすると、各モデルのインスタンスに主キーを指定できなくなります（データベースが通常サポートしている場合）。

Changed in Django 5.0:

古いバージョンでは、update_conflicts パラメータを有効にすると、各モデルインスタンスに主キーを指定できませんでした。

警告

MySQL と MariaDB では、 ignore_conflicts パラメータを True に設定すると、重複キー以外の特定の種類のエラーが警告に変わります。Strict モードでも同様です。たとえば、無効な値やnull制約違反などです。詳細は MySQL documentation と MariaDB documentation を参照してください。

bulk_update()

bulk_update(objs, fields, batch_size=None)

abulk_update(objs, fields, batch_size=None)

非同期バージョン: abulk_update()

このメソッドは、通常1回のクエリで、指定されたモデルインスタンスの指定されたフィールドを効率的に更新し、更新されたオブジェクトの数を返します:

>>> objs = [
...     Entry.objects.create(headline="Entry 1"),
...     Entry.objects.create(headline="Entry 2"),
... ]
>>> objs[0].headline = "This is entry 1"
>>> objs[1].headline = "This is entry 2"
>>> Entry.objects.bulk_update(objs, ["headline"])
2

QuerySet.update() は変更を保存するために使用されるので、モデルのリストをイテレートしてそれぞれ save() を呼び出すよりも効率的ですが、いくつかの注意点があります:

• モデルの主キーは更新できません。
• 各モデルの save() メソッドは呼び出されず、 pre_save と post_save シグナルは送信されません。
• 多数の行の多数のカラムを更新する場合、生成されるSQLは非常に大きくなる可能性があります。これを避けるには、適切な batch_size を指定します。
• 複数テーブル継承の継承元に定義されたフィールドを更新すると、継承元ごとに追加のクエリが発生します。
• 独立した1つのバッチ内に重複がある場合、そのバッチの最初のインスタンスだけが更新されます。
• 関数が返す更新されたオブジェクトの数は、渡されたオブジェクトの数より少ない場合があります。これは、渡されたオブジェクトが重複して同じバッチで更新されたり、オブジェクトがデータベースに存在しなくなるような競合状態が発生したりすることが原因です。

batch_size パラメータは、1回のクエリで保存されるオブジェクトの数を制御します。クエリで使用できる変数の数に制限がある SQLite と Oracle を除いて、デフォルトではすべてのオブジェクトを一括で更新します。

count()

count()

acount()

非同期バージョン: acount()

QuerySet にマッチするデータベース内のオブジェクトの数を整数で返します。

実装例:

# Returns the total number of entries in the database.
Entry.objects.count()

# Returns the number of entries whose headline contains 'Lennon'
Entry.objects.filter(headline__contains="Lennon").count()

count() 呼び出しは裏で SELECT COUNT(*) を実行するので、すべてのレコードを Python オブジェクトに読み込んで、その結果に対して len() を呼び出すのではなく、常に count() を使うべきです（オブジェクトをメモリに読み込む必要がある場合は別です、その場合は len() の方が高速です）。

もし QuerySet に含まれるアイテムの数が必要で、かつそこからモデルインスタンスを取得する場合 (たとえば、それをイテレートする場合) は、おそらく len(queryset) を使用する方が効率的でしょう。count() のように余分なデータベースクエリが発生することがないからです。

クエリセットがすでに完全に取得されている場合、 count() は余計なデータベースクエリを実行するのではなく、その長さを使用します。

in_bulk()

in_bulk(id_list=None, *, field_name='pk')

ain_bulk(id_list=None, *, field_name='pk')

非同期バージョン: ain_bulk()

フィールド値のリスト (id_list) とそれらの値の field_name を受け取り、各値を与えられたフィールド値を持つオブジェクトのインスタンスにマッピングした辞書を返します。 django.core.exceptions.ObjectDoesNotExist 例外が in_bulk によって発生することはありません。つまり、インスタンスにマッチしない id_list 値は無視されます。 id_list が指定されなかった場合、クエリセット内の全てのオブジェクトが返されます。フィールド名 field_name は一意なフィールドか、(distinct() で指定されたフィールドが一つしかない場合は) 区別されたフィールドでなければなりません。デフォルトは主キーです。

例:

>>> Blog.objects.in_bulk([1])
{1: <Blog: Beatles Blog>}
>>> Blog.objects.in_bulk([1, 2])
{1: <Blog: Beatles Blog>, 2: <Blog: Cheddar Talk>}
>>> Blog.objects.in_bulk([])
{}
>>> Blog.objects.in_bulk()
{1: <Blog: Beatles Blog>, 2: <Blog: Cheddar Talk>, 3: <Blog: Django Weblog>}
>>> Blog.objects.in_bulk(["beatles_blog"], field_name="slug")
{'beatles_blog': <Blog: Beatles Blog>}
>>> Blog.objects.distinct("name").in_bulk(field_name="name")
{'Beatles Blog': <Blog: Beatles Blog>, 'Cheddar Talk': <Blog: Cheddar Talk>, 'Django Weblog': <Blog: Django Weblog>}

in_bulk() に空のリストを渡すと、空の辞書が返されます。

iterator()

iterator(chunk_size=None)

aiterator(chunk_size=None)

非同期バージョン: aiterator()

( クエリを実行して ) QuerySet を評価し、その結果に対するイテレータ (PEP 234 を参照) を返します。非同期バージョンの aiterator を呼び出した場合は、非同期イテレータ (PEP 492 を参照) を返します。

クエリセット QuerySet は通常、結果を内部的にキャッシュするので、繰り返し評価しても追加のクエリが発生することはありません。一方、 iterator() は QuerySet レベルでのキャッシュを行わずに、結果を直接読み込みます (内部的には、デフォルトのイテレータは iterator() を呼び出し、戻り値をキャッシュします)。一度しかアクセスする必要のない大量のオブジェクトを返す QuerySet では、この方がパフォーマンスが向上し、メモリを大幅に削減できます。

すでに評価された クエリセット に対して iterator() を使用すると、クエリを再度評価することになるので注意してください。

chunk_size が与えられている限り、 iterator() は以前の prefetch_related() の呼び出しと互換性があります。より大きな値を指定すると、より少ないクエリでプリフェッチを行う必要がありますが、その代償としてメモリの使用量が大きくなります。

Changed in Django 5.0:

以前の prefetch_related() 呼び出しによる aiterator() のサポートが追加されました。

データベースによっては(例えばOracleや SQLite )、SQLの IN 句の最大項数が制限されている場合があります。そのため、この制限値以下の値を使用する必要があります。(特に、2つ以上のリレーションにまたがってプリフェッチを行う場合、chunk_size は、プリフェッチされた各リレーションに対して予測される結果の数が制限を下回る程度に小さくする必要があります)。

クエリセットがリレーション先のオブジェクトをプリフェッチしない限り、 chunk_size に何も値を指定しないと、 Django は暗黙のデフォルト値 2000 を使います。

データベースのバックエンドによっては、クエリの結果は一度に読み込まれるか、サーバーサイドのカーソルを使ってデータベースからストリーミングされます。

サーバーサイドカーソルとともに使う

Oracle と PostgreSQL はサーバーサイドカーソルを使用して、結果セット全体をメモリに読み込むことなくデータベースから結果をストリームします。

Oracle データベースドライバは常にサーバーサイドカーソルを使用します。

サーバーサイドカーソルでは、chunk_size パラメータはデータベースドライバレベルでキャッシュする結果の数を指定します。より大きなチャンクをフェッチすることで、データベースドライバとデータベース間の往復回数を減らすことができます。

PostgreSQLでは、サーバーサイドカーソルは DISABLE_SERVER_SIDE_CURSORS 設定が False の場合のみ使用されます。トランザクションプーリングモードで構成された接続プーラを使用している場合は トランザクションプールとサーバーサイドカーソル を参照してください。サーバーサイドカーソルが無効な場合、動作はサーバーサイドカーソルをサポートしていないデータベースと同じです。

サーバーサイドカーソルなしで使う

MySQL は結果のストリーミングをサポートしていないので、Python データベースドライバは結果セット全体をメモリに読み込みます。結果セットはその後、データベースアダプタによって PEP 249 で定義されている fetchmany() メソッドを使用して Python の行オブジェクトに変換されます。

SQLite は fetchmany() を使用してバッチで結果を取得できますが、SQLite は接続内のクエリ間の分離を提供していないため、イテレートするテーブルに書き込む際には注意が必要です。詳細は QuerySet.iterator() を使用する際の分離の問題 を参照してください。

chunk_size パラメータは Django がデータベースドライバから取得するバッチのサイ ズを制御します。バッチを大きくすると、データベースドライバとの通信のオーバヘッ ドが減りますが、その分メモリ消費量が少し増えます。

クエリセットがリレーション先のオブジェクトをプリフェッチしない限り、 chunk_size に何も値を与えない場合、 Django は暗黙のデフォルト値である 2000 を使うことになります。この値は、 psycopg メーリングリスト で計算された値です：

テキストデータと数値データが混在した10～20列の行を想定すると、2000行で100KB以下のデータを取得することになります。これは、転送される行数と、ループが早期に終了した場合に破棄されるデータとの間の良い妥協点だと思われます。

latest()

latest(*fields)

alatest(*fields)

非同期バージョン: alatest()

指定されたフィールドに基づいて、テーブル内の最新のオブジェクトを返します。

この例では、 pub_date フィールドに従って、テーブル内の最新の Entry を返します:

Entry.objects.latest("pub_date")

また、複数のフィールドから最新のものを選択することもできます。たとえば2つのエントリが同じ pub_date を持つ場合に、最も早い expire_date を持つ Entry を下記のように選択できます:

Entry.objects.latest("pub_date", "-expire_date")

'-expire_date' の負の符号は、expire_date を 降順 でソートすることを意味します。 latest() は最後の結果を取得するので、 expire_date が最も古い Entry が選択されます。

モデルの Meta が get_latest_by を指定している場合、 earliest() や latest() の引数を省略できます。 get_latest_by で指定されたフィールドがデフォルトで使用されます。

get() と同様に、 earliest() と latest() は与えられたパラメータを持つオブジェクトが存在しない場合、 DoesNotExist を発生させます。

なお、earliest() と latest() は単に利便性と可読性のために存在しています。

earliest() と latest() は null の日付を持つインスタンスを返すことがあります。

ソートはデータベースに委譲されるため、異なるデータベースを使用している場合、NULL値を許可するフィールドの結果は異なる順序になる可能性があります。たとえば、PostgreSQLとMySQLはnull値をnull値でない値よりも上位にあるかのようにソートしますが、SQLiteはその逆です。

下記のように、null 値をフィルタリングしたいこともあるでしょう:

Entry.objects.filter(pub_date__isnull=False).latest("pub_date")

earliest()

earliest(*fields)

aearliest(*fields)

非同期バージョン: aearliest()

向きが変わる以外は latest() のように動作します。

first()

first()

afirst()

非同期バージョン: afirst()

クエリセットにマッチする最初のオブジェクトを返します。マッチするオブジェクトがない場合は None を返します。QuerySet にソートが定義されていない場合、クエリセットは自動的にプライマリキーでソートされます。これは order_by() と一緒に使う で説明されているように、アグリゲーション（集計）の結果に影響を与える可能性があります。

実装例:

p = Article.objects.order_by("title", "pub_date").first()

first() は便利なメソッドであることに注意してください。以下のコードサンプルは上記の例と等価です:

try:
    p = Article.objects.order_by("title", "pub_date")[0]
except IndexError:
    p = None

last()

last()

alast()

非同期バージョン: alast()

first() のように動作しますが、クエリセットの最後のオブジェクトを返します。

aggregate()

aggregate(*args, **kwargs)

aaggregate(*args, **kwargs)

非同期バージョン: aaggregate()

QuerySet に対して計算された集計値 (平均、合計など) の辞書を返します。 aggregate() の各引数は、返却される辞書に含まれる値を指定します。

Django が提供する集計関数は以下の Aggregation Functions で説明されています。 集計は クエリ式 でもあるので、集計を他の集計や値と組み合わせて複雑な集計を作ることができます。

キーワード引数を使用して指定されたアグリゲーション（集計）は、アノテーションの名前としてキーワードを使用します。 無名の引数には、集計関数の名前と集約されるモデルフィールドに基づいて生成された名前が付けられます。複雑な集計では無名の引数を使用することはできず、エイリアスとしてキーワード引数を指定する必要があります。

たとえば、ブログエントリーを扱う場合、下記のように、ブログエントリーを投稿した著者の数を知りたいことがあるでしょう:

>>> from django.db.models import Count
>>> Blog.objects.aggregate(Count("entry"))
{'entry__count': 16}

キーワード引数を使用して集計関数を指定すると、返される集計値の名前を制御できます:

>>> Blog.objects.aggregate(number_of_entries=Count("entry"))
{'number_of_entries': 16}

集計処理についての深い議論については、 アグリゲーションについてのトピックガイド を確認してください。

exists()

exists()

aexists()

非同期バージョン: aexists()

戻り値は QuerySet に結果が含まれていれば True を、含まれていなければ False を返します。これは可能な限りシンプルで高速な方法でクエリを実行しようとしますが、通常の QuerySet クエリとほぼ同じクエリを実行します。

exists() は QuerySet に含まれるオブジェクトの存在に関連する検索、特に大きな QuerySet の検索に便利です。

クエリセットに項目が含まれているかどうかを調べるには、次のようにします:

if some_queryset.exists():
    print("There is at least one object in some_queryset")

これは以下のコードより高速です:

if some_queryset:
    print("There is at least one object in some_queryset")

...しかしそれほど大きな差はありません（したがって、効果を感じるには大きなクエリセットが必要です）。

さらに、some_queryset がまだ評価されていないが、いずれ評価されることがわかっている場合、some_queryset.exists() を使用すると、結果を取得してから返されたかどうかをチェックする bool(some_queryset) を使用するよりも、全体的な作業量（存在チェックのためのクエリ1回と、後で結果を取得するためのクエリ1回）が増えます。

contains()

contains(obj)

acontains(obj)

非同期バージョン: acontains()

QuerySet に obj が含まれていれば True を、含まれていなければ False を返します。これは、可能な限りシンプルで高速な方法でクエリを実行しようとします。

contains() は、特に大きな QuerySet のコンテキストにおいて、 QuerySet 内のオブジェクトの所属関係をチェックするのに便利です。

クエリセットに特定の項目が含まれているかどうかを確認するには、次のようにします:

if some_queryset.contains(obj):
    print("Entry contained in queryset")

これは、クエリセット全体を評価し、イテレートする必要がある以下の方法よりも高速です:

if obj in some_queryset:
    print("Entry contained in queryset")

exists() と同様に、some_queryset がまだ評価されていないが、いずれ評価されることがわかっている場合、some_queryset.contains(obj) を使用すると、追加のデータベースクエリを行うことになり、通常は全体的なパフォーマンスが低下します。

update()

update(**kwargs)

aupdate(**kwargs)

非同期バージョン: aupdate()

指定したフィールドに対して SQL の UPDATE クエリを実行し、マッチした行の数を返します (一部の行が既に新しい値を持っている場合は、更新された行の数と一致しないことがあります)。

たとえば、2010年に公開されたすべてのブログエントリーのコメントをオフにするには、次のようにします:

>>> Entry.objects.filter(pub_date__year=2010).update(comments_on=False)

(これは Entry モデルに pub_date と comments_on フィールドがあると仮定しています)。

複数のフィールドを更新できます。たとえば、以下のコードでは comments_on フィールドと headline フィールドを更新しています:

>>> Entry.objects.filter(pub_date__year=2010).update(
...     comments_on=False, headline="This is old"
... )

update() メソッドは即座に適用されます。更新される QuerySet の唯一の制限は、モデルのメインテーブルのカラムのみを更新することができ、リレーション先のモデルのカラムを更新することはできないということです。たとえば、このようなことはできません:

>>> Entry.objects.update(blog__name="foo")  # Won't work!

リレーション先のフィールドに基づくフィルタリングは可能です:

>>> Entry.objects.filter(blog__id=1).update(comments_on=True)

スライスが取られたり、それ以外の理由でこれ以上フィルタリングできなくなった QuerySet に対しては update() を呼び出すことはできません。

update() メソッドは、影響を受ける行の数を返します:

>>> Entry.objects.filter(id=64).update(comments_on=True)
1

>>> Entry.objects.filter(slug="nonexistent-slug").update(comments_on=True)
0

>>> Entry.objects.filter(pub_date__year=2010).update(comments_on=False)
132

レコードを更新するだけで、モデルオブジェクトに対して何もする必要がない場合、最も効率的なアプローチは、モデルオブジェクトをメモリに読み込むのではなく、 update() を呼び出すことです。たとえば、次のようにす書く代わりに、:

e = Entry.objects.get(id=10)
e.comments_on = False
e.save()

...次のように書きます:

Entry.objects.filter(id=10).update(comments_on=False)

また、update() を使用することで、オブジェクトを読み込んでから save() を呼び出すまでの短い間にデータベース内で何かが変更されてしまう競合状態を防ぐことができます。

最後に、 update() は SQL レベルで更新を行うので、モデル上の save() メソッドを呼び出したり、 pre_save や post_save シグナル ( Model.save() を呼び出した結果発生するシグナル) を発したりしないことに注意してください。カスタム save() メソッドを持つモデルのレコードを更新したい場合は、次のようにループして save() を呼び出します:

for e in Entry.objects.filter(pub_date__year=2010):
    e.comments_on = False
    e.save()

ソートされたクエリセット

order_by() と update() の連結は MariaDB と MySQL でのみサポートされており、異なるデータベースでは無視されます。これは、一意なフィールドを指定された順序で矛盾なく更新する場合に便利です。たとえば次のようにします:

Entry.objects.order_by("-number").update(number=F("number") + 1)

注釈

order_by() 句がアノテーション、継承されたフィールド、リレーション先のルックアップを含んでいる場合、order_by() 句は無視されます。

delete()

delete()

adelete()

非同期バージョン: adelete()

QuerySet 内のすべての行に対して SQL による DELETE クエリを実行し、削除されたオブジェクトの数とオブジェクトの種類ごとの削除数を辞書として返します。

delete() は即座に適用されます。スライスが取られたり、それ以外の理由でこれ以上フィルタリングできなくなった QuerySet に対しては delete() を呼び出すことはできません。

たとえば、特定のブログ内のすべてのエントリを削除するには、:

>>> b = Blog.objects.get(pk=1)

# Delete all the entries belonging to this Blog.
>>> Entry.objects.filter(blog=b).delete()
(4, {'blog.Entry': 2, 'blog.Entry_authors': 2})

デフォルトでは、 Django の ForeignKey は SQL の制約 ON DELETE CASCADE をエミュレートします。つまり、削除されるオブジェクトを指す外部キー を持つオブジェクトは一緒に削除されます。たとえば、次のようになります:

>>> blogs = Blog.objects.all()

# This will delete all Blogs and all of their Entry objects.
>>> blogs.delete()
(5, {'blog.Blog': 1, 'blog.Entry': 2, 'blog.Entry_authors': 2})

このカスケードの動作は、ForeignKey に対する on_delete 属性によってカスタマイズできます。

delete() メソッドは一括削除を行い、モデルの delete() メソッドを呼び出しません。しかし、削除されたオブジェクト (カスケード削除を含む) に対して pre_delete と post_delete シグナルを発行します。

Django はシグナルを送ったり、カスケードを処理したりするために、オブジェクトをメモリにフェッチする必要があります。しかし、カスケードもシグナルもない場合、 Django は高速な経路をとり、メモリにフェッチせずにオブジェクトを削除するかもしれ ません。大きな削除の場合、メモリ使用量を大幅に減らすことができます。クエリの実行量も減ります。

on_delete DO_NOTHING に設定されている外部キーは、削除の際に fast-path を取ることを防ぎません。

オブジェクトの削除で生成されるクエリは、実装の詳細部分であり、変更される可能性があることに注意してください。

as_manager()

classmethod as_manager()

QuerySet のメソッドをコピーした Manager のインスタンスを返すクラスメソッドです。詳細は QuerySet のメソッドで、マネージャを生成する を参照してください。

このセクションの他の項目とは異なり、クエリを実行しないため、非同期バージョンがないことに注意してください。

explain()

explain(format=None, **options)

aexplain(format=None, **options)

非同期バージョン: aexplain()

QuerySet の実行計画文字列を返します。この実行計画は、使用するインデックスや結合を含め、データベースがどのようにクエリを実行するかの詳細を示します。これらの詳細を知ることで、遅いクエリのパフォーマンスを向上させることができます。

たとえば、PostgreSQLを使う場合:

>>> print(Blog.objects.filter(title="My Blog").explain())
Seq Scan on blog  (cost=0.00..35.50 rows=10 width=12)
  Filter: (title = 'My Blog'::bpchar)

出力はデータベースによって大きく異なります。

explain() は Oracle を除くすべての組み込みデータベースバックエンドでサポートされています。これは Oracle での実装が一筋縄ではいかないからです。

format パラメータは、データベースのデフォルトの出力形式 (通常はテキストベース) から変更します。PostgreSQLは 'TEXT' 、 'JSON' 、 'YAML' 、 'XML' フォーマットをサポートしています。MariaDB と MySQL は 'TEXT' ( 'TRADITIONAL' とも呼びます) と 'JSON' 形式をサポートしています。MySQL 8.0.16+ では、改良された TREE' フォーマットもサポートしています。これは PostgreSQL の 'TEXT' 出力に似ており、サポートされていればデフォルトで使用されます。

データベースによっては、クエリに関する詳細な情報を返すフラグを受け付けるものがあります。これらのフラグをキーワード引数として渡してください。たとえば、PostgreSQLを使用している場合:

>>> print(Blog.objects.filter(title="My Blog").explain(verbose=True, analyze=True))
Seq Scan on public.blog  (cost=0.00..35.50 rows=10 width=12) (actual time=0.004..0.004 rows=10 loops=1)
  Output: id, title
  Filter: (blog.title = 'My Blog'::bpchar)
Planning time: 0.064 ms
Execution time: 0.058 ms

データベースによっては、フラグによってクエリが実行され、データベースに悪影響を及ぼす可能性があります。たとえば、MariaDB、MySQL 8.0.18+、PostgreSQLでサポートされている ANALYZE フラグは、 SELECT クエリであっても、トリガがある場合や関数が呼び出された場合にデータを変更してしまう可能性があります。

Field ルックアップ

フィールドルックアップは SQL の WHERE 句の内容を指定する方法です。これらは filter() 、 exclude() 、 get() メソッドのキーワード引数として指定します。

概要については モデルとデータベースクエリのドキュメント を参照してください。

Django の組み込みルックアップを以下に示します。モデルフィールドのために カスタムルックアップ を書くこともできます。

利便性のために、ルックアップタイプが指定されていない場合（ Entry.objects.get(id=14) のように）、ルックアップタイプは exact とみなされます。

exact

完全一致。比較に指定された値が None の場合、SQL の NULL と解釈されます (詳細は isnull を参照してください)。

例:

Entry.objects.get(id__exact=14)
Entry.objects.get(id__exact=None)

これは下記のSQL文と等価です。

SELECT ... WHERE id = 14;
SELECT ... WHERE id IS NULL;

MySQL における比較

MySQL では、データベースのテーブルの「照合順序」の設定で、exact 比較が大文字小文字を区別するかどうかを決めます。これはデータベースの設定で、 Django の設定ではありません。大文字小文字を区別して比較するように MySQL のテーブルを設定することは可能ですが、いくつかの トレードオフが伴います。これについては データベース ドキュメントの 照合順序のセクション を参照してください。

iexact

大文字小文字を区別しない完全一致。比較に指定された値が None の場合、SQL の NULL と解釈されます (詳細は isnull を参照してください)。

実装例:

Blog.objects.get(name__iexact="beatles blog")
Blog.objects.get(name__iexact=None)

これは下記のSQL文と等価です。

SELECT ... WHERE name ILIKE 'beatles blog';
SELECT ... WHERE name IS NULL;

最初のクエリは 'Beatles Blog', 'beatles blog', 'BeAtLes BLoG' などにマッチすることに注意してください。

SQLite ユーザーの場合

SQLite バックエンドで非 ASCII 文字列を使用する場合は、文字列の比較に関する データベースのノート に注意してください。SQLiteは非ASCII文字列に対して大文字小文字を区別しないマッチングを行いません。

contains

大文字小文字を区別し、文字列を含むかをチェックします。

実装例:

Entry.objects.get(headline__contains="Lennon")

これらは SQL で言う下記と同等です:

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

'Lennon honored today' という見出しにはマッチしますが、 'lennon honored today' という見出しにはマッチしないことに注意してください。

SQLite ユーザーの場合

SQLite は大文字小文字を区別する LIKE ステートメントをサポートしていません。詳細は データベースに関する注意事項 を参照してください。

icontains

大文字小文字を区別せずに文字列を含むかをチェックします。

実装例:

Entry.objects.get(headline__icontains="Lennon")

これらは SQL で言う下記と同等です:

SELECT ... WHERE headline ILIKE '%Lennon%';

SQLite ユーザーの場合

SQLite バックエンドで非 ASCII 文字列を使用する場合は、文字列の比較に関する データベースに関する注意事項 に注意してください。

in

指定されたイテラブル（多くの場合、リスト、タプル、クエリセット）内に含まれるかをチェックします。あまり使われませんが、（イテラブルである）文字列は使用可能です。

例:

Entry.objects.filter(id__in=[1, 3, 4])
Entry.objects.filter(headline__in="abc")

これは下記のSQL文と等価です。

SELECT ... WHERE id IN (1, 3, 4);
SELECT ... WHERE headline IN ('a', 'b', 'c');

リテラル値のリストを提供する代わりに、クエリセットを使用して以下のように値のリストを動的に評価することもできます:

inner_qs = Blog.objects.filter(name__contains="Cheddar")
entries = Entry.objects.filter(blog__in=inner_qs)

このクエリセットは下記のようなサブクエリ内の SELECT 文として評価されます:

SELECT ... WHERE blog.id IN (SELECT id FROM ... WHERE NAME LIKE '%Cheddar%')

もし values() や values_list() の結果の クエリセット を __in ルックアップの値として渡す場合は、結果の中の1つのフィールドだけを抽出するようにする必要があります。たとえば、次のようにします（ブログ名でフィルタリングする場合）:

inner_qs = Blog.objects.filter(name__contains="Ch").values("name")
entries = Entry.objects.filter(blog__name__in=inner_qs)

下記の例では例外が発生します。内側のクエリは2つのフィールド値を抽出しようとしているからです:

# Bad code! Will raise a TypeError.
inner_qs = Blog.objects.filter(name__contains="Ch").values("name", "id")
entries = Entry.objects.filter(blog__name__in=inner_qs)

パフォーマンスに関する注意事項

ネストされたクエリの使用には注意し、データベースサーバーのパフォーマンス特性を理解しましょう (疑わしい場合はベンチマークを使用しましょう！)。データベースバックエンドによっては、特に MySQL はネストされたクエリをあまり最適化しません。そのような場合は、値のリストを抽出してから 2 番目のクエリに渡すほうが効率的です。つまり、1つのクエリではなく、下記のように2つのクエリを実行するのです。

values = Blog.objects.filter(name__contains="Cheddar").values_list("pk", flat=True)
entries = Entry.objects.filter(blog__in=list(values))

最初のクエリを強制的に実行するために、Blog QuerySet を list() 呼び出しで囲んでいることに注意してください。これがないと、ネストされたクエリが実行されてしまうからです。これは QuerySet は遅延評価される ためです。

gt

～～より大きい（greater than）。

実装例:

Entry.objects.filter(id__gt=4)

これらは SQL で言う下記と同等です:

SELECT ... WHERE id > 4;

gte

～～以上（greater than or equal to）。

lt

～～未満（less than）。

lte

～～以下（less than equal to）。

startswith

大文字と小文字を区別して、指定された文字列から始まるかどうかをチェックします。

実装例:

Entry.objects.filter(headline__startswith="Lennon")

これらは SQL で言う下記と同等です:

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

SQLite は大文字小文字を区別する LIKE 文をサポートしていません。 SQLite では startswith は istartswith のように動作します。

istartswith

大文字と小文字を区別せず、指定された文字列から始まるかどうかをチェックします。

実装例:

Entry.objects.filter(headline__istartswith="Lennon")

これらは SQL で言う下記と同等です:

SELECT ... WHERE headline ILIKE 'Lennon%';

SQLite ユーザーの場合

SQLite バックエンドで非 ASCII 文字列を使用する場合は、文字列の比較に関する データベースに関する注意事項 に注意してください。

endswith

大文字と小文字を区別して、指定された文字列で終わるかどうかをチェックします。

実装例:

Entry.objects.filter(headline__endswith="Lennon")

これらは SQL で言う下記と同等です:

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

SQLite ユーザーの場合

SQLite は大文字小文字を区別する LIKE 文をサポートしていません。 endswith は SQLite の iendswith のように動作します。詳しくは データベースに関する注意事項 のドキュメントを参照してください。

iendswith

大文字と小文字を区別せず、指定された文字列で終わるかどうかをチェックします。

実装例:

Entry.objects.filter(headline__iendswith="Lennon")

これらは SQL で言う下記と同等です:

SELECT ... WHERE headline ILIKE '%Lennon'

SQLite ユーザーの場合

SQLite バックエンドで非 ASCII 文字列を使用する場合は、文字列の比較に関する データベースに関する注意事項 に注意してください。

range

範囲のチェック（～～を含む）。

実装例:

import datetime

start_date = datetime.date(2005, 1, 1)
end_date = datetime.date(2005, 3, 31)
Entry.objects.filter(pub_date__range=(start_date, end_date))

これらは SQL で言う下記と同等です:

SELECT ... WHERE pub_date BETWEEN '2005-01-01' and '2005-03-31';

range は SQL で BETWEEN が使えるところならどこでも使えます。日付、数字、そして文字でも使えます。

警告

日付で DateTimeField をフィルタリングすると、最終日のアイテムは含まれません。もし pub_date が DateTimeField であった場合、上記の式はこのようなSQLになります:

SELECT ... WHERE pub_date BETWEEN '2005-01-01 00:00:00' and '2005-03-31 00:00:00';

一般的に言って、日付と日時を混在させることはできません。

date

datetime フィールドの値を date としてキャストします。追加のフィールドルックアップを連結できます。 date 値を取ります。

実装例:

Entry.objects.filter(pub_date__date=datetime.date(2005, 1, 1))
Entry.objects.filter(pub_date__date__gt=datetime.date(2005, 1, 1))

(このルックアップに等価なSQLの例はありません。これは、関連するクエリの実装がデータベースエンジンによって異なるためです)。

USE_TZ が True の場合、フィールドはフィルタリングの前にカレントタイムゾーンに変換されます。これには データベースのタイムゾーン定義 が必要です。

year

日付フィールドとdatetimeフィールドにおける、"年" の完全一致。追加のフィールドルックアップを連結できます。年を整数で指定します。

実装例:

Entry.objects.filter(pub_date__year=2005)
Entry.objects.filter(pub_date__year__gte=2005)

これらは SQL で言う下記と同等です:

SELECT ... WHERE pub_date BETWEEN '2005-01-01' AND '2005-12-31';
SELECT ... WHERE pub_date >= '2005-01-01';

(正確なSQL構文はデータベースエンジンによって異なります）。

USE_TZ が True の場合、日付フィールドはフィルタリングの前にカレントタイムゾーンに変換されます。これにはデータベースの タイムゾーン定義 が必要です。

iso_year

日付フィールドとdatetimeフィールドにおける、ISO 8601の週番号と年との完全一致。追加のフィールドルックアップを連結できます。年を整数で指定します。

実装例:

Entry.objects.filter(pub_date__iso_year=2005)
Entry.objects.filter(pub_date__iso_year__gte=2005)

(正確なSQL構文はデータベースエンジンによって異なります）。

USE_TZ が True の場合、日付フィールドはフィルタリングの前にカレントタイムゾーンに変換されます。これにはデータベースの タイムゾーン定義 が必要です。

month

日付フィールドおよびdatetimeフィールドにおける、"月" の完全一致。追加のフィールドルックアップを連結できます。1 (1月) から 12 (12月) までの整数を指定します。

実装例:

Entry.objects.filter(pub_date__month=12)
Entry.objects.filter(pub_date__month__gte=6)

これらは SQL で言う下記と同等です:

SELECT ... WHERE EXTRACT('month' FROM pub_date) = '12';
SELECT ... WHERE EXTRACT('month' FROM pub_date) >= '6';

(正確なSQL構文はデータベースエンジンによって異なります）。

USE_TZ が True の場合、日付フィールドはフィルタリングの前にカレントタイムゾーンに変換されます。これにはデータベースの タイムゾーン定義 が必要です。

day

日付フィールドとdatetimeフィールドにおける、"日" の完全一致。追加のフィールドルックアップを連結できます。日を整数で指定します。

実装例:

Entry.objects.filter(pub_date__day=3)
Entry.objects.filter(pub_date__day__gte=3)

これらは SQL で言う下記と同等です:

SELECT ... WHERE EXTRACT('day' FROM pub_date) = '3';
SELECT ... WHERE EXTRACT('day' FROM pub_date) >= '3';

(正確なSQL構文はデータベースエンジンによって異なります）。

これは、1 月 3 日、7 月 3 日など、pub_date が月の 3 日目のレコードに一致します。

USE_TZ が True の場合、日付フィールドはフィルタリングの前にカレントタイムゾーンに変換されます。これにはデータベースの タイムゾーン定義 が必要です。

week

日付フィールドおよびdatetimeフィールドにおける、 ISO-8601 に従った週番号 (1～52または53) を返します。すなわち、週は月曜日から始まり、最初の週にはその年の最初の木曜日が含まれます。

実装例:

Entry.objects.filter(pub_date__week=52)
Entry.objects.filter(pub_date__week__gte=32, pub_date__week__lte=38)

(このルックアップに等価なSQLの例はありません。これは、関連するクエリの実装がデータベースエンジンによって異なるためです)。

USE_TZ が True の場合、日付フィールドはフィルタリングの前にカレントタイムゾーンに変換されます。これにはデータベースの タイムゾーン定義 が必要です。

week_day

日付フィールドとdatetimeフィールドにおける "曜日" の一致。追加のフィールドルックアップを連結できます。

1 (日曜日) から 7 (土曜日) までの曜日を表す整数値を指定します。

実装例:

Entry.objects.filter(pub_date__week_day=2)
Entry.objects.filter(pub_date__week_day__gte=2)

(このルックアップに等価なSQLの例はありません。これは、関連するクエリの実装がデータベースエンジンによって異なるためです)。

pub_date が月曜日(週の2日目)のレコードは、月や年に関係なくマッチすることに注意してください。 週の曜日のインデックスは1日目が日曜日、7日目が土曜日です。

USE_TZ が True の場合、日付フィールドはフィルタリングの前にカレントタイムゾーンに変換されます。これにはデータベースの タイムゾーン定義 が必要です。

iso_week_day

日付フィールドおよび datetime フィールドにおける、ISO 8601 曜日との完全一致。追加のフィールドルックアップを連結できます。

1(月曜日)から7(日曜日)までの曜日を表す整数値を取ります。

実装例:

Entry.objects.filter(pub_date__iso_week_day=1)
Entry.objects.filter(pub_date__iso_week_day__gte=1)

(このルックアップに等価なSQLの例はありません。これは、関連するクエリの実装がデータベースエンジンによって異なるためです)。

pub_date が月曜日(週の1日目)のレコードは、月や年に関係なくマッチすることに注意してください。週の曜日のインデックスは1日目が月曜日、7日目が日曜日です。

USE_TZ が True の場合、日付フィールドはフィルタリングの前にカレントタイムゾーンに変換されます。これにはデータベースの タイムゾーン定義 が必要です。

quarter

日付および datetime フィールドにおける、"四半期" の一致。追加のフィールドルックアップを連結できます。年の四半期を表す 1 から 4 までの整数値を指定します。

第2四半期（4月1日から6月30日まで）のエントリーを検索する例:

Entry.objects.filter(pub_date__quarter=2)

(このルックアップに等価なSQLの例はありません。これは、関連するクエリの実装がデータベースエンジンによって異なるためです)。

USE_TZ が True の場合、日付フィールドはフィルタリングの前にカレントタイムゾーンに変換されます。これにはデータベースの タイムゾーン定義 が必要です。

time

datetime フィールドの場合、値を time としてキャストします。追加のフィールドルックアップを連結できます。 datetime.time 値を取ります。

実装例:

Entry.objects.filter(pub_date__time=datetime.time(14, 30))
Entry.objects.filter(pub_date__time__range=(datetime.time(8), datetime.time(17)))

(このルックアップに等価なSQLの例はありません。これは、関連するクエリの実装がデータベースエンジンによって異なるためです)。

USE_TZ が True の場合、フィールドはフィルタリングの前にカレントタイムゾーンに変換されます。これには データベースのタイムゾーン定義 が必要です。

hour

datetimeフィールドとtimeフィールドにおける、"時（hour）" の完全一致。追加のフィールドルックアップを連結できます。0 から 23 までの整数を指定します。

実装例:

Event.objects.filter(timestamp__hour=23)
Event.objects.filter(time__hour=5)
Event.objects.filter(timestamp__hour__gte=12)

これらは SQL で言う下記と同等です:

SELECT ... WHERE EXTRACT('hour' FROM timestamp) = '23';
SELECT ... WHERE EXTRACT('hour' FROM time) = '5';
SELECT ... WHERE EXTRACT('hour' FROM timestamp) >= '12';

(正確なSQL構文はデータベースエンジンによって異なります）。

USE_TZ が True の場合、日付フィールドはフィルタリングの前にカレントタイムゾーンに変換されます。これにはデータベースの タイムゾーン定義 が必要です。

minute

datetime フィールドと time フィールドにおける、"分" の完全一致。追加のフィールドルックアップを連結できます。0 から 59 までの整数を指定します。

実装例:

Event.objects.filter(timestamp__minute=29)
Event.objects.filter(time__minute=46)
Event.objects.filter(timestamp__minute__gte=29)

これらは SQL で言う下記と同等です:

SELECT ... WHERE EXTRACT('minute' FROM timestamp) = '29';
SELECT ... WHERE EXTRACT('minute' FROM time) = '46';
SELECT ... WHERE EXTRACT('minute' FROM timestamp) >= '29';

(正確なSQL構文はデータベースエンジンによって異なります）。

USE_TZ が True の場合、日付フィールドはフィルタリングの前にカレントタイムゾーンに変換されます。これにはデータベースの タイムゾーン定義 が必要です。

second

datetime および time フィールドにおける、"秒" の完全一致。追加のフィールドルックアップを連結できます。0 から 59 までの整数を指定します。

実装例:

Event.objects.filter(timestamp__second=31)
Event.objects.filter(time__second=2)
Event.objects.filter(timestamp__second__gte=31)

これらは SQL で言う下記と同等です:

SELECT ... WHERE EXTRACT('second' FROM timestamp) = '31';
SELECT ... WHERE EXTRACT('second' FROM time) = '2';
SELECT ... WHERE EXTRACT('second' FROM timestamp) >= '31';

(正確なSQL構文はデータベースエンジンによって異なります）。

USE_TZ が True の場合、日付フィールドはフィルタリングの前にカレントタイムゾーンに変換されます。これにはデータベースの タイムゾーン定義 が必要です。

isnull

"True" または "False" を受け取り、それぞれ IS NULL と IS NOT NULL の SQL クエリに対応します。

実装例:

Entry.objects.filter(pub_date__isnull=True)

これらは SQL で言う下記と同等です:

SELECT ... WHERE pub_date IS NULL;

regex

大文字小文字を区別する正規表現マッチ。

正規表現の構文は、使用するデータベースバックエンドのものです。正規表現のサポートが組み込まれていないSQLiteの場合、この機能は(Pythonの)ユーザー定義REGEXP関数によって提供され、正規表現の構文はPythonの re モジュールのものとなります。

実装例:

Entry.objects.get(title__regex=r"^(An?|The) +")

これは下記のSQL文と等価です。

SELECT ... WHERE title REGEXP BINARY '^(An?|The) +'; -- MySQL

SELECT ... WHERE REGEXP_LIKE(title, '^(An?|The) +', 'c'); -- Oracle

SELECT ... WHERE title ~ '^(An?|The) +'; -- PostgreSQL

SELECT ... WHERE title REGEXP '^(An?|The) +'; -- SQLite

正規表現の構文を渡す際には、生の文字列(例: 'foo' の代わりに r'foo') を使うことを推奨します。

iregex

大文字小文字を区別しない正規表現マッチ。

実装例:

Entry.objects.get(title__iregex=r"^(an?|the) +")

これは下記のSQL文と等価です。

SELECT ... WHERE title REGEXP '^(an?|the) +'; -- MySQL

SELECT ... WHERE REGEXP_LIKE(title, '^(an?|the) +', 'i'); -- Oracle

SELECT ... WHERE title ~* '^(an?|the) +'; -- PostgreSQL

SELECT ... WHERE title REGEXP '(?i)^(an?|the) +'; -- SQLite

集計（Aggregation）関数

Django は django.db.models モジュールで以下の集計関数を提供しています。これらの集計関数の使い方は アグリゲーション（集計）に関するトピックガイド を参照してください。集計関数の作成方法については Aggregate ドキュメント を参照してください。

警告

SQLite は日付/時刻フィールドの集計をそのままでは扱えません。これは、 SQLite にはネイティブな日付/時刻フィールドが存在せず、Django は現在、テキストフィールドを使っ てこれらの機能をエミュレートしているからです。SQLite で日付/時刻フィールドの集計を使おうとすると、 NotSupportedError が発生します。

空のクエリセットやグループの場合

集計関数は空の クエリセット やグループで使用すると None を返します。たとえば、 Sum 集計関数は、 QuerySet にエントリが含まれていない場合や、空ではない QuerySet に含まれる空のグループに対して、 0 の代わりに None を返します。代わりに別の値を返すには、 default 引数を定義します。 Count は default 引数をサポートしていないため、 QuerySet が空の場合は 0 を返します。

すべての集計に共通するパラメータは以下の通りです:

expressions

モデル上のフィールド、フィールドのトランスフォーム、または クエリ式 を参照する文字列です。

output_field

戻り値の モデルフィールド を表すオプションの引数です。

注釈

複数のフィールドタイプを組み合わせる場合、Django が output_field を決定できるのは、全てのフィールドタイプが同じ場合だけです。そうでない場合は、 output_field を自分で指定しなければなりません。

filter

オプションで、 Q オブジェクト で、集計する行をフィルタリングします。

たとえば 条件付きの集計 や アノテーションのフィルタリング を参照してください。

default

オプションの引数で、クエリセット（またはグループ化）にエントリがない場合にデフォルト値として使用する値を指定できます。

**extra

集計によって生成されるSQLに追加のコンテキストを提供できるキーワード引数。

Avg

class Avg(expression, output_field=None, distinct=False, filter=None, default=None, **extra)

指定した式の平均値を返します。これは、別の output_field を指定しない限り、必ず数値となります。

• デフォルトのエイリアス: <field>__avg
• 戻り値の型： 入力が int の場合は float を、それ以外の場合は入力フィールドと同じものを、 output_field を指定した場合は output_field を返します。クエリセットまたはグループ化が空の場合は default を返します。

distinct

オプションです。 distinct=True の場合、 Avg は一意な値の平均値を返します。これは SQL の AVG(DISTINCT <field>) と等価です。デフォルト値は False です。

Count

class Count(expression, distinct=False, filter=None, **extra)

指定した式で関連付けられたオブジェクトの数を返します。 Count('*') は SQL の COUNT(*) 式と等価です。

• デフォルトのエイリアス: <field>__count
• 戻り値の型: int

distinct

オプションです。 distinct=True の場合、一意なインスタンスのみをカウントします。これは SQL の COUNT(DISTINCT <field>) と等価です。デフォルト値は False です。

注釈

default 引数はサポートされていません。

Max

class Max(expression, output_field=None, filter=None, default=None, **extra)

指定された式の最大値を返します。

• デフォルトのエイリアス: <field>__max
• 戻り値の型: 入力フィールドと同じ、または output_field が指定されている場合は output_field を返します。クエリセットまたはグループ化が空の場合は default が返されます。

Min

class Min(expression, output_field=None, filter=None, default=None, **extra)

指定した式の最小値を返します。

• デフォルトのエイリアス: <field>__min
• 戻り値の型: 入力フィールドと同じ、または output_field が指定されている場合は output_field を返します。クエリセットまたはグループ化が空の場合は default が返されます。

StdDev

class StdDev(expression, output_field=None, sample=False, filter=None, default=None, **extra)

指定した式のデータの標準偏差を返します。

• デフォルトのエイリアス: <field>__stddev
• 戻り値の型： 入力が int の場合は float を、それ以外の場合は入力フィールドと同じものを、 output_field を指定した場合は output_field を返します。クエリセットまたはグループ化が空の場合は default を返します。

sample

オプションです。デフォルトでは StdDev は母集団の標準偏差を返します。ただし、 sample=True の場合は、標本の標準偏差が返されます。

Sum

class Sum(expression, output_field=None, distinct=False, filter=None, default=None, **extra)

与えられた式のすべての値の合計を計算します。

• デフォルトのエイリアス: <field>__sum
• 戻り値の型: 入力フィールドと同じ、または output_field が指定されている場合は output_field を返します。クエリセットまたはグループ化が空の場合は default が返されます。

distinct

オプションです。 distinct=True の場合、 Sum は一意な値の合計を返します。これは SQL の SUM(DISTINCT ) と等価です。デフォルト値は False です。

Variance

class Variance(expression, output_field=None, sample=False, filter=None, default=None, **extra)

指定された式のデータの分散を返します。

• デフォルトのエイリアス: <field>__variance
• 戻り値の型： 入力が int の場合は float を、それ以外の場合は入力フィールドと同じものを、 output_field を指定した場合は output_field を返します。クエリセットまたはグループ化が空の場合は default を返します。

sample

オプションです。デフォルトでは Variance は母分散を返します。ただし、 sample=True の場合は、標本の分散を返します。

クエリ関連ツール

このセクションでは、他のセクションで説明されていないクエリ関連ツールの参考資料を提供します。

Q() オブジェクト

class Q

A Q() object represents an SQL condition that can be used in database-related operations. It's similar to how an F() object represents the value of a model field or annotation. They make it possible to define and reuse conditions. These can be negated using the ~ (NOT) operator, and combined using operators such as | (OR), & (AND), and ^ (XOR). See Q オブジェクトを使った複雑なルックアップ.

Prefetch() オブジェクト

class Prefetch(lookup, queryset=None, to_attr=None)

Prefetch() オブジェクトは prefetch_related() の動作を制御するために使用できます。

引数 lookup にはたどるリレーションを記述し、 prefetch_related() に渡す文字列ベースのルックアップと同じように動作します。たとえば、次のようにします:

>>> from django.db.models import Prefetch
>>> Question.objects.prefetch_related(Prefetch("choice_set")).get().choice_set.all()
<QuerySet [<Choice: Not much>, <Choice: The sky>, <Choice: Just hacking again>]>
# This will only execute two queries regardless of the number of Question
# and Choice objects.
>>> Question.objects.prefetch_related(Prefetch("choice_set"))
<QuerySet [<Question: What's up?>]>

queryset 引数には、与えられたルックアップのベースとなる QuerySet を指定します。これは、プリフェッチ操作をさらに絞り込んだり、 プリフェッチされたリレーションから select_related() を呼び出してクエリの数をさらに減らしたりするのに便利です:

>>> voted_choices = Choice.objects.filter(votes__gt=0)
>>> voted_choices
<QuerySet [<Choice: The sky>]>
>>> prefetch = Prefetch("choice_set", queryset=voted_choices)
>>> Question.objects.prefetch_related(prefetch).get().choice_set.all()
<QuerySet [<Choice: The sky>]>

引数 to_attr は、プリフェッチ操作の結果をカスタム属性にセットします:

>>> prefetch = Prefetch("choice_set", queryset=voted_choices, to_attr="voted_choices")
>>> Question.objects.prefetch_related(prefetch).get().voted_choices
[<Choice: The sky>]
>>> Question.objects.prefetch_related(prefetch).get().choice_set.all()
<QuerySet [<Choice: Not much>, <Choice: The sky>, <Choice: Just hacking again>]>

注釈

to_attr を使用すると、プリフェッチされた結果はリストに格納されます。これは、キャッシュされた結果を QuerySet インスタンスに格納する従来の prefetch_related 呼び出しよりも大幅に速度を向上させることができます。

prefetch_related_objects()

prefetch_related_objects(model_instances, *related_lookups)

aprefetch_related_objects(model_instances, *related_lookups)

非同期バージョン: aprefetch_related_objects()

与えられたルックアップをモデルインスタンスのイテラブルでプリフェッチします。これは クエリセット とは対照的に、モデルインスタンスのリストを受け取るコードで有用です。たとえば、キャッシュからモデルを取得するときや、手動でインスタンスを作成するときなどです。

同じクラスのモデルインスタンスのイテラブルと、プリフェッチしたいルックアップまたは Prefetch オブジェクトを渡します。例えば：

>>> from django.db.models import prefetch_related_objects
>>> restaurants = fetch_top_restaurants_from_cache()  # A list of Restaurants
>>> prefetch_related_objects(restaurants, "pizzas__toppings")

複数のデータベースを prefetch_related_objects で使用する場合、プリフェッチクエリはモデルインスタンスに関連付けられたデータベースを使用します。これは、リレーションのルックアップでカスタムクエリセットを使用することで上書きできます。

Changed in Django 5.0:

aprefetch_related_objects() 関数が追加されました。

FilteredRelation() オブジェクト

class FilteredRelation(relation_name, *, condition=Q())

relation_name

リレーションをフィルタしたいフィールドの名前

condition

フィルタリングを制御する Q オブジェクトです。

FilteredRelation は annotate() と共に使用し、 JOIN 時に ON 句を作成します。これはデフォルトのリレーションシップではなく、アノテーション名 (下の例では pizzas_vegetarian) に対して動作します。

たとえば、名前に「モッツァレラチーズ」が入っているベジタリアンのピザがあるレストランを探す場合、次のようにします:

>>> from django.db.models import FilteredRelation, Q
>>> Restaurant.objects.annotate(
...     pizzas_vegetarian=FilteredRelation(
...         "pizzas",
...         condition=Q(pizzas__vegetarian=True),
...     ),
... ).filter(pizzas_vegetarian__name__icontains="mozzarella")

ピザが大量にある場合、上記のクエリセットの方が下記より良いパフォーマンスを発揮します:

>>> Restaurant.objects.filter(
...     pizzas__vegetarian=True,
...     pizzas__name__icontains="mozzarella",
... )

なぜなら、1つめのクエリセットの WHERE 句のフィルタリングはベジタリアンのピザに対してのみ行われるからです。

FilteredRelation は下記をサポートしていません。

• QuerySet.only() と prefetch_related() メソッド。
• 親モデルから継承された GenericForeignKey 。