一度 データモデル を作成すれば、Django はデータオブジェクトの作成、取得、更新および削除を行えるようにデータベースを抽象化した API を自動的に提供します。本ドキュメントではこの API をどのように用いるかを説明します。多様なモデル探索オプション全てに関する詳細については データモデルの項目 を参照ください。
\nThroughout this guide (and in the reference), we'll refer to the following\nmodels, which comprise a blog application:
\nfrom datetime import date\n\nfrom django.db import models\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\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\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\nデータベースのテーブル上のデータを Python オブジェクトに対応付けるため、 Django は直観的なシステムを利用しています: 1 つのモデルクラスが 1 つのデータベーステーブルに対応し、そのモデルクラスの 1 インスタンスが対応するデータベーステーブルの特定のレコードに対応します。
\nオブジェクトを生成するためには、作成するモデルのクラスにキーワード引数を渡してインスタンス化し、そのデータをデータベースに保存するために save() を呼び出します。
モデル定義が mysite/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 が与えられたとして、次の例ではその name を変更してデータベースのレコードを更新します:
>>> b5.name = 'New name'\n>>> b5.save()\nこの例では内部で UPDATE SQL 文が処理されます。明示的に save() が呼ばれるまで Django はデータベースを操作しません。
ForeignKey と ManyToManyField フィールドを扱うLink to this heading#Updating a ForeignKey field works exactly the same\nway as saving a normal field -- assign an object of the right type to the field\nin question. This example updates the blog attribute of an Entry\ninstance entry, assuming appropriate instances of Entry and Blog\nare already saved to the database (so we can retrieve them below):
>>> 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() メソッドを対象となるフィールドに対して用います。以下の例では entry オブジェクトに Author のインスタンス joe を追加します。
>>> from blog.models import Author\n>>> joe = Author.objects.create(name="Joe")\n>>> entry.authors.add(joe)\nManyToManyField に対して複数のレコードを一度に追加するには、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 のような絞り込みに用いる句に対応しています。
モデルの Manager を用いることで QuerySet を取得します。各モデルは少なくとも一つの 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 はモデルの QuerySet の主な取得元になります。たとえば、 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(\n... headline__startswith='What'\n... ).exclude(\n... pub_date__gte=datetime.date.today()\n... ).filter(\n... pub_date__gte=datetime.date(2005, 1, 30)\n... )\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つの QuerySets は独立しています。1番目は基本の QuerySet で、"What" で始まるヘッドラインを持つ全てのエントリーを含みます。2番めは1番目の部分集合で、 pub_date が今日または未来の日付であるレコードを除外する追加条件を持ちます。3番目も1番目の部分集合で、 pub_date が今日または未来の日付であるレコードだけを選択する追加条件を持ちます。1番目の QuerySet (q1) は、絞り込みの過程において何ら影響を受けません。
QuerySet は遅延評価されるLink to this heading#QuerySets は遅延評価されます。 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 Reference を参照してください。
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]\nFurther filtering or ordering of a sliced queryset is prohibited due to the\nambiguous nature of how that might work.
\nTo retrieve a single object rather than a list\n(e.g. SELECT foo FROM bar LIMIT 1), use an index instead of a slice. For\nexample, this returns the first Entry in the database, after ordering\nentries alphabetically by headline:
>>> 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個のルックアップタイプをサポートしており、完全なガイドは field lookup reference で見ることができます。ルックアップを使って何ができるのかがよく分かるように、以下によく使う一般的なルックアップをいくつか挙げます。
\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 もあります。
繰り返しになりますが、以上はルックアップの表面をさらったに過ぎません。完全なリファレンスは field lookup reference を参照してください。
\nDjango offers a powerful and intuitive way to "follow" relationships in\nlookups, taking care of the SQL JOINs for you automatically, behind the\nscenes. To span a relationship, use the field name of related fields\nacross models, separated by double underscores, until you get to the field you\nwant.
次の例は、name に 'Beatles Blog' を持つ Blog のすべての Entry オブジェクトを取得します。
>>> Entry.objects.filter(blog__name='Beatles Blog')\nこの横断は好きなだけ深くすることができます。
\nIt works backwards, too. While it can be customized, by default you refer to a "reverse"\nrelationship in a lookup using the lowercase name of the model.
次の例は、 少なくとも1つの headline が 'Lennon' を含む Entry を持つ、すべての Blog オブジェクトを取得します。
>>> Blog.objects.filter(entry__headline__contains='Lennon')\n複数のリレーションにまたがってフィルタリングをしていて、仲介するどれかが条件に合致しない場合、Django は空 (すべての値が NULL) だけど有効なオブジェクトとして扱います これが意味するのは、エラーが投げられないと言うことです。例えば、以下のフィルタでは:
Blog.objects.filter(entry__authors__name='Lennon')\n(関係づけられた Author モデルがあった場合で) entry に関係づけられた author がない場合、 name がなかったかのように扱われ、author がないという理由でエラーを投げることはありません。通常、これは必要とされる動作です。もし混乱するとしたら、isnull を使っている場合でしょう。なので:
Blog.objects.filter(entry__authors__name__isnull=True)\nこれは author に空の name を持つ Blog オブジェクトと entry に空の author を返します。後者のオブジェクトがほしくない場合、以下のように書くことができます:
Blog.objects.filter(entry__authors__isnull=False, entry__authors__name__isnull=True)\nWhen spanning a ManyToManyField or a reverse\nForeignKey (such as from Blog to Entry),\nfiltering on multiple attributes raises the question of whether to require each\nattribute to coincide in the same related object. We might seek blogs that have\nan entry from 2008 with “Lennon” in its headline, or we might seek blogs that\nmerely have any entry from 2008 as well as some newer or older entry with\n“Lennon” in its headline.
To select all blogs containing at least one entry from 2008 having "Lennon"\nin its headline (the same entry satisfying both conditions), we would write:
\nBlog.objects.filter(entry__headline__contains='Lennon', entry__pub_date__year=2008)\nOtherwise, to perform a more permissive query selecting any blogs with merely\nsome entry with "Lennon" in its headline and some entry from 2008, we\nwould write:
\nBlog.objects.filter(entry__headline__contains='Lennon').filter(entry__pub_date__year=2008)\nSuppose there is only one blog that has both entries containing "Lennon" and\nentries from 2008, but that none of the entries from 2008 contained "Lennon".\nThe first query would not return any blogs, but the second query would return\nthat one blog. (This is because the entries selected by the second filter may\nor may not be the same as the entries in the first filter. We are filtering the\nBlog items with each filter statement, not the Entry items.) In short,\nif each condition needs to match the same related object, then each should be\ncontained in a single filter() call.
今まで見てきた例では、モデルのフィールドの値を定数と比較するフィルタを作ってきました。しかし、もしモデルのフィールドの値を、同じモデルの他のフィールドと比較したい時にはどうすればいいのでしょう？
\nそのような比較を行うために、Django は F 式 を用意しています。 F() のインスタンスは、クエリの中でモデルのフィールドへの参照として振る舞います。したがって、この参照をクエリの中で使うことで、同じモデルのインスタンスの異なる2つのフィールドの値を比較することができます。
たとえば、pingback の数よりコメントの数が多いすべてのブログエントリーのリストを検索するには、pingback の数を参照する F() オブジェクトを作り、その F() オブジェクトをクエリの中で次のように使います。
>>> from django.db.models import F\n>>> Entry.objects.filter(number_of_comments__gt=F('number_of_pingbacks'))\nDjango supports the use of addition, subtraction, multiplication,\ndivision, modulo, and power arithmetic with F() objects, both with constants\nand with other F() objects. To find all the blog entries with more than\ntwice as many comments as pingbacks, we modify the query:
>>> Entry.objects.filter(number_of_comments__gt=F('number_of_pingbacks') * 2)\nTo find all the entries where the rating of the entry is less than the\nsum of the pingback count and comment count, we would issue the\nquery:
\n>>> Entry.objects.filter(rating__lt=F('number_of_comments') + F('number_of_pingbacks'))\nYou can also use the double underscore notation to span relationships in\nan F() object. An F() object with a double underscore will introduce\nany joins needed to access the related object. For example, to retrieve all\nthe entries where the author's name is the same as the blog name, we could\nissue the query:
>>> Entry.objects.filter(authors__name=F('blog__name'))\nFor date and date/time fields, you can add or subtract a\ntimedelta object. The following would return all entries\nthat were modified more than 3 days after they were published:
>>> from datetime import timedelta\n>>> Entry.objects.filter(mod_date__gt=F('pub_date') + timedelta(days=3))\nThe F() objects support bitwise operations by .bitand(), .bitor(),\n.bitxor(), .bitrightshift(), and .bitleftshift(). For example:
>>> F('somefield').bitand(16)\nDjango supports using transforms in expressions.
\nFor example, to find all Entry objects published in the same year as they\nwere last modified:
>>> from django.db.models import F\n>>> Entry.objects.filter(pub_date__year=F('mod_date__year'))\nTo find the earliest year an entry was published, we can issue the query:
\n>>> from django.db.models import Min\n>>> Entry.objects.aggregate(first_published_year=Min('pub_date__year'))\nThis example finds the value of the highest rated entry and the total number\nof comments on all entries for each year:
\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... ).order_by('-rating').values('rating')[:1]\n... ),\n... total_comments=Sum('number_of_comments'),\n... )\npk ルックアップショートカットLink to this heading#利便性のために、Django は pk ルックアップショートカットを用意しています。pk とは "primary key" を表します。
プライマリーキーが id フィールドである Blog モデルの例では、次の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\nThe use of pk isn't limited to __exact queries -- any query term\ncan be combined with pk to perform a query on the primary key of a model:
# 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 lookups also work across joins. For example, these three statements are\nequivalent:
>>> 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#The field lookups that equate to LIKE SQL statements (iexact,\ncontains, icontains, startswith, istartswith, endswith\nand iendswith) will automatically escape the two special characters used in\nLIKE statements -- the percent sign and the underscore. (In a LIKE\nstatement, the percent sign signifies a multiple-character wildcard and the\nunderscore signifies a single-character wildcard.)
This means things should work intuitively, so the abstraction doesn't leak.\nFor example, to retrieve all the entries that contain a percent sign, use the\npercent sign as any other character:
\n>>> Entry.objects.filter(headline__contains='%')\nDjango takes care of the quoting for you; the resulting SQL will look something\nlike this:
\nSELECT ... WHERE headline LIKE '%\\%%';\nSame goes for underscores. Both percentage signs and underscores are handled\nfor you transparently.
\nQuerySetLink to this heading#それぞれの QuerySet には、データベースへのアクセスを最小にするために内部にキャッシュがあります。キャッシュのしくみを理解すれば、最も効率の良いコードが書けるようになります。
In a newly created QuerySet, the cache is\nempty. The first time a QuerySet is evaluated\n-- and, hence, a database query happens -- Django saves the query results in\nthe QuerySet’s cache and returns the results\nthat have been explicitly requested (e.g., the next element, if the\nQuerySet is being iterated over). Subsequent\nevaluations of the QuerySet reuse the cached\nresults.
Keep this caching behavior in mind, because it may bite you if you don't use\nyour QuerySets correctly. For example, the\nfollowing will create two QuerySets, evaluate\nthem, and throw them away:
>>> print([e.headline for e in Entry.objects.all()])\n>>> print([e.pub_date for e in Entry.objects.all()])\nThat means the same database query will be executed twice, effectively doubling\nyour database load. Also, there's a possibility the two lists may not include\nthe same database records, because an Entry may have been added or deleted\nin the split second between the two requests.
To avoid this problem, save the QuerySet and\nreuse it:
>>> 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.
\nFor example, repeatedly getting a certain index in a queryset object will query\nthe database each time:
\n>>> queryset = Entry.objects.all()\n>>> print(queryset[5]) # Queries the database\n>>> print(queryset[5]) # Queries the database again\nHowever, if the entire queryset has already been evaluated, the cache will be\nchecked instead:
\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\nHere are some examples of other actions that will result in the entire queryset\nbeing evaluated and therefore populate the cache:
\n>>> [entry for entry in queryset]\n>>> bool(queryset)\n>>> entry in queryset\n>>> list(queryset)\nIf you are writing asynchronous views or code, you cannot use the ORM for\nqueries in quite the way we have described above, as you cannot call blocking\nsynchronous code from asynchronous code - it will block up the event loop\n(or, more likely, Django will notice and raise a SynchronousOnlyOperation\nto stop that from happening).
Fortunately, you can do many queries using Django's asynchronous query APIs.\nEvery method that might block - such as get() or delete() - has an\nasynchronous variant (aget() or adelete()), and when you iterate over\nresults, you can use asynchronous iteration (async for) instead.
The default way of iterating over a query - with for - will result in a\nblocking database query behind the scenes as Django loads the results at\niteration time. To fix this, you can swap to async for:
async for entry in Authors.objects.filter(name__startswith="A"):\n ...\nBe aware that you also can't do other things that might iterate over the\nqueryset, such as wrapping list() around it to force its evaluation (you\ncan use async for in a comprehension, if you want it).
Because QuerySet methods like filter() and exclude() do not\nactually run the query - they set up the queryset to run when it's iterated\nover - you can use those freely in asynchronous code. For a guide to which\nmethods can keep being used like this, and which have asynchronous versions,\nread the next section.
QuerySet and manager methodsLink to this heading#Some methods on managers and querysets - like get() and first() - force\nexecution of the queryset and are blocking. Some, like filter() and\nexclude(), don't force execution and so are safe to run from asynchronous\ncode. But how are you supposed to tell the difference?
While you could poke around and see if there is an a-prefixed version of\nthe method (for example, we have aget() but not afilter()), there is a\nmore logical way - look up what kind of method it is in the\nQuerySet reference.
In there, you'll find the methods on QuerySets grouped into two sections:
\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, though read the notes on defer() and only() before you use\nthem.
Methods that do not return querysets: These are the blocking ones, and\nhave asynchronous versions - the asynchronous name for each is noted in its\ndocumentation, though our standard pattern is to add an a prefix.
Using this distinction, you can work out when you need to use asynchronous\nversions, and when you don't. For example, here's a valid asynchronous query:
\nuser = await User.objects.filter(username=my_input).afirst()\nfilter() returns a queryset, and so it's fine to keep chaining it inside an\nasynchronous environment, whereas first() evaluates and returns a model\ninstance - thus, we change to afirst(), and use await at the front of\nthe whole expression in order to call it in an asynchronous-friendly way.
Transactions are not currently supported with asynchronous queries and\nupdates. You will find that trying to use one raises\nSynchronousOnlyOperation.
If you wish to use a transaction, we suggest you write your ORM code inside a\nseparate, synchronous function and then call that using sync_to_async - see\n非同期サポート for more.
JSONFieldLink to this heading#Lookups implementation is different in JSONField,\nmainly due to the existence of key transformations. To demonstrate, we will use\nthe following example model:
from django.db import models\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\nNoneLink 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 Value('null').
Whichever of the values is stored, when retrieved from the database, the Python\nrepresentation of the JSON scalar null is the same as SQL NULL, i.e.\nNone. Therefore, it can be hard to distinguish between them.
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, None value will always be interpreted as JSON null. To\nquery for SQL NULL, use isnull:
>>> Dog.objects.create(name='Max', data=None) # SQL NULL.\n<Dog: Max>\n>>> Dog.objects.create(name='Archie', data=Value('null')) # JSON null.\n<Dog: Archie>\n>>> Dog.objects.filter(data=None)\n<QuerySet [<Dog: Archie>]>\n>>> Dog.objects.filter(data=Value('null'))\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>]>\nUnless you are sure you wish to work with SQL NULL values, consider setting\nnull=False and providing a suitable default for empty values, such as\ndefault=dict.
To query based on a given dictionary key, use that key as the lookup name:
\n>>> Dog.objects.create(name='Rufus', data={\n... 'breed': 'labrador',\n... 'owner': {\n... 'name': 'Bob',\n... 'other_pets': [{\n... 'name': 'Fishy',\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>]>\nMultiple keys can be chained together to form a path lookup:
\n>>> Dog.objects.filter(data__owner__name='Bob')\n<QuerySet [<Dog: Rufus>]>\nIf the key is an integer, it will be interpreted as an index transform in an\narray:
\n>>> Dog.objects.filter(data__owner__other_pets__0__name='Fishy')\n<QuerySet [<Dog: Rufus>]>\nIf the key you wish to query by clashes with the name of another lookup, use\nthe contains lookup instead.
To query for missing keys, use the isnull lookup:
>>> Dog.objects.create(name='Shep', data={'breed': 'collie'})\n<Dog: Shep>\n>>> Dog.objects.filter(data__owner__isnull=True)\n<QuerySet [<Dog: Shep>]>\ncontainsLink to this heading#The contains lookup is overridden on JSONField. The returned\nobjects are those where the given dict of key-value pairs are all\ncontained in the top-level of the field. For example:
>>> 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.filter(data__contains={'owner': 'Bob'})\n<QuerySet [<Dog: Rufus>, <Dog: Meg>]>\n>>> Dog.objects.filter(data__contains={'breed': 'collie'})\n<QuerySet [<Dog: Meg>]>\ncontained_byLink to this heading#This is the inverse of the contains lookup - the\nobjects returned will be those where the key-value pairs on the object are a\nsubset of those in the value passed. For example:
>>> 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.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>]>\nhas_keyLink to this heading#Returns objects where the given key is in the top-level of the data. For\nexample:
\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#Returns objects where all of the given keys are in the top-level of the data.\nFor example:
\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#Returns objects where any of the given keys are in the top-level of the data.\nFor example:
\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\nused to encapsulate a collection of keyword arguments. These keyword arguments\nare specified as in "Field lookups" above.
たとえば、次の Q オブジェクトは、1つの LIKE クエリをカプセル化しています。
from django.db.models import Q\nQ(question__startswith='What')\nQ objects can be combined using the &, |, and ^ operators. When\nan operator is used on two Q objects, it yields a new Q object.
たとえば、次の文は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%'\nYou can compose statements of arbitrary complexity by combining Q objects\nwith the &, |, and ^ operators and use parenthetical grouping.\nAlso, Q objects can be negated using the ~ operator, allowing for\ncombined lookups that combine both a normal query and a negated (NOT)\nquery:
Q(question__startswith='Who') | ~Q(pub_date__year=2005)\nEach lookup function that takes keyword-arguments\n(e.g. filter(),\nexclude(),\nget()) can also be passed one or more\nQ objects as positional (not-named) arguments. If you provide multiple\nQ object arguments to a lookup function, the arguments will be "AND"ed\ntogether. For example:
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... roughly translates into the SQL:
\nSELECT * from polls WHERE question LIKE 'Who%'\n AND (pub_date = '2005-05-02' OR pub_date = '2005-05-06')\nLookup functions can mix the use of Q objects and keyword arguments. All\narguments provided to a lookup function (be they keyword arguments or Q\nobjects) are "AND"ed together. However, if a Q object is provided, it must\nprecede the definition of any keyword arguments. For example:
Poll.objects.get(\n Q(pub_date=date(2005, 5, 2)) | Q(pub_date=date(2005, 5, 6)),\n question__startswith='Who',\n)\n... would be a valid query, equivalent to the previous example; but:
\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... would not be valid.
\n\n\nTo compare two model instances, use the standard Python comparison operator,\nthe double equals sign: ==. Behind the scenes, that compares the primary\nkey values of two models.
上記の例の 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() は、Manager で露出していない唯一の QuerySet のメソッドです。これは、Entry.objects.delete() を誤ってリクエストして すべての entry を削除してしまうことを防ぐ安全上の仕組みです。すべてのオブジェクトを削除 したい 場合、明示的に完全なクエリセットをリクエストする必要があります:
Entry.objects.all().delete()\nAlthough there is no built-in method for copying model instances, it is\npossible to easily create new instance with all fields' values copied. In the\nsimplest case, you can set pk to None and\n_state.adding to True. Using our\nblog example:
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\ndjango_blog = ThemeBlog(name='Django', tagline='Django is easy', theme='python')\ndjango_blog.save() # django_blog.pk == 3\nDue to how inheritance works, you have to set both pk and id to\nNone, and _state.adding to 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()\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')\nBe aware that the update() method is converted directly to an SQL\nstatement. It is a bulk operation for direct updates. It doesn't run any\nsave() methods on your models, or emit the\npre_save or post_save signals (which are a consequence of calling\nsave()), or honor the\nauto_now field option.\nIf you want to save every item in a QuerySet\nand make sure that the save() method is called on\neach instance, you don't need any special function to handle that. Loop over\nthem and call save():
for item in my_queryset:\n item.save()\n更新の呼び出しでは、F 式 を使ってモデル内の別のフィールドの値に基づいてフィールドを更新することもできます。これは、現在値に基づいてカウンタを増加させる場合に特に有用です。例えば、ブログの各 entry のpingback カウントを増加させるには:
>>> Entry.objects.update(number_of_pingbacks=F('number_of_pingbacks') + 1)\nしかし、filter および exclude 節での F() オブジェクトとは異なり、更新で F() オブジェクトを使うときには join を導入することはできません -- できるのは、更新されるモデルに関係付いたフィールドを参照することだけです。 F() オブジェクトで join の導入を試みた場合、FieldError が投げられます:
# This will raise a FieldError\n>>> Entry.objects.update(headline=F('blog__name'))\nDjango のデータベースマッパが扱うには複雑すぎる SQL クエリを記述する必要がある場合、手書きで SQL を書くことができます。Django には、素の SQL クエリを記述するための方法がいくつかあります; 素の SQL 文の実行 を参照してください。
\n最後に、覚えておいてほしい重要な点は、Django のデータベースレイヤはあなたのデータベースに対する単なるインターフェースでしかないということです。あなたは、他のツール、プログラミング言語、データベースフレームワークなどを通じてデータベースを操作することもできます; データベースに関して Django 特有のことは何もありません。
\n