QuerySet API リファレンスLink to this heading#

filter()Link to this heading#

filter(*args, **kwargs)Link to this definition#

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

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

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

exclude()Link to this heading#

exclude(*args, **kwargs)Link to this definition#

与えられたルックアップパラメータにマッチ しない 新しい 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()Link to this heading#

annotate(*args, **kwargs)Link to this definition#

QuerySet 内の各オブジェクトに、指定された クエリ式 または Q オブジェクトのリストを使ってアノテーション（注釈）を追加します。各オブジェクトには、以下のようなものをアノテーションとして追加できます。

• Value() で指定する単純な値。

• F() で指定するモデル（または関連モデル）のフィールドへの参照。

• Q() で指定する真偽値（判定式）。

• QuerySet 内のオブジェクトに関連付けられたオブジェクトに対して計算された集約式（平均、合計など）の結果。

annotate() に渡される引数はそれぞれがアノテーションとなって、返される QuerySet 内の各オブジェクトに追加されます。

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

キーワード引数を使って指定されたアノテーションは、そのキーワードがアノテーションのエイリアスとして使用されます。匿名引数の場合は、集計関数の名前と集計対象のモデルフィールド名に基づいて自動的にエイリアスが生成されます。匿名引数として使用できるのは、単一のフィールドを参照する集計式のみです。それ以外のすべての式はキーワード引数として指定する必要があります。

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

>>> 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()Link to this heading#

alias(*args, **kwargs)Link to this definition#

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()Link to this heading#

order_by(*fields)Link to this definition#

デフォルトでは、 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)をとります。

Be cautious when ordering by fields in related models if you are also using distinct(). See the note in distinct() for an explanation of how related model ordering can change the expected results.

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

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

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

If you don't want any ordering to be applied to a query, not even the default ordering, call order_by() with no parameters.

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

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

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

reverse()Link to this heading#

reverse()Link to this definition#

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

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

my_queryset.reverse()[:5]

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

Also, note that reverse() should generally only be called on a QuerySet which has a defined ordering (e.g., when querying against a model which defines a default ordering, or when using order_by()). If no such ordering is defined for a given QuerySet, calling reverse() on it has no real effect (the ordering was undefined prior to calling reverse(), and will remain undefined afterward).

distinct()Link to this heading#

distinct(*fields)Link to this definition#

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

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

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

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

>>> Author.objects.distinct()
<QuerySet [...]>
>>> Entry.objects.order_by("pub_date").distinct("pub_date")
<QuerySet [...]>
>>> Entry.objects.order_by("blog").distinct("blog")
<QuerySet [...]>
>>> Entry.objects.order_by("author", "pub_date").distinct("author", "pub_date")
<QuerySet [...]>
>>> Entry.objects.order_by("blog__name", "mod_date").distinct("blog__name", "mod_date")
<QuerySet [...]>
>>> Entry.objects.order_by("author", "pub_date").distinct("author")
<QuerySet [...]>

values()Link to this heading#

values(*fields, **expressions)Link to this definition#

イテラブルオブジェクトとして使用するとき、モデルインスタンスではなく辞書を返す 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 のどちらを渡しても、同じものが返ってきます（辞書のキーは渡したフィールド名と一致します）。

  例:

  Python console

  >>> 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}, ...]>
  

• When using values() together with distinct(), be aware that ordering can affect the results. See the note in distinct() for details.

• If you use a values() clause after an extra() call, any fields defined by a select argument in the extra() must be explicitly included in the values() call. Any extra() call made after a values() call will have its extra selected fields ignored.

• Calling only() and defer() after values() doesn't make sense, so doing so will raise a TypeError.

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

  Python console

  >>> 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'}, ...]>

values_list()Link to this heading#

values_list(*fields, flat=False, named=False)Link to this definition#

この関数は 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,)]>

dates()Link to this heading#

dates(field, kind, order='ASC')Link to this definition#

この 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()Link to this heading#

datetimes(field_name, kind, order='ASC', tzinfo=None)Link to this definition#

これは、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()Link to this definition#

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

例:

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

all()Link to this heading#

all()Link to this definition#

Returns a copy of the current QuerySet (or QuerySet subclass). This can be useful in situations where you might want to pass in either a model manager or a QuerySet and do further filtering on the result. After calling all() on either object, you'll definitely have a QuerySet to work with.

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

union()Link to this heading#

union(*other_qs, all=False)Link to this definition#

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")

In addition, only LIMIT, OFFSET, COUNT(*), ORDER BY, and specifying columns (i.e. slicing, count(), exists(), order_by(), and values()/values_list()) are allowed on the resulting QuerySet. Further, databases place restrictions on what operations are allowed in the combined queries. For example, most databases don't allow LIMIT or OFFSET in the combined queries.

