QuerySet API リファレンスLink to this heading#このドキュメントでは、QuerySet API の詳細を説明しています。モデル と データベースクエリ ガイドにある説明を前提としていますので、このドキュメントを読む前にこの 2 つを読んでおいた方がよいでしょう。
このリファレンスでは、 データベースクエリガイド で提供された Blogモデルの例 を使用します。
\nQuerySets are evaluatedLink to this heading#内部的に、 QuerySet は実際にデータベースにアクセスすることなく、構築、フィルタ、スライス、そして基本的に他に渡されます。あなたがクエリセットを評価するために何かしない限り、実際のデータベースへのアクセスは発生しません。
あなたは次のような方法で QuerySet を評価することができます:
イテレーション。 QuerySet はイテラブルで、初めてイテレートした時にデータベースのクエリを実行します。たとえば、これはデータベースにある全エントリのヘッドラインを出力するプログラムです:
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\nスライス。 QuerySet の要素数を制限する で説明されているとおり、 QuerySet はPythonのリストスライスを用いてスライス可能です。未評価の QuerySet をスライスすると、通常は新たな未評価の QuerySet が返されます。しかし、スライスの "step" パラメータを使用した場合、Djangoはデータベースクエリを実行し、リストを返します。評価された QuerySet をスライスした場合も同様にリストが返されます。
未評価の QuerySet をスライスして別の未評価の QuerySet が返されても、それをさらに変更すること(たとえば、さらにフィルタを追加したり、順序を変更したりすること)は許されていないことに気を付けてください。これは、その操作がSQLに正しく変換されず、明確な意味を持たないためです。
Pickle 化/キャッシュ化。 詳細については、後述の pickling QuerySets を参照してください。結果がデータベースから読み出されることが、このセクションの目的として重要なことです。
repr()。 QuerySet は repr() が呼び出された時点で評価されます。これはPythonの対話型インタプリタでの利便性を図るためで、APIを対話的に使用する際にクエリの結果をすぐに確認することができます。
len()。 QuerySet は len() を呼び出した時点で評価されます。想像される通り、この操作は結果のリストの長さを返します。
メモ: セット内のレコード数を決定したいだけであれば(そして実際のオブジェクトが必要ないのであれば)、SQLの SELECT COUNT(*) を使ってデータベースレベルでハンドルする方がより効率的です。Djangoはまさにこの理由から count() メソッドを提供しています。
list()。 list() を呼び出すことで、 QuerySet の評価を強制します。たとえば:
entry_list = list(Entry.objects.all())\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() を使うべきです。
QuerySetsLink 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 を操作する際には chaining filters を使用します。これを実現するために、ほとんどの 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 objects (*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 objects (*args) を使用してください。
annotate()Link to this heading#query expressions で提供されるリストに従い、 QuerySet の各オブジェクトに集計情報を付加します。式としては、シンプルな値、モデル(または関連モデル)のフィールド参照、あるいは QuerySet 内のオブジェクトに関連するオブジェクトに対して計算された集計式(平均、合計など)が含まれます。
annotate() の引数は、それぞれが返り値となる QuerySet 内の各オブジェクトに追加される集計情報となります。
Djangoが提供する集計関数については、 Aggregation Functions で説明されています。
\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集計処理についての深い議論については、 the topic guide on Aggregation を確認してください。
\nalias()Link to this heading#annotate() と同じですが、 QuerySet にオブジェクトをアノテーションするかわりに、後で他の QuerySet メソッドで再利用できるように式を保存します。これは式の結果自体は必要ないが、フィルタリングやソート、あるいは複雑な式の一部として利用する場合に便利です。未使用の値を選択しないことで、データベースで冗長な処理を行わずに済み、結果的にパフォーマンスを向上させることができます。
For example, if you want to find blogs with more than 5 entries, but are not\ninterested in the exact number of entries, you could do this:
\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() を式中で呼び出すことで、 query expressions を使うこともできます:
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() の呼び出しでは、データベースは指定されたフィールド名のみを比較することができます。
例を示します(1行目以外は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ソートには、ビルトインのルックアップまたは :doc:`カスタムルックアップ </howto/custom-lookups> ` を使用することができます。例えば、次のようになります：
\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'}]>\nAn aggregate within a values() clause is applied before other arguments\nwithin the same values() clause. If you need to group by another value,\nadd it to an earlier values() clause instead. For example:
>>> 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}]>\nA few subtleties that are worth mentioning:
\nIf you have a field called foo that is a\nForeignKey, the default values() call\nwill return a dictionary key called foo_id, since this is the name\nof the hidden model attribute that stores the actual value (the foo\nattribute refers to the related model). When you are calling\nvalues() and passing in field names, you can pass in either foo\nor foo_id and you will get back the same thing (the dictionary key\nwill match the field name you passed in).
例:
\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}, ...]>\nWhen using values() together with distinct(), be aware that\nordering can affect the results. See the note in distinct() for\ndetails.
If you use a values() clause after an extra() call,\nany fields defined by a select argument in the extra() must\nbe explicitly included in the values() call. Any extra() call\nmade after a values() call will have its extra selected fields\nignored.
Calling only() and defer() after values() doesn't make\nsense, so doing so will raise a TypeError.
Combining transforms and aggregates requires the use of two annotate()\ncalls, either explicitly or as keyword arguments to values(). As above,\nif the transform has been registered on the relevant field type the first\nannotate() can be omitted, thus the following examples are equivalent:
>>> 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(\n... entry__authors__name__lower=Lower('entry__authors__name')\n... ).annotate(entries=Count('entry'))\n<QuerySet [{'entry__authors__name__lower': 'test author', 'entries': 33}]>\n>>> Blog.objects.annotate(\n... entry__authors__name__lower=Lower('entry__authors__name')\n... ).values('entry__authors__name__lower').annotate(entries=Count('entry'))\n<QuerySet [{'entry__authors__name__lower': 'test author', 'entries': 33}]>\nIt is useful when you know you're only going to need values from a small number\nof the available fields and you won't need the functionality of a model\ninstance object. It's more efficient to select only the fields you need to use.
\nFinally, note that you can call filter(), order_by(), etc. after the\nvalues() call, that means that these two calls are identical:
Blog.objects.values().order_by('id')\nBlog.objects.order_by('id').values()\nThe people who made Django prefer to put all the SQL-affecting methods first,\nfollowed (optionally) by any output-affecting methods (such as values()),\nbut it doesn't really matter. This is your chance to really flaunt your\nindividualism.
You can also refer to fields on related models with reverse relations through\nOneToOneField, ForeignKey and ManyToManyField attributes:
>>> 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#This is similar to values() except that instead of returning dictionaries,\nit returns tuples when iterated over. Each tuple contains the value from the\nrespective field or expression passed into the values_list() call — so the\nfirst item is the first field, etc. For example:
>>> 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'), ...]>\nIf you only pass in a single field, you can also pass in the flat\nparameter. If True, this will mean the returned results are single values,\nrather than one-tuples. An example should make the difference clearer:
>>> 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, ...]>\nIt is an error to pass in flat when there is more than one field.
You can pass named=True to get results as a\nnamedtuple():
>>> Entry.objects.values_list('id', 'headline', named=True)\n<QuerySet [Row(id=1, headline='First entry'), ...]>\nUsing a named tuple may make use of the results more readable, at the expense\nof a small performance penalty for transforming the results into a named tuple.
\nIf you don't pass any values to values_list(), it will return all the\nfields in the model, in the order they were declared.
A common need is to get a specific field value of a certain model instance. To\nachieve that, use values_list() followed by a get() call:
>>> Entry.objects.values_list('headline', flat=True).get(pk=1)\n'First entry'\nvalues() and values_list() are both intended as optimizations for a\nspecific use case: retrieving a subset of data without the overhead of creating\na model instance. This metaphor falls apart when dealing with many-to-many and\nother multivalued relations (such as the one-to-many relation of a reverse\nforeign key) because the "one row, one object" assumption doesn't hold.
For example, notice the behavior when querying across a\nManyToManyField:
>>> 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)]>\nAuthors with multiple entries appear multiple times and authors without any\nentries have None for the entry headline.
Similarly, when querying a reverse foreign key, None appears for entries\nnot having any author:
>>> Entry.objects.values_list('authors')\n<QuerySet [('Noam Chomsky',), ('George Orwell',), (None,)]>\ndates()Link to this heading#Returns a QuerySet that evaluates to a list of datetime.date\nobjects representing all available dates of a particular kind within the\ncontents of the QuerySet.
field should be the name of a DateField of your model.\nkind should be either "year", "month", "week", or "day".\nEach datetime.date object in the result list is "truncated" to the\ngiven type.
"year" returns a list of all distinct year values for the field.
"month" returns a list of all distinct year/month values for the\nfield.
"week" returns a list of all distinct year/week values for the field. All\ndates will be a Monday.
"day" returns a list of all distinct year/month/day values for the\nfield.
order, which defaults to 'ASC', should be either 'ASC' or\n'DESC'. This specifies how to order the results.
例:
\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#Returns a QuerySet that evaluates to a list of datetime.datetime\nobjects representing all available dates of a particular kind within the\ncontents of the QuerySet.
field_name should be the name of a DateTimeField of your model.
kind should be either "year", "month", "week", "day",\n"hour", "minute", or "second". Each datetime.datetime\nobject in the result list is "truncated" to the given type.
order, which defaults to 'ASC', should be either 'ASC' or\n'DESC'. This specifies how to order the results.
tzinfo defines the time zone to which datetimes are converted prior to\ntruncation. Indeed, a given datetime has different representations depending\non the time zone in use. This parameter must be a datetime.tzinfo\nobject. If it's None, Django uses the current time zone. It has no effect when USE_TZ is\nFalse.
is_dst indicates whether or not pytz should interpret nonexistent and\nambiguous datetimes in daylight saving time. By default (when is_dst=None),\npytz raises an exception for such datetimes.
none()Link to this heading#Calling none() will create a queryset that never returns any objects and no\nquery will be executed when accessing the results. A qs.none() queryset\nis an instance of 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#Returns a copy of the current QuerySet (or QuerySet subclass). This\ncan be useful in situations where you might want to pass in either a model\nmanager or a QuerySet and do further filtering on the result. After calling\nall() on either object, you'll definitely have a QuerySet to work with.
QuerySet が 評価される とき、通常その結果はキャッシュされます。もし QuerySet が評価された後にデータベースのデータが更新された場合、以前に評価された QuerySet に対して``all()`` を呼び出すことで、同じクエリの最新の結果を取得することができます。
union()Link to this heading#Uses SQL's UNION operator to combine the results of two or more\nQuerySets. For example:
>>> qs1.union(qs2, qs3)\nThe UNION operator selects only distinct values by default. To allow\nduplicate values, use the all=True argument.
union(), intersection(), and difference() return model instances\nof the type of the first QuerySet even if the arguments are QuerySets\nof other models. Passing different models works as long as the SELECT list\nis the same in all QuerySets (at least the types, the names don't matter\nas long as the types are in the same order). In such cases, you must use the\ncolumn names from the first QuerySet in QuerySet methods applied to the\nresulting QuerySet. For example:
>>> qs1 = Author.objects.values_list('name')\n>>> qs2 = Entry.objects.values_list('headline')\n>>> qs1.union(qs2).order_by('name')\nIn addition, only LIMIT, OFFSET, COUNT(*), ORDER BY, and\nspecifying columns (i.e. slicing, count(), exists(),\norder_by(), and values()/values_list()) are allowed\non the resulting QuerySet. Further, databases place restrictions on\nwhat operations are allowed in the combined queries. For example, most\ndatabases don't allow LIMIT or OFFSET in the combined queries.
intersection()Link to this heading#Uses SQL's INTERSECT operator to return the shared elements of two or more\nQuerySets. For example:
>>> qs1.intersection(qs2, qs3)\nSee union() for some restrictions.
difference()Link to this heading#Uses SQL's EXCEPT operator to keep only elements present in the\nQuerySet but not in some other QuerySets. For example:
>>> qs1.difference(qs2, qs3)\nSee union() for some restrictions.
extra()Link to this heading#Sometimes, the Django query syntax by itself can't easily express a complex\nWHERE clause. For these edge cases, Django provides the extra()\nQuerySet modifier — a hook for injecting specific clauses into the SQL\ngenerated by a QuerySet.
By definition, these extra lookups may not be portable to different database\nengines (because you're explicitly writing SQL code) and violate the DRY\nprinciple, so you should avoid them if possible.
\nSpecify one or more of params, select, where or tables. None\nof the arguments is required, but you should use at least one of them.
select
The select argument lets you put extra fields in the SELECT\nclause. It should be a dictionary mapping attribute names to SQL\nclauses to use to calculate that attribute.
実装例:
\nEntry.objects.extra(select={'is_recent': "pub_date > '2006-01-01'"})\nAs a result, each Entry object will have an extra attribute,\nis_recent, a boolean representing whether the entry's pub_date\nis greater than Jan. 1, 2006.
Django inserts the given SQL snippet directly into the SELECT\nstatement, so the resulting SQL of the above example would be something like:
SELECT blog_entry.*, (pub_date > '2006-01-01') AS is_recent\nFROM blog_entry;\nThe next example is more advanced; it does a subquery to give each\nresulting Blog object an entry_count attribute, an integer count\nof associated Entry objects:
Blog.objects.extra(\n select={\n 'entry_count': 'SELECT COUNT(*) FROM blog_entry WHERE blog_entry.blog_id = blog_blog.id'\n },\n)\nIn this particular case, we're exploiting the fact that the query will\nalready contain the blog_blog table in its FROM clause.
The resulting SQL of the above example would be:
\nSELECT blog_blog.*, (SELECT COUNT(*) FROM blog_entry WHERE blog_entry.blog_id = blog_blog.id) AS entry_count\nFROM blog_blog;\nNote that the parentheses required by most database engines around\nsubqueries are not required in Django's select clauses. Also note\nthat some database backends, such as some MySQL versions, don't support\nsubqueries.
In some rare cases, you might wish to pass parameters to the SQL\nfragments in extra(select=...). For this purpose, use the\nselect_params parameter.
This will work, for example:
\nBlog.objects.extra(\n select={'a': '%s', 'b': '%s'},\n select_params=('one', 'two'),\n)\nIf you need to use a literal %s inside your select string, use\nthe sequence %%s.
where / tables
You can define explicit SQL WHERE clauses — perhaps to perform\nnon-explicit joins — by using where. You can manually add tables to\nthe SQL FROM clause by using tables.
where and tables both take a list of strings. All where\nparameters are "AND"ed to any other search criteria.
実装例:
\nEntry.objects.extra(where=["foo='a' OR bar = 'a'", "baz = 'a'"])\n...translates (roughly) into the following SQL:
\nSELECT * FROM blog_entry WHERE (foo='a' OR bar='a') AND (baz='a')\nBe careful when using the tables parameter if you're specifying\ntables that are already used in the query. When you add extra tables\nvia the tables parameter, Django assumes you want that table\nincluded an extra time, if it is already included. That creates a\nproblem, since the table name will then be given an alias. If a table\nappears multiple times in an SQL statement, the second and subsequent\noccurrences must use aliases so the database can tell them apart. If\nyou're referring to the extra table you added in the extra where\nparameter this is going to cause errors.
Normally you'll only be adding extra tables that don't already appear\nin the query. However, if the case outlined above does occur, there are\na few solutions. First, see if you can get by without including the\nextra table and use the one already in the query. If that isn't\npossible, put your extra() call at the front of the queryset\nconstruction so that your table is the first use of that table.\nFinally, if all else fails, look at the query produced and rewrite your\nwhere addition to use the alias given to your extra table. The\nalias will be the same each time you construct the queryset in the same\nway, so you can rely upon the alias name to not change.
order_by
If you need to order the resulting queryset using some of the new\nfields or tables you have included via extra() use the order_by\nparameter to extra() and pass in a sequence of strings. These\nstrings should either be model fields (as in the normal\norder_by() method on querysets), of the form\ntable_name.column_name or an alias for a column that you specified\nin the select parameter to extra().
例:
\nq = Entry.objects.extra(select={'is_recent': "pub_date > '2006-01-01'"})\nq = q.extra(order_by = ['-is_recent'])\nThis would sort all the items for which is_recent is true to the\nfront of the result set (True sorts before False in a\ndescending ordering).
This shows, by the way, that you can make multiple calls to extra()\nand it will behave as you expect (adding new constraints each time).
params
The where parameter described above may use standard Python\ndatabase string placeholders — '%s' to indicate parameters the\ndatabase engine should automatically quote. The params argument is\na list of any extra parameters to be substituted.
実装例:
\nEntry.objects.extra(where=['headline=%s'], params=['Lennon'])\nAlways use params instead of embedding values directly into\nwhere because params will ensure values are quoted correctly\naccording to your particular backend. For example, quotes will be\nescaped correctly.
Bad:
\nEntry.objects.extra(where=["headline='Lennon'"])\nGood:
\nEntry.objects.extra(where=['headline=%s'], params=['Lennon'])\ndefer()Link to this heading#In some complex data-modeling situations, your models might contain a lot of\nfields, some of which could contain a lot of data (for example, text fields),\nor require expensive processing to convert them to Python objects. If you are\nusing the results of a queryset in some situation where you don't know\nif you need those particular fields when you initially fetch the data, you can\ntell Django not to retrieve them from the database.
\nThis is done by passing the names of the fields to not load to defer():
Entry.objects.defer("headline", "body")\nA queryset that has deferred fields will still return model instances. Each\ndeferred field will be retrieved from the database if you access that field\n(one at a time, not all the deferred fields at once).
\n\nYou can make multiple calls to defer(). Each call adds new fields to the\ndeferred set:
# Defers both the body and headline fields.\nEntry.objects.defer("body").filter(rating=5).defer("headline")\nThe order in which fields are added to the deferred set does not matter.\nCalling defer() with a field name that has already been deferred is\nharmless (the field will still be deferred).
You can defer loading of fields in related models (if the related models are\nloading via select_related()) by using the standard double-underscore\nnotation to separate related fields:
Blog.objects.select_related().defer("entry__headline", "entry__body")\nIf you want to clear the set of deferred fields, pass None as a parameter\nto defer():
# Load all fields immediately.\nmy_queryset.defer(None)\nSome fields in a model won't be deferred, even if you ask for them. You can\nnever defer the loading of the primary key. If you are using\nselect_related() to retrieve related models, you shouldn't defer the\nloading of the field that connects from the primary model to the related\none, doing so will result in an error.
only()Link to this heading#The only() method is essentially the opposite of defer(). Only the\nfields passed into this method and that are not already specified as deferred\nare loaded immediately when the queryset is evaluated.
If you have a model where almost all the fields need to be deferred, using\nonly() to specify the complementary set of fields can result in simpler\ncode.
Suppose you have a model with fields name, age and biography. The\nfollowing two querysets are the same, in terms of deferred fields:
Person.objects.defer("age", "biography")\nPerson.objects.only("name")\nWhenever you call only() it replaces the set of fields to load\nimmediately. The method's name is mnemonic: only those fields are loaded\nimmediately; the remainder are deferred. Thus, successive calls to only()\nresult in only the final fields being considered:
# This will defer all fields except the headline.\nEntry.objects.only("body", "rating").only("headline")\nSince defer() acts incrementally (adding fields to the deferred list), you\ncan combine calls to only() and defer() and things will behave\nlogically:
# 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")\nAll of the cautions in the note for the defer() documentation apply to\nonly() as well. Use it cautiously and only after exhausting your other\noptions.
Using only() and omitting a field requested using select_related()\nis an error as well.
As with defer(), you cannot access the non-loaded fields from asynchronous\ncode and expect them to load. Instead, you will get a\nSynchronousOnlyOperation exception. Ensure that all fields you might access\nare in your only() call.
using()Link to this heading#This method is for controlling which database the QuerySet will be\nevaluated against if you are using more than one database. The only argument\nthis method takes is the alias of a database, as defined in\nDATABASES.
例:
\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#Returns a queryset that will lock rows until the end of the transaction,\ngenerating a SELECT ... FOR UPDATE SQL statement on supported databases.
例:
\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 ...\nWhen the queryset is evaluated (for entry in entries in this case), all\nmatched entries will be locked until the end of the transaction block, meaning\nthat other transactions will be prevented from changing or acquiring locks on\nthem.
通常、選択された行の1つに対して他のトランザクションが既にロックを取得している場合、ロックが解除されるまでクエリはブロックされます。このような動作が望ましくない場合は、 select_for_update(nowait=True) を呼び出してください。これにより、呼び出しがノンブロッキングになります。競合するロックが既に他のトランザクションによって取得されている場合は、クエリセットが評価される際に DatabaseError が発生します。代わりに select_for_update(skip_locked=True) を使用すれば、ロックされた行を無視することもできます。 nowait と skip_locked``は互いに排他的であり、両方のオプションを有効にして ``select_for_update() を呼び出そうとすると ValueError が発生します。
By default, select_for_update() locks all rows that are selected by the\nquery. For example, rows of related objects specified in select_related()\nare locked in addition to rows of the queryset's model. If this isn't desired,\nspecify the related objects you want to lock in select_for_update(of=(...))\nusing the same fields syntax as select_related(). Use the value 'self'\nto refer to the queryset's model.
On PostgreSQL only, you can pass no_key=True in order to acquire a weaker\nlock, that still allows creating rows that merely reference locked rows\n(through a foreign key, for example) while the lock is in place. The\nPostgreSQL documentation has more details about row-level lock modes.
You can't use select_for_update() on nullable relations:
>>> 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\nTo avoid that restriction, you can exclude null objects if you don't care about\nthem:
\n>>> Person.objects.select_related('hometown').select_for_update().exclude(hometown=None)\n<QuerySet [<Person: ...)>, ...]>\nThe postgresql, oracle, and mysql database backends support\nselect_for_update(). However, MariaDB only supports the nowait\nargument, MariaDB 10.6+ also supports the skip_locked argument, and MySQL\n8.0.1+ supports the nowait, skip_locked, and of arguments. The\nno_key argument is only supported on PostgreSQL.
Passing nowait=True, skip_locked=True, no_key=True, or of to\nselect_for_update() using database backends that do not support these\noptions, such as MySQL, raises a NotSupportedError. This\nprevents code from unexpectedly blocking.
Evaluating a queryset with select_for_update() in autocommit mode on\nbackends which support SELECT ... FOR UPDATE is a\nTransactionManagementError error because the\nrows are not locked in that case. If allowed, this would facilitate data\ncorruption and could easily be caused by calling code that expects to be run in\na transaction outside of one.
Using select_for_update() on backends which do not support\nSELECT ... FOR UPDATE (such as SQLite) will have no effect.\nSELECT ... FOR UPDATE will not be added to the query, and an error isn't\nraised if select_for_update() is used in autocommit mode.
raw()Link to this heading#Takes a raw SQL query, executes it, and returns a\ndjango.db.models.query.RawQuerySet instance. This RawQuerySet instance\ncan be iterated over just like a normal QuerySet to provide object\ninstances.
See the 素の SQL 文の実行 for more information.
\n\nQuerySetsLink to this heading#Combined querysets must use the same model.
\n&)Link to this heading#Combines two QuerySets using the SQL AND operator.
The following are equivalent:
\nModel.objects.filter(x=1) & Model.objects.filter(y=2)\nModel.objects.filter(x=1, y=2)\nfrom django.db.models import Q\nModel.objects.filter(Q(x=1) & Q(y=2))\nSQL equivalent:
\nSELECT ... WHERE x=1 AND y=2\n|)Link to this heading#Combines two QuerySets using the SQL OR operator.
The following are equivalent:
\nModel.objects.filter(x=1) | Model.objects.filter(y=2)\nfrom django.db.models import Q\nModel.objects.filter(Q(x=1) | Q(y=2))\nSQL equivalent:
\nSELECT ... WHERE x=1 OR y=2\n| is not a commutative operation, as different (though equivalent) queries\nmay be generated.
^)Link to this heading#Combines two QuerySets using the SQL XOR operator.
The following are equivalent:
\nModel.objects.filter(x=1) ^ Model.objects.filter(y=2)\nfrom django.db.models import Q\nModel.objects.filter(Q(x=1) ^ Q(y=2))\nSQL equivalent:
\nSELECT ... WHERE x=1 XOR y=2\nQuerySetsLink to this heading#The following QuerySet methods evaluate the QuerySet and return\nsomething other than a QuerySet.
These methods do not use a cache (see キャッシングと QuerySet). Rather,\nthey query the database each time they're called.
\nBecause these methods evaluate the QuerySet, they are blocking calls, and so\ntheir main (synchronous) versions cannot be called from asynchronous code. For\nthis reason, each has a corresponding asynchronous version with an a prefix\n- for example, rather than get(…) you can await aget(…).
There is usually no difference in behavior apart from their asynchronous\nnature, but any differences are noted below next to each method.
\n\nget()Link to this heading#Asynchronous version: aget()
Returns the object matching the given lookup parameters, which should be in\nthe format described in Field lookups. You should use lookups that are\nguaranteed unique, such as the primary key or fields in a unique constraint.\nFor example:
\nEntry.objects.get(id=1)\nEntry.objects.get(Q(blog=blog) & Q(entry_number=1))\nIf you expect a queryset to already return one row, you can use get()\nwithout any arguments to return the object for that row:
Entry.objects.filter(pk=1).get()\nIf get() doesn't find any object, it raises a Model.DoesNotExist exception:
Entry.objects.get(id=-999) # raises Entry.DoesNotExist\nIf get() finds more than one object, it raises a\nModel.MultipleObjectsReturned exception:
Entry.objects.get(name='A Duplicated Name') # raises Entry.MultipleObjectsReturned\nBoth these exception classes are attributes of the model class, and specific to\nthat model. If you want to handle such exceptions from several get() calls\nfor different models, you can use their generic base classes. For example, you\ncan use django.core.exceptions.ObjectDoesNotExist to handle\nDoesNotExist exceptions from multiple models:
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#Asynchronous version: acreate()
A convenience method for creating an object and saving it all in one step. Thus:
\np = Person.objects.create(first_name="Bruce", last_name="Springsteen")\nand:
\np = Person(first_name="Bruce", last_name="Springsteen")\np.save(force_insert=True)\nare equivalent.
\nThe force_insert parameter is documented\nelsewhere, but all it means is that a new object will always be created.\nNormally you won't need to worry about this. However, if your model contains a\nmanual primary key value that you set and if that value already exists in the\ndatabase, a call to create() will fail with an\nIntegrityError since primary keys must be unique. Be\nprepared to handle the exception if you are using manual primary keys.
get_or_create()Link to this heading#Asynchronous version: aget_or_create()
A convenience method for looking up an object with the given kwargs (may be\nempty if your model has defaults for all fields), creating one if necessary.
(Object, created) のタプルを返します。"Object"は受け取ったものか作られたものです。そして"created"はそのObjectが作られたものかどうかのBooleanです。
\nThis is meant to prevent duplicate objects from being created when requests are\nmade in parallel, and as a shortcut to boilerplatish code. For example:
\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()\nHere, with concurrent requests, multiple attempts to save a Person with\nthe same parameters may be made. To avoid this race condition, the above\nexample can be rewritten using get_or_create() like so:
obj, created = Person.objects.get_or_create(\n first_name='John',\n last_name='Lennon',\n defaults={'birthday': date(1940, 10, 9)},\n)\nAny keyword arguments passed to get_or_create() — except an optional one\ncalled defaults — will be used in a get() call. If an object is\nfound, get_or_create() returns a tuple of that object and False.
You can specify more complex conditions for the retrieved object by chaining\nget_or_create() with filter() and using Q objects. For example, to retrieve Robert or Bob Marley if either\nexists, and create the latter otherwise:
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'})\nIf multiple objects are found, get_or_create() raises\nMultipleObjectsReturned. If an object is not\nfound, get_or_create() will instantiate and save a new object, returning a\ntuple of the new object and True. The new object will be created roughly\naccording to this algorithm:
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()\nIn English, that means start with any non-'defaults' keyword argument that\ndoesn't contain a double underscore (which would indicate a non-exact lookup).\nThen add the contents of defaults, overriding any keys if necessary, and\nuse the result as the keyword arguments to the model class. If there are any\ncallables in defaults, evaluate them. As hinted at above, this is a\nsimplification of the algorithm that is used, but it contains all the pertinent\ndetails. The internal implementation has some more error-checking than this and\nhandles some extra edge-conditions; if you're interested, read the code.
If you have a field named defaults and want to use it as an exact lookup in\nget_or_create(), use 'defaults__exact', like so:
Foo.objects.get_or_create(defaults__exact='bar', defaults={'defaults': 'baz'})\nThe get_or_create() method has similar error behavior to create()\nwhen you're using manually specified primary keys. If an object needs to be\ncreated and the key already exists in the database, an\nIntegrityError will be raised.
Finally, a word on using get_or_create() in Django views. Please make sure\nto use it only in POST requests unless you have a good reason not to.\nGET requests shouldn't have any effect on data. Instead, use POST\nwhenever a request to a page has a side effect on your data. For more, see\nSafe methods in the HTTP spec.
update_or_create()Link to this heading#Asynchronous version: aupdate_or_create()
A convenience method for updating an object with the given kwargs, creating\na new one if necessary. The defaults is a dictionary of (field, value)\npairs used to update the object. The values in defaults can be callables.
(Object, created) のタプルを返します。"Object"は受け取ったものか更新したものです。そして"created"はそのObjectが更新されたものかどうかのBooleanです。
\nThe update_or_create method tries to fetch an object from database based on\nthe given kwargs. If a match is found, it updates the fields passed in the\ndefaults dictionary.
これは手っ取り早い定型的なコードです。例えば:
\ndefaults = {'first_name': 'Bob'}\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(defaults)\n obj = Person(**new_values)\n obj.save()\nThis pattern gets quite unwieldy as the number of fields in a model goes up.\nThe above example can be rewritten using update_or_create() like so:
obj, created = Person.objects.update_or_create(\n first_name='John', last_name='Lennon',\n defaults={'first_name': 'Bob'},\n)\nFor a detailed description of how names passed in kwargs are resolved, see\nget_or_create().
As described above in get_or_create(), this method is prone to a\nrace-condition which can result in multiple rows being inserted simultaneously\nif uniqueness is not enforced at the database level.
Like get_or_create() and create(), if you're using manually\nspecified primary keys and an object needs to be created but the key already\nexists in the database, an IntegrityError is raised.
bulk_create()Link to this heading#Asynchronous version: abulk_create()
This method inserts the provided list of objects into the database in an\nefficient manner (generally only 1 query, no matter how many objects there\nare), and returns created objects as a list, in the same order as provided:
\n>>> objs = Entry.objects.bulk_create([\n... Entry(headline='This is a test'),\n... Entry(headline='This is only a test'),\n... ])\nThis has a number of caveats though:
\nThe model's save() method will not be called, and the pre_save and\npost_save signals will not be sent.
It does not work with child models in a multi-table inheritance scenario.
If the model's primary key is an AutoField, the\nprimary key attribute can only be retrieved on certain databases (currently\nPostgreSQL, MariaDB 10.5+, and SQLite 3.35+). On other databases, it will not\nbe set.
It does not work with many-to-many relationships.
It casts objs to a list, which fully evaluates objs if it's a\ngenerator. The cast allows inspecting all objects so that any objects with a\nmanually set primary key can be inserted first. If you want to insert objects\nin batches without evaluating the entire generator at once, you can use this\ntechnique as long as the objects don't have any manually set primary keys:
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)\nThe batch_size parameter controls how many objects are created in a single\nquery. The default is to create all objects in one batch, except for SQLite\nwhere the default is such that at most 999 variables per query are used.
On databases that support it (all but Oracle), setting the ignore_conflicts\nparameter to True tells the database to ignore failure to insert any rows\nthat fail constraints such as duplicate unique values.
On databases that support it (all except Oracle and SQLite < 3.24), setting the\nupdate_conflicts parameter to True, tells the database to update\nupdate_fields when a row insertion fails on conflicts. On PostgreSQL and\nSQLite, in addition to update_fields, a list of unique_fields that may\nbe in conflict must be provided.
Enabling the ignore_conflicts or update_conflicts parameter disable\nsetting the primary key on each model instance (if the database normally\nsupport it).
bulk_update()Link to this heading#Asynchronous version: abulk_update()
This method efficiently updates the given fields on the provided model\ninstances, generally with one query, and returns the number of objects\nupdated:
\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() is used to save the changes, so this is more efficient\nthan iterating through the list of models and calling save() on each of\nthem, but it has a few caveats:
You cannot update the model's primary key.
Each model's save() method isn't called, and the\npre_save and\npost_save signals aren't sent.
If updating a large number of columns in a large number of rows, the SQL\ngenerated can be very large. Avoid this by specifying a suitable\nbatch_size.
Updating fields defined on multi-table inheritance ancestors will incur an\nextra query per ancestor.
When an individual batch contains duplicates, only the first instance in that\nbatch will result in an update.
The number of objects updated returned by the function may be fewer than the\nnumber of objects passed in. This can be due to duplicate objects passed in\nwhich are updated in the same batch or race conditions such that objects are\nno longer present in the database.
The batch_size parameter controls how many objects are saved in a single\nquery. The default is to update all objects in one batch, except for SQLite\nand Oracle which have restrictions on the number of variables used in a query.
count()Link to this heading#Asynchronous version: acount()
Returns an integer representing the number of objects in the database matching\nthe 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()\nA count() call performs a SELECT COUNT(*) behind the scenes, so you\nshould always use count() rather than loading all of the record into Python\nobjects and calling len() on the result (unless you need to load the\nobjects into memory anyway, in which case len() will be faster).
Note that if you want the number of items in a QuerySet and are also\nretrieving model instances from it (for example, by iterating over it), it's\nprobably more efficient to use len(queryset) which won't cause an extra\ndatabase query like count() would.
If the queryset has already been fully retrieved, count() will use that\nlength rather than perform an extra database query.
in_bulk()Link to this heading#Asynchronous version: ain_bulk()
Takes a list of field values (id_list) and the field_name for those\nvalues, and returns a dictionary mapping each value to an instance of the\nobject with the given field value. No\ndjango.core.exceptions.ObjectDoesNotExist exceptions will ever be raised\nby in_bulk; that is, any id_list value not matching any instance will\nsimply be ignored. If id_list isn't provided, all objects\nin the queryset are returned. field_name must be a unique field or a\ndistinct field (if there's only one field specified in distinct()).\nfield_name defaults to the primary key.
実装例:
\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>}\nIf you pass in_bulk() an empty list, you'll get an empty dictionary.
iterator()Link to this heading#Asynchronous version: aiterator()
Evaluates the QuerySet (by performing the query) and returns an iterator\n(see PEP 234) over the results, or an asynchronous iterator (see PEP 492)\nif you call its asynchronous version aiterator.
A QuerySet typically caches its results internally so that repeated\nevaluations do not result in additional queries. In contrast, iterator()\nwill read results directly, without doing any caching at the QuerySet level\n(internally, the default iterator calls iterator() and caches the return\nvalue). For a QuerySet which returns a large number of objects that you\nonly need to access once, this can result in better performance and a\nsignificant reduction in memory.
Note that using iterator() on a QuerySet which has already been\nevaluated will force it to evaluate again, repeating the query.
iterator() is compatible with previous calls to prefetch_related() as\nlong as chunk_size is given. Larger values will necessitate fewer queries\nto accomplish the prefetching at the cost of greater memory usage.
On some databases (e.g. Oracle, SQLite), the maximum number\nof terms in an SQL IN clause might be limited. Hence values below this\nlimit should be used. (In particular, when prefetching across two or more\nrelations, a chunk_size should be small enough that the anticipated number\nof results for each prefetched relation still falls below the limit.)
So long as the QuerySet does not prefetch any related objects, providing no\nvalue for chunk_size will result in Django using an implicit default of\n2000.
Depending on the database backend, query results will either be loaded all at\nonce or streamed from the database using server-side cursors.
\n\n\nOracle and PostgreSQL use server-side\ncursors to stream results from the database without loading the entire result\nset into memory.
\nThe Oracle database driver always uses server-side cursors.
\nWith server-side cursors, the chunk_size parameter specifies the number of\nresults to cache at the database driver level. Fetching bigger chunks\ndiminishes the number of round trips between the database driver and the\ndatabase, at the expense of memory.
On PostgreSQL, server-side cursors will only be used when the\nDISABLE_SERVER_SIDE_CURSORS\nsetting is False. Read Transaction pooling and server-side cursors if\nyou're using a connection pooler configured in transaction pooling mode. When\nserver-side cursors are disabled, the behavior is the same as databases that\ndon't support server-side cursors.
MySQL doesn't support streaming results, hence the Python database driver loads\nthe entire result set into memory. The result set is then transformed into\nPython row objects by the database adapter using the fetchmany() method\ndefined in PEP 249.
SQLite can fetch results in batches using fetchmany(), but since SQLite\ndoesn't provide isolation between queries within a connection, be careful when\nwriting to the table being iterated over. See Isolation when using QuerySet.iterator() for\nmore information.
The chunk_size parameter controls the size of batches Django retrieves from\nthe database driver. Larger batches decrease the overhead of communicating with\nthe database driver at the expense of a slight increase in memory consumption.
So long as the QuerySet does not prefetch any related objects, providing no\nvalue for chunk_size will result in Django using an implicit default of\n2000, a value derived from a calculation on the psycopg mailing list:
\n\nAssuming rows of 10-20 columns with a mix of textual and numeric data, 2000\nis going to fetch less than 100KB of data, which seems a good compromise\nbetween the number of rows transferred and the data discarded if the loop\nis exited early.
\n
latest()Link to this heading#Asynchronous version: alatest()
Returns the latest object in the table based on the given field(s).
\nThis example returns the latest Entry in the table, according to the\npub_date field:
Entry.objects.latest('pub_date')\nYou can also choose the latest based on several fields. For example, to select\nthe Entry with the earliest expire_date when two entries have the same\npub_date:
Entry.objects.latest('pub_date', '-expire_date')\nThe negative sign in '-expire_date' means to sort expire_date in\ndescending order. Since latest() gets the last result, the Entry with\nthe earliest expire_date is selected.
If your model's Meta specifies\nget_latest_by, you can omit any arguments to\nearliest() or latest(). The fields specified in\nget_latest_by will be used by default.
Like get(), earliest() and latest() raise\nDoesNotExist if there is no object with the\ngiven parameters.
Note that earliest() and latest() exist purely for convenience and\nreadability.
earliest()Link to this heading#Asynchronous version: aearliest()
Works otherwise like latest() except\nthe direction is changed.
first()Link to this heading#Asynchronous version: afirst()
Returns the first object matched by the queryset, or None if there\nis no matching object. If the QuerySet has no ordering defined, then the\nqueryset is automatically ordered by the primary key. This can affect\naggregation results as described in Interaction with order_by().
実装例:
\np = Article.objects.order_by('title', 'pub_date').first()\nNote that first() is a convenience method, the following code sample is\nequivalent to the above example:
try:\n p = Article.objects.order_by('title', 'pub_date')[0]\nexcept IndexError:\n p = None\nlast()Link to this heading#Asynchronous version: alast()
Works like first(), but returns the last object in the queryset.
aggregate()Link to this heading#Asynchronous version: aaggregate()
Returns a dictionary of aggregate values (averages, sums, etc.) calculated over\nthe QuerySet. Each argument to aggregate() specifies a value that will\nbe included in the dictionary that is returned.
The aggregation functions that are provided by Django are described in\nAggregation Functions below. Since aggregates are also query\nexpressions, you may combine aggregates with other\naggregates or values to create complex aggregates.
\nAggregates specified using keyword arguments will use the keyword as the name\nfor the annotation. Anonymous arguments will have a name generated for them\nbased upon the name of the aggregate function and the model field that is being\naggregated. Complex aggregates cannot use anonymous arguments and must specify\na keyword argument as an alias.
\nFor example, when you are working with blog entries, you may want to know the\nnumber of authors that have contributed blog entries:
\n>>> from django.db.models import Count\n>>> q = Blog.objects.aggregate(Count('entry'))\n{'entry__count': 16}\nBy using a keyword argument to specify the aggregate function, you can\ncontrol the name of the aggregation value that is returned:
\n>>> q = Blog.objects.aggregate(number_of_entries=Count('entry'))\n{'number_of_entries': 16}\n集計処理についての深い議論については、 the topic guide on Aggregation を確認してください。
\n\nexists()Link to this heading#Asynchronous version: aexists()
Returns True if the QuerySet contains any results, and False\nif not. This tries to perform the query in the simplest and fastest way\npossible, but it does execute nearly the same query as a normal\nQuerySet query.
exists() is useful for searches relating to the existence of\nany objects in a QuerySet, particularly in the context of a large\nQuerySet.
To find whether a queryset contains any items:
\nif some_queryset.exists():\n print("There is at least one object in some_queryset")\nWhich will be faster than:
\nif some_queryset:\n print("There is at least one object in some_queryset")\n... but not by a large degree (hence needing a large queryset for efficiency\ngains).
\nAdditionally, if a some_queryset has not yet been evaluated, but you know\nthat it will be at some point, then using some_queryset.exists() will do\nmore overall work (one query for the existence check plus an extra one to later\nretrieve the results) than using bool(some_queryset), which retrieves the\nresults and then checks if any were returned.
contains()Link to this heading#Asynchronous version: acontains()
Returns True if the QuerySet contains obj, and False if\nnot. This tries to perform the query in the simplest and fastest way possible.
contains() is useful for checking an object membership in a\nQuerySet, particularly in the context of a large QuerySet.
To check whether a queryset contains a specific item:
\nif some_queryset.contains(obj):\n print('Entry contained in queryset')\nThis will be faster than the following which requires evaluating and iterating\nthrough the entire queryset:
\nif obj in some_queryset:\n print('Entry contained in queryset')\nLike exists(), if some_queryset has not yet been evaluated, but you\nknow that it will be at some point, then using some_queryset.contains(obj)\nwill make an additional database query, generally resulting in slower overall\nperformance.
update()Link to this heading#Asynchronous version: aupdate()
Performs an SQL update query for the specified fields, and returns\nthe number of rows matched (which may not be equal to the number of rows\nupdated if some rows already have the new value).
\nFor example, to turn comments off for all blog entries published in 2010,\nyou could do this:
\n>>> Entry.objects.filter(pub_date__year=2010).update(comments_on=False)\n(This assumes your Entry model has fields pub_date and comments_on.)
You can update multiple fields — there's no limit on how many. For example,\nhere we update the comments_on and headline fields:
>>> Entry.objects.filter(pub_date__year=2010).update(comments_on=False, headline='This is old')\nThe update() method is applied instantly, and the only restriction on the\nQuerySet that is updated is that it can only update columns in the\nmodel's main table, not on related models. You can't do this, for example:
>>> Entry.objects.update(blog__name='foo') # Won't work!\nFiltering based on related fields is still possible, though:
\n>>> Entry.objects.filter(blog__id=1).update(comments_on=True)\nYou cannot call update() on a QuerySet that has had a slice taken\nor can otherwise no longer be filtered.
The update() method returns the number of affected rows:
>>> 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\nIf you're just updating a record and don't need to do anything with the model\nobject, the most efficient approach is to call update(), rather than\nloading the model object into memory. For example, instead of doing this:
e = Entry.objects.get(id=10)\ne.comments_on = False\ne.save()\n...do this:
\nEntry.objects.filter(id=10).update(comments_on=False)\nUsing update() also prevents a race condition wherein something might\nchange in your database in the short period of time between loading the object\nand calling save().
Finally, realize that update() does an update at the SQL level and, thus,\ndoes not call any save() methods on your models, nor does it emit the\npre_save or\npost_save signals (which are a consequence of\ncalling Model.save()). If you want to\nupdate a bunch of records for a model that has a custom\nsave() method, loop over them and call\nsave(), like this:
for e in Entry.objects.filter(pub_date__year=2010):\n e.comments_on = False\n e.save()\nChaining order_by() with update() is supported only on MariaDB and\nMySQL, and is ignored for different databases. This is useful for updating a\nunique field in the order that is specified without conflicts. For example:
Entry.objects.order_by('-number').update(number=F('number') + 1)\ndelete()Link to this heading#Asynchronous version: adelete()
Performs an SQL delete query on all rows in the QuerySet and\nreturns the number of objects deleted and a dictionary with the number of\ndeletions per object type.
The delete() is applied instantly. You cannot call delete() on a\nQuerySet that has had a slice taken or can otherwise no longer be\nfiltered.
For example, to delete all the entries in a particular blog:
\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})\nBy default, Django's ForeignKey emulates the SQL\nconstraint ON DELETE CASCADE — in other words, any objects with foreign\nkeys pointing at the objects to be deleted will be deleted along with them.\nFor example:
>>> 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 属性によってカスタマイズできます。
The delete() method does a bulk delete and does not call any delete()\nmethods on your models. It does, however, emit the\npre_delete and\npost_delete signals for all deleted objects\n(including cascaded deletions).
Django needs to fetch objects into memory to send signals and handle cascades.\nHowever, if there are no cascades and no signals, then Django may take a\nfast-path and delete objects without fetching into memory. For large\ndeletes this can result in significantly reduced memory usage. The amount of\nexecuted queries can be reduced, too.
\nForeignKeys which are set to on_delete\nDO_NOTHING do not prevent taking the fast-path in deletion.
Note that the queries generated in object deletion is an implementation\ndetail subject to change.
\n\nas_manager()Link to this heading#Class method that returns an instance of Manager\nwith a copy of the QuerySet’s methods. See\nQuerySet のメソッドで、マネージャを生成する for more details.
Note that unlike the other entries in this section, this does not have an\nasynchronous variant as it does not execute a query.
\nexplain()Link to this heading#Asynchronous version: aexplain()
Returns a string of the QuerySet’s execution plan, which details how the\ndatabase would execute the query, including any indexes or joins that would be\nused. Knowing these details may help you improve the performance of slow\nqueries.
For example, when using 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)\nThe output differs significantly between databases.
\nexplain() is supported by all built-in database backends except Oracle\nbecause an implementation there isn't straightforward.
The format parameter changes the output format from the databases's\ndefault, which is usually text-based. PostgreSQL supports 'TEXT',\n'JSON', 'YAML', and 'XML' formats. MariaDB and MySQL support\n'TEXT' (also called 'TRADITIONAL') and 'JSON' formats. MySQL\n8.0.16+ also supports an improved 'TREE' format, which is similar to\nPostgreSQL's 'TEXT' output and is used by default, if supported.
Some databases accept flags that can return more information about the query.\nPass these flags as keyword arguments. For example, when using 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\nOn some databases, flags may cause the query to be executed which could have\nadverse effects on your database. For example, the ANALYZE flag supported\nby MariaDB, MySQL 8.0.18+, and PostgreSQL could result in changes to data if\nthere are triggers or if a function is called, even for a SELECT query.
Field lookupsLink to this heading#Field lookups are how you specify the meat of an SQL WHERE clause. They're\nspecified as keyword arguments to the QuerySet methods filter(),\nexclude() and get().
For an introduction, see models and database queries documentation.
\nDjango's built-in lookups are listed below. It is also possible to write\ncustom lookups for model fields.
\nAs a convenience when no lookup type is provided (like in\nEntry.objects.get(id=14)) the lookup type is assumed to be exact.
exactLink to this heading#Exact match. If the value provided for comparison is None, it will be\ninterpreted as an SQL NULL (see isnull for more details).
例:
\nEntry.objects.get(id__exact=14)\nEntry.objects.get(id__exact=None)\nSQL equivalents:
\nSELECT ... WHERE id = 14;\nSELECT ... WHERE id IS NULL;\niexactLink to this heading#Case-insensitive exact match. If the value provided for comparison is None,\nit will be interpreted as an SQL NULL (see isnull for more\ndetails).
実装例:
\nBlog.objects.get(name__iexact='beatles blog')\nBlog.objects.get(name__iexact=None)\nSQL equivalents:
\nSELECT ... WHERE name ILIKE 'beatles blog';\nSELECT ... WHERE name IS NULL;\nNote the first query will match 'Beatles Blog', 'beatles blog',\n'BeAtLes BLoG', etc.
containsLink to this heading#Case-sensitive containment test.
\n実装例:
\nEntry.objects.get(headline__contains='Lennon')\nSQL equivalent:
\nSELECT ... WHERE headline LIKE '%Lennon%';\nNote this will match the headline 'Lennon honored today' but not 'lennon\nhonored today'.
icontainsLink to this heading#Case-insensitive containment test.
\n実装例:
\nEntry.objects.get(headline__icontains='Lennon')\nSQL equivalent:
\nSELECT ... WHERE headline ILIKE '%Lennon%';\ninLink to this heading#In a given iterable; often a list, tuple, or queryset. It's not a common use\ncase, but strings (being iterables) are accepted.
\n例:
\nEntry.objects.filter(id__in=[1, 3, 4])\nEntry.objects.filter(headline__in='abc')\nSQL equivalents:
\nSELECT ... WHERE id IN (1, 3, 4);\nSELECT ... WHERE headline IN ('a', 'b', 'c');\nYou can also use a queryset to dynamically evaluate the list of values\ninstead of providing a list of literal values:
\ninner_qs = Blog.objects.filter(name__contains='Cheddar')\nentries = Entry.objects.filter(blog__in=inner_qs)\nThis queryset will be evaluated as subselect statement:
\nSELECT ... WHERE blog.id IN (SELECT id FROM ... WHERE NAME LIKE '%Cheddar%')\nIf you pass in a QuerySet resulting from values() or values_list()\nas the value to an __in lookup, you need to ensure you are only extracting\none field in the result. For example, this will work (filtering on the blog\nnames):
inner_qs = Blog.objects.filter(name__contains='Ch').values('name')\nentries = Entry.objects.filter(blog__name__in=inner_qs)\nThis example will raise an exception, since the inner query is trying to\nextract two field values, where only one is expected:
\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)\nSQL equivalent:
\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 or equal to.
\nstartswithLink to this heading#Case-sensitive starts-with.
\n実装例:
\nEntry.objects.filter(headline__startswith='Lennon')\nSQL equivalent:
\nSELECT ... WHERE headline LIKE 'Lennon%';\nSQLite doesn't support case-sensitive LIKE statements; startswith acts\nlike istartswith for SQLite.
istartswithLink to this heading#Case-insensitive starts-with.
\n実装例:
\nEntry.objects.filter(headline__istartswith='Lennon')\nSQL equivalent:
\nSELECT ... WHERE headline ILIKE 'Lennon%';\nendswithLink to this heading#Case-sensitive ends-with.
\n実装例:
\nEntry.objects.filter(headline__endswith='Lennon')\nSQL equivalent:
\nSELECT ... WHERE headline LIKE '%Lennon';\niendswithLink to this heading#Case-insensitive ends-with.
\n実装例:
\nEntry.objects.filter(headline__iendswith='Lennon')\nSQL equivalent:
\nSELECT ... WHERE headline ILIKE '%Lennon'\nrangeLink to this heading#Range test (inclusive).
\n実装例:
\nimport datetime\nstart_date = datetime.date(2005, 1, 1)\nend_date = datetime.date(2005, 3, 31)\nEntry.objects.filter(pub_date__range=(start_date, end_date))\nSQL equivalent:
\nSELECT ... WHERE pub_date BETWEEN '2005-01-01' and '2005-03-31';\nYou can use range anywhere you can use BETWEEN in SQL — for dates,\nnumbers and even characters.
dateLink to this heading#For datetime fields, casts the value as date. Allows chaining additional field\nlookups. Takes a date value.
\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(No equivalent SQL code fragment is included for this lookup because\nimplementation of the relevant query varies among different database engines.)
\nWhen USE_TZ is True, fields are converted to the current time\nzone before filtering. This requires time zone definitions in the\ndatabase.
yearLink to this heading#For date and datetime fields, an exact year match. Allows chaining additional\nfield lookups. Takes an integer year.
\n実装例:
\nEntry.objects.filter(pub_date__year=2005)\nEntry.objects.filter(pub_date__year__gte=2005)\nSQL equivalent:
\nSELECT ... WHERE pub_date BETWEEN '2005-01-01' AND '2005-12-31';\nSELECT ... WHERE pub_date >= '2005-01-01';\n(The exact SQL syntax varies for each database engine.)
\nWhen USE_TZ is True, datetime fields are converted to the\ncurrent time zone before filtering. This requires time zone definitions\nin the database.
iso_yearLink to this heading#For date and datetime fields, an exact ISO 8601 week-numbering year match.\nAllows chaining additional field lookups. Takes an integer year.
\n実装例:
\nEntry.objects.filter(pub_date__iso_year=2005)\nEntry.objects.filter(pub_date__iso_year__gte=2005)\n(The exact SQL syntax varies for each database engine.)
\nWhen USE_TZ is True, datetime fields are converted to the\ncurrent time zone before filtering. This requires time zone definitions\nin the database.
monthLink to this heading#For date and datetime fields, an exact month match. Allows chaining additional\nfield lookups. Takes an integer 1 (January) through 12 (December).
\n実装例:
\nEntry.objects.filter(pub_date__month=12)\nEntry.objects.filter(pub_date__month__gte=6)\nSQL equivalent:
\nSELECT ... WHERE EXTRACT('month' FROM pub_date) = '12';\nSELECT ... WHERE EXTRACT('month' FROM pub_date) >= '6';\n(The exact SQL syntax varies for each database engine.)
\nWhen USE_TZ is True, datetime fields are converted to the\ncurrent time zone before filtering. This requires time zone definitions\nin the database.
dayLink to this heading#For date and datetime fields, an exact day match. Allows chaining additional\nfield lookups. Takes an integer day.
\n実装例:
\nEntry.objects.filter(pub_date__day=3)\nEntry.objects.filter(pub_date__day__gte=3)\nSQL equivalent:
\nSELECT ... WHERE EXTRACT('day' FROM pub_date) = '3';\nSELECT ... WHERE EXTRACT('day' FROM pub_date) >= '3';\n(The exact SQL syntax varies for each database engine.)
\nNote this will match any record with a pub_date on the third day of the month,\nsuch as January 3, July 3, etc.
\nWhen USE_TZ is True, datetime fields are converted to the\ncurrent time zone before filtering. This requires time zone definitions\nin the database.
weekLink to this heading#For date and datetime fields, return the week number (1-52 or 53) according\nto ISO-8601, i.e., weeks start\non a Monday and the first week contains the year's first Thursday.
\n実装例:
\nEntry.objects.filter(pub_date__week=52)\nEntry.objects.filter(pub_date__week__gte=32, pub_date__week__lte=38)\n(No equivalent SQL code fragment is included for this lookup because\nimplementation of the relevant query varies among different database engines.)
\nWhen USE_TZ is True, datetime fields are converted to the\ncurrent time zone before filtering. This requires time zone definitions\nin the database.
week_dayLink to this heading#For date and datetime fields, a 'day of the week' match. Allows chaining\nadditional field lookups.
\nTakes an integer value representing the day of week from 1 (Sunday) to 7\n(Saturday).
\n実装例:
\nEntry.objects.filter(pub_date__week_day=2)\nEntry.objects.filter(pub_date__week_day__gte=2)\n(No equivalent SQL code fragment is included for this lookup because\nimplementation of the relevant query varies among different database engines.)
\nNote this will match any record with a pub_date that falls on a Monday (day\n2 of the week), regardless of the month or year in which it occurs. Week days\nare indexed with day 1 being Sunday and day 7 being Saturday.
When USE_TZ is True, datetime fields are converted to the\ncurrent time zone before filtering. This requires time zone definitions\nin the database.
iso_week_dayLink to this heading#For date and datetime fields, an exact ISO 8601 day of the week match. Allows\nchaining additional field lookups.
\nTakes an integer value representing the day of the week from 1 (Monday) to 7\n(Sunday).
\n実装例:
\nEntry.objects.filter(pub_date__iso_week_day=1)\nEntry.objects.filter(pub_date__iso_week_day__gte=1)\n(No equivalent SQL code fragment is included for this lookup because\nimplementation of the relevant query varies among different database engines.)
\nNote this will match any record with a pub_date that falls on a Monday (day\n1 of the week), regardless of the month or year in which it occurs. Week days\nare indexed with day 1 being Monday and day 7 being Sunday.
When USE_TZ is True, datetime fields are converted to the\ncurrent time zone before filtering. This requires time zone definitions\nin the database.
quarterLink to this heading#For date and datetime fields, a 'quarter of the year' match. Allows chaining\nadditional field lookups. Takes an integer value between 1 and 4 representing\nthe quarter of the year.
\nExample to retrieve entries in the second quarter (April 1 to June 30):
\nEntry.objects.filter(pub_date__quarter=2)\n(No equivalent SQL code fragment is included for this lookup because\nimplementation of the relevant query varies among different database engines.)
\nWhen USE_TZ is True, datetime fields are converted to the\ncurrent time zone before filtering. This requires time zone definitions\nin the database.
timeLink to this heading#For datetime fields, casts the value as time. Allows chaining additional field\nlookups. Takes a datetime.time value.
実装例:
\nEntry.objects.filter(pub_date__time=datetime.time(14, 30))\nEntry.objects.filter(pub_date__time__range=(datetime.time(8), datetime.time(17)))\n(No equivalent SQL code fragment is included for this lookup because\nimplementation of the relevant query varies among different database engines.)
\nWhen USE_TZ is True, fields are converted to the current time\nzone before filtering. This requires time zone definitions in the\ndatabase.
hourLink to this heading#For datetime and time fields, an exact hour match. Allows chaining additional\nfield lookups. Takes an integer between 0 and 23.
\n実装例:
\nEvent.objects.filter(timestamp__hour=23)\nEvent.objects.filter(time__hour=5)\nEvent.objects.filter(timestamp__hour__gte=12)\nSQL equivalent:
\nSELECT ... WHERE EXTRACT('hour' FROM timestamp) = '23';\nSELECT ... WHERE EXTRACT('hour' FROM time) = '5';\nSELECT ... WHERE EXTRACT('hour' FROM timestamp) >= '12';\n(The exact SQL syntax varies for each database engine.)
\nWhen USE_TZ is True, datetime fields are converted to the\ncurrent time zone before filtering. This requires time zone definitions\nin the database.
minuteLink to this heading#For datetime and time fields, an exact minute match. Allows chaining additional\nfield lookups. Takes an integer between 0 and 59.
\n実装例:
\nEvent.objects.filter(timestamp__minute=29)\nEvent.objects.filter(time__minute=46)\nEvent.objects.filter(timestamp__minute__gte=29)\nSQL equivalent:
\nSELECT ... WHERE EXTRACT('minute' FROM timestamp) = '29';\nSELECT ... WHERE EXTRACT('minute' FROM time) = '46';\nSELECT ... WHERE EXTRACT('minute' FROM timestamp) >= '29';\n(The exact SQL syntax varies for each database engine.)
\nWhen USE_TZ is True, datetime fields are converted to the\ncurrent time zone before filtering. This requires time zone definitions\nin the database.
secondLink to this heading#For datetime and time fields, an exact second match. Allows chaining additional\nfield lookups. Takes an integer between 0 and 59.
\n実装例:
\nEvent.objects.filter(timestamp__second=31)\nEvent.objects.filter(time__second=2)\nEvent.objects.filter(timestamp__second__gte=31)\nSQL equivalent:
\nSELECT ... WHERE EXTRACT('second' FROM timestamp) = '31';\nSELECT ... WHERE EXTRACT('second' FROM time) = '2';\nSELECT ... WHERE EXTRACT('second' FROM timestamp) >= '31';\n(The exact SQL syntax varies for each database engine.)
\nWhen USE_TZ is True, datetime fields are converted to the\ncurrent time zone before filtering. This requires time zone definitions\nin the database.
isnullLink to this heading#Takes either True or False, which correspond to SQL queries of\nIS NULL and IS NOT NULL, respectively.
実装例:
\nEntry.objects.filter(pub_date__isnull=True)\nSQL equivalent:
\nSELECT ... WHERE pub_date IS NULL;\nregexLink to this heading#Case-sensitive regular expression match.
\nThe regular expression syntax is that of the database backend in use.\nIn the case of SQLite, which has no built in regular expression support,\nthis feature is provided by a (Python) user-defined REGEXP function, and\nthe regular expression syntax is therefore that of Python's re module.
実装例:
\nEntry.objects.get(title__regex=r'^(An?|The) +')\nSQL equivalents:
\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\nUsing raw strings (e.g., r'foo' instead of 'foo') for passing in the\nregular expression syntax is recommended.
iregexLink to this heading#Case-insensitive regular expression match.
\n実装例:
\nEntry.objects.get(title__iregex=r'^(an?|the) +')\nSQL equivalents:
\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 provides the following aggregation functions in the\ndjango.db.models module. For details on how to use these\naggregate functions, see the topic guide on aggregation. See the Aggregate\ndocumentation to learn how to create your aggregates.
All aggregates have the following parameters in common:
\nexpressionsLink to this heading#Strings that reference fields on the model, transforms of the field, or\nquery expressions.
\noutput_fieldLink to this heading#An optional argument that represents the model field\nof the return value
\n\nfilterLink to this heading#An optional Q object that's used to filter the\nrows that are aggregated.
See Conditional aggregation and Filtering on annotations for\nexample usage.
\ndefaultLink to this heading#An optional argument that allows specifying a value to use as a default value\nwhen the queryset (or grouping) contains no entries.
\n**extraLink to this heading#Keyword arguments that can provide extra context for the SQL generated\nby the aggregate.
\nAvgLink to this heading#Returns the mean value of the given expression, which must be numeric\nunless you specify a different output_field.
Default alias: <field>__avg
Return type: float if input is int, otherwise same as input\nfield, or output_field if supplied
Optional. If distinct=True, Avg returns the mean value of\nunique values. This is the SQL equivalent of AVG(DISTINCT <field>).\nThe default value is False.
CountLink to this heading#Returns the number of objects that are related through the provided\nexpression.
\nDefault alias: <field>__count
Return type: int
Optional. If distinct=True, the count will only include unique\ninstances. This is the SQL equivalent of COUNT(DISTINCT <field>).\nThe default value is False.
MaxLink to this heading#Returns the maximum value of the given expression.
\nDefault alias: <field>__max
Return type: same as input field, or output_field if supplied
MinLink to this heading#Returns the minimum value of the given expression.
\nDefault alias: <field>__min
Return type: same as input field, or output_field if supplied
StdDevLink to this heading#Returns the standard deviation of the data in the provided expression.
\nDefault alias: <field>__stddev
Return type: float if input is int, otherwise same as input\nfield, or output_field if supplied
Optional. By default, StdDev returns the population standard\ndeviation. However, if sample=True, the return value will be the\nsample standard deviation.
SumLink to this heading#Computes the sum of all values of the given expression.
\nDefault alias: <field>__sum
Return type: same as input field, or output_field if supplied
Optional. If distinct=True, Sum returns the sum of unique\nvalues. This is the SQL equivalent of SUM(DISTINCT <field>). The\ndefault value is False.
VarianceLink to this heading#Returns the variance of the data in the provided expression.
\nDefault alias: <field>__variance
Return type: float if input is int, otherwise same as input\nfield, or output_field if supplied
Optional. By default, Variance returns the population variance.\nHowever, if sample=True, the return value will be the sample\nvariance.