一度 データモデル を作成すれば、Django はデータオブジェクトの作成、取得、更新および削除を行えるようにデータベースを抽象化した API を自動的に提供します。本ドキュメントではこの API をどのように用いるかを説明します。多様なモデル探索オプション全てに関する詳細については データモデルの項目 を参照ください。
\nこのガイド（およびリファレンス）全体を通して、以下のモデルを参照します。これらはブログアプリケーションを構成するものです。
\nfrom datetime import date\n\nfrom django.db import models\n\n\nclass Blog(models.Model):\n name = models.CharField(max_length=100)\n tagline = models.TextField()\n\n def __str__(self):\n return self.name\n\n\nclass Author(models.Model):\n name = models.CharField(max_length=200)\n email = models.EmailField()\n\n def __str__(self):\n return self.name\n\n\nclass Entry(models.Model):\n blog = models.ForeignKey(Blog, on_delete=models.CASCADE)\n headline = models.CharField(max_length=255)\n body_text = models.TextField()\n pub_date = models.DateField()\n mod_date = models.DateField(default=date.today)\n authors = models.ManyToManyField(Author)\n number_of_comments = models.IntegerField(default=0)\n number_of_pingbacks = models.IntegerField(default=0)\n rating = models.IntegerField(default=5)\n\n def __str__(self):\n return self.headline\nDjangoでは、データベースのテーブルデータをPythonオブジェクトで表現するために、直感的な仕組みを採用しています。モデルクラスはデータベースのテーブルを表し、そのクラスのインスタンスはデータベーステーブル内の特定のレコードを表します。
\nオブジェクトを生成するためには、作成するモデルのクラスにキーワード引数を渡してインスタンス化し、そのデータをデータベースに保存するために save() を呼び出します。
以下はモデルがDjangoアプリ blog 内の models.py ファイルに存在する場合の例です。
>>> from blog.models import Blog\n>>> b = Blog(name="Beatles Blog", tagline="All the latest Beatles news.")\n>>> b.save()\nこの例では内部で INSERT SQL 文が処理されます。明示的に save() を呼ぶまで Django はデータベースを操作しません。
save() メソッドは値を返しません。
既にデータベース上に存在する 1 つのオブジェクトに対する変更を保存するには、 save() を利用します。
すでにデータベースに保存されている Blog インスタンス b5 がある場合、この例ではその名前を変更し、データベース内のレコードを更新します:
>>> b5.name = "New name"\n>>> b5.save()\nこの例では内部で UPDATE SQL 文が処理されます。明示的に save() が呼ばれるまで Django はデータベースを操作しません。
ForeignKey と ManyToManyField フィールドを扱うLink to this heading#ForeignKey フィールドを更新するには、通常のフィールドを保存するのと全く同じように、該当のフィールドに適切なタイプのオブジェクトを割り当てます。以下の例では、 Entry インスタンス entry の blog 属性を更新しています。ここでは、 Entry と Blog の適切なインスタンスが既にデータベースに保存されていると仮定しています（したがって、以下でそれらを取得できます）。
>>> from blog.models import Blog, Entry\n>>> entry = Entry.objects.get(pk=1)\n>>> cheese_blog = Blog.objects.get(name="Cheddar Talk")\n>>> entry.blog = cheese_blog\n>>> entry.save()\nManyToManyField を更新する方法は少し異なります。関連するフィールド上の add() メソッドを使用して、リレーションにレコードを追加します。以下の例では、 Author インスタンス joe を entry オブジェクトに追加しています:
>>> from blog.models import Author\n>>> joe = Author.objects.create(name="Joe")\n>>> entry.authors.add(joe)\n複数のレコードを ManyToManyField に一気に追加するには、 add() の呼び出しに複数の引数を含めてください:
>>> john = Author.objects.create(name="John")\n>>> paul = Author.objects.create(name="Paul")\n>>> george = Author.objects.create(name="George")\n>>> ringo = Author.objects.create(name="Ringo")\n>>> entry.authors.add(john, paul, george, ringo)\nもし間違った型のオブジェクトを設定もしくは追加しようとすれば Django はエラーを発生させます。
\nデータベースからオブジェクトを取得するには、モデルクラスの Manager から QuerySet を作ります。
QuerySet はデータベース上のオブジェクトの集合を表しています。多数の フィルタ を持つことができます。フィルタは与えられたパラメータに基づいてクエリの検索結果を絞り込みます。SQL 文においては、 QuerySet は SELECT 句、フィルタは WHERE や LIMIT のような絞り込みに用いる句に対応しています。
モデルの QuerySet を取得するには、モデルの Manager を使用します。各モデルには少なくとも1つの Manager があり、デフォルトでは objects という名前がついています。モデルクラスから直接アクセスしてください:
>>> Blog.objects\n<django.db.models.manager.Manager object at ...>\n>>> b = Blog(name="Foo", tagline="Bar")\n>>> b.objects\nTraceback:\n ...\nAttributeError: "Manager isn't accessible via Blog instances."\nManager はモデルのクエリセットの主な取得元になります。たとえば、 Blog.objects.all() はデータベース内の Blog オブジェクト全てを含んだ QuerySet を返します。
テーブルからオブジェクトを取得する最も簡単な方法は、全てのオブジェクトを取得することです。これを行うには、 Manager の all() メソッドを使います:
>>> all_entries = Entry.objects.all()\nall() が返す QuerySet には、データベーステーブルのすべてのオブジェクトが含まれています。しかし、ふつう必要になるのはオブジェクト全体の集合ではなく、その部分集合でしょう。
そのような部分集合を作るには、条件フィルタを追加して最初の QuerySet を絞り込みます。 QuerySet を絞り込む代表的な方法として次の2つのものがあります。
filter(**kwargs)与えられたルックアップパラメータにマッチする新しい QuerySet を返します。
exclude(**kwargs)与えられたルックアップパラメータにマッチ しない 新しい QuerySet を返します。
ルックアップパラメータ (上の関数定義における **kwargs ) は、以下の Field lookups で説明するフォーマットに従わなければなりません。
たとえば、2006年以降のブログエントリーの QuerySet を取得するには、 filter() を次のように使用します。
Entry.objects.filter(pub_date__year=2006)\nデフォルトの manager クラスの場合、これは次のコードと等価です。
\nEntry.objects.all().filter(pub_date__year=2006)\nフィルタを行った QuerySet の結果自体も QuerySet です。そのため、複数のフィルタを連結することが可能です。たとえば、次のように書くことができます。
>>> Entry.objects.filter(headline__startswith="What").exclude(\n... pub_date__gte=datetime.date.today()\n... ).filter(pub_date__gte=datetime.date(2005, 1, 30))\nこれはデータベース内のすべてのエントリーを含む QuerySet をとり、フィルタを追加し、除外フィルタを追加し、さらにもう1つのフィルタを追加しています。最終的な結果は、"What" で始まるヘッドラインを持ち、2005年1月30日から今日までに公開されたすべてのエントリーを含んだ QuerySet となります。
QuerySet はユニークLink to this heading#QuerySet に対してフィルタを適用するごとに、前の QuerySet から独立した完全に新しい QuerySet が作られます。フィルタごとに独立した QuerySet が作られるため、保存したり何度も再利用したりできます。
例:
\n>>> q1 = Entry.objects.filter(headline__startswith="What")\n>>> q2 = q1.exclude(pub_date__gte=datetime.date.today())\n>>> q3 = q1.filter(pub_date__gte=datetime.date.today())\nこれら3つのクエリセットは独立しています。1番目は基本の QuerySet で、"What" で始まるヘッドラインを持つ全てのエントリーを含みます。2番めは1番目の部分集合で、 pub_date が今日または未来の日付であるレコードを除外する追加条件を持ちます。3番目も1番目の部分集合で、 pub_date が今日または未来の日付であるレコードだけを選択する追加条件を持ちます。1番目の QuerySet (q1) は、絞り込みの過程において何ら影響を受けません。
QuerySet は遅延評価されるLink to this heading#QuerySet オブジェクトは遅延評価されます。 QuerySet を作る行為はいかなるデータベース操作も引き起こしません。たとえあなたが 1 日中フィルタのスタックを積み上げたとしても、 QuerySet が 評価される までは、Django は実際にはクエリを実行しません。次の例を見てください。
>>> q = Entry.objects.filter(headline__startswith="What")\n>>> q = q.filter(pub_date__lte=datetime.date.today())\n>>> q = q.exclude(body_text__icontains="food")\n>>> print(q)\nこの例ではデータベースに3回アクセスしているように見えますが、実際にアクセスしているのは、最終行 (print(q)) での1回だけです。一般に、 QuerySet の結果は、明示的に要求するまでデータベースから取得されません。取得するように要求した時点で、 QuerySet は 評価 され、データベースへのアクセスが発生します。評価が起こる正確なタイミングの詳細については、 When QuerySets are evaluated を参照してください。
get() を使って1つのオブジェクトを取得するLink to this heading#filter() は、たとえクエリーにマッチしたのが1つのオブジェクトだけだったとしても、常に QuerySet を返します。この場合、 QuerySet には1つの要素だけが含まれることになります。
クエリーにマッチするのは1つのオブジェクトだけだと分かっている場合、 Manager の get() メソッドを呼べば、そのオブジェクトが直接返されます。
>>> one_entry = Entry.objects.get(pk=1)\nfilter() と同じように、 get() には任意のクエリー表現が使用できます。 繰り返しますが、詳しくはあとで説明する Field lookups を見てください。
get() と filter() を [0] でスライスすることには、次のような違いがあることに注意してください。クエリにマッチする結果が存在しない場合、 get() は DoesNotExist 例外を起こします。この例外はクエリーが実行されるモデルクラスの属性です。たとえば上のコードでは、1というプライマリーキーを持つ Entry オブジェクトがなければ、Django は Entry.DoesNotExist 例外を起こします。
同様に get() のクエリーが2つ以上のアイテムにマッチした場合にも、Djangoは文句を言います。この場合には、やはり同じクエリのモデルクラスの属性の MultipleObjectsReturned 例外が起こります。
QuerySet メソッドLink to this heading#データベースからオブジェクトを検索する必要がある大抵の場合は、 all(), get(), filter() および exclude() のいずれかを使うことになるでしょう。しかしこれらのメソッドだけでは不十分な場合は、さまざまな QuerySet メソッドの全リストが掲載されている QuerySet API リファレンス を参照してください。
QuerySet の要素数を制限するLink to this heading#Python のリストスライスのサブセットを使うことで QuerySet の結果を特定の要素数に制限できます。これは SQL の LIMIT と OFFSET 句に対応します。
たとえば、次のコードは最初の5つのオブジェクトを返します (LIMIT 5)。
>>> Entry.objects.all()[:5]\n次のコードは、6番目から10番目までのオブジェクトを返します (OFFSET 5 LIMIT 5)。
>>> Entry.objects.all()[5:10]\n負のインデックスには対応していません (例: Entry.objects.all()[-1])。
一般に、 QuerySet をスライスしたとしても、新しい QuerySet が返り、クエリーの評価は行われません。例外は、Python のリストスライス構文の "step" パラメーターを使用した場合です。たとえば、次のコードは実際にクエリを実行し、最初の10個のオブジェクトから一つおきにとったオブジェクトのリストを返します。
>>> Entry.objects.all()[:10:2]\nスライスされたクエリーセットのフィルタリングやソートは、動作が曖昧なため禁止されています。
\nリスト (例: SELECT foo FROM bar LIMIT 1) ではなく 1つの オブジェクトを取得するには、スライスではなくリストのインデックスを使用してください。たとえば、次のコードは、ヘッドラインでアルファベット順にソートしたあと、データベースの1番目の Entry を返します。
>>> Entry.objects.order_by("headline")[0]\n上の例は次のコードとほとんど同じです。
\n>>> Entry.objects.order_by("headline")[0:1].get()\nただし、与えられた条件を満たすオブジェクトが存在しない場合に、前者は IndexError を起こすのに対して、後者は DoesNotExist を起こすことに注意してください。詳細については get() を参照してください。
フィールドルックアップは、SQL の WHERE 句の内容を指定する手段です。 QuerySet メソッド、 filter() 、 exclude() および get() にキーワード引数として指定します。
基本のルックアップキーワード引数は field__lookuptype=value という形を取ります (2文字連続するアンダースコアです)。たとえば、
>>> Entry.objects.filter(pub_date__lte="2006-01-01")\nというコードは、(だいたい) 次の SQL 文に変換されます。
\nSELECT * FROM blog_entry WHERE pub_date <= '2006-01-01';\nルックアップに指定するフィールドはモデルが持つフィールド名でなければなりません。ただし1つだけ例外があり、 ForeignKey の場合にはフィールド名の末尾に _id を付けた名前を指定できます。その場合、value パラメータには外部モデルのプライマリーキーの生の値を書くことが期待されます。
>>> Entry.objects.filter(blog_id=4)\n無効なキーワード引数を指定すると、ルックアップ関数は TypeError を起こします。
データベース API は約30個のルックアップタイプをサポートしており、完全なガイドは フィールドルックアップのリファレンス で見ることができます。ルックアップを使って何ができるのかがよく分かるように、以下によく使う一般的なルックアップをいくつか挙げます。
\nexact完全な ("exact") マッチを行います。たとえば、
\n>>> Entry.objects.get(headline__exact="Cat bites dog")\nは次のような SQL を生成します。
\nSELECT ... WHERE headline = 'Cat bites dog';\nルックアップタイプを指定しなかった場合、つまりキーワード引数がダブルアンダースコアを含まない場合、ルックアップタイプは exact が指定されたものとみなされます。
たとえば、次の2つの文は等価です。
\n>>> Blog.objects.get(id__exact=14) # Explicit form\n>>> Blog.objects.get(id=14) # __exact is implied\nexact ルックアップが最もよく使われるため、利便性のためにこのようになっています。
iexactcase-insensitive なマッチを行います。したがって、次のクエリ
\n>>> Blog.objects.get(name__iexact="beatles blog")\nは "Beatles Blog"、 "beatles blog"、あるいは "BeAtlES blOG" というタイトルを持つ Blog にもマッチします。
containscase-sensitive な部分一致テストを行います。たとえば、
\nEntry.objects.get(headline__contains="Lennon")\nはだいたい次のような SQL に変換されます。
\nSELECT ... WHERE headline LIKE '%Lennon%';\nこの例では、ヘッドライン 'Today Lennon honored' にはマッチしても 'today lennon honored' にはマッチしないことに注意してください。
case-insensitive バージョンの icontains もあります。
startswith と endswithそれぞれ starts-with と ends-with 検索を行います。case-insensitive バージョン istartswith と iendswith もあります。
繰り返しになりますが、以上はルックアップの表面をさらったに過ぎません。完全なリファレンスは フィールドルックアップのリファレンス を参照してください。
\nDjango はルックアップの中でリレーションシップを「横断する」強力で直感的な方法を提供します。あなたのために、背後で SQL の JOIN を自動的に実行しています。リレーションシップを横断するには、使いたいフィールドにたどり着くまで、モデル間を横断する関連フィールドのフィールド名をダブルアンダースコアで繋ぎます。
次の例は、name に 'Beatles Blog' を持つ Blog のすべての Entry オブジェクトを取得します。
>>> Entry.objects.filter(blog__name="Beatles Blog")\nこの横断は好きなだけ深くすることができます。
\nIt works backwards, too. While it can be customized by setting\nrelated_query_name, by default you\nrefer to a "reverse" relationship in a lookup using the lowercase name of the\nmodel.
次の例は、少なくとも1つの headline が 'Lennon' を含む Entry を持つ、すべての Blog オブジェクトを取得します。
>>> Blog.objects.filter(entry__headline__contains="Lennon")\n複数のリレーションにまたがってフィルタリングをしていて、中間モデルのどれかが条件に合致しない場合、Django は空 (すべての値が NULL) だが有効なオブジェクトとして扱います。これは、エラーにはならないということです。たとえば以下のフィルタでは、
Blog.objects.filter(entry__authors__name="Lennon")\n（リレーションシップを持つ Author モデルがあったとして、）もしあるエントリに関連付けられた author がいなかった場合、author が無いことを理由にエラーになるのではなく、単に name が無かったかのように扱われます。通常はこれが望ましい動作です。もし混乱するとしたら、isnull を使う場合でしょう。つまり、
Blog.objects.filter(entry__authors__name__isnull=True)\nこれは、author の name が空であるような Blog オブジェクトと、entry の author が空であるような Blog オブジェクトの両方を返します。後者のオブジェクトが欲しくない場合は、次のように書きます。
Blog.objects.filter(entry__authors__isnull=False, entry__authors__name__isnull=True)\nManyToManyField や逆の ForeignKey (例えば Blog から Entry へ) をまたぐとき、複数の属性でフィルタリングを行う場合、それぞれの属性がリレーション先の同一オブジェクト内で同時に一致する必要があるのかどうかが問題になります。「2008年に公開された、見出しに “Lennon” が含まれるエントリ」を持つブログを探したいかもしれませんし、「2008年に公開されたエントリを持ち、かつ2008年より新しいか古い、見出しに “Lennon” の含まれた別のエントリを持つブログ」を探したいかも知れません。
少なくとも1つの2008年のエントリーを含み、かつそのエントリーに「Lennon」というヘッドラインが含まれている（同じエントリーが両方の条件を満たしている）ブログをすべて取得する場合、このように書きます:
\nBlog.objects.filter(entry__headline__contains="Lennon", entry__pub_date__year=2008)\n一方、ヘッドラインに「Lennon」が含まれる 何らか のエントリーと、2008年の 何らかの エントリーを持つ任意のブログを取得する寛容なクエリを実行する場合は、次のように書きます:
\nBlog.objects.filter(entry__headline__contains="Lennon").filter(\n entry__pub_date__year=2008\n)\n"Lennon " を含むエントリーと2008年のエントリーの両方を持つブログが1つだけあり、2008年のエントリーには "Lennon " が含まれていなかったとします。最初のクエリはどのブログも返しませんが、2番目のクエリはその1つのブログを返します (これは、2番目のフィルタによって選択されたエントリーが1番目のフィルタのエントリーと違っていても構わないからです。私たちはそれぞれのフィルタ文で、 Entry アイテムではなく、 Blog アイテムをフィルタしているのです)。つまり、各条件がリレーション先の同じオブジェクトにマッチする必要がある場合、それぞれを 1 つの filter() 呼び出しに含める必要があります。
今まで見てきた例では、モデルのフィールドの値を定数と比較するフィルタを作ってきました。しかし、もしモデルのフィールドの値を、同じモデルの他のフィールドと比較したい時にはどうすればいいのでしょう？
\nDjango provides F() expressions to allow such comparisons. Instances of\nF() act as a reference to a model field within a query. These references\ncan then be used in query filters to compare the values of two different fields\non the same model instance.
たとえば、pingback の数よりコメントの数のほうが多いすべてのブログエントリーのリストを検索するには、pingback の数を参照する F() オブジェクトを作り、その F() オブジェクトをクエリの中で次のように使います。
>>> from django.db.models import F\n>>> Entry.objects.filter(number_of_comments__gt=F("number_of_pingbacks"))\nDjango は F() オブジェクトを使った足し算、引き算、掛け算、割り算、モジュロ、累乗算術を、定数や他の F() オブジェクトとの両方でサポートしています。コメント数がピンバック数の 2倍 を超えるブログエントリをすべて見つけるには、このようにクエリを変更します:
>>> Entry.objects.filter(number_of_comments__gt=F("number_of_pingbacks") * 2)\nエントリーのレーティングがピンバック数とコメント数の合計より少ないエントリーをすべて見つけるには、次のようなクエリを発行します:
\n>>> Entry.objects.filter(rating__lt=F("number_of_comments") + F("number_of_pingbacks"))\nF() オブジェクトのリレーションシップに 2重アンダースコア表記を使うこともできます。 F() オブジェクトに2重アンダースコアを付けると、リレーション先オブジェクトにアクセスするために必要な結合を行うことができます。例えば、作者名がブログ名と同じすべてのエントリを取得するには、次のようなクエリを発行します:
>>> Entry.objects.filter(authors__name=F("blog__name"))\n日付と日付/時刻フィールドには、 timedelta オブジェクトを足し引きできます。次のようにすると、公開から3日以上経ってから更新されたすべてのエントリーが返されます:
>>> from datetime import timedelta\n>>> Entry.objects.filter(mod_date__gt=F("pub_date") + timedelta(days=3))\nF() オブジェクトは .bitand(), .bitor(), .bitxor(), .bitrightshift(), .bitleftshift() によるビット演算をサポートしています。例えばこのようにします:
>>> F("somefield").bitand(16)\nDjango は式でトランスフォーム（変換）を使うことをサポートしています。
\nたとえば、次のコードは最終更新年と同じ年に発行されたすべてのEntryオブジェクトを検索します:
\n>>> from django.db.models import F\n>>> Entry.objects.filter(pub_date__year=F("mod_date__year"))\n最も古い出版年を調べるには、次のクエリを実行します:
\n>>> from django.db.models import Min\n>>> Entry.objects.aggregate(first_published_year=Min("pub_date__year"))\nたとえばこの例では、各年の最高評価エントリーの値と、全エントリーに対するコメントの総数を求めています:
\n>>> from django.db.models import OuterRef, Subquery, Sum\n>>> Entry.objects.values("pub_date__year").annotate(\n... top_rating=Subquery(\n... Entry.objects.filter(\n... pub_date__year=OuterRef("pub_date__year"),\n... )\n... .order_by("-rating")\n... .values("rating")[:1]\n... ),\n... total_comments=Sum("number_of_comments"),\n... )\npk ルックアップショートカットLink to this heading#利便性のために、Django は pk ルックアップショートカットを用意しています。pk とは "primary key" を表します。
例の Blog モデルでは、主キーは id フィールドなので、次の3つの文は等価です:
>>> Blog.objects.get(id__exact=14) # Explicit form\n>>> Blog.objects.get(id=14) # __exact is implied\n>>> Blog.objects.get(pk=14) # pk implies id__exact\npk は、 __exact クエリ以外でも使えます。好きなクエリ語句を pk と組み合わせて、モデルの主キーに対するクエリを実行できます:
# Get blogs entries with id 1, 4 and 7\n>>> Blog.objects.filter(pk__in=[1, 4, 7])\n\n# Get all blog entries with id > 14\n>>> Blog.objects.filter(pk__gt=14)\npk ルックアップは結合をまたいでも動作します。たとえば、次の3つの文は等価です:
>>> Entry.objects.filter(blog__id__exact=3) # Explicit form\n>>> Entry.objects.filter(blog__id=3) # __exact is implied\n>>> Entry.objects.filter(blog__pk=3) # __pk implies __id__exact\nLIKE 文の中ではパーセント記号とアンダースコアがエスケープされるLink to this heading#LIKE SQL文 (iexact, contains, icontains, startswith, istartswith, endswith, iendswith) に相当するフィールドルックアップでは、 LIKE 文で使用される2つの特殊文字 (パーセント記号とアンダースコア) が自動的にエスケープされます。 (LIKE 文では、パーセント記号は複数文字のワイルドカードを意味し、アンダースコアは1文字のワイルドカードを意味します)。
つまり、直感的に動作するので、抽象化が漏れることはありません。たとえば、パーセント記号を含むすべてのエントリを取得するには、パーセント記号を他の文字と同じように使用します:
\n>>> Entry.objects.filter(headline__contains="%")\nDjango は以下のように、あなたの代わりにクォート処理をしてくれます:
\nSELECT ... WHERE headline LIKE '%\\%%';\nアンダースコアも同様です。パーセント記号もアンダースコアも透過的に処理されます。
\nQuerySetLink to this heading#それぞれの QuerySet には、データベースへのアクセスを最小にするために内部にキャッシュがあります。キャッシュのしくみを理解すれば、最も効率の良いコードが書けるようになります。
新しく作成された QuerySet では、キャッシュは空です。初めて QuerySet が評価されたとき、つまりデータベースへのクエリが発生したとき、Django はクエリの結果を QuerySet のキャッシュに保存し、明示的に要求された結果 (例えば、 QuerySet が繰り返し処理されている場合は次の要素) を返します。それ以降の QuerySet の評価はキャッシュされた結果を再利用します。
このキャッシュの動作は覚えておきましょう。 QuerySet を正しく使わないと、痛い目を見るかもしれません。たとえば、次のようにしてしまうと QuerySet が 2 つ作成され、評価され、そして破棄されます:
>>> print([e.headline for e in Entry.objects.all()])\n>>> print([e.pub_date for e in Entry.objects.all()])\nつまり、同じデータベースクエリが2回実行されることになり、事実上データベースの負荷が2倍になります。また、2つのリクエストの間の一瞬の間に Entry が追加されたり削除されたりして、2つのリストに同じデータベースレコードが含まれない可能性もあります。
この問題を回避するには、 QuerySet を保存して再利用します:
>>> queryset = Entry.objects.all()\n>>> print([p.headline for p in queryset]) # Evaluate the query set.\n>>> print([p.pub_date for p in queryset]) # Reuse the cache from the evaluation.\nQuerySet がキャッシュされないケースLink to this heading#Querysets do not always cache their results. When evaluating only part of\nthe queryset, the cache is checked, but if it is not populated then the items\nreturned by the subsequent query are not cached. Specifically, this means that\nlimiting the queryset using an array slice or an\nindex will not populate the cache.
\nたとえば、クエリセットオブジェクトで特定のインデックスを繰り返し取得すると、その度にデータベースにクエリが送られます:
\n>>> queryset = Entry.objects.all()\n>>> print(queryset[5]) # Queries the database\n>>> print(queryset[5]) # Queries the database again\nしかし、クエリセット全体がすでに評価されている場合は、代わりにキャッシュが調べられます:
\n>>> queryset = Entry.objects.all()\n>>> [entry for entry in queryset] # Queries the database\n>>> print(queryset[5]) # Uses cache\n>>> print(queryset[5]) # Uses cache\n以下に、クエリセット全体が評価され、その結果キャッシュに入力される他の操作の例をいくつか示します:
\n>>> [entry for entry in queryset]\n>>> bool(queryset)\n>>> entry in queryset\n>>> list(queryset)\n非同期ビューやコードを書いている場合、上記で説明した方法でORMをクエリに使用することはできません。非同期コードから ブロッキングな 同期コードを呼び出すことはできず、イベントループをブロックしてしまいます（それか、大抵はDjangoがそのことを検出し、 SynchronousOnlyOperation を発生させて防ぐでしょう）。
幸い、Django の非同期クエリ API を使えば、多くのクエリを実行できます。 get() や delete() のようなブロッキングされる可能性のあるメソッドにはすべて非同期型 (aget() や adelete()) があり、結果を反復処理するときには、代わりに非同期反復処理 (async for) が使えます。
クエリを繰り返し処理するデフォルトの方法 for では、 Django が繰り返し処理時に結果をロードするため、裏でデータベースのクエリがブロッキングされます。これを修正するには、 async for に変更します:
async for entry in Authors.objects.filter(name__startswith="A"):\n ...\n例えば、 list() をクエリセットにラップして強制的にクエリセットを評価するようなことはできません (必要であれば、内包表記の中で async for を使うことができます)。
filter() や exclude() のような QuerySet メソッドは実際にクエリを実行するわけではなく、クエリセットがイテレートされたときに実行されるように指定するものなので、非同期コードで自由に使用できます。どのメソッドがこのように使い続けられるか、またどのメソッドに非同期バージョンがあるかについては、次のセクションを読んでください。
QuerySet とマネージャメソッドLink to this heading#マネージャやクエリセットに関するメソッドの中には、 get() や first() のように、クエリセットを強制的に実行し、ブロッキングするものがあります。 filter() や exclude() のように、実行を強制しないメソッドもあります。しかし、どうやって見分けるのでしょうか？
メソッドに a で始まるバージョンがあるかどうかを探ることもできます（例えば、aget() はありますが、 afilter() はありません）。しかし、もっとロジカルな方法があります。それは、 QuerySet リファレンス でそのメソッドがどのような種類のものかを調べることです。
そこでは、QuerySet に関するメソッドを2つのセクションに分けています:
\nMethods that return new querysets: These are the non-blocking ones,\nand don't have asynchronous versions. You're free to use these in any\nsituation, but understand the constraint of no deferred queries before\nusing defer(),\nonly(), or\nfetch_mode().
クエリセットを返さないメソッド: これらはブロッキングメソッドで、非同期バージョンもあります。それぞれの非同期名はドキュメントに書かれていますが、私たちの標準的なパターンは接頭辞に a をつけることです。
この区別を使えば、非同期バージョンを使う必要があるときとないときを判断できます。たとえば、これは有効な非同期クエリです:
\nuser = await User.objects.filter(username=my_input).afirst()\nfilter() はクエリセットを返すため、非同期環境内で連結して使用しても問題ありません。一方で first() は評価してモデルインスタンスを返すため、 afirst() に変更し、非同期に適した方法で呼び出すために、式全体の前に await を使用します。
Relations are deferred by default. If the blog relation is not prefetched,\naccessing entry.blog during asynchronous evaluation of a queryset attempts\na blocking database query, raising SynchronousOnlyOperation. (A similar\nlimitation applies to fields deferred via defer() or only().) To avoid\nthis, see the advice on prefetching in リレーション先のオブジェクト.
トランザクションは現在、非同期クエリや更新ではサポートされていません。これを使用しようとすると SynchronousOnlyOperation が発生します。
トランザクションを使用したい場合は、ORMコードを別の同期関数の中に記述し、 sync_to_async を使用して呼び出すことをおすすめします。詳しくは 非同期サポート を参照してください。
JSONField へのクエリLink to this heading#JSONField では、ルックアップの実装は主にキーのトランスフォーム（変換）の存在によって異なります。デモンストレーションのために、次のモデル例を使います:
from django.db import models\n\n\nclass Dog(models.Model):\n name = models.CharField(max_length=200)\n data = models.JSONField(null=True)\n\n def __str__(self):\n return self.name\nNone の保存とクエリLink to this heading#As with other fields, storing None as the field's value will store it as\nSQL NULL. While not recommended, it is possible to store JSON scalar\nnull instead of SQL NULL by using the JSONNull() expression.
どちらの値が格納されていても、データベースから取得したとき、JSON のスカラー null の Python 表現は SQL の NULL と同じ、つまり None になります。そのため、両者を区別するのは難しいでしょう。
This only applies to None as the top-level value of the field. If None\nis inside a list or dict, it will always be interpreted\nas JSON null.
When querying, isnull=True is used to match SQL NULL,\nwhile exact-matching JSONNull() is used to match JSON null.
>>> from django.db.models import JSONNull\n>>> Dog.objects.create(name="Max", data=None) # SQL NULL.\n<Dog: Max>\n>>> Dog.objects.create(name="Archie", data=JSONNull()) # JSON null.\n<Dog: Archie>\n>>> Dog.objects.filter(data=None)\n...: RemovedInDjango2028Warning: Using None as the right-hand side of an\nexact lookup on JSONField to mean JSON scalar 'null' is deprecated. Use\nJSONNull() instead (or use the __isnull lookup if you meant SQL NULL).\n...\n<QuerySet [<Dog: Archie>]>\n>>> Dog.objects.filter(data=JSONNull())\n<QuerySet [<Dog: Archie>]>\n>>> Dog.objects.filter(data__isnull=True)\n<QuerySet [<Dog: Max>]>\n>>> Dog.objects.filter(data__isnull=False)\n<QuerySet [<Dog: Archie>]>\nSQL の NULL 値を使いたいのでなければ、 null=False を設定し、 default=dict のように空の値に対して適切なデフォルト値を指定することを検討してください。
指定された辞書のキーに基づいてクエリを実行するには、そのキーをルックアップ名として使います:
\n>>> Dog.objects.create(\n... name="Rufus",\n... data={\n... "breed": "labrador",\n... "owner": {\n... "name": "Bob",\n... "other_pets": [\n... {\n... "name": "Fishy",\n... }\n... ],\n... },\n... },\n... )\n<Dog: Rufus>\n>>> Dog.objects.create(name="Meg", data={"breed": "collie", "owner": None})\n<Dog: Meg>\n>>> Dog.objects.filter(data__breed="collie")\n<QuerySet [<Dog: Meg>]>\nTo query a key for JSON null, None or JSONNull() can be used.
>>> Dog.objects.filter(data__owner=None)\n<Dog: Meg>\n>>> Dog.objects.filter(data__owner=JSONNull())\n<Dog: Meg>\n複数のキーを連結して1本のルックアップパス（経路）を形成することもできます。
\n>>> Dog.objects.filter(data__owner__name="Bob")\n<QuerySet [<Dog: Rufus>]>\nキーが整数の場合は、配列のインデックスのトランスフォームとして解釈されます:
\n>>> Dog.objects.filter(data__owner__other_pets__0__name="Fishy")\n<QuerySet [<Dog: Rufus>]>\nIf the key is a negative integer, it cannot be used in a filter keyword\ndirectly, but you can still use dictionary unpacking to use it in a query:
\n>>> Dog.objects.filter(**{"data__owner__other_pets__-1__name": "Fishy"})\n<QuerySet [<Dog: Rufus>]>\nクエリしたいキーが他のルックアップ名と衝突する場合は、代わりに contains ルックアップを使用してください。
欠損したキーをクエリで探したいときは、 isnull ルックアップを使用します:
>>> Dog.objects.create(name="Shep", data={"breed": "collie"})\n<Dog: Shep>\n>>> Dog.objects.filter(data__owner__isnull=True)\n<QuerySet [<Dog: Shep>]>\nKT() 式Link to this heading#JSONField のキー、インデックス、パス（経路）のトランスフォーム（変換）のテキスト値を表します。 lookup で2重アンダースコア表記を使用すると、辞書のキーやインデックス変換を連結できます。
例えば次のようにします:
\n>>> from django.db.models.fields.json import KT\n>>> Dog.objects.create(\n... name="Shep",\n... data={\n... "owner": {"name": "Bob"},\n... "breed": ["collie", "lhasa apso"],\n... },\n... )\n<Dog: Shep>\n>>> Dog.objects.annotate(\n... first_breed=KT("data__breed__1"), owner_name=KT("data__owner__name")\n... ).filter(first_breed__startswith="lhasa", owner_name="Bob")\n<QuerySet [<Dog: Shep>]>\ncontain の概念とキーのルックアップLink to this heading#containsLink to this heading#contains ルックアップは JSONField でオーバーライドされます。返されるオブジェクトは、与えられた dict キーと値のペアが、フィールドのトップレベルにすべて含まれているものです。たとえば、次のようになります:
>>> Dog.objects.create(name="Rufus", data={"breed": "labrador", "owner": "Bob"})\n<Dog: Rufus>\n>>> Dog.objects.create(name="Meg", data={"breed": "collie", "owner": "Bob"})\n<Dog: Meg>\n>>> Dog.objects.create(name="Fred", data={})\n<Dog: Fred>\n>>> Dog.objects.create(\n... name="Merry", data={"breed": "pekingese", "tricks": ["fetch", "dance"]}\n... )\n>>> Dog.objects.filter(data__contains={"owner": "Bob"})\n<QuerySet [<Dog: Rufus>, <Dog: Meg>]>\n>>> Dog.objects.filter(data__contains={"breed": "collie"})\n<QuerySet [<Dog: Meg>]>\n>>> Dog.objects.filter(data__contains={"tricks": ["dance"]})\n<QuerySet [<Dog: Merry>]>\ncontained_byLink to this heading#これは contains ルックアップの逆です。そのオブジェクト上のキーと値のペアが、引数で渡されたJSON値のサブセットになるようなオブジェクトを返します。例えば:
>>> Dog.objects.create(name="Rufus", data={"breed": "labrador", "owner": "Bob"})\n<Dog: Rufus>\n>>> Dog.objects.create(name="Meg", data={"breed": "collie", "owner": "Bob"})\n<Dog: Meg>\n>>> Dog.objects.create(name="Fred", data={})\n<Dog: Fred>\n>>> Dog.objects.create(\n... name="Merry", data={"breed": "pekingese", "tricks": ["fetch", "dance"]}\n... )\n>>> Dog.objects.filter(data__contained_by={"breed": "collie", "owner": "Bob"})\n<QuerySet [<Dog: Meg>, <Dog: Fred>]>\n>>> Dog.objects.filter(data__contained_by={"breed": "collie"})\n<QuerySet [<Dog: Fred>]>\n>>> Dog.objects.filter(\n... data__contained_by={"breed": "pekingese", "tricks": ["dance", "fetch", "hug"]}\n... )\n<QuerySet [<Dog: Merry>, <Dog: Fred>]>\nhas_keyLink to this heading#与えられたキーがデータのトップレベルにあるオブジェクトを返します。たとえば次のようになります:
\n>>> Dog.objects.create(name="Rufus", data={"breed": "labrador"})\n<Dog: Rufus>\n>>> Dog.objects.create(name="Meg", data={"breed": "collie", "owner": "Bob"})\n<Dog: Meg>\n>>> Dog.objects.filter(data__has_key="owner")\n<QuerySet [<Dog: Meg>]>\nhas_keysLink to this heading#与えられたキーがすべて、データのトップレベルにあるオブジェクトを返します。たとえば次のようになります:
\n>>> Dog.objects.create(name="Rufus", data={"breed": "labrador"})\n<Dog: Rufus>\n>>> Dog.objects.create(name="Meg", data={"breed": "collie", "owner": "Bob"})\n<Dog: Meg>\n>>> Dog.objects.filter(data__has_keys=["breed", "owner"])\n<QuerySet [<Dog: Meg>]>\nhas_any_keysLink to this heading#与えられたキーのいずれかがデータのトップレベルにあるオブジェクトを返します。たとえば次のようになります:
\n>>> Dog.objects.create(name="Rufus", data={"breed": "labrador"})\n<Dog: Rufus>\n>>> Dog.objects.create(name="Meg", data={"owner": "Bob"})\n<Dog: Meg>\n>>> Dog.objects.filter(data__has_any_keys=["owner", "breed"])\n<QuerySet [<Dog: Rufus>, <Dog: Meg>]>\nQ オブジェクトを使った複雑なルックアップLink to this heading#Keyword argument queries -- in filter(),\netc. -- are "AND"ed together. If you need to execute more complex queries (for\nexample, queries with OR statements), you can use Q() objects.
A Q object (django.db.models.Q) is an object used to\nencapsulate a collection of keyword arguments. These keyword arguments are\nspecified as in "Field lookups" above.
たとえば、次の Q オブジェクトは、1つの LIKE クエリをカプセル化しています。
from django.db.models import Q\n\nQ(question__startswith="What")\nQ オブジェクトは &, |, ^ 演算子を使って結合できます。演算子を2つの Q オブジェクトに使用すると、新しい Q オブジェクトが生成されます。
たとえば、次の文は2つの "question__startswith" の "OR" を表す、1つの Q オブジェクトを生み出します。
Q(question__startswith="Who") | Q(question__startswith="What")\nこのコードは次の SQL の WHERE 句と同等です:
WHERE question LIKE 'Who%' OR question LIKE 'What%'\nQ オブジェクトと &, |, ^ 演算子を組み合わせ、括弧でグループ化することで、任意の複雑な文を作成できます。また、 Q オブジェクトは ~ 演算子を使用して否定することができ、通常のクエリと否定された (NOT) クエリの両方を組み合わせてルックアップできます:
Q(question__startswith="Who") | ~Q(pub_date__year=2005)\nキーワード引数を取るルックアップ関数 (例えば filter(), exclude(), get()) には、1つ以上の Q オブジェクトを（名前なし）位置引数として渡すこともできます。複数の Q オブジェクトの引数をルックアップ関数に渡すと、引数は "AND" されます。たとえば、次のようになります:
Poll.objects.get(\n Q(question__startswith="Who"),\n Q(pub_date=date(2005, 5, 2)) | Q(pub_date=date(2005, 5, 6)),\n)\n... これは大ざっぱにSQLに翻訳すると次のようになります:
\nSELECT * from polls WHERE question LIKE 'Who%'\n AND (pub_date = '2005-05-02' OR pub_date = '2005-05-06')\nルックアップ関数は Q オブジェクトとキーワード引数を混ぜて使うことができます。ルックアップ関数に提供されたすべての引数は（キーワード引数でも Q オブジェクトでも） "AND" で結合されます。しかし、もし Q オブジェクトが指定された場合は、キーワード引数の定義よりも前に指定する必要があります。たとえば次のようにします:
Poll.objects.get(\n Q(pub_date=date(2005, 5, 2)) | Q(pub_date=date(2005, 5, 6)),\n question__startswith="Who",\n)\n...上記は有効なクエリで、1つ前の例と同じです。しかし、:
\n# INVALID QUERY\nPoll.objects.get(\n question__startswith="Who",\n Q(pub_date=date(2005, 5, 2)) | Q(pub_date=date(2005, 5, 6)),\n)\n...これは無効なクエリです。
\n\n2つのモデルインスタンスを比較するには、Pythonの標準的な比較演算子である二重の等号 == を使います。裏では、2つのモデルの主キーの値を比較します。
上記の Entry を例にすると、次の2つの文は等価です:
>>> some_entry == other_entry\n>>> some_entry.id == other_entry.id\nモデルの主キーが id という名前でなくても問題ありません。どのような名前であっても、比較は常に主キーを使用します。たとえば、モデルの主キーフィールドが name と呼ばれている場合、これら2つの文は等価です:
>>> some_obj == other_obj\n>>> some_obj.name == other_obj.name\n削除メソッドは便利なことに delete() という名前です。このメソッドはオブジェクトを即座に削除し、削除されたオブジェクトの数と、オブジェクトの種類ごとの削除数を辞書として返します。例:
>>> e.delete()\n(1, {'blog.Entry': 1})\nオブジェクトを一括で削除することもできます。すべての QuerySet は delete() メソッドを持っており、その QuerySet のすべてのメンバーを削除します。
たとえば、これは pub_date が2005年の Entry オブジェクトをすべて削除します:
>>> Entry.objects.filter(pub_date__year=2005).delete()\n(5, {'webapp.Entry': 5})\nこれは可能な限り純粋にSQLで実行されます。そのため、処理中に個々のオブジェクトインスタンスの delete() メソッドが呼び出される必要はないことに注意してください。もしあなたが独自の delete() メソッドをモデルクラスに定義しており、それを確実に呼び出したい場合は、QuerySet の delete() メソッドを使って一括削除するのではなく、「手動で」そのモデルインスタンスを削除する必要があります（たとえば、 QuerySet をイテレートして各オブジェクトに対し個別に delete() を呼び出します）。
Django がオブジェクトを削除するとき、デフォルトでは SQL の制約 ON DELETE CASCADE の動作をエミュレートします。言い換えると、削除するオブジェクトを指している外部キーを持つすべてのオブジェクトは、ともに削除されます。たとえば、
b = Blog.objects.get(pk=1)\n# This will delete the Blog and all of its Entry objects.\nb.delete()\nこのカスケード動作は、ForeignKey の on_delete 引数でカスタマイズできます。
注意点として、 delete() は、 QuerySet メソッドの中で唯一、 Manager 自身からは公開されていません。これは、誤って Entry.objects.delete() を呼び出して すべての エントリを削除してしまわないようにするための安全対策です。もしあなたが 本当に すべてのオブジェクトを削除したい場合は、下記のように明示的に完全なクエリセットに対して呼び出す必要があります。
Entry.objects.all().delete()\nモデルインスタンスをコピーする組み込みメソッドはありませんが、全てのフィールドの値をコピーした新しいインスタンスは簡単に作ることができます。最も単純なケースでは、 pk を None に設定し、 _state.adding を True に設定します。ブログの例で説明すると、次のようになります:
blog = Blog(name="My blog", tagline="Blogging is easy")\nblog.save() # blog.pk == 1\n\nblog.pk = None\nblog._state.adding = True\nblog.save() # blog.pk == 2\n継承を使っている場合、もっと複雑になります。Blog のサブクラスを考えると:
class ThemeBlog(Blog):\n theme = models.CharField(max_length=200)\n\n\ndjango_blog = ThemeBlog(name="Django", tagline="Django is easy", theme="python")\ndjango_blog.save() # django_blog.pk == 3\n継承のしくみ上、pk と id の両方を None に設定し、 _state.adding を True に設定する必要があります:
django_blog.pk = None\ndjango_blog.id = None\ndjango_blog._state.adding = True\ndjango_blog.save() # django_blog.pk == 4\nこの処理では、モデルのデータベーステーブルの一部ではないリレーションは複製しません。例えば、Entry は Author への ManyToManyField を持ちます。entry の複製後、新しい entry に対して多対多のリレーションをセットする必要があります:
entry = Entry.objects.all()[0] # some previous entry\nold_authors = entry.authors.all()\nentry.pk = None\nentry._state.adding = True\nentry.save()\nentry.authors.set(old_authors)\nOneToOneField については、1 対 1 のユニーク制約への違反を避けるため、リレーション先オブジェクトを複製して新しいオブジェクトのフィールドに割り当てる必要があります。たとえば上記のように entry がすでに複製されている場合、次のようにします。
detail = EntryDetail.objects.all()[0]\ndetail.pk = None\ndetail._state.adding = True\ndetail.entry = entry\ndetail.save()\nNote that it is not possible to copy instances of models with deferred fields\nusing this pattern unless values are assigned to them:
\n>>> blog = Blog.objects.defer("name")[0]\n>>> blog.pk = None\n>>> blog._state.adding = True\n>>> blog.save()\nTraceback (most recent call last):\n ...\nAttributeError: Cannot retrieve deferred field 'name' from an unsaved model.\n>>> blog.name = "Another Blog"\n>>> blog.save()\nQuerySet のすべてのオブジェクトに、特定の値をセットしたい場合があります。update() を使えば実現できます。例えば:
# Update all the headlines with pub_date in 2007.\nEntry.objects.filter(pub_date__year=2007).update(headline="Everything is the same")\nこのメソッドを使ってセットできるのは非リレーションフィールドと ForeignKey フィールドのみです。非リレーションフィールドを更新するには、新しい値を定数として渡します。 ForeignKey フィールドを更新するには、結び付けたい新しいモデルインスタンスを新しい値にセットしてください。たとえば、次のようにします:
>>> b = Blog.objects.get(pk=1)\n\n# Change every Entry so that it belongs to this Blog.\n>>> Entry.objects.update(blog=b)\nupdate() は即座に適用され、クエリにマッチした行数を返します (行はすでに新しい値を持っていることがあるので、更新された行の数と一致するとは限りません)。更新する QuerySet の唯一の制限は、1 つのデータベーステーブル (モデルのメインテーブル) にしかアクセスできないことです。リレーション先のフィールドでフィルタすることもできますが、モデルのメインテーブルのカラムしか更新できません。例えば:
>>> b = Blog.objects.get(pk=1)\n\n# Update all the headlines belonging to this Blog.\n>>> Entry.objects.filter(blog=b).update(headline="Everything is the same")\nupdate() は直接 SQL文に変換されることに注意してください。これは、直接更新する一括操作です。 save() を実行することは一切なく、(save() を呼び出した結果である) pre_save や post_save のシグナルも出しません。 auto_now フィールドオプションも実施しません。 QuerySet のすべてのアイテムを保存し、各インスタンスで save() メソッドが確実に呼ばれるようにしたい場合、特別な機能は不要です。これらをループし、 save() を呼び出してください:
for item in my_queryset:\n item.save()\nCalls to update can also use F() expressions to update one field based on\nthe value of another field in the model. This is especially useful for\nincrementing counters based upon their current value. For example, to increment\nthe pingback count for every entry in the blog:
\n>>> Entry.objects.update(number_of_pingbacks=F("number_of_pingbacks") + 1)\nしかし、filter および exclude 句での F() オブジェクトとは異なり、update で F() オブジェクトを使うときはテーブル結合はできません。できるのは、更新されるモデルに関係付けられたフィールドを参照することだけです。 F() オブジェクト内でテーブル結合が必要なルックアップを行おうとすると、 FieldError が送出されます。
# This will raise a FieldError\n>>> Entry.objects.update(headline=F("blog__name"))\nDjango のデータベースマッパが扱うには複雑すぎる SQL クエリを記述する必要がある場合、手書きで SQL を書くことができます。Django には、素の SQL クエリを記述するための方法がいくつかあります。詳しくは 素の SQL 文の実行 を参照してください。
\n最後に、覚えておいてほしい重要な点は、Django のデータベースレイヤはあなたのデータベースに対する単なるインターフェースでしかないということです。あなたは、他のツール、プログラミング言語、データベースフレームワークなどを通じてデータベースを操作することもできます。データベースに関して Django 特有のことは何もありません。
\n