intersection()Link to this heading#

intersection(*other_qs)Link to this definition#

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

>>> qs1.intersection(qs2, qs3)

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

difference()Link to this heading#

difference(*other_qs)Link to this definition#

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

>>> qs1.difference(qs2, qs3)

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

select_related()Link to this heading#

select_related(*fields)Link to this definition#

クエリを実行する際に、追加で関連オブジェクトのデータを選択し、外部キーのリレーションシップを "辿る" 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)

Then a call to Book.objects.select_related('author__hometown').get(id=4) will cache the related Person and the related 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()Link to this heading#

prefetch_related(*lookups)Link to this definition#

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

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

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

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

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

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()
<QuerySet [<Pizza: Hawaiian (ham, pineapple)>, <Pizza: 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 のキャッシュを利用するようになります。

つまり、関連するトッピングはすべて単一のクエリで取得され、関連する結果があらかじめキャッシュされた QuerySet インスタンスの作成に使用されます。これらはその後、 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 の典型的な挙動を変更するもので、QuerySet は通常、データベースでクエリが実行された後であっても、必要になるまで全オブジェクトをメモリに読み込まないように動作します。

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

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"))
... )

Or to call select_related() when applicable to reduce the number of queries even further:

>>> 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()

Custom prefetching also works with single related relations like forward ForeignKey or OneToOneField. Generally you'll want to use select_related() for these relations, but there are a number of cases where prefetching with a custom QuerySet is useful:

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

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

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

  Python console

  >>> 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")

extra()Link to this heading#

extra(select=None, where=None, params=None, tables=None, order_by=None, select_params=None)Link to this definition#

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

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

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

• select

  The select argument lets you put extra fields in the SELECT clause. It should be a dictionary mapping attribute names to SQL clauses to use to calculate that attribute.

  実装例:

  Code

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

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

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

  SQL

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

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

  Code

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

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

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

  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 句では必要ありません。

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

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

  Code

  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" 演算されます。

  実装例:

  Code

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

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

  SQL

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

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

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

• order_by

  If you need to order the resulting queryset using some of the new fields or tables you have included via extra() use the order_by parameter to extra() and pass in a sequence of strings. These strings should either be model fields (as in the normal order_by() method on querysets), of the form table_name.column_name or an alias for a column that you specified in the select parameter to extra().

  例:

  Code

  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 引数は、代入される追加のパラメータのリストです。

  実装例:

  Code

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

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

  悪い例:

  Code

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

  良い例:

  Code

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

defer()Link to this heading#

defer(*fields)Link to this definition#

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

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

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

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

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

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

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

You can defer loading of fields in related models (if the related models are loading via select_related()) by using the standard double-underscore notation to separate related fields:

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

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

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

Some fields in a model won't be deferred, even if you ask for them. You can never defer the loading of the primary key. If you are using select_related() to retrieve related models, you shouldn't defer the loading of the field that connects from the primary model to the related one, doing so will result in an error.

Similarly, calling defer() (or its counterpart only()) including an argument from an aggregation (e.g. using the result of annotate()) doesn't make sense: doing so will raise an exception. The aggregated values will always be fetched into the resulting queryset.

only()Link to this heading#

only(*fields)Link to this definition#

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() 呼び出し内に含まれていることを確認してください。

using()Link to this heading#

using(alias)Link to this definition#

This method is for controlling which database the QuerySet will be evaluated against if you are using more than one database. The only argument this method takes is the alias of a database, as defined in 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()Link to this heading#

select_for_update(nowait=False, skip_locked=False, of=(), no_key=False)Link to this definition#

トランザクションが終了するまで行をロックし、サポートされているデータベース上で 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' という値を使用します。

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() がオートコミットモードで使用されてもエラーは発生しません。

raw()Link to this heading#

raw(raw_query, params=(), translations=None, using=None)Link to this definition#

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

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

AND (&)Link to this heading#

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 (|)Link to this heading#

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 (^)Link to this heading#

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

get()Link to this heading#

get(*args, **kwargs)Link to this definition#

aget(*args, **kwargs)Link to this definition#

非同期バージョン: 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()Link to this heading#

create(**kwargs)Link to this definition#

acreate(**kwargs)Link to this definition#

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

A convenience method for creating an object and saving it all in one step. Thus:

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()Link to this heading#

get_or_create(defaults=None, **kwargs)Link to this definition#

aget_or_create(defaults=None, **kwargs)Link to this definition#

非同期バージョン: 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)},
)

Any keyword arguments passed to get_or_create() — except an optional one called defaults — will be used in a get() call. If an object is found, get_or_create() returns a tuple of that object and False.

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"})

