QuerySet API リファレンスLink to this heading#このドキュメントでは、QuerySet API の詳細を説明しています。モデル と データベースクエリ ガイドにある説明を前提としていますので、このドキュメントを読む前にこの 2 つを読んでおくことをおすすめします。
このリファレンスでは、 データベースクエリガイド で提供された Blogモデルの例 を使用します。
\nQuerySet が評価されるタイミングLink to this heading#内部的には、 QuerySet は実際にデータベースにアクセスすることなく、構築、フィルタリング、スライス、受け渡しを行うことができます。クエリセットを評価するための操作が行われない限り、実際のデータベースへのアクセスは発生しません。
次の操作を行なったとき、 QuerySet は評価されます。
イテレーション。 QuerySet はイテラブルで、初めてイテレートした時にデータベースのクエリを実行します。たとえば、これはデータベースにある全エントリのheadline属性を出力するプログラムです:
for e in Entry.objects.all():\n print(e.headline)\nメモ: 1つ以上の結果が存在するかどうかを判定したいだけなら、これは使わないでください。 exists() を使った方が効率的です。
非同期イテレーション. QuerySet は async for を使ってイテレートすることもできます:
async for e in Entry.objects.all():\n results.append(e)\nクエリセットの同期的・非同期的イテレータは、同じキャッシュを共有します。
\nスライス。 QuerySet の要素数を制限する で説明されているとおり、 QuerySet はPythonのリストスライスを用いてスライスできます。未評価の QuerySet をスライスすると、通常は新たな未評価の QuerySet が返されます。しかし、スライスの "step" パラメータを使用した場合、Djangoはデータベースクエリを実行し、リストを返します。評価された QuerySet をスライスした場合も同様にリストが返されます。
未評価の QuerySet をスライスして別の未評価の QuerySet が返されても、それをさらに変更すること(たとえば、さらにフィルタを追加したり、順序を変更したりすること)は許されていないことに気を付けてください。これは、その操作がSQLに正しく変換されず、明確な意味を持たないためです。
pickle 化/キャッシュ化。 QuerySet を pickle 化する 際に何が行われるかは次節を参照してください。次節において重要なことは、結果がデータベースから読み出されるという点です。
repr()。 QuerySet は repr() が呼び出された時点で評価されます。これはPythonの対話型インタプリタでの利便性を図るためで、APIを対話的に使用する際にクエリの結果をすぐに確認できます。
len()。 QuerySet は len() を呼び出した時点で評価されます。想像される通り、この操作は結果のリストの長さを返します。
メモ: セット内のレコード数を決定したいだけであれば(そして実際のオブジェクトが必要ないのであれば)、SQLの SELECT COUNT(*) を使ってデータベースレベルでハンドルする方がより効率的です。Djangoはまさにこの理由から count() メソッドを提供しています。
list()。 list() を呼び出すことで、 QuerySet の評価を強制します。たとえば:
entry_list = list(Entry.objects.all())\nbool()。 bool(), or, and または if 文を使用してブール値として QuerySet をテストすると、クエリが実行されます。 QuerySet も少なくとも1つ以上の結果が含まれれば True となり、そうでなければ False になります。例えば:
if Entry.objects.filter(headline="Test"):\n print("There is at least one Entry with the headline Test")\n注意: もしクエリの結果が少なくとも1つ存在するかどうかを確認したいだけであれば(そして実際のオブジェクトを必要としないのであれば)、 exists() を使うべきです。
QuerySet の Pickle 化Link to this heading#QuerySet を pickle 化するとき、pickle化の前にすべての結果がメモリにロードされるように強制されます。キャッシュされたクエリセットがリロードされた時、結果がすでに存在し、使用できる状態になっていることが望ましいからです(データベースからの読み込みには時間がかかるので、キャッシュとしての目的を達成できません)。つまり、 QuerySet のpickle化を解除すると、解除した時点でデータベースにある結果ではなく、pickle化した時点での結果が出力されることになります。
もし、後でデータベースから QuerySet を再生成するために必要な情報だけを取り出したい場合は、 QuerySet の query を属性を取り出してください。そうすることで、以下のようなコードで本来の QuerySet (結果を読み込む前の状態)を再現できます:
>>> import pickle\n>>> query = pickle.loads(s) # Assuming 's' is the pickled string.\n>>> qs = MyModel.objects.all()\n>>> qs.query = query # Restore the original 'query'.\nquery 属性は不透明なオブジェクトです。これは内側でのクエリ構築を表すもので、公開APIの一部ではありません。しかし、ここで説明しているように、この属性の内容のpickle化・pickle化の解除は安全に行うことができます(完全にサポートもされています)。
QuerySet APILink to this heading#これが QuerySet の正式な宣言です:
通常、 QuerySet を操作する際には フィルタの連結 を使用します。これを実現するために、ほとんどの QuerySet のメソッドは新たなクエリセットを返します。これらのメソッドについては、このセクションで後ほど詳しく説明します。
QuerySet クラスは、イントロスペクションのために以下のパブリックな属性を持っています:
QuerySet が order_by() やモデルのデフォルトの順序指定によって並び替えられた場合に True となります。それ以外のときは False になります。
このクエリが実行されるデータベースを示します。
\nQuerySets を返すメソッドLink to this heading#QuerySet が返す結果の種類や、SQLクエリの実行方法を変更するための、さまざまな QuerySet の改良メソッドをDjangoは提供します。
filter()Link to this heading#与えられたルックアップパラメータにマッチする新しい QuerySet を返します。
ルックアップパラメータ (**kwargs) は以下の Field lookups で説明されているフォーマットに従わなければなりません。複数のパラメータは、元となるSQLステートメントでは AND によって結合されます。
より複雑なクエリを実行したい場合(たとえば OR ステートメントを含むクエリ)は、 Q オブジェクト (*args) を使用してください。
exclude()Link to this heading#与えられたルックアップパラメータにマッチ しない 新しい 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")\nSQL文では、次のように評価されます:
\nSELECT ...\nWHERE NOT (pub_date > '2005-1-3' AND headline = 'Hello')\nこの例では pub_date が 2005-1-3より新しいか、 headline が "Hello" であるようなエントリーを除外しています:
Entry.objects.exclude(pub_date__gt=datetime.date(2005, 1, 3)).exclude(headline="Hello")\nSQL文では、次のように評価されます:
\nSELECT ...\nWHERE NOT pub_date > '2005-1-3'\nAND NOT headline = 'Hello'\n2つ目の例の方が、制約がより強いことに留意してください。
\nより複雑なクエリを実行したい場合(たとえば OR ステートメントを含むクエリ)は、 Q オブジェクト (*args) を使用してください。
annotate()Link to this heading#QuerySet 内の各オブジェクトに、指定された クエリ式 または Q オブジェクトのリストを使ってアノテーション（注釈）を追加します。各オブジェクトには、以下のようなものをアノテーションとして追加できます。
Value() で指定する単純な値。
F() で指定するモデル（または関連モデル）のフィールドへの参照。
Q() で指定する真偽値（判定式）。
QuerySet 内のオブジェクトに関連付けられたオブジェクトに対して計算された集約式（平均、合計など）の結果。
annotate() に渡される引数はそれぞれがアノテーションとなって、返される QuerySet 内の各オブジェクトに追加されます。
Djangoが提供する集計関数については、下記の 集計関数 で説明されています。
\nキーワード引数を使って指定されたアノテーションは、そのキーワードがアノテーションのエイリアスとして使用されます。匿名引数の場合は、集計関数の名前と集計対象のモデルフィールド名に基づいて自動的にエイリアスが生成されます。匿名引数として使用できるのは、単一のフィールドを参照する集計式のみです。それ以外のすべての式はキーワード引数として指定する必要があります。
\nたとえば、ブログのリストを操作しているときに、ブログごとのエントリー数を決定したいとします:
\n>>> from django.db.models import Count\n>>> q = Blog.objects.annotate(Count("entry"))\n# The name of the first blog\n>>> q[0].name\n'Blogasaurus'\n# The number of entries on the first blog\n>>> q[0].entry__count\n42\nBlog モデル自体は entry__count 属性を定義しませんが、集計式を指定したキーワード引数を用いることで、集計情報の名前を制御できます:
>>> q = Blog.objects.annotate(number_of_entries=Count("entry"))\n# The number of entries on the first blog, using the name provided\n>>> q[0].number_of_entries\n42\n集計処理についての深い議論については、 アグリゲーションについてのトピックガイド を確認してください。
\nalias()Link to this heading#annotate() と同じですが、 QuerySet にオブジェクトをアノテーションするかわりに、後で他の QuerySet メソッドで再利用できるように式を保存します。これは式の結果自体は必要ないが、フィルタリングやソート、あるいは複雑な式の一部として利用する場合に便利です。未使用の値を選択しないことで、データベースで冗長な処理を行わずに済み、結果的にパフォーマンスを向上させることができます。
例えば、5エントリ以上のブログを探したいが、エントリ数自体に興味がない場合は、以下のようにできます:
\n>>> from django.db.models import Count\n>>> blogs = Blog.objects.alias(entries=Count("entry")).filter(entries__gt=5)\nalias() は annotate(), exclude(), filter(), order_by(), update() と組み合わせて使用できます。エイリアス式をその他のメソッド(aggregate() など)と組み合わせるためには、アノテーションを用いる必要があります
Blog.objects.alias(entries=Count("entry")).annotate(\n entries=F("entries"),\n).aggregate(Sum("entries"))\nfilter() と order_by() は式を直接受け取ることができますが、式の構築と評価は同じ場所では行われないことが多いです(例えば、 QuerySet メソッドは式を作成し、後からビューを表示するときに使用されるため)。 alias() は、複数のメソッドやモジュールにまたがる複雑な式を段階的に構築することができ、式の部分をエイリアスで参照し、最終結果に対してのみ annotate() を使用する、といった使い方ができます。
order_by()Link to this heading#デフォルトでは、 QuerySet の返り値はモデルの Meta 内の ordering オプションで指定されたタプルに基づいて並び替えられます。 order_by メソッドを使うことで、 QuerySet ごとにこれをオーバーライドできます。
実装例:
\nEntry.objects.filter(pub_date__year=2005).order_by("-pub_date", "headline")\n上のコードの結果は pub_date の降順、次に headline の昇順で並び替えられます。 "-pub_date" のように、前にマイナス符号をつけることで降順を表現します。昇順は暗黙的に表現されます。ランダムに並び替えたい場合、次のように "?" を使います:
Entry.objects.order_by("?")\nメモ: order_by('?') クエリは、使用するデータベースバックエンドによっては高負荷で遅くなる可能性があります。
異なるモデルのフィールドで並び替えたい場合、モデル間を横断して参照するクエリを発行するときと同じ構文を使用します。すなわち、フィールド名の後にダブルアンダースコア(__)を続けて、その後に新たなモデルのフィールド名を続けます。そして、それを結合したいモデルの数だけ繰り返します。例えば:
Entry.objects.order_by("blog__name", "headline")\n異なるモデルを参照するフィールドで並び替えるとき、Djangoは参照先のモデルのデフォルトの順序を用いますが、 Meta.ordering が設定されていなければ参照先のモデルのプライマリーキーで並び替えます。たとえば、 Blog モデルにはデフォルトで設定された順序がないとき:
Entry.objects.order_by("blog")\n...は以下と同じです:
\nEntry.objects.order_by("blog__id")\nBlog が ordering = ['name'] を保持している場合、最初のクエリセットは以下と同じになります:
Entry.objects.order_by("blog__name")\nasc() か desc() を式の中で呼び出すことで、 クエリ式 を使うこともできます:
Entry.objects.order_by(Coalesce("summary", "headline").desc())\nasc() と desc() は、null値をどのようにソートするかを制御する引数 (nulls_first と nulls_last)をとります。
モデル参照フィールドによる並び替えと同時に distinct() を使用する際は注意してください。参照先のモデルの順序によって、期待される結果がどのように変化するかについては、 distinct() の注記を確認してください。
大文字と小文字を区別して並べ替えるかどうかを指定することはできません。Djangoは使用するデータベースバックエンドが通常このCase-sensitiveをどのように扱うかに従って結果を並び替えます。
\nLower によって小文字に変換したフィールドで並び替えることで、一貫したルールでの並び替えを実現できます:
Entry.objects.order_by(Lower("headline").desc())\nクエリに対し、デフォルトの順序付けも含めて並び替えを適用したくない場合、パラメータを指定せずに order_by() を呼び出してください。
クエリに並び替えが適用されたかどうかは、 QuerySet.ordered 属性を確認することで知ることができます。 QuerySet がなんらかの方法で並び替えられれば、この属性の値は True となります。
order_by() の呼び出しごとに、過去の並び替えは解除されます。たとえば、以下のクエリでは並び替えに pub_date が使われ、 headline は使われません:
Entry.objects.order_by("headline").order_by("pub_date")\nreverse()Link to this heading#reverse() メソッドを使用すると、クエリセットの要素を返す順序を逆にすることができます。再度 reverse() を呼び出すと、順序が元に戻ります。
クエリセットの「最後の」5つの項目を取り出すには、次のようにします:
\nmy_queryset.reverse()[:5]\nこの処理がPythonでシーケンスの最後からスライスするのとは全く違うことに注意してください。上記の例では、まず最後の項目が返され、次に最後から5番目の項目が返されます。Python のシーケンスに対して seq[-5:] を参照すると、最後の 5 番目の項目が最初に表示されるはずです。そのようなアクセスモード (末尾からのスライス) は、SQL で効率的に行うことができないため、Django ではサポートされていません。
また、通常 reverse() は、順序が定義されている QuerySet に対してしか呼び出せないことに注意してください（例えば、デフォルトの順序を定義しているモデルに対するクエリや、 order_by() を使用する場合など）。 QuerySet に順序が定義されていなかったら、 reverse() を呼び出しても何の効果もありません（順序は reverse() を呼び出す前から未定義であり、その後も未定義のままです）。
distinct()Link to this heading#SQL クエリで SELECT DISTINCT を使用した新しい QuerySet を返します。これにより、クエリ結果から重複した行を取り除くことができます。
デフォルトでは、 QuerySet は重複した行を削除しません。なぜなら、 Blog.objects.all() のような単純なクエリでは、結果の行が重複する可能性はないからです。しかし、クエリが複数のテーブルにまたがっている場合、 QuerySet が評価されたときに重複した結果を得る可能性があります。このような場合は distinct() を使用します。
PostgreSQL のみ、位置引数 (*fields) を渡して、 DISTINCT を適用するフィールドの名前を指定できます。これは SELECT DISTINCT ON というSQLクエリに相当します。通常の distinct() 呼び出しでは、データベースはどの行が区別されるかを判断する際に、各行の each フィールドを比較しますが、フィールド名を指定した distinct() の呼び出しでは、データベースは指定されたフィールド名のみを比較できます。
例 (2つ目以降のコードは、PostgreSQL上でのみ動作します):
\n>>> Author.objects.distinct()\n[...]\n\n>>> Entry.objects.order_by("pub_date").distinct("pub_date")\n[...]\n\n>>> Entry.objects.order_by("blog").distinct("blog")\n[...]\n\n>>> Entry.objects.order_by("author", "pub_date").distinct("author", "pub_date")\n[...]\n\n>>> Entry.objects.order_by("blog__name", "mod_date").distinct("blog__name", "mod_date")\n[...]\n\n>>> Entry.objects.order_by("author", "pub_date").distinct("author")\n[...]\nvalues()Link to this heading#イテラブルオブジェクトとして使用するとき、モデルインスタンスではなく辞書を返す QuerySet を返します。
これらの辞書はそれぞれオブジェクトを表し、キーはモデルオブジェクトの属性名に対応しています。
\nこの例では、values() によって得られる辞書と通常のモデルのオブジェクトを比較しています:
# This list contains a Blog object.\n>>> Blog.objects.filter(name__startswith="Beatles")\n<QuerySet [<Blog: Beatles Blog>]>\n\n# This list contains a dictionary.\n>>> Blog.objects.filter(name__startswith="Beatles").values()\n<QuerySet [{'id': 1, 'name': 'Beatles Blog', 'tagline': 'All the latest Beatles news.'}]>\nvalues() メソッドはオプションの位置引数 *fields を取り、 SELECT で絞り込むフィールド名を指定します。フィールドを指定した場合、それぞれの辞書は指定したフィールドのキー/値のみを保有します。フィールドを指定しない場合、各辞書は、データベーステーブルのすべてのフィールドのキーと値を保有します。
例:
\n>>> Blog.objects.values()\n<QuerySet [{'id': 1, 'name': 'Beatles Blog', 'tagline': 'All the latest Beatles news.'}]>\n>>> Blog.objects.values("id", "name")\n<QuerySet [{'id': 1, 'name': 'Beatles Blog'}]>\nvalues() メソッドはオプションでキーワード引数 **expressions を受け取り、 annotate() に渡すこともできます:
>>> from django.db.models.functions import Lower\n>>> Blog.objects.values(lower_name=Lower("name"))\n<QuerySet [{'lower_name': 'beatles blog'}]>\nソートには、組み込みのルックアップまたは カスタムルックアップ が使用できます。例えば、次のようになります:
\n>>> from django.db.models import CharField\n>>> from django.db.models.functions import Lower\n>>> CharField.register_lookup(Lower)\n>>> Blog.objects.values("name__lower")\n<QuerySet [{'name__lower': 'beatles blog'}]>\nvalues() 句内の集計処理は、同じ values() 句内の他の引数の前に適用されます。別の値でグループ化する必要がある場合は、その値を先の values() 句に追加してください。例えば:
>>> from django.db.models import Count\n>>> Blog.objects.values("entry__authors", entries=Count("entry"))\n<QuerySet [{'entry__authors': 1, 'entries': 20}, {'entry__authors': 1, 'entries': 13}]>\n>>> Blog.objects.values("entry__authors").annotate(entries=Count("entry"))\n<QuerySet [{'entry__authors': 1, 'entries': 33}]>\nいくつかの際どいポイントについて言及しておきます:
\nもし foo というフィールドが ForeignKey である場合、デフォルトの values() は foo_id という辞書キーを返します。それが実際の値を格納するモデルの隠し属性名だからです (foo 属性はリレーション先モデルを指します)。 value() を呼び出してフィールド名を渡す場合、foo と foo_id のどちらを渡しても、同じものが返ってきます（辞書のキーは渡したフィールド名と一致します）。
例:
\n>>> Entry.objects.values()\n<QuerySet [{'blog_id': 1, 'headline': 'First Entry', ...}, ...]>\n\n>>> Entry.objects.values("blog")\n<QuerySet [{'blog': 1}, ...]>\n\n>>> Entry.objects.values("blog_id")\n<QuerySet [{'blog_id': 1}, ...]>\nvalues() と distinct() を一緒に使う場合、呼び出す順番が結果に影響する場合があるので注意してください。 詳細は distinct() のノートを参照してください。
extra() 呼び出しの後に values() 句を使用する場合、 extra() の select 引数で定義したフィールドは、明示的に values() 呼び出しに含めなければなりません。 values() 呼び出しの後に extra() を呼び出しても、後から追加した選択フィールドは返り値に含まれません。
values() の後に only() と defer() を呼び出すのは意味がなく、 TypeError が発生します。
トランスフォームと集計の処理を組み合わせるには、2つの annotate() 呼び出しを、明示的にまたは values() へのキーワード引数として使用する必要があります。上記の例のように、リレーション先のフィールドタイプにトランスフォームが登録されていれば、最初の annotate() は省略できます。よって以下の例はすべて等価です:
>>> from django.db.models import CharField, Count\n>>> from django.db.models.functions import Lower\n>>> CharField.register_lookup(Lower)\n>>> Blog.objects.values("entry__authors__name__lower").annotate(entries=Count("entry"))\n<QuerySet [{'entry__authors__name__lower': 'test author', 'entries': 33}]>\n>>> Blog.objects.values(entry__authors__name__lower=Lower("entry__authors__name")).annotate(\n... entries=Count("entry")\n... )\n<QuerySet [{'entry__authors__name__lower': 'test author', 'entries': 33}]>\n>>> Blog.objects.annotate(entry__authors__name__lower=Lower("entry__authors__name")).values(\n... "entry__authors__name__lower"\n... ).annotate(entries=Count("entry"))\n<QuerySet [{'entry__authors__name__lower': 'test author', 'entries': 33}]>\nこれは、値が欲しい利用可能フィールドが少なく、モデルインスタンスオブジェクトの機能が必要ないことが分かっている場合に便利です。使用する必要のあるフィールドだけを選択する方がより効率的です。
\n最後に、values() の後に filter() や order_by() などを呼び出すことができますが、これはこの2つの呼び出しが同じであることを意味しています:
Blog.objects.values().order_by("id")\nBlog.objects.order_by("id").values()\nDjango を作った人たちは、SQL に影響するメソッドを最初に置き、その後に出力に影響するメソッド (values() など) を (オプションで) 置くことを好みますが、それは本当に重要ではありません。しかし、そんなことはどうでもいいのです。この機会に、あなたの個性を存分に発揮してください。
リレーション先モデルのフィールドには、 OneToOneField 、 ForeignKey 、 ManyToManyField 属性を使用して逆リレーションで参照することもできます。
>>> Blog.objects.values("name", "entry__headline")\n<QuerySet [{'name': 'My blog', 'entry__headline': 'An entry'},\n {'name': 'My blog', 'entry__headline': 'Another entry'}, ...]>\nvalues_list()Link to this heading#この関数は values() と似ていますが、イテレートしたときに辞書の代わりにタプルを返します。それぞれのタプルには、 values_list() に渡された各フィールドまたは式の値が、渡された順番で含まれます。例えば:
>>> Entry.objects.values_list("id", "headline")\n<QuerySet [(1, 'First entry'), ...]>\n>>> from django.db.models.functions import Lower\n>>> Entry.objects.values_list("id", Lower("headline"))\n<QuerySet [(1, 'first entry'), ...]>\nフィールドを1つだけ渡す場合は、 flat パラメータを渡すことができます。これに True を渡すと、返り値はタプルではなく単一の値になります。この違いは例を見て理解してください。
>>> Entry.objects.values_list("id").order_by("id")\n<QuerySet[(1,), (2,), (3,), ...]>\n\n>>> Entry.objects.values_list("id", flat=True).order_by("id")\n<QuerySet [1, 2, 3, ...]>\n複数のフィールドがある場合に flat を渡すとエラーになります。
namedtuple(): として結果を得るには、named=True を渡します:
>>> Entry.objects.values_list("id", "headline", named=True)\n<QuerySet [Row(id=1, headline='First entry'), ...]>\n名前付きタプルを使用することで、名前付きタプルに変換するためのわずかなパフォーマンスの低下を犠牲にして、クエリの実行結果の可読性を高めることができます。
\nもし values_list() に何も値を渡さなければ、モデル内のすべてのフィールドを宣言された順に返します。
よくあるニーズは、特定のモデルインスタンスの特定のフィールドの値を取得することです。これを実現するには、 values_list() の後に get() を呼び出します:
>>> Entry.objects.values_list("headline", flat=True).get(pk=1)\n'First entry'\nvalues() と values_list() はいずれも、モデルインスタンスを作成するオーバーヘッドなしにデータのサブセットを取得するという、特定のユースケースに対する最適化を意図したものです。このメタファーは、多対多の関係やその他の多値の関係（逆引き外部キーの1対多の関係など）を扱うときには、「1行に1オブジェクト」の前提が成り立たないために崩れてしまいます。
例えば、 ManyToManyField: を通してクエリを実行したときの挙動に注目してみましょう:
>>> Author.objects.values_list("name", "entry__headline")\n<QuerySet [('Noam Chomsky', 'Impressions of Gaza'),\n ('George Orwell', 'Why Socialists Do Not Believe in Fun'),\n ('George Orwell', 'In Defence of English Cooking'),\n ('Don Quixote', None)]>\n複数のエントリを持つ著者は複数回表示され、エントリのない著者のエントリとして None と表示されます。
同様に、外部キーを逆引きするクエリでは、著者が設定されていないエントリに対して None が表示されます。
>>> Entry.objects.values_list("authors")\n<QuerySet [('Noam Chomsky',), ('George Orwell',), (None,)]>\ndates()Link to this heading#この QuerySet は datetime.date オブジェクトのリストとして評価され、QuerySet の内容から指定された種類の日付を返します。
field にはモデルの DateField の名前を指定します。 kind には "year", "month", "week", "day" のいずれかを指定します。結果のリストに含まれる datetime.date オブジェクトは、指定された type に "切り捨て" られます。
"year" は、そのフィールドのすべての年の値のリストを重複なしで返します。
"month" はそのフィールドの年/月の値のリストを重複なしで返します。
"week" はそのフィールドの年/週の値のリストを重複なしで返します。すべての date は月曜日になります。
"day" はそのフィールドの年/月/日の値のリストを重複なしで返します。
order のデフォルトは 'ASC' で、 'ASC' または 'DESC' のいずれかを指定します。これは結果のソート方法を指定します。
例:
\n>>> Entry.objects.dates("pub_date", "year")\n[datetime.date(2005, 1, 1)]\n>>> Entry.objects.dates("pub_date", "month")\n[datetime.date(2005, 2, 1), datetime.date(2005, 3, 1)]\n>>> Entry.objects.dates("pub_date", "week")\n[datetime.date(2005, 2, 14), datetime.date(2005, 3, 14)]\n>>> Entry.objects.dates("pub_date", "day")\n[datetime.date(2005, 2, 20), datetime.date(2005, 3, 20)]\n>>> Entry.objects.dates("pub_date", "day", order="DESC")\n[datetime.date(2005, 3, 20), datetime.date(2005, 2, 20)]\n>>> Entry.objects.filter(headline__contains="Lennon").dates("pub_date", "day")\n[datetime.date(2005, 3, 20)]\ndatetimes()Link to this heading#これは、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 の場合には効果がありません。
none()Link to this heading#none() を呼び出すと、オブジェクトを返さないクエリセットが作成され、結果にアクセスする際にクエリが実行されることはありません。 qs.none() のクエリセットは EmptyQuerySet のインスタンスです。
例:
\n>>> Entry.objects.none()\n<QuerySet []>\n>>> from django.db.models.query import EmptyQuerySet\n>>> isinstance(Entry.objects.none(), EmptyQuerySet)\nTrue\nall()Link to this heading#現在の QuerySet (または QuerySet サブクラス)の コピー を返します。これは、モデルマネージャまたは QuerySet のどちらかを渡して、その結果に対してさらにフィルタリングを行いたいときに便利です。いずれかのオブジェクトに対して all() を呼び出すと、動作する QuerySet が必ず作成されます。
QuerySet が 評価される とき、通常その結果はキャッシュされます。もし QuerySet が評価された後にデータベースのデータが更新された場合、以前に評価された QuerySet に対して all() を呼び出すことで、同じクエリの最新の結果を取得できます。
union()Link to this heading#SQLの UNION コマンドを使用して、2つ以上の QuerySet の結果を結合します。例えば:
>>> qs1.union(qs2, qs3)\nUNION 演算子は、デフォルトでは明確な値のみを選択します。重複した値を取得するには、 all=True 引数を使用します。
union(), intersection(), difference() は、引数が他のモデルの QuerySet であっても、最初の QuerySet の型のモデルインスタンスを返します。すべての QuerySet で SELECT リストが同じであれば、異なるモデルを渡すことができます（少なくとも型と、型の順番が同じであれば名前は関係ありません）。 このような場合、結果の QuerySet に適用される QuerySet メソッドでは、最初の QuerySet のカラム名を使用する必要があります。たとえば、次のようになります:
>>> qs1 = Author.objects.values_list("name")\n>>> qs2 = Entry.objects.values_list("headline")\n>>> qs1.union(qs2).order_by("name")\n結果として得られる QuerySet では、LIMIT、OFFSET、COUNT(*)、ORDER BY、およびカラムの指定（すなわち、スライス、 count() 、 exists() 、 order_by() 、 values() / values_list() ）のみが許可されます。さらに、データベースによっては、組み合わせたクエリで許可される操作に制限があります。例えば、ほとんどのデータベースでは組み合わせたクエリで「LIMIT」や「OFFSET」は許可されていません。
intersection()Link to this heading#SQL の INTERSECT 演算子を使用して、2つ以上の QuerySet の全てに含まれる共有要素を返します。例:
>>> qs1.intersection(qs2, qs3)\n制限については union() を参照してください。
difference()Link to this heading#SQL の EXCEPT 演算子を使用して、 QuerySet には存在するが、他の QuerySet には存在しない要素のみを保持します。例:
>>> qs1.difference(qs2, qs3)\n制限については union() を参照してください。
extra()Link to this heading#Django のクエリ構文だけでは、複雑な WHERE 節を簡単に表現できないことがあります。このようなエッジケースのために、 Django は extra() QuerySet 修飾子、つまり QuerySet が生成する SQL に特定の句を注入するフックを提供します。
定義上、これらの extra ルックアップは異なるデータベースエンジンに移植できない可能性があり（明示的にSQLコードを記述しているため）、DRY原則に違反するため、可能であれば避けるべきです。
\nparams、select、where、tables のうち、少なくとも1つを指定します。どの引数も必須ではありませんが、少なくとも1つは指定する必要があります。
select
select 引数を使用すると、SELECT 句に追加のフィールドを配置できます。属性名を SQL 句にマッピングした辞書を使用して、その属性を計算するために使用します。
実装例:
\nEntry.objects.extra(select={"is_recent": "pub_date > '2006-01-01'"})\nその結果、各 Entry オブジェクトには、追加の属性である is_recent が付与されます。これは、エントリーの pub_date が2006年1月1日よりも後の日付であるかどうかを表す真偽値です。
Django は指定された SQL スニペットを SELECT 文に直接挿入するので、上の例の SQL は次のようになります:
SELECT blog_entry.*, (pub_date > '2006-01-01') AS is_recent\nFROM blog_entry;\n次の例はもっと高度です。サブクエリを使って、各結果の Blog オブジェクトに、関連する Entry オブジェクトの整数カウントである entry_count 属性を付与します。
Blog.objects.extra(\n select={\n "entry_count": "SELECT COUNT(*) FROM blog_entry WHERE blog_entry.blog_id = blog_blog.id"\n },\n)\nこの特別なケースでは、クエリの FROM 句に既に blog_blog テーブルが含まれていることを利用している。
上記の例の結果として得られる SQL は次のとおりです:
\nSELECT blog_blog.*, (SELECT COUNT(*) FROM blog_entry WHERE blog_entry.blog_id = blog_blog.id) AS entry_count\nFROM blog_blog;\nほとんどのデータベースエンジンでサブクエリに必要な括弧は、Django の select 句では必要ありません。
まれに、extra(select=...) でSQLフラグメントにパラメータを渡したい場合があります。その場合は、select_params パラメータを使用してください。
これは、次のように動作します:
\nBlog.objects.extra(\n select={"a": "%s", "b": "%s"},\n select_params=("one", "two"),\n)\nselect 文内で文字列 %s をそのまま使いたい場合は、 %%s というシーケンスを使用してください。
where / tables
SQLの明示的な WHERE 句を定義できます。たとえば、明示的でない結合を実行するために where を使用できます。また、SQLの FROM 句に手動でテーブルを追加できます。これには tables を使用します。
where と tables は、どちらも文字列のリストを取ります。全ての where パラメーターは、他の検索条件と "AND" 演算されます。
実装例:
\nEntry.objects.extra(where=["foo='a' OR bar = 'a'", "baz = 'a'"])\n...これは大まかに次の SQL に翻訳されます:
\nSELECT * FROM blog_entry WHERE (foo='a' OR bar='a') AND (baz='a')\nすでにクエリで使われているテーブルを指定する場合、 tables パラメータを使うときには注意してください。テーブル tables パラメータを使ってテーブルを追加すると、 Django はそのテーブルが既に含まれている場合、そのテーブルをもう一回追加したいと仮定します。この場合、テーブル名にエイリアスが付けられるので、問題が生じます。テーブルが SQL 文の中で複数回出現する場合、データベースが区別できるように、2 回目以降の出現にはエイリアスを使う必要があります。追加の where パラメータで追加したテーブルを参照している場合、これはエラーの原因になります。
通常は、クエリに既に表示されていない追加のテーブルのみを追加します。しかし、上記の場合が発生した場合は、いくつかの解決策があります。まず、追加のテーブルを含めずに、すでにクエリにあるテーブルを使用できるかどうかを確認してください。それが不可能な場合は、extra() メソッドをクエリセットの構築の最初に配置して、そのテーブルが最初に使用されるようにします。最後に、すべてが失敗した場合は、生成されたクエリを確認し、 where 句への追加をエイリアスの利用に書き直します。エイリアスは、同じ方法でクエリセットを構築するたびに同じであるため、エイリアス名は変わらないことを信頼できます。
order_by
extra() で追加した新しいフィールドやテーブルを使用してクエリセットを並べ替える必要がある場合は、extra() の order_by パラメータを使用し、文字列のシーケンスを渡します。 これらの文字列は、通常の querysets の order_by() メソッドのようなモデルフィールド、table_name.column_name の形式、または extra() の select パラメータで指定した列のエイリアスである必要があります。
例:
\nq = Entry.objects.extra(select={"is_recent": "pub_date > '2006-01-01'"})\nq = q.extra(order_by=["-is_recent"])\nこれにより、is_recent が true であるすべてのアイテムが結果セットの先頭に並べ替えられます (降順では True が False よりも先に並びます)。
ちなみに、これは extra() を複数回呼び出しても期待通りに動作する（つまり、毎回新しい制約を追加する）ことを示しています。
params
上記の where パラメータは、標準のPythonデータベース文字列プレースホルダー、 '%s' を使用して、データベースエンジンが自動的に引用符で囲むべきパラメータを示すことができます。 params 引数は、代入される追加のパラメータのリストです。
実装例:
\nEntry.objects.extra(where=["headline=%s"], params=["Lennon"])\n常に params を使用し、値を直接 where に埋め込まないでください。なぜなら params を使用することで、値が特定のバックエンドに応じて正しく引用符で囲まれることが保証されるからです。例えば、引用符は正しくエスケープされます。
悪い例:
\nEntry.objects.extra(where=["headline='Lennon'"])\n良い例:
\nEntry.objects.extra(where=["headline=%s"], params=["Lennon"])\ndefer()Link to this heading#複雑なデータモデリングの場面では、モデルにはたくさんのフィールドが含まれるかもしれません。その中には、大量のデータを含むフィールド (たとえばテキストフィールド) や、Python オブジェクトに変換するために高コストな処理を必要とするフィールドがあるかもしれません。QuerySet の結果を、最初にデータを取得するときにはまだそのフィールドが必要かどうかわからないような状況で使う場合、まだデータベースからは読み込まないように Django に指示できます。
\n読み込ませたくないフィールドの名前を defer() に渡すことで、それを実現できます:
Entry.objects.defer("headline", "body")\nDefer（遅延読み込み）されたフィールドを持つ QuerySet はモデルインスタンスを返します。それぞれの遅延読み込みフィールドは、そのフィールドにアクセスしたときにデータベースから取得されます (すべての遅延読み込みフィールドを一度に取得するのではなく、1つずつ取得します)。
\n\ndefer() を複数回呼び出すこともできます。それぞれの呼び出しは新しいフィールドを遅延読み込みリストに追加します:
# Defers both the body and headline fields.\nEntry.objects.defer("body").filter(rating=5).defer("headline")\nフィールドが遅延読み込みリストに追加される順番は重要ではありません。すでに遅延読み込みに指定されているフィールド名で defer() を呼び出しても意味はありません（フィールドは遅延読み込みに指定されたままです）。
標準的な2重アンダースコア記法を用いてリレーション先のフィールドを区切ることで、(リレーション先のモデルが select_related() によって読み込まれる場合) リレーション先のモデルのフィールドの読み込みを遅延させることもできます:
Blog.objects.select_related().defer("entry__headline", "entry__body")\n遅延読み込みフィールドの指定を消去したい場合は、 defer() のパラメータとして None を渡します:
# Load all fields immediately.\nmy_queryset.defer(None)\nモデル内のいくつかのフィールドは、指定しても遅延読み込みされません。主キーの読み込みは決して遅延できません。リレーション先のモデルを取得するために select_related() を使っている場合、最初のモデルからリレーション先のモデルに接続するフィールドの読み込みを遅延すべきではありません。
同様に、 defer() (またはそれに対応する only()) を集計関数の引数を含めて (例えば annotate() の結果を使って) 呼び出しても意味はありません。集計された値は常に結果の QuerySet に取り込まれます。
only()Link to this heading#only() メソッドは本質的に defer() の逆です。このメソッドに渡されたフィールドのうち、既に遅延読み込みフィールドに指定されていないものだけが、 QuerySet が評価されたときに直ちにロードされます。
ほとんどのフィールドが遅延読み込みされる必要があるようなモデルの場合、only() を使って補完的なフィールドセットを指定すると、よりシンプルなコードになります。
name, age, biography という3つのフィールドを持つモデルがあるとします。次の2つのQuerySetは、どのフィールドが遅延読み込みされるかという点では同じです:
Person.objects.defer("age", "biography")\nPerson.objects.only("name")\nonly() を呼び出すと、読み込むフィールドの設定を即座に置き換えます。このメソッドは名前の通り、指定したフィールド だけ を読み込み、残りのフィールドの読み込みを先送りします。その結果、連続して only() を呼び出すと、最後に指定したフィールドだけが考慮されることになります:
# This will defer all fields except the headline.\nEntry.objects.only("body", "rating").only("headline")\ndefer() は段階的に（遅延読み込みリストにフィールドを追加しながら）動作するので、 only() と defer() の呼び出しは組み合わせることができ、ロジカルに動作します:
# Final result is that everything except "headline" is deferred.\nEntry.objects.only("headline", "body").defer("body")\n\n# Final result loads headline immediately.\nEntry.objects.defer("body").only("headline", "body")\ndefer() のドキュメントにある注意事項はすべて only() にも当てはまります。 only() は慎重に、そして他のオプションを使い果たした後にだけ使用してください。
only() を使って select_related() で要求したフィールドを省略した場合もエラーになります。 一方、引数なしで only() を呼び出すと、queryset によって取得された全てのフィールド (アノテーションを含む) が返されます。
defer() と同様に、非同期コードからは、まだ読み込まれていないフィールドにアクセスすることはできません。その場合、SynchronousOnlyOperation 例外が発生します。アクセスする可能性のあるすべてのフィールドが only() 呼び出し内に含まれていることを確認してください。
using()Link to this heading#このメソッドは、複数のデータベースを使用している場合に QuerySet がどのデータベースに対して評価されるかを制御するためのものです。 このメソッドが受け取る唯一の引数は DATABASES で定義されているデータベースのエイリアスです。
例:
\n# queries the database with the 'default' alias.\n>>> Entry.objects.all()\n\n# queries the database with the 'backup' alias\n>>> Entry.objects.using("backup")\nselect_for_update()Link to this heading#トランザクションが終了するまで行をロックし、サポートされているデータベース上で SELECT ... FOR UPDATE SQL 文を生成する QuerySet を返します。
例:
\nfrom django.db import transaction\n\nentries = Entry.objects.select_for_update().filter(author=request.user)\nwith transaction.atomic():\n for entry in entries:\n ...\nクエリセットが評価されるとき（この場合、 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' という値を使用します。
PostgreSQLの場合のみ、no_key=True を渡すことで、ロックがかかっている間、（たとえば外部キーによって）ロックされた行を参照するだけの行を作成できる、より弱いロックを取得できます。PostgreSQLのドキュメントに row-level lock modes についての詳細があります。
null 可能なリレーションでは select_for_update() は使用できません:
>>> Person.objects.select_related("hometown").select_for_update()\nTraceback (most recent call last):\n...\ndjango.db.utils.NotSupportedError: FOR UPDATE cannot be applied to the nullable side of an outer join\nこの制限を回避するために、nullオブジェクトを気にしない場合は除外できます:
\n>>> Person.objects.select_related("hometown").select_for_update().exclude(hometown=None)\n<QuerySet [<Person: ...)>, ...]>\nデータベースバックエンドの 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() がオートコミットモードで使用されてもエラーは発生しません。
raw()Link to this heading#素の SQL クエリを受け取って実行し、 django.db.models.query.RawQuerySet インスタンスを返します。この RawQuerySet インスタンスは、通常の QuerySet と同様にイテレートすることで、オブジェクトインスタンスを生成できます。
詳細は 素の SQL 文の実行 を参照してください。
\n\nQuerySet を返す演算子Link to this heading#結合したクエリセットは同じモデルを使用しなければなりません。
\n&)Link to this heading#SQL の AND 演算子を使い、フィルタを連結するのと同じように、2つの QuerySet を結合します。
以下のコードは同等です:
\nModel.objects.filter(x=1) & Model.objects.filter(y=2)\nModel.objects.filter(x=1).filter(y=2)\nこれらは SQL で言う下記と同等です:
\nSELECT ... WHERE x=1 AND y=2\n|)Link to this heading#SQL の OR 演算子を使用して、2つの QuerySet を結合します。
以下のコードは同等です:
\nModel.objects.filter(x=1) | Model.objects.filter(y=2)\nfrom django.db.models import Q\n\nModel.objects.filter(Q(x=1) | Q(y=2))\nこれらは SQL で言う下記と同等です:
\nSELECT ... WHERE x=1 OR y=2\n| は可換演算ではないので、（等価ではあるが）異なるクエリが生成される可能性があります。
^)Link to this heading#SQLの XOR 演算子を使用して、2つの QuerySet を結合します。XOR 式は、奇数個の条件が真である行にマッチします。
以下のコードは同等です:
\nModel.objects.filter(x=1) ^ Model.objects.filter(y=2)\nfrom django.db.models import Q\n\nModel.objects.filter(Q(x=1) ^ Q(y=2))\nこれらは SQL で言う下記と同等です:
\nSELECT ... WHERE x=1 XOR y=2\nQuerySet を返さないメソッドLink to this heading#以下の QuerySet メソッドは QuerySet を評価し、 QuerySet 以外のものを返します。
これらのメソッドはキャッシュを使用しません ( キャッシュと QuerySet を参照してください)。むしろ、呼び出されるたびにデータベースにクエリを行います。
\nこれらのメソッドは QuerySet を評価するので、ブロッキング呼び出しとなり、そのため主な（同期）バージョンは非同期コードから呼び出すことはできません。このため、それぞれに対応する非同期バージョンがあり、 a 接頭辞が付いています。例えば、 get(…) の代わりに await aget(…) が使用できます。
これらのメソッドの挙動には、通常その非同期性以外に違いはありませんが、各メソッドの具体的な違いは、それぞれのメソッドの説明のすぐそばに記載されています。
\nget()Link to this heading#非同期バージョン: aget()
指定されたルックアップパラメータに一致するオブジェクトを返します。これらのパラメータは、 Field lookups で説明されている形式に従うべきです。主キーやユニーク制約のあるフィールドのように、一意性が保証されるルックアップを使うべきです。例えば下記のようにします:
\nEntry.objects.get(id=1)\nEntry.objects.get(Q(blog=blog) & Q(entry_number=1))\nクエリセットがすでに1行だけを返すことがわかっている場合、引数なしで get() を使うことでその行のオブジェクトを取得できます。
Entry.objects.filter(pk=1).get()\nもし get() がオブジェクトを見つけられなかった場合は、 Model.DoesNotExist 例外が発生します。
Entry.objects.get(id=-999) # raises Entry.DoesNotExist\nもし get() が複数のオブジェクトを見つけた場合は、 Model.MultipleObjectsReturned 例外が発生します。
Entry.objects.get(name="A Duplicated Name") # raises Entry.MultipleObjectsReturned\nこれらの例外クラスはモデルクラスの属性であり、そのモデルに特有のものです。複数のモデルに対する get() 呼び出しでこのような例外を処理したい場合、一般的な基底クラスを使用できます。たとえば下記のように、 django.core.exceptions.ObjectDoesNotExist を使って、複数のモデルからの DoesNotExist 例外をできます:
from django.core.exceptions import ObjectDoesNotExist\n\ntry:\n blog = Blog.objects.get(id=1)\n entry = Entry.objects.get(blog=blog, entry_number=1)\nexcept ObjectDoesNotExist:\n print("Either the blog or entry doesn't exist.")\ncreate()Link to this heading#非同期バージョン: acreate()
1ステップでオブジェクトを作成して保存するための便利なメソッドす。たとえばこのようにします:
\np = Person.objects.create(first_name="Bruce", last_name="Springsteen")\nそして、:
\np = Person(first_name="Bruce", last_name="Springsteen")\np.save(force_insert=True)\nこれらは同等です。
\n別の場所で force_insert パラメータについても説明していますが、それは新しいオブジェクトを常に作成するよう強制するものです。普通はこれを気にする必要はありません。しかし、モデルが手動で指定した主キー値を含み、その値が既にデータベースに存在する場合、 create() の呼び出しは IntegrityError で失敗します。これは、主キーは一意である必要があるためです。手動の主キーを使用している場合は、例外処理に備える必要があります。
get_or_create()Link to this heading#非同期バージョン: aget_or_create()
与えられた kwargs を持つオブジェクトを検索するための便利なメソッドです (モデルがすべてのフィールドをデフォルトで持っている場合は空でもかまいません)。
(Object, created) のタプルを返します。"Object"は受け取ったものか作られたものです。そして"created"はそのObjectが作られたものかどうかのBooleanです。
\nこれは、リクエストが並列処理されたときに、重複したオブジェクトが生成されるのを防ぐため、また、定型的なコードへのショートカットのためです。たとえば次のような場合、:
\ntry:\n obj = Person.objects.get(first_name="John", last_name="Lennon")\nexcept Person.DoesNotExist:\n obj = Person(first_name="John", last_name="Lennon", birthday=date(1940, 10, 9))\n obj.save()\nここで、同時リクエストにより、同じパラメータで Person を保存しようとする試みが複数回行われる可能性があります。この競合状態を回避するために、上記の例は get_or_create() を使って次のように書き換えることができます:
obj, created = Person.objects.get_or_create(\n first_name="John",\n last_name="Lennon",\n defaults={"birthday": date(1940, 10, 9)},\n)\nget_or_create() に渡されたキーワード引数（オプションの defaults を除く）は get() 呼び出しで使用されます。オブジェクトが見つかった場合、 get_or_create() はそのオブジェクトと False のタプルを返します。
get_or_create() と filter() を連結し、 Q オブジェクト を使用することで、取得するオブジェクトに対してより複雑な条件を指定できます。たとえば次のコードは、Robert と Bob Marley のどちらかが存在すればそれを取得し、そうでなければ後者（Bob Marley）を作成します:
from django.db.models import Q\n\nobj, created = Person.objects.filter(\n Q(first_name="Bob") | Q(first_name="Robert"),\n).get_or_create(last_name="Marley", defaults={"first_name": "Bob"})\n複数のオブジェクトが見つかった場合、 get_or_create() は MultipleObjectsReturned を発生させます。オブジェクトが ** 見つからなかった** 場合、 get_or_create() は新しいオブジェクトをインスタンス化して保存し、新しいオブジェクトと True のタプルを返します。新しいオブジェクトはおおよそ以下のアルゴリズムに従って作成されます:
params = {k: v for k, v in kwargs.items() if "__" not in k}\nparams.update({k: v() if callable(v) else v for k, v in defaults.items()})\nobj = self.model(**params)\nobj.save()\n英語では、defaults' 以外のキーワード引数で、2重アンダースコア（これはexact以外のルックアップを意味します）を含まないものから始めることを意味します。次に defaults の内容を追加し、必要であればキーを上書きして、その結果をモデルクラスのキーワード引数として使用します。もし defaults に呼び出し可能オブジェクトがあれば、それを評価します。上記のように、これは使用されるアルゴリズムを簡略化したものですが、適切な詳細はすべて含まれています。内部実装では、これよりもさらに多くのエラーチェックが行われ、エッジ条件も処理されます。興味があれば、コードを読んでください。
もし defaults という名前のフィールドがあり、それを get_or_create() で正確にルックアップしたい場合は、次のように 'defaults__exact' を使用します：
Foo.objects.get_or_create(defaults__exact="bar", defaults={"defaults": "baz"})\nget_or_create() メソッドは create() と同様のエラー動作をします。オブジェクトを作成する必要があり、そのキーが既にデータベースに存在する場合、 IntegrityError が発生します。
最後に、Djangoビューで``get_or_create()``を使用する際の注意点について説明します。よほどの理由がない限り、 POST リクエスト以外では使用しないようにしてください。 GET リクエストはデータに影響を与えるべきではありません。代わりに、データに副作用がある場合は常に``POST``を使用してください。詳細については、HTTP仕様の 安全なメソッド を参照してください。
update_or_create()Link to this heading#非同期バージョン: aupdate_or_create()
与えられた kwargs でオブジェクトを更新し、必要に応じて新しいオブジェクトを作成する便利なメソッドです。 create_defaults と defaults はどちらも (field, value) のペアの辞書です。 create_defaults と defaults の値はどちらも呼び出し可能オブジェクトです。 defaults はオブジェクトを更新する際に使用され、create_defaults はオブジェクトを作成する際に使用されます。もし create_defaults が指定されなかった場合、 defaults が作成操作に使用されます。
(Object, created) のタプルを返します。"Object"は受け取ったものか更新したものです。そして"created"はそのObjectが更新されたものかどうかのBooleanです。
\nupdate_or_create メソッドは、与えられた kwargs に基づいてデータベースからオブジェクトを取得しようとします。一致するオブジェクトが見つかった場合、 defaults 辞書に渡されたフィールドを更新します。
これは定型的なコードへのショートカットです。たとえば次のようなものです:
\ndefaults = {"first_name": "Bob"}\ncreate_defaults = {"first_name": "Bob", "birthday": date(1940, 10, 9)}\ntry:\n obj = Person.objects.get(first_name="John", last_name="Lennon")\n for key, value in defaults.items():\n setattr(obj, key, value)\n obj.save()\nexcept Person.DoesNotExist:\n new_values = {"first_name": "John", "last_name": "Lennon"}\n new_values.update(create_defaults)\n obj = Person(**new_values)\n obj.save()\nモデル内のフィールドの数が増えるにつれて、このパターンはかなり扱いにくくなります。上記の例は、 update_or_create() を使って次のように書き換えることができます:
obj, created = Person.objects.update_or_create(\n first_name="John",\n last_name="Lennon",\n defaults={"first_name": "Bob"},\n create_defaults={"first_name": "Bob", "birthday": date(1940, 10, 9)},\n)\nkwargs で渡された名前がどのように解決されるかについては get_or_create() を参照してください。
上記の get_or_create() で説明したように、このメソッドは、データベースレベルで一意性が強制されていない場合、複数の行が同時に挿入される競合状態に陥りがちです。
get_or_create() や create() と同様に、手動で指定した主キーを使用していて、オブジェクトを作成する必要があるが、そのキーが既にデータベースに存在する場合、 IntegrityError が発生します。
bulk_create()Link to this heading#非同期バージョン: abulk_create()
このメソッドは、指定されたオブジェクトのリストを効率的な方法でデータベースに挿入し (通常、オブジェクトの数にかかわらずクエリは 1 回だけです)、作成されたオブジェクトを指定された順序でリストとして返します:
\n>>> objs = Entry.objects.bulk_create(\n... [\n... Entry(headline="This is a test"),\n... Entry(headline="This is only a test"),\n... ]\n... )\nしかし、これにはいくつかの注意点があります:
\nモデルの save() メソッドは呼び出されず、 pre_save と post_save シグナルは送信されません。
マルチテーブル継承の子にあたるモデルでは動作しません。
モデルの主キーが AutoField で、ignore_conflicts が False の場合、主キー属性は特定のデータベース（現在は PostgreSQL、MariaDB、SQLite 3.35+）でのみ取得できます。他のデータベースでは、主キーは設定されません。
多対多のリレーションシップでは動作しません。
これは objs をリストにキャストし、それがジェネレータであれば objs を完全に評価します。このキャストにより、手動で主キーを指定したオブジェクトを最初に挿入できるように、すべてのオブジェクトを検査できます。ジェネレータ全体を一度に評価することなく、オブジェクトを一括して挿入したい場合は、オブジェクトに手動で指定した主キーがない限り、このテクニックを使用できます:
from itertools import islice\n\nbatch_size = 100\nobjs = (Entry(headline="Test %s" % i) for i in range(1000))\nwhile True:\n batch = list(islice(objs, batch_size))\n if not batch:\n break\n Entry.objects.bulk_create(batch, batch_size)\nbatch_size パラメータは、1 回のクエリで作成されるオブジェクトの数を制御します。デフォルトでは、データベースが許容する限り多くのオブジェクトを 1 バッチで作成します。（SQLite および Oracle では、クエリ内のパラメータ数に制限があります。）
これをサポートしているデータベース（Oracleを除くすべてのデータベース）では、 ignore_conflicts パラメータを True に設定すると、一意な値の重複などの制約に違反する行の挿入の失敗を無視するようになります。
これをサポートしているデータベース（Oracleを除くすべてのデータベース）では、 update_conflicts パラメータを True に設定すると、行の挿入が競合して失敗したときに update_fields を更新するようになります。PostgreSQL と SQLite では、 update_fields に加えて、競合する可能性のある unique_fields のリストを指定する必要があります。
パラメータ ignore_conflicts を有効にすると、各モデルのインスタンスに主キーを指定できなくなります（データベースが通常サポートしている場合）。
bulk_update()Link to this heading#非同期バージョン: abulk_update()
このメソッドは、通常1回のクエリで、指定されたモデルインスタンスの指定されたフィールドを効率的に更新し、更新されたオブジェクトの数を返します:
\n>>> objs = [\n... Entry.objects.create(headline="Entry 1"),\n... Entry.objects.create(headline="Entry 2"),\n... ]\n>>> objs[0].headline = "This is entry 1"\n>>> objs[1].headline = "This is entry 2"\n>>> Entry.objects.bulk_update(objs, ["headline"])\n2\nQuerySet.update() は変更を保存するために使用されるので、モデルのリストをイテレートしてそれぞれ save() を呼び出すよりも効率的ですが、いくつかの注意点があります:
モデルの主キーは更新できません。
各モデルの save() メソッドは呼び出されず、 pre_save と post_save シグナルは送信されません。
多数の行の多数のカラムを更新する場合、生成されるSQLは非常に大きくなる可能性があります。これを避けるには、適切な batch_size を指定します。
多数のオブジェクトを更新する場合、 bulk_update() はクエリを実行する前に、すべてのバッチにわたって各オブジェクトに対する WHEN 句をあらかじめ準備することに注意してください。この処理は予想以上に多くのメモリを必要とする場合があります。メモリ使用量を削減するには、次のような方法を利用できます:
from itertools import islice\n\nbatch_size = 100\nids_iter = range(1000)\nwhile ids := list(islice(ids_iter, batch_size)):\n batch = Entry.objects.filter(ids__in=ids)\n for entry in batch:\n entry.headline = f"Updated headline {entry.pk}"\n Entry.objects.bulk_update(batch, ["headline"], batch_size=batch_size)\nマルチテーブル継承の継承元に定義されたフィールドを更新すると、継承元ごとに追加のクエリが発生します。
独立した1つのバッチ内に重複がある場合、そのバッチの最初のインスタンスだけが更新されます。
関数が返す更新されたオブジェクトの数は、渡されたオブジェクトの数より少ない場合があります。これは、渡されたオブジェクトが重複して同じバッチで更新されたり、オブジェクトがデータベースに存在しなくなるような競合状態が発生したりすることが原因です。
batch_size パラメータは、1回のクエリで保存されるオブジェクトの数を制御します。クエリで使用できる変数の数に制限がある SQLite と Oracle を除いて、デフォルトではすべてのオブジェクトを一括で更新します。
count()Link to this heading#非同期バージョン: acount()
QuerySet にマッチするデータベース内のオブジェクトの数を整数で返します。
実装例:
\n# Returns the total number of entries in the database.\nEntry.objects.count()\n\n# Returns the number of entries whose headline contains 'Lennon'\nEntry.objects.filter(headline__contains="Lennon").count()\ncount() 呼び出しは裏で SELECT COUNT(*) を実行するので、すべてのレコードを Python オブジェクトに読み込んで、その結果に対して len() を呼び出すのではなく、常に count() を使うべきです（オブジェクトをメモリに読み込む必要がある場合は別です、その場合は len() の方が高速です）。
もし QuerySet に含まれるアイテムの数が必要で、かつそこからモデルインスタンスを取得する場合 (たとえば、それをイテレートする場合) は、おそらく len(queryset) を使用する方が効率的でしょう。count() のように余分なデータベースクエリが発生することがないからです。
クエリセットがすでに完全に取得されている場合、 count() は余計なデータベースクエリを実行するのではなく、その長さを使用します。
in_bulk()Link to this heading#非同期バージョン: ain_bulk()
フィールド値のリスト (id_list) とそれらの値の field_name を受け取り、各値を与えられたフィールド値を持つオブジェクトのインスタンスにマッピングした辞書を返します。 django.core.exceptions.ObjectDoesNotExist 例外が in_bulk によって発生することはありません。つまり、インスタンスにマッチしない id_list 値は無視されます。 id_list が指定されなかった場合、クエリセット内の全てのオブジェクトが返されます。フィールド名 field_name は一意なフィールドか、(distinct() で指定されたフィールドが一つしかない場合は) 区別されたフィールドでなければなりません。デフォルトは主キーです。
例:
\n>>> Blog.objects.in_bulk([1])\n{1: <Blog: Beatles Blog>}\n>>> Blog.objects.in_bulk([1, 2])\n{1: <Blog: Beatles Blog>, 2: <Blog: Cheddar Talk>}\n>>> Blog.objects.in_bulk([])\n{}\n>>> Blog.objects.in_bulk()\n{1: <Blog: Beatles Blog>, 2: <Blog: Cheddar Talk>, 3: <Blog: Django Weblog>}\n>>> Blog.objects.in_bulk(["beatles_blog"], field_name="slug")\n{'beatles_blog': <Blog: Beatles Blog>}\n>>> Blog.objects.distinct("name").in_bulk(field_name="name")\n{'Beatles Blog': <Blog: Beatles Blog>, 'Cheddar Talk': <Blog: Cheddar Talk>, 'Django Weblog': <Blog: Django Weblog>}\nin_bulk() に空のリストを渡すと、空の辞書が返されます。
iterator()Link to this heading#非同期バージョン: aiterator()
( クエリを実行して ) QuerySet を評価し、その結果に対するイテレータ (PEP 234 を参照) を返します。非同期バージョンの aiterator を呼び出した場合は、非同期イテレータ (PEP 492 を参照) を返します。
クエリセット QuerySet は通常、結果を内部的にキャッシュするので、繰り返し評価しても追加のクエリが発生することはありません。一方、 iterator() は QuerySet レベルでのキャッシュを行わずに、結果を直接読み込みます (内部的には、デフォルトのイテレータは iterator() を呼び出し、戻り値をキャッシュします)。一度しかアクセスする必要のない大量のオブジェクトを返す QuerySet では、この方がパフォーマンスが向上し、メモリを大幅に削減できます。
すでに評価された クエリセット に対して iterator() を使用すると、クエリを再度評価することになるので注意してください。
chunk_size が与えられている限り、 iterator() は以前の prefetch_related() の呼び出しと互換性があります。より大きな値を指定すると、より少ないクエリでプリフェッチを行う必要がありますが、その代償としてメモリの使用量が大きくなります。
データベースによっては(例えばOracleや SQLite )、SQLの IN 句の最大項数が制限されている場合があります。そのため、この制限値以下の値を使用する必要があります。(特に、2つ以上のリレーションにまたがってプリフェッチを行う場合、chunk_size は、プリフェッチされた各リレーションに対して予測される結果の数が制限を下回る程度に小さくする必要があります)。
クエリセットがリレーション先のオブジェクトをプリフェッチしない限り、 chunk_size に何も値を指定しないと、 Django は暗黙のデフォルト値 2000 を使います。
データベースのバックエンドによっては、クエリの結果は一度に読み込まれるか、サーバーサイドのカーソルを使ってデータベースからストリーミングされます。
\nOracle と PostgreSQL はサーバーサイドカーソルを使用して、結果セット全体をメモリに読み込むことなくデータベースから結果をストリームします。
\nOracle データベースドライバは常にサーバーサイドカーソルを使用します。
\nサーバーサイドカーソルでは、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 メーリングリスト で計算された値です：
\n\nテキストデータと数値データが混在した10～20列の行を想定すると、2000行で100KB以下のデータを取得することになります。これは、転送される行数と、ループが早期に終了した場合に破棄されるデータとの間の良い妥協点だと思われます。
\n
latest()Link to this heading#非同期バージョン: alatest()
指定されたフィールドに基づいて、テーブル内の最新のオブジェクトを返します。
\nこの例では、 pub_date フィールドに従って、テーブル内の最新の Entry を返します:
Entry.objects.latest("pub_date")\nまた、複数のフィールドから最新のものを選択することもできます。たとえば2つのエントリが同じ pub_date を持つ場合に、最も早い expire_date を持つ Entry を下記のように選択できます:
Entry.objects.latest("pub_date", "-expire_date")\n'-expire_date' の負の符号は、expire_date を 降順 でソートすることを意味します。 latest() は最後の結果を取得するので、 expire_date が最も古い Entry が選択されます。
モデルの Meta が get_latest_by を指定している場合、 earliest() や latest() の引数を省略できます。 get_latest_by で指定されたフィールドがデフォルトで使用されます。
get() と同様に、 earliest() と latest() は与えられたパラメータを持つオブジェクトが存在しない場合、 DoesNotExist を発生させます。
なお、earliest() と latest() は単に利便性と可読性のために存在しています。
earliest()Link to this heading#非同期バージョン: aearliest()
向きが変わる以外は latest() のように動作します。
first()Link to this heading#非同期バージョン: afirst()
クエリセットにマッチする最初のオブジェクトを返します。マッチするオブジェクトがない場合は None を返します。QuerySet にソートが定義されていない場合、クエリセットは自動的に主キーでソートされます。これは order_by() と一緒に使う で説明されているように、アグリゲーション（集計）の結果に影響を与える可能性があります。
実装例:
\np = Article.objects.order_by("title", "pub_date").first()\nfirst() は便利なメソッドであることに注意してください。以下のコードサンプルは上記の例と等価です:
try:\n p = Article.objects.order_by("title", "pub_date")[0]\nexcept IndexError:\n p = None\nlast()Link to this heading#非同期バージョン: alast()
first() のように動作しますが、クエリセットの最後のオブジェクトを返します。
aggregate()Link to this heading#非同期バージョン: aaggregate()
QuerySet に対して計算された集計値 (平均、合計など) の辞書を返します。 aggregate() の各引数は、返却される辞書に含まれる値を指定します。
Django が提供する集計関数は以下の Aggregation Functions で説明されています。 集計は クエリ式 でもあるので、集計を他の集計や値と組み合わせて複雑な集計を作ることができます。
\nキーワード引数を使用して指定されたアグリゲーション（集計）は、アノテーションの名前としてキーワードを使用します。 無名の引数には、集計関数の名前と集約されるモデルフィールドに基づいて生成された名前が付けられます。複雑な集計では無名の引数を使用することはできず、エイリアスとしてキーワード引数を指定する必要があります。
\nたとえば、ブログエントリーを扱う場合、下記のように、ブログエントリーを投稿した著者の数を知りたいことがあるでしょう:
\n>>> from django.db.models import Count\n>>> Blog.objects.aggregate(Count("entry__authors"))\n{'entry__authors__count': 16}\nキーワード引数を使用して集計関数を指定すると、返される集計値の名前を制御できます:
\n>>> Blog.objects.aggregate(number_of_authors=Count("entry__authors"))\n{'number_of_authors': 16}\n集計処理についての深い議論については、 アグリゲーションについてのトピックガイド を確認してください。
\nexists()Link to this heading#非同期バージョン: aexists()
戻り値は QuerySet に結果が含まれていれば True を、含まれていなければ False を返します。これは可能な限りシンプルで高速な方法でクエリを実行しようとしますが、通常の QuerySet クエリとほぼ同じクエリを実行します。
exists() は QuerySet に含まれるオブジェクトの存在に関連する検索、特に大きな QuerySet の検索に便利です。
クエリセットに項目が含まれているかどうかを調べるには、次のようにします:
\nif some_queryset.exists():\n print("There is at least one object in some_queryset")\nこれは以下のコードより高速です:
\nif some_queryset:\n print("There is at least one object in some_queryset")\n...しかしそれほど大きな差はありません（したがって、効果を感じるには大きなクエリセットが必要です）。
\nさらに、some_queryset がまだ評価されていないが、いずれ評価されることがわかっている場合、some_queryset.exists() を使用すると、結果を取得してから返されたかどうかをチェックする bool(some_queryset) を使用するよりも、全体的な作業量（存在チェックのためのクエリ1回と、後で結果を取得するためのクエリ1回）が増えます。
contains()Link to this heading#非同期バージョン: acontains()
QuerySet に obj が含まれていれば True を、含まれていなければ False を返します。これは、可能な限りシンプルで高速な方法でクエリを実行しようとします。
contains() は、特に大きな QuerySet のコンテキストにおいて、 QuerySet 内のオブジェクトの所属関係をチェックするのに便利です。
クエリセットに特定の項目が含まれているかどうかを確認するには、次のようにします:
\nif some_queryset.contains(obj):\n print("Entry contained in queryset")\nこれは、クエリセット全体を評価し、イテレートする必要がある以下の方法よりも高速です:
\nif obj in some_queryset:\n print("Entry contained in queryset")\nexists() と同様に、some_queryset がまだ評価されていないが、いずれ評価されることがわかっている場合、some_queryset.contains(obj) を使用すると、追加のデータベースクエリを行うことになり、通常は全体的なパフォーマンスが低下します。
update()Link to this heading#非同期バージョン: aupdate()
指定したフィールドに対して SQL の UPDATE クエリを実行し、マッチした行の数を返します (一部の行が既に新しい値を持っている場合は、更新された行の数と一致しないことがあります)。
\nたとえば、2010年に公開されたすべてのブログエントリーのコメントをオフにするには、次のようにします:
\n>>> Entry.objects.filter(pub_date__year=2010).update(comments_on=False)\n(これは Entry モデルに pub_date と comments_on フィールドがあると仮定しています)。
複数のフィールドを更新できます。たとえば、以下のコードでは comments_on フィールドと headline フィールドを更新しています:
>>> Entry.objects.filter(pub_date__year=2010).update(\n... comments_on=False, headline="This is old"\n... )\nupdate() メソッドは即座に適用されます。更新される QuerySet の唯一の制限は、モデルのメインテーブルのカラムのみを更新することができ、リレーション先のモデルのカラムを更新することはできないということです。たとえば、このようなことはできません:
>>> Entry.objects.update(blog__name="foo") # Won't work!\nリレーション先のフィールドに基づくフィルタリングは可能です:
\n>>> Entry.objects.filter(blog__id=1).update(comments_on=True)\nスライスが取られたり、それ以外の理由でこれ以上フィルタリングできなくなった QuerySet に対しては update() を呼び出すことはできません。
update() メソッドは、影響を受ける行の数を返します:
>>> Entry.objects.filter(id=64).update(comments_on=True)\n1\n\n>>> Entry.objects.filter(slug="nonexistent-slug").update(comments_on=True)\n0\n\n>>> Entry.objects.filter(pub_date__year=2010).update(comments_on=False)\n132\nレコードを更新するだけで、モデルオブジェクトに対して何もする必要がない場合、最も効率的なアプローチは、モデルオブジェクトをメモリに読み込むのではなく、 update() を呼び出すことです。たとえば、次のようにす書く代わりに、:
e = Entry.objects.get(id=10)\ne.comments_on = False\ne.save()\n...次のように書きます:
\nEntry.objects.filter(id=10).update(comments_on=False)\nまた、update() を使用することで、オブジェクトを読み込んでから save() を呼び出すまでの短い間にデータベース内で何かが変更されてしまう競合状態を防ぐことができます。
最後に、 update() は SQL レベルで更新を行うので、モデル上の save() メソッドを呼び出したり、 pre_save や post_save シグナル ( Model.save() を呼び出した結果発生するシグナル) を発したりしないことに注意してください。カスタム save() メソッドを持つモデルのレコードを更新したい場合は、次のようにループして save() を呼び出します:
for e in Entry.objects.filter(pub_date__year=2010):\n e.comments_on = False\n e.save()\norder_by() と update() の連結は MariaDB と MySQL でのみサポートされており、異なるデータベースでは無視されます。これは、一意なフィールドを指定された順序で矛盾なく更新する場合に便利です。たとえば次のようにします:
Entry.objects.order_by("-number").update(number=F("number") + 1)\ndelete()Link to this heading#非同期バージョン: adelete()
QuerySet 内のすべての行に対して SQL による DELETE クエリを実行し、削除されたオブジェクトの数とオブジェクトの種類ごとの削除数を辞書として返します。
delete() は即座に適用されます。スライスが取られたり、それ以外の理由でこれ以上フィルタリングできなくなった QuerySet に対しては delete() を呼び出すことはできません。
たとえば、特定のブログ内のすべてのエントリを削除するには、:
\n>>> b = Blog.objects.get(pk=1)\n\n# Delete all the entries belonging to this Blog.\n>>> Entry.objects.filter(blog=b).delete()\n(4, {'blog.Entry': 2, 'blog.Entry_authors': 2})\nデフォルトでは、 Django の ForeignKey は SQL の制約 ON DELETE CASCADE をエミュレートします。つまり、削除されるオブジェクトを指す外部キー を持つオブジェクトは一緒に削除されます。たとえば、次のようになります:
>>> blogs = Blog.objects.all()\n\n# This will delete all Blogs and all of their Entry objects.\n>>> blogs.delete()\n(5, {'blog.Blog': 1, 'blog.Entry': 2, 'blog.Entry_authors': 2})\nこのカスケードの動作は、ForeignKey に対する on_delete 属性によってカスタマイズできます。
delete() メソッドは一括削除を行い、モデルの delete() メソッドを呼び出しません。しかし、削除されたオブジェクト (カスケード削除を含む) に対して pre_delete と post_delete シグナルを発行します。
Django はシグナルを送ったり、カスケードを処理したりするために、オブジェクトをメモリにフェッチする必要があります。しかし、カスケードもシグナルもない場合、 Django は高速な経路をとり、メモリにフェッチせずにオブジェクトを削除するかもしれ ません。大きな削除の場合、メモリ使用量を大幅に減らすことができます。クエリの実行量も減ります。
\non_delete DO_NOTHING に設定されている外部キーは、削除の際に fast-path を取ることを防ぎません。
オブジェクトの削除で生成されるクエリは、実装の詳細部分であり、変更される可能性があることに注意してください。
\nas_manager()Link to this heading#QuerySet のメソッドをコピーした Manager のインスタンスを返すクラスメソッドです。詳細は QuerySet のメソッドで、マネージャを生成する を参照してください。
このセクションの他の項目とは異なり、クエリを実行しないため、非同期バージョンがないことに注意してください。
\nexplain()Link to this heading#非同期バージョン: aexplain()
QuerySet の実行計画文字列を返します。この実行計画は、使用するインデックスや結合を含め、データベースがどのようにクエリを実行するかの詳細を示します。これらの詳細を知ることで、遅いクエリのパフォーマンスを向上させることができます。
たとえば、PostgreSQLを使う場合:
\n>>> print(Blog.objects.filter(title="My Blog").explain())\nSeq Scan on blog (cost=0.00..35.50 rows=10 width=12)\n Filter: (title = 'My Blog'::bpchar)\n出力はデータベースによって大きく異なります。
\nexplain() は Oracle を除くすべての組み込みデータベースバックエンドでサポートされています。これは Oracle での実装が一筋縄ではいかないからです。
format パラメータは、データベースのデフォルトの出力形式 (通常はテキストベース) から変更します。PostgreSQLは 'TEXT' 、 'JSON' 、 'YAML' 、 'XML' フォーマットをサポートしています。MariaDB と MySQL は 'TEXT' ( 'TRADITIONAL' とも呼びます) と 'JSON' 形式をサポートしています。MySQL 8.0.16+ では、改良された TREE' フォーマットもサポートしています。これは PostgreSQL の 'TEXT' 出力に似ており、サポートされていればデフォルトで使用されます。
データベースによっては、クエリに関する詳細な情報を返すフラグを受け付けるものがあります。これらのフラグをキーワード引数として渡してください。たとえば、PostgreSQLを使用している場合:
\n>>> print(Blog.objects.filter(title="My Blog").explain(verbose=True, analyze=True))\nSeq Scan on public.blog (cost=0.00..35.50 rows=10 width=12) (actual time=0.004..0.004 rows=10 loops=1)\n Output: id, title\n Filter: (blog.title = 'My Blog'::bpchar)\nPlanning time: 0.064 ms\nExecution time: 0.058 ms\nデータベースによっては、フラグによってクエリが実行され、データベースに悪影響を及ぼす可能性があります。たとえば、MariaDB、MySQL 8.0.18+、PostgreSQLでサポートされている ANALYZE フラグは、 SELECT クエリであっても、トリガがある場合や関数が呼び出された場合にデータを変更してしまう可能性があります。
Field ルックアップLink to this heading#フィールドルックアップは SQL の WHERE 句の内容を指定する方法です。これらは filter() 、 exclude() 、 get() メソッドのキーワード引数として指定します。
概要については モデルとデータベースクエリのドキュメント を参照してください。
\nDjango の組み込みルックアップを以下に示します。モデルフィールドのために カスタムルックアップ を書くこともできます。
\n利便性のために、ルックアップタイプが指定されていない場合（ Entry.objects.get(id=14) のように）、ルックアップタイプは exact とみなされます。
exactLink to this heading#完全一致。比較に指定された値が None の場合、SQL の NULL と解釈されます (詳細は isnull を参照してください)。
例:
\nEntry.objects.get(id__exact=14)\nEntry.objects.get(id__exact=None)\nこれは下記のSQL文と等価です。
\nSELECT ... WHERE id = 14;\nSELECT ... WHERE id IS NULL;\niexactLink to this heading#大文字小文字を区別しない完全一致。比較に指定された値が None の場合、SQL の NULL と解釈されます (詳細は isnull を参照してください)。
実装例:
\nBlog.objects.get(name__iexact="beatles blog")\nBlog.objects.get(name__iexact=None)\nこれは下記のSQL文と等価です。
\nSELECT ... WHERE name ILIKE 'beatles blog';\nSELECT ... WHERE name IS NULL;\n最初のクエリは 'Beatles Blog', 'beatles blog', 'BeAtLes BLoG' などにマッチすることに注意してください。
containsLink to this heading#大文字小文字を区別し、文字列を含むかをチェックします。
\n実装例:
\nEntry.objects.get(headline__contains="Lennon")\nこれらは SQL で言う下記と同等です:
\nSELECT ... WHERE headline LIKE '%Lennon%';\n'Lennon honored today' という見出しにはマッチしますが、 'lennon honored today' という見出しにはマッチしないことに注意してください。
icontainsLink to this heading#大文字小文字を区別せずに文字列を含むかをチェックします。
\n実装例:
\nEntry.objects.get(headline__icontains="Lennon")\nこれらは SQL で言う下記と同等です:
\nSELECT ... WHERE headline ILIKE '%Lennon%';\ninLink to this heading#指定されたイテラブル（多くの場合、リスト、タプル、クエリセット）内に含まれるかをチェックします。あまり使われませんが、（イテラブルである）文字列は使用可能です。
\n例:
\nEntry.objects.filter(id__in=[1, 3, 4])\nEntry.objects.filter(headline__in="abc")\nこれは下記のSQL文と等価です。
\nSELECT ... WHERE id IN (1, 3, 4);\nSELECT ... WHERE headline IN ('a', 'b', 'c');\nリテラル値のリストを提供する代わりに、クエリセットを使用して以下のように値のリストを動的に評価することもできます:
\ninner_qs = Blog.objects.filter(name__contains="Cheddar")\nentries = Entry.objects.filter(blog__in=inner_qs)\nこのクエリセットは下記のようなサブクエリ内の SELECT 文として評価されます:
\nSELECT ... WHERE blog.id IN (SELECT id FROM ... WHERE NAME LIKE '%Cheddar%')\nもし values() や values_list() の結果の クエリセット を __in ルックアップの値として渡す場合は、結果の中の1つのフィールドだけを抽出するようにする必要があります。たとえば、次のようにします（ブログ名でフィルタリングする場合）:
inner_qs = Blog.objects.filter(name__contains="Ch").values("name")\nentries = Entry.objects.filter(blog__name__in=inner_qs)\n下記の例では例外が発生します。内側のクエリは2つのフィールド値を抽出しようとしているからです:
\n# Bad code! Will raise a TypeError.\ninner_qs = Blog.objects.filter(name__contains="Ch").values("name", "id")\nentries = Entry.objects.filter(blog__name__in=inner_qs)\ngtLink to this heading#～～より大きい（greater than）。
\n実装例:
\nEntry.objects.filter(id__gt=4)\nこれらは SQL で言う下記と同等です:
\nSELECT ... WHERE id > 4;\ngteLink to this heading#～～以上（greater than or equal to）。
\nltLink to this heading#～～未満（less than）。
\nlteLink to this heading#～～以下（less than equal to）。
\nstartswithLink to this heading#大文字と小文字を区別して、指定された文字列から始まるかどうかをチェックします。
\n実装例:
\nEntry.objects.filter(headline__startswith="Lennon")\nこれらは SQL で言う下記と同等です:
\nSELECT ... WHERE headline LIKE 'Lennon%';\nSQLite は大文字小文字を区別する LIKE 文をサポートしていません。 SQLite では startswith は istartswith のように動作します。
istartswithLink to this heading#大文字と小文字を区別せず、指定された文字列から始まるかどうかをチェックします。
\n実装例:
\nEntry.objects.filter(headline__istartswith="Lennon")\nこれらは SQL で言う下記と同等です:
\nSELECT ... WHERE headline ILIKE 'Lennon%';\nendswithLink to this heading#大文字と小文字を区別して、指定された文字列で終わるかどうかをチェックします。
\n実装例:
\nEntry.objects.filter(headline__endswith="Lennon")\nこれらは SQL で言う下記と同等です:
\nSELECT ... WHERE headline LIKE '%Lennon';\niendswithLink to this heading#大文字と小文字を区別せず、指定された文字列で終わるかどうかをチェックします。
\n実装例:
\nEntry.objects.filter(headline__iendswith="Lennon")\nこれらは SQL で言う下記と同等です:
\nSELECT ... WHERE headline ILIKE '%Lennon'\nrangeLink to this heading#範囲のチェック（～～を含む）。
\n実装例:
\nimport datetime\n\nstart_date = datetime.date(2005, 1, 1)\nend_date = datetime.date(2005, 3, 31)\nEntry.objects.filter(pub_date__range=(start_date, end_date))\nこれらは SQL で言う下記と同等です:
\nSELECT ... WHERE pub_date BETWEEN '2005-01-01' and '2005-03-31';\nrange は SQL で BETWEEN が使えるところならどこでも使えます。日付、数字、そして文字でも使えます。
dateLink to this heading#datetime フィールドの値を date としてキャストします。追加のフィールドルックアップを連結できます。 date 値を取ります。
\n実装例:
\nEntry.objects.filter(pub_date__date=datetime.date(2005, 1, 1))\nEntry.objects.filter(pub_date__date__gt=datetime.date(2005, 1, 1))\n(このルックアップに等価なSQLの例はありません。これは、関連するクエリの実装がデータベースエンジンによって異なるためです)。
\nUSE_TZ が True の場合、フィールドはフィルタリングの前にカレントタイムゾーンに変換されます。これには データベースのタイムゾーン定義 が必要です。
yearLink to this heading#日付フィールドとdatetimeフィールドにおける、"年" の完全一致。追加のフィールドルックアップを連結できます。年を整数で指定します。
\n実装例:
\nEntry.objects.filter(pub_date__year=2005)\nEntry.objects.filter(pub_date__year__gte=2005)\nこれらは SQL で言う下記と同等です:
\nSELECT ... WHERE pub_date BETWEEN '2005-01-01' AND '2005-12-31';\nSELECT ... WHERE pub_date >= '2005-01-01';\n(正確なSQL構文はデータベースエンジンによって異なります）。
\nUSE_TZ が True の場合、日付フィールドはフィルタリングの前にカレントタイムゾーンに変換されます。これにはデータベースの タイムゾーン定義 が必要です。
iso_yearLink to this heading#日付フィールドとdatetimeフィールドにおける、ISO 8601の週番号と年との完全一致。追加のフィールドルックアップを連結できます。年を整数で指定します。
\n実装例:
\nEntry.objects.filter(pub_date__iso_year=2005)\nEntry.objects.filter(pub_date__iso_year__gte=2005)\n(正確なSQL構文はデータベースエンジンによって異なります）。
\nUSE_TZ が True の場合、日付フィールドはフィルタリングの前にカレントタイムゾーンに変換されます。これにはデータベースの タイムゾーン定義 が必要です。
monthLink to this heading#日付フィールドおよびdatetimeフィールドにおける、"月" の完全一致。追加のフィールドルックアップを連結できます。1 (1月) から 12 (12月) までの整数を指定します。
\n実装例:
\nEntry.objects.filter(pub_date__month=12)\nEntry.objects.filter(pub_date__month__gte=6)\nこれらは SQL で言う下記と同等です:
\nSELECT ... WHERE EXTRACT('month' FROM pub_date) = '12';\nSELECT ... WHERE EXTRACT('month' FROM pub_date) >= '6';\n(正確なSQL構文はデータベースエンジンによって異なります）。
\nUSE_TZ が True の場合、日付フィールドはフィルタリングの前にカレントタイムゾーンに変換されます。これにはデータベースの タイムゾーン定義 が必要です。
dayLink to this heading#日付フィールドとdatetimeフィールドにおける、"日" の完全一致。追加のフィールドルックアップを連結できます。日を整数で指定します。
\n実装例:
\nEntry.objects.filter(pub_date__day=3)\nEntry.objects.filter(pub_date__day__gte=3)\nこれらは SQL で言う下記と同等です:
\nSELECT ... WHERE EXTRACT('day' FROM pub_date) = '3';\nSELECT ... WHERE EXTRACT('day' FROM pub_date) >= '3';\n(正確なSQL構文はデータベースエンジンによって異なります）。
\nこれは、1 月 3 日、7 月 3 日など、pub_date が月の 3 日目のレコードに一致します。
\nUSE_TZ が True の場合、日付フィールドはフィルタリングの前にカレントタイムゾーンに変換されます。これにはデータベースの タイムゾーン定義 が必要です。
weekLink to this heading#日付フィールドおよびdatetimeフィールドにおける、 ISO-8601 に従った週番号 (1～52または53) を返します。すなわち、週は月曜日から始まり、最初の週にはその年の最初の木曜日が含まれます。
\n実装例:
\nEntry.objects.filter(pub_date__week=52)\nEntry.objects.filter(pub_date__week__gte=32, pub_date__week__lte=38)\n(このルックアップに等価なSQLの例はありません。これは、関連するクエリの実装がデータベースエンジンによって異なるためです)。
\nUSE_TZ が True の場合、日付フィールドはフィルタリングの前にカレントタイムゾーンに変換されます。これにはデータベースの タイムゾーン定義 が必要です。
week_dayLink to this heading#日付フィールドとdatetimeフィールドにおける "曜日" の一致。追加のフィールドルックアップを連結できます。
\n1 (日曜日) から 7 (土曜日) までの曜日を表す整数値を指定します。
\n実装例:
\nEntry.objects.filter(pub_date__week_day=2)\nEntry.objects.filter(pub_date__week_day__gte=2)\n(このルックアップに等価なSQLの例はありません。これは、関連するクエリの実装がデータベースエンジンによって異なるためです)。
\npub_date が月曜日(週の2日目)のレコードは、月や年に関係なくマッチすることに注意してください。 週の曜日のインデックスは1日目が日曜日、7日目が土曜日です。
USE_TZ が True の場合、日付フィールドはフィルタリングの前にカレントタイムゾーンに変換されます。これにはデータベースの タイムゾーン定義 が必要です。
iso_week_dayLink to this heading#日付フィールドおよび datetime フィールドにおける、ISO 8601 曜日との完全一致。追加のフィールドルックアップを連結できます。
\n1(月曜日)から7(日曜日)までの曜日を表す整数値を取ります。
\n実装例:
\nEntry.objects.filter(pub_date__iso_week_day=1)\nEntry.objects.filter(pub_date__iso_week_day__gte=1)\n(このルックアップに等価なSQLの例はありません。これは、関連するクエリの実装がデータベースエンジンによって異なるためです)。
\npub_date が月曜日(週の1日目)のレコードは、月や年に関係なくマッチすることに注意してください。週の曜日のインデックスは1日目が月曜日、7日目が日曜日です。
USE_TZ が True の場合、日付フィールドはフィルタリングの前にカレントタイムゾーンに変換されます。これにはデータベースの タイムゾーン定義 が必要です。
quarterLink to this heading#日付および datetime フィールドにおける、"四半期" の一致。追加のフィールドルックアップを連結できます。年の四半期を表す 1 から 4 までの整数値を指定します。
\n第2四半期（4月1日から6月30日まで）のエントリーを検索する例:
\nEntry.objects.filter(pub_date__quarter=2)\n(このルックアップに等価なSQLの例はありません。これは、関連するクエリの実装がデータベースエンジンによって異なるためです)。
\nUSE_TZ が True の場合、日付フィールドはフィルタリングの前にカレントタイムゾーンに変換されます。これにはデータベースの タイムゾーン定義 が必要です。
timeLink to this heading#datetime フィールドの場合、値を time としてキャストします。追加のフィールドルックアップを連結できます。 datetime.time 値を取ります。
実装例:
\nEntry.objects.filter(pub_date__time=datetime.time(14, 30))\nEntry.objects.filter(pub_date__time__range=(datetime.time(8), datetime.time(17)))\n(このルックアップに等価なSQLの例はありません。これは、関連するクエリの実装がデータベースエンジンによって異なるためです)。
\nUSE_TZ が True の場合、フィールドはフィルタリングの前にカレントタイムゾーンに変換されます。これには データベースのタイムゾーン定義 が必要です。
hourLink to this heading#datetimeフィールドとtimeフィールドにおける、"時（hour）" の完全一致。追加のフィールドルックアップを連結できます。0 から 23 までの整数を指定します。
\n実装例:
\nEvent.objects.filter(timestamp__hour=23)\nEvent.objects.filter(time__hour=5)\nEvent.objects.filter(timestamp__hour__gte=12)\nこれらは SQL で言う下記と同等です:
\nSELECT ... WHERE EXTRACT('hour' FROM timestamp) = '23';\nSELECT ... WHERE EXTRACT('hour' FROM time) = '5';\nSELECT ... WHERE EXTRACT('hour' FROM timestamp) >= '12';\n(正確なSQL構文はデータベースエンジンによって異なります）。
\nUSE_TZ が True の場合、日付フィールドはフィルタリングの前にカレントタイムゾーンに変換されます。これにはデータベースの タイムゾーン定義 が必要です。
minuteLink to this heading#datetime フィールドと time フィールドにおける、"分" の完全一致。追加のフィールドルックアップを連結できます。0 から 59 までの整数を指定します。
\n実装例:
\nEvent.objects.filter(timestamp__minute=29)\nEvent.objects.filter(time__minute=46)\nEvent.objects.filter(timestamp__minute__gte=29)\nこれらは SQL で言う下記と同等です:
\nSELECT ... WHERE EXTRACT('minute' FROM timestamp) = '29';\nSELECT ... WHERE EXTRACT('minute' FROM time) = '46';\nSELECT ... WHERE EXTRACT('minute' FROM timestamp) >= '29';\n(正確なSQL構文はデータベースエンジンによって異なります）。
\nUSE_TZ が True の場合、日付フィールドはフィルタリングの前にカレントタイムゾーンに変換されます。これにはデータベースの タイムゾーン定義 が必要です。
secondLink to this heading#datetime および time フィールドにおける、"秒" の完全一致。追加のフィールドルックアップを連結できます。0 から 59 までの整数を指定します。
\n実装例:
\nEvent.objects.filter(timestamp__second=31)\nEvent.objects.filter(time__second=2)\nEvent.objects.filter(timestamp__second__gte=31)\nこれらは SQL で言う下記と同等です:
\nSELECT ... WHERE EXTRACT('second' FROM timestamp) = '31';\nSELECT ... WHERE EXTRACT('second' FROM time) = '2';\nSELECT ... WHERE EXTRACT('second' FROM timestamp) >= '31';\n(正確なSQL構文はデータベースエンジンによって異なります）。
\nUSE_TZ が True の場合、日付フィールドはフィルタリングの前にカレントタイムゾーンに変換されます。これにはデータベースの タイムゾーン定義 が必要です。
isnullLink to this heading#"True" または "False" を受け取り、それぞれ IS NULL と IS NOT NULL の SQL クエリに対応します。
実装例:
\nEntry.objects.filter(pub_date__isnull=True)\nこれらは SQL で言う下記と同等です:
\nSELECT ... WHERE pub_date IS NULL;\nregexLink to this heading#大文字小文字を区別する正規表現マッチ。
\n正規表現の構文は、使用するデータベースバックエンドのものです。正規表現のサポートが組み込まれていないSQLiteの場合、この機能は(Pythonの)ユーザー定義REGEXP関数によって提供され、正規表現の構文はPythonの re モジュールのものとなります。
実装例:
\nEntry.objects.get(title__regex=r"^(An?|The) +")\nこれは下記のSQL文と等価です。
\nSELECT ... WHERE title REGEXP BINARY '^(An?|The) +'; -- MySQL\n\nSELECT ... WHERE REGEXP_LIKE(title, '^(An?|The) +', 'c'); -- Oracle\n\nSELECT ... WHERE title ~ '^(An?|The) +'; -- PostgreSQL\n\nSELECT ... WHERE title REGEXP '^(An?|The) +'; -- SQLite\n正規表現の構文を渡す際には、生の文字列(例: 'foo' の代わりに r'foo') を使うことを推奨します。
iregexLink to this heading#大文字小文字を区別しない正規表現マッチ。
\n実装例:
\nEntry.objects.get(title__iregex=r"^(an?|the) +")\nこれは下記のSQL文と等価です。
\nSELECT ... WHERE title REGEXP '^(an?|the) +'; -- MySQL\n\nSELECT ... WHERE REGEXP_LIKE(title, '^(an?|the) +', 'i'); -- Oracle\n\nSELECT ... WHERE title ~* '^(an?|the) +'; -- PostgreSQL\n\nSELECT ... WHERE title REGEXP '(?i)^(an?|the) +'; -- SQLite\nDjango は django.db.models モジュールで以下の集計関数を提供しています。これらの集計関数の使い方は アグリゲーション（集計）に関するトピックガイド を参照してください。集計関数の作成方法については Aggregate ドキュメント を参照してください。
すべての集計に共通するパラメータは以下の通りです:
\nexpressionsLink to this heading#モデル上のフィールド、フィールドのトランスフォーム、または クエリ式 を参照する文字列です。
\noutput_fieldLink to this heading#戻り値の モデルフィールド を表すオプションの引数です。
\n\nfilterLink to this heading#オプションで、 Q オブジェクト で、集計する行をフィルタリングします。
たとえば 条件付きの集計 や アノテーションのフィルタリング を参照してください。
\ndefaultLink to this heading#オプションの引数で、クエリセット（またはグループ化）にエントリがない場合にデフォルト値として使用する値を指定できます。
\n**extraLink to this heading#集計によって生成されるSQLに追加のコンテキストを提供できるキーワード引数。
\nAvgLink to this heading#指定した式の平均値を返します。これは、別の output_field を指定しない限り、必ず数値となります。
デフォルトのエイリアス: <field>__avg
戻り値の型： 入力が int の場合は float を、それ以外の場合は入力フィールドと同じものを、 output_field を指定した場合は output_field を返します。クエリセットまたはグループ化が空の場合は default を返します。
オプションです。 distinct=True の場合、 Avg は一意な値の平均値を返します。これは SQL の AVG(DISTINCT <field>) と等価です。デフォルト値は False です。
CountLink to this heading#指定した式で関連付けられたオブジェクトの数を返します。 Count('*') は SQL の COUNT(*) 式と等価です。
デフォルトのエイリアス: <field>__count
戻り値の型: int
オプションです。 distinct=True の場合、一意なインスタンスのみをカウントします。これは SQL の COUNT(DISTINCT <field>) と等価です。デフォルト値は False です。
MaxLink to this heading#指定された式の最大値を返します。
\nデフォルトのエイリアス: <field>__max
戻り値の型: 入力フィールドと同じ、または output_field が指定されている場合は output_field を返します。クエリセットまたはグループ化が空の場合は default が返されます。
MinLink to this heading#指定した式の最小値を返します。
\nデフォルトのエイリアス: <field>__min
戻り値の型: 入力フィールドと同じ、または output_field が指定されている場合は output_field を返します。クエリセットまたはグループ化が空の場合は default が返されます。
StdDevLink to this heading#指定した式のデータの標準偏差を返します。
\nデフォルトのエイリアス: <field>__stddev
戻り値の型： 入力が int の場合は float を、それ以外の場合は入力フィールドと同じものを、 output_field を指定した場合は output_field を返します。クエリセットまたはグループ化が空の場合は default を返します。
オプションです。デフォルトでは StdDev は母集団の標準偏差を返します。ただし、 sample=True の場合は、標本の標準偏差が返されます。
SumLink to this heading#与えられた式のすべての値の合計を計算します。
\nデフォルトのエイリアス: <field>__sum
戻り値の型: 入力フィールドと同じ、または output_field が指定されている場合は output_field を返します。クエリセットまたはグループ化が空の場合は default が返されます。
オプションです。 distinct=True の場合、 Sum は一意な値の合計を返します。これは SQL の SUM(DISTINCT ) と等価です。デフォルト値は False です。
VarianceLink to this heading#指定された式のデータの分散を返します。
\nデフォルトのエイリアス: <field>__variance
戻り値の型： 入力が int の場合は float を、それ以外の場合は入力フィールドと同じものを、 output_field を指定した場合は output_field を返します。クエリセットまたはグループ化が空の場合は default を返します。
オプションです。デフォルトでは Variance は母分散を返します。ただし、 sample=True の場合は、標本の分散を返します。