Djangoのデータベース抽象API のトピックガイドでは、個別のオブジェクトの作成、取得、削除を行うDjangoのクエリの使い方を説明しました。しかし、オブジェクトのコレクションを 集計 (アグリゲーション) した値や、集計することによって派生された値を取得しなければならないことがあります。 このトピックガイドはで、Django のクエリを使って集計値を生成して返す方法を説明します。
\nこのガイドでは、以下のモデルを使用します。これらのモデルは、一連のオンライン書店の在庫を追跡するために使用されます。
\nfrom django.db import models\n\nclass Author(models.Model):\n name = models.CharField(max_length=100)\n age = models.IntegerField()\n\nclass Publisher(models.Model):\n name = models.CharField(max_length=300)\n\nclass Book(models.Model):\n name = models.CharField(max_length=300)\n pages = models.IntegerField()\n price = models.DecimalField(max_digits=10, decimal_places=2)\n rating = models.FloatField()\n authors = models.ManyToManyField(Author)\n publisher = models.ForeignKey(Publisher, on_delete=models.CASCADE)\n pubdate = models.DateField()\n\nclass Store(models.Model):\n name = models.CharField(max_length=300)\n books = models.ManyToManyField(Book)\nお急ぎですか？ 上記のモデルを使った場合の一般的な集計クエリは以下のようになります:
\n# Total number of books.\n>>> Book.objects.count()\n2452\n\n# Total number of books with publisher=BaloneyPress\n>>> Book.objects.filter(publisher__name='BaloneyPress').count()\n73\n\n# Average price across all books.\n>>> from django.db.models import Avg\n>>> Book.objects.all().aggregate(Avg('price'))\n{'price__avg': 34.35}\n\n# Max price across all books.\n>>> from django.db.models import Max\n>>> Book.objects.all().aggregate(Max('price'))\n{'price__max': Decimal('81.20')}\n\n# Difference between the highest priced book and the average price of all books.\n>>> from django.db.models import FloatField\n>>> Book.objects.aggregate(\n... price_diff=Max('price', output_field=FloatField()) - Avg('price'))\n{'price_diff': 46.85}\n\n# All the following queries involve traversing the Book<->Publisher\n# foreign key relationship backwards.\n\n# Each publisher, each with a count of books as a "num_books" attribute.\n>>> from django.db.models import Count\n>>> pubs = Publisher.objects.annotate(num_books=Count('book'))\n>>> pubs\n<QuerySet [<Publisher: BaloneyPress>, <Publisher: SalamiPress>, ...]>\n>>> pubs[0].num_books\n73\n\n# Each publisher, with a separate count of books with a rating above and below 5\n>>> from django.db.models import Q\n>>> above_5 = Count('book', filter=Q(book__rating__gt=5))\n>>> below_5 = Count('book', filter=Q(book__rating__lte=5))\n>>> pubs = Publisher.objects.annotate(below_5=below_5).annotate(above_5=above_5)\n>>> pubs[0].above_5\n23\n>>> pubs[0].below_5\n12\n\n# The top 5 publishers, in order by number of books.\n>>> pubs = Publisher.objects.annotate(num_books=Count('book')).order_by('-num_books')[:5]\n>>> pubs[0].num_books\n1323\nQuerySet に対して集計を生成するLink to this heading#Django では集約を生成するために 2 つの方法が用意されています。1 つめは、 全 QuerySet に対して合計値を生成する方法です。例えば、販売中の全ての書籍の平均価格を計算したい場合などです。Django のクエリ文法では、全書籍セットを表現するための方法が用意されています:
>>> Book.objects.all()\n必要なのは、この QuerySet に含まれるオブジェクトに対して合計値を計算する方法です。QuerySet に aggregate() 句を加えることで計算されます:
>>> from django.db.models import Avg\n>>> Book.objects.all().aggregate(Avg('price'))\n{'price__avg': 34.35}\n例にある all() は冗長なので、よりシンプルにできます:
>>> Book.objects.aggregate(Avg('price'))\n{'price__avg': 34.35}\naggregate() 句への引数は計算したい集約値を表します - この例では、 Book モデルの price フィールドの平均になります。 利用可能な集約関数の一覧は QuerySet リファレンス にあります。
aggregate() は QuerySet の最後の句になります。それが呼び出されると、name-value のペアの辞書が返されます。name は集計値に対する識別子です; valueは 計算された集計値です。 name はフィールド名と集計関数より自動的に生成されます。 集約値の name を手動で指定したい場合は、集約句を指定する際に名前を指定します:
>>> Book.objects.aggregate(average_price=Avg('price'))\n{'average_price': 34.35}\n2つ以上の集計を生成したい場合は、aggregate() 句に別の引数を追加します。たとえば全書籍の最高の価格と最低の価格を知りたい場合は 、以下のクエリを発行します:
>>> from django.db.models import Avg, Max, Min\n>>> Book.objects.aggregate(Avg('price'), Max('price'), Min('price'))\n{'price__avg': 34.35, 'price__max': Decimal('81.20'), 'price__min': Decimal('12.99')}\nQuerySet の各アイテムに対する集計を生成するLink to this heading#QuerySet 内の各オブジェクトに対して個別の集計を生成することもできます。たとえば、書籍の一覧を取得しようとする場合には、それぞれの書籍に寄稿している著者が何名いるのかを知りたいこともあるでしょう。 各 Book は Author に対して多対多のリレーションを持っています; この QuerySet 内で、各書籍の関係性を集計できます。
オブジェクトごとの集計は annotate() 句を使うことで生成することができ ます。 annotate() が指定されると、 QuerySet の各オブジェクトは 指定された値で注釈付け (annotate) されます。
この集計の構文は aggregate() 句で使われる構文と全く同じです。 annotate() への各引数は、計算される集計方法を記述します。 例えば、書籍を著者数で注釈付けするには:
# Build an annotated queryset\n>>> from django.db.models import Count\n>>> q = Book.objects.annotate(Count('authors'))\n# Interrogate the first object in the queryset\n>>> q[0]\n<Book: The Definitive Guide to Django>\n>>> q[0].authors__count\n2\n# Interrogate the second object in the queryset\n>>> q[1]\n<Book: Practical Django Projects>\n>>> q[1].authors__count\n1\naggregate() と同様に、注釈 (annotation) の名前は集計関数の名前と集計されるフィールドから自動的に作成されます。 注釈付けを指定する時にエイリアス名を指定すると、このデフォルトの名前をオーバーライドすることができます:
>>> q = Book.objects.annotate(num_authors=Count('authors'))\n>>> q[0].num_authors\n2\n>>> q[1].num_authors\n1\naggregate() とは違って、annotate() は最終句では ありません 。annotate() 句のアウトプットは QuerySet です; この QuerySet は、他の QuerySet の操作によって修正可能です。 filter()、order_by などに加えて、別の annotate() を追加呼び出しすることもできます。
annotate() を用いて複数の集計 (アグリゲーション) を統合することは、 誤った結果を生み出します。サブクエリの代わりに結合(JOIN)が使われるからです:
>>> book = Book.objects.first()\n>>> book.authors.count()\n2\n>>> book.store_set.count()\n3\n>>> q = Book.objects.annotate(Count('authors'), Count('store'))\n>>> q[0].authors__count\n6\n>>> q[0].store__count\n6\nほとんどの集計方法では、この問題を逃れるすべはありませんが、Count では distinct が助けになります:
>>> q = Book.objects.annotate(Count('authors', distinct=True), Count('store', distinct=True))\n>>> q[0].authors__count\n2\n>>> q[0].store__count\n3\nこれまでのところ、クエリ問い合わせされたモデルに属したフィールドに対する集計だけを見てきました。しかし、集計したい値が、クエリ問い合わせをしているモデルに関係しているモデルに属している場合もあります。
\n集計関数の中で、集計するフィールドを特定するとき、Django はフィルター内で関係するフィールドを参照するためにも使われる double underscore notation を使えるようにしています。Django は関連する値を取得し集計するために必要なテーブル結合を処理します。
\nたとえば、各店舗で販売されている書籍の価格帯を調べるために、以下のアノテーションを使うことができます。
\n>>> from django.db.models import Max, Min\n>>> Store.objects.annotate(min_price=Min('books__price'), max_price=Max('books__price'))\nこれは、Store モデルを取得し、(many-to-many リレーションシップを通じて) Book モデルと結合し、そして書籍モデルの price フィールドの最大値と最小値を計算するように、Django に通知します。
同じルールが aggregate() 句にも適用されます。全店舗で販売中の全書籍の中での最低価格と最高価格を知りたい場合は、以下の集計方法を使うことができます。
>>> Store.objects.aggregate(min_price=Min('books__price'), max_price=Max('books__price'))\n結合チェーンは、必要なだけ深くできます。たとえば、販売可能な書籍のうち最年少の著者の年齢を抽出するには、次のクエリを発行できます。
\n>>> Store.objects.aggregate(youngest_age=Min('books__authors__age'))\nリレーションを横断するルックアップ と似たように、モデルのフィールドやモデルのリレーションに関する集計は"後ろ向きの"リレーションを含むことができます。ここでも小文字にしたモデル名と2つのアンダースコアが用いられます。
\nたとえば全ての出版社に対して、その出版社に対してリレーションをもつ本の数を集計することができます。（'book' という名前で Publisher -> Book の逆向きの外部キーを指定できることに注意してください）:
>>> from django.db.models import Avg, Count, Min, Sum\n>>> Publisher.objects.annotate(Count('book'))\n(QuerySet に含まれる全ての Publisher には book__count という名前の属性が追加されます。)
また、全ての出版社に対して、その出版社のもっとも古い本の出版日を集計することもできます:
\n>>> Publisher.objects.aggregate(oldest_pubdate=Min('book__pubdate'))\n(結果は 'oldest_pubdate' というキーで参照できるようになります。もしこのように別名を指定しなければ、キーの名前は 'book__pubdate__min' のように長くなります。)
多対多これらが使用できるのは外部キーだけではありません。多対多のリレーションでも利用できます。例えば全ての著者に対して、それぞれが書いた本のページ数の合計を集計することができます。 ('book' という名前で Author -> Book の逆向きリレーションを指定できることに注意してください):
>>> Author.objects.annotate(total_pages=Sum('book__pages'))\n(QuerySet に含まれる Author は total_pages 属性を持ちます。別名が指定されなければ、 book__pages__sum のようになります。)
または書いた本の評価の平均を集計することもできます:
\n>>> Author.objects.aggregate(average_rating=Avg('book__rating'))\n(結果は average_rating 属性を持ちます。別名が指定されなければ、 book__rating__avg のように長くなります。)
filter() と exclude()Link to this heading#集計はフィルタと一緒に使うこともできます。通常のモデルフィールドに適用される全ての filter() (または exclude()) は集計に利用できるオブジェクトを構築します。
annotate() 句とともに使われた場合、フィルタは集計を計算するオブジェクトを決定するのに使われます。たとえば、"Django"で始まる本のリストを集計とともに生成することができます:
>>> from django.db.models import Avg, Count\n>>> Book.objects.filter(name__startswith="Django").annotate(num_authors=Count('authors'))\nWhen used with an aggregate() clause, a filter has the effect of\nconstraining the objects over which the aggregate is calculated.\nFor example, you can generate the average price of all books with a\ntitle that starts with "Django" using the query:
>>> Book.objects.filter(name__startswith="Django").aggregate(Avg('price'))\nAnnotated values can also be filtered. The alias for the annotation can be\nused in filter() and exclude() clauses in the same way as any other\nmodel field.
For example, to generate a list of books that have more than one author,\nyou can issue the query:
\n>>> Book.objects.annotate(num_authors=Count('authors')).filter(num_authors__gt=1)\nThis query generates an annotated result set, and then generates a filter\nbased upon that annotation.
\nIf you need two annotations with two separate filters you can use the\nfilter argument with any aggregate. For example, to generate a list of\nauthors with a count of highly rated books:
>>> highly_rated = Count('book', filter=Q(book__rating__gte=7))\n>>> Author.objects.annotate(num_books=Count('book'), highly_rated_books=highly_rated)\nEach Author in the result set will have the num_books and\nhighly_rated_books attributes. See also Conditional aggregation.
annotate() and filter() clausesLink to this heading#When developing a complex query that involves both annotate() and\nfilter() clauses, pay particular attention to the order in which the\nclauses are applied to the QuerySet.
When an annotate() clause is applied to a query, the annotation is computed\nover the state of the query up to the point where the annotation is requested.\nThe practical implication of this is that filter() and annotate() are\nnot commutative operations.
Given:
\nPublisher A has two books with ratings 4 and 5.
Publisher B has two books with ratings 1 and 4.
Publisher C has one book with rating 1.
Here's an example with the Count aggregate:
>>> a, b = Publisher.objects.annotate(num_books=Count('book', distinct=True)).filter(book__rating__gt=3.0)\n>>> a, a.num_books\n(<Publisher: A>, 2)\n>>> b, b.num_books\n(<Publisher: B>, 2)\n\n>>> a, b = Publisher.objects.filter(book__rating__gt=3.0).annotate(num_books=Count('book'))\n>>> a, a.num_books\n(<Publisher: A>, 2)\n>>> b, b.num_books\n(<Publisher: B>, 1)\nBoth queries return a list of publishers that have at least one book with a\nrating exceeding 3.0, hence publisher C is excluded.
\nIn the first query, the annotation precedes the filter, so the filter has no\neffect on the annotation. distinct=True is required to avoid a query\nbug.
The second query counts the number of books that have a rating exceeding 3.0\nfor each publisher. The filter precedes the annotation, so the filter\nconstrains the objects considered when calculating the annotation.
\nHere's another example with the Avg aggregate:
>>> a, b = Publisher.objects.annotate(avg_rating=Avg('book__rating')).filter(book__rating__gt=3.0)\n>>> a, a.avg_rating\n(<Publisher: A>, 4.5) # (5+4)/2\n>>> b, b.avg_rating\n(<Publisher: B>, 2.5) # (1+4)/2\n\n>>> a, b = Publisher.objects.filter(book__rating__gt=3.0).annotate(avg_rating=Avg('book__rating'))\n>>> a, a.avg_rating\n(<Publisher: A>, 4.5) # (5+4)/2\n>>> b, b.avg_rating\n(<Publisher: B>, 4.0) # 4/1 (book with rating 1 excluded)\nThe first query asks for the average rating of all a publisher's books for\npublisher's that have at least one book with a rating exceeding 3.0. The second\nquery asks for the average of a publisher's book's ratings for only those\nratings exceeding 3.0.
\nIt's difficult to intuit how the ORM will translate complex querysets into SQL\nqueries so when in doubt, inspect the SQL with str(queryset.query) and\nwrite plenty of tests.
order_by()Link to this heading#Annotations can be used as a basis for ordering. When you\ndefine an order_by() clause, the aggregates you provide can reference\nany alias defined as part of an annotate() clause in the query.
For example, to order a QuerySet of books by the number of authors\nthat have contributed to the book, you could use the following query:
>>> Book.objects.annotate(num_authors=Count('authors')).order_by('num_authors')\nvalues()Link to this heading#Ordinarily, annotations are generated on a per-object basis - an annotated\nQuerySet will return one result for each object in the original\nQuerySet. However, when a values() clause is used to constrain the\ncolumns that are returned in the result set, the method for evaluating\nannotations is slightly different. Instead of returning an annotated result\nfor each result in the original QuerySet, the original results are\ngrouped according to the unique combinations of the fields specified in the\nvalues() clause. An annotation is then provided for each unique group;\nthe annotation is computed over all members of the group.
For example, consider an author query that attempts to find out the average\nrating of books written by each author:
\n>>> Author.objects.annotate(average_rating=Avg('book__rating'))\nThis will return one result for each author in the database, annotated with\ntheir average book rating.
\nHowever, the result will be slightly different if you use a values() clause:
>>> Author.objects.values('name').annotate(average_rating=Avg('book__rating'))\nIn this example, the authors will be grouped by name, so you will only get\nan annotated result for each unique author name. This means if you have\ntwo authors with the same name, their results will be merged into a single\nresult in the output of the query; the average will be computed as the\naverage over the books written by both authors.
\nannotate() and values() clausesLink to this heading#As with the filter() clause, the order in which annotate() and\nvalues() clauses are applied to a query is significant. If the\nvalues() clause precedes the annotate(), the annotation will be\ncomputed using the grouping described by the values() clause.
However, if the annotate() clause precedes the values() clause,\nthe annotations will be generated over the entire query set. In this case,\nthe values() clause only constrains the fields that are generated on\noutput.
For example, if we reverse the order of the values() and annotate()\nclause from our previous example:
>>> Author.objects.annotate(average_rating=Avg('book__rating')).values('name', 'average_rating')\nThis will now yield one unique result for each author; however, only\nthe author's name and the average_rating annotation will be returned\nin the output data.
You should also note that average_rating has been explicitly included\nin the list of values to be returned. This is required because of the\nordering of the values() and annotate() clause.
If the values() clause precedes the annotate() clause, any annotations\nwill be automatically added to the result set. However, if the values()\nclause is applied after the annotate() clause, you need to explicitly\ninclude the aggregate column.
order_by()Link to this heading#Fields that are mentioned in the order_by() part of a queryset are used\nwhen selecting the output data, even if they are not otherwise specified in the\nvalues() call. These extra fields are used to group "like" results together\nand they can make otherwise identical result rows appear to be separate. This\nshows up, particularly, when counting things.
By way of example, suppose you have a model like this:
\nfrom django.db import models\n\nclass Item(models.Model):\n name = models.CharField(max_length=10)\n data = models.IntegerField()\nIf you want to count how many times each distinct data value appears in an\nordered queryset, you might try this:
items = Item.objects.order_by('name')\n# Warning: not quite correct!\nitems.values('data').annotate(Count('id'))\n...which will group the Item objects by their common data values and\nthen count the number of id values in each group. Except that it won't\nquite work. The ordering by name will also play a part in the grouping, so\nthis query will group by distinct (data, name) pairs, which isn't what you\nwant. Instead, you should construct this queryset:
items.values('data').annotate(Count('id')).order_by()\n...clearing any ordering in the query. You could also order by, say, data\nwithout any harmful effects, since that is already playing a role in the\nquery.
This behavior is the same as that noted in the queryset documentation for\ndistinct() and the general rule is the\nsame: normally you won't want extra columns playing a part in the result, so\nclear out the ordering, or at least make sure it's restricted only to those\nfields you also select in a values() call.
You can also generate an aggregate on the result of an annotation. When you\ndefine an aggregate() clause, the aggregates you provide can reference\nany alias defined as part of an annotate() clause in the query.
For example, if you wanted to calculate the average number of authors per\nbook you first annotate the set of books with the author count, then\naggregate that author count, referencing the annotation field:
\n>>> from django.db.models import Avg, Count\n>>> Book.objects.annotate(num_authors=Count('authors')).aggregate(Avg('num_authors'))\n{'num_authors__avg': 1.66}\n