The get_or_create() method has similar error behavior to create() when you're using manually specified primary keys. If an object needs to be created and the key already exists in the database, an IntegrityError will be raised.

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

update_or_create()Link to this heading#

update_or_create(defaults=None, create_defaults=None, **kwargs)Link to this definition#

aupdate_or_create(defaults=None, create_defaults=None, **kwargs)Link to this definition#

非同期バージョン: 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 が発生します。

bulk_create()Link to this heading#

bulk_create(objs, batch_size=None, ignore_conflicts=False, update_conflicts=False, update_fields=None, unique_fields=None)Link to this definition#

abulk_create(objs, batch_size=None, ignore_conflicts=False, update_conflicts=False, update_fields=None, unique_fields=None)Link to this definition#

非同期バージョン: 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 シグナルは送信されません。

• マルチテーブル継承の子にあたるモデルでは動作しません。

• If the model's primary key is an AutoField or has a db_default value, and ignore_conflicts is False, the primary key attribute can only be retrieved on certain databases (currently PostgreSQL, MariaDB, and SQLite 3.35+). On other databases, it will not be set.

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

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

  Code

  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 および 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#

bulk_update(objs, fields, batch_size=None)Link to this definition#

abulk_update(objs, fields, batch_size=None)Link to this definition#

非同期バージョン: 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 を指定します。

• 多数のオブジェクトを更新する場合、 bulk_update() はクエリを実行する前に、すべてのバッチにわたって各オブジェクトに対する WHEN 句をあらかじめ準備することに注意してください。この処理は予想以上に多くのメモリを必要とする場合があります。メモリ使用量を削減するには、次のような方法を利用できます:

  Code

  from itertools import islice
  
  batch_size = 100
  ids_iter = iter(range(1000))
  while ids := list(islice(ids_iter, batch_size)):
      batch = Entry.objects.filter(id__in=ids)
      for entry in batch:
          entry.headline = f"Updated headline {entry.pk}"
      Entry.objects.bulk_update(batch, ["headline"], batch_size=batch_size)
  

• マルチテーブル継承の継承元に定義されたフィールドを更新すると、継承元ごとに追加のクエリが発生します。

• 独立した1つのバッチ内に重複がある場合、そのバッチの最初のインスタンスだけが更新されます。

• 関数が返す更新されたオブジェクトの数は、渡されたオブジェクトの数より少ない場合があります。これは、渡されたオブジェクトが重複して同じバッチで更新されたり、オブジェクトがデータベースに存在しなくなるような競合状態が発生したりすることが原因です。

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

count()Link to this heading#

count()Link to this definition#

acount()Link to this definition#

非同期バージョン: 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()Link to this heading#

in_bulk(id_list=None, *, field_name='pk')Link to this definition#

ain_bulk(id_list=None, *, field_name='pk')Link to this definition#

非同期バージョン: 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()Link to this heading#

iterator(chunk_size=None)Link to this definition#

aiterator(chunk_size=None)Link to this definition#

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

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

A QuerySet typically caches its results internally so that repeated evaluations do not result in additional queries. In contrast, iterator() will read results directly, without doing any caching at the QuerySet level. For a QuerySet which returns a large number of objects that you only need to access once, this can result in better performance and a significant reduction in memory.

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

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

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

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

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

latest()Link to this heading#

latest(*fields)Link to this definition#

alatest(*fields)Link to this definition#

非同期バージョン: 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 で指定されたフィールドがデフォルトで使用されます。

Like get(), earliest() and latest() raise DoesNotExist if there is no object with the given parameters.

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

earliest()Link to this heading#

earliest(*fields)Link to this definition#

aearliest(*fields)Link to this definition#

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

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

first()Link to this heading#

first()Link to this definition#

afirst()Link to this definition#

非同期バージョン: 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()Link to this heading#

last()Link to this definition#

alast()Link to this definition#

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

Works like first(), but returns the last object in the queryset.

aggregate()Link to this heading#

aggregate(*args, **kwargs)Link to this definition#

aaggregate(*args, **kwargs)Link to this definition#

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

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

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

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

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

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

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

>>> Blog.objects.aggregate(number_of_authors=Count("entry__authors"))
{'number_of_authors': 16}

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

exists()Link to this heading#

exists()Link to this definition#

aexists()Link to this definition#

非同期バージョン: 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()Link to this heading#

contains(obj)Link to this definition#

acontains(obj)Link to this definition#

非同期バージョン: 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()Link to this heading#

update(**kwargs)Link to this definition#

aupdate(**kwargs)Link to this definition#

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

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

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

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

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