Django 文檔協(xié)作翻譯小組人手緊缺港谊，有興趣的朋友可以加入我們浑此，完全公益性質(zhì)西乖。

交流群：467338606

網(wǎng)站：http://python.usyiyi.cn/django/index.html

聚合

Django數(shù)據(jù)庫(kù)抽象API描述了使用Django查詢(xún)來(lái)增刪查改單個(gè)對(duì)象的方法侣集。然而允跑，你有時(shí)候會(huì)想要獲取從一組對(duì)象導(dǎo)出的值或者是聚合一組對(duì)象王凑。這份指南描述了通過(guò)Django查詢(xún)來(lái)生成和返回聚合值的方法。

整篇指南我們都將引用以下模型聋丝。這些模型用來(lái)記錄多個(gè)網(wǎng)上書(shū)店的庫(kù)存索烹。

from django.db import models

class Author(models.Model):
    name = models.CharField(max_length=100)
    age = models.IntegerField()

class Publisher(models.Model):
    name = models.CharField(max_length=300)
    num_awards = models.IntegerField()

class Book(models.Model):
    name = models.CharField(max_length=300)
    pages = models.IntegerField()
    price = models.DecimalField(max_digits=10, decimal_places=2)
    rating = models.FloatField()
    authors = models.ManyToManyField(Author)
    publisher = models.ForeignKey(Publisher)
    pubdate = models.DateField()

class Store(models.Model):
    name = models.CharField(max_length=300)
    books = models.ManyToManyField(Book)
    registered_users = models.PositiveIntegerField()

速查表

急著用嗎？以下是在上述模型的基礎(chǔ)上弱睦，進(jìn)行一般的聚合查詢(xún)的方法:

# Total number of books.
>>> Book.objects.count()
2452

# Total number of books with publisher=BaloneyPress
>>> Book.objects.filter(publisher__name='BaloneyPress').count()
73

# Average price across all books.
>>> from django.db.models import Avg
>>> Book.objects.all().aggregate(Avg('price'))
{'price__avg': 34.35}

# Max price across all books.
>>> from django.db.models import Max
>>> Book.objects.all().aggregate(Max('price'))
{'price__max': Decimal('81.20')}

# Cost per page
>>> Book.objects.all().aggregate(
...    price_per_page=Sum(F('price')/F('pages'), output_field=FloatField()))
{'price_per_page': 0.4470664529184653}

# All the following queries involve traversing the Book<->Publisher
# many-to-many relationship backward

# Each publisher, each with a count of books as a "num_books" attribute.
>>> from django.db.models import Count
>>> pubs = Publisher.objects.annotate(num_books=Count('book'))
>>> pubs
[<Publisher BaloneyPress>, <Publisher SalamiPress>, ...]
>>> pubs[0].num_books
73

# The top 5 publishers, in order by number of books.
>>> pubs = Publisher.objects.annotate(num_books=Count('book')).order_by('-num_books')[:5]
>>> pubs[0].num_books
1323

在查詢(xún)集上生成聚合

Django提供了兩種生成聚合的方法百姓。第一種方法是從整個(gè)查詢(xún)集生成統(tǒng)計(jì)值。比如况木，你想要計(jì)算所有在售書(shū)的平均價(jià)錢(qián)垒拢。Django的查詢(xún)語(yǔ)法提供了一種方式描述所有圖書(shū)的集合旬迹。

>>> Book.objects.all()

我們需要在QuerySet.對(duì)象上計(jì)算出總價(jià)格。這可以通過(guò)在QuerySet后面附加aggregate() 子句來(lái)完成求类。

>>> from django.db.models import Avg
>>> Book.objects.all().aggregate(Avg('price'))
{'price__avg': 34.35}

all()在這里是多余的奔垦，所以可以簡(jiǎn)化為：

>>> Book.objects.aggregate(Avg('price'))
{'price__avg': 34.35}

aggregate()子句的參數(shù)描述了我們想要計(jì)算的聚合值，在這個(gè)例子中尸疆，是Book 模型中price字段的平均值椿猎。查詢(xún)集參考中列出了聚合函數(shù)的列表。

aggregate()是QuerySet 的一個(gè)終止子句寿弱，意思是說(shuō)犯眠，它返回一個(gè)包含一些鍵值對(duì)的字典。鍵的名稱(chēng)是聚合值的標(biāo)識(shí)符症革，值是計(jì)算出來(lái)的聚合值筐咧。鍵的名稱(chēng)是按照字段和聚合函數(shù)的名稱(chēng)自動(dòng)生成出來(lái)的。如果你想要為聚合值指定一個(gè)名稱(chēng)地沮，可以向聚合子句提供它嗜浮。

>>> Book.objects.aggregate(average_price=Avg('price'))
{'average_price': 34.35}

如果你希望生成不止一個(gè)聚合，你可以向aggregate()子句中添加另一個(gè)參數(shù)摩疑。所以危融，如果你也想知道所有圖書(shū)價(jià)格的最大值和最小值，可以這樣查詢(xún)：

>>> from django.db.models import Avg, Max, Min
>>> Book.objects.aggregate(Avg('price'), Max('price'), Min('price'))
{'price__avg': 34.35, 'price__max': Decimal('81.20'), 'price__min': Decimal('12.99')}

為查詢(xún)集的每一項(xiàng)生成聚合

生成匯總值的第二種方法雷袋，是為QuerySet中每一個(gè)對(duì)象都生成一個(gè)獨(dú)立的匯總值吉殃。比如，如果你在檢索一列圖書(shū)楷怒，你可能想知道有多少作者寫(xiě)了每一本書(shū)蛋勺。每本書(shū)和作者是多對(duì)多的關(guān)系。我們想要匯總QuerySet.中每本書(shū)里的這種關(guān)系鸠删。

逐個(gè)對(duì)象的匯總結(jié)果可以由annotate()子句生成抱完。當(dāng)annotate()子句被指定之后，QuerySet中的每個(gè)對(duì)象都會(huì)被注上特定的值刃泡。

這些注解的語(yǔ)法都和aggregate()子句所使用的相同巧娱。annotate()的每個(gè)參數(shù)都描述了將要被計(jì)算的聚合。比如烘贴，給圖書(shū)添加作者數(shù)量的注解：

# Build an annotated queryset
>>> from django.db.models import Count
>>> q = Book.objects.annotate(Count('authors'))
# Interrogate the first object in the queryset
>>> q[0]
<Book: The Definitive Guide to Django>
>>> q[0].authors__count
2
# Interrogate the second object in the queryset
>>> q[1]
<Book: Practical Django Projects>
>>> q[1].authors__count
1

和使用 aggregate()一樣禁添，注解的名稱(chēng)也根據(jù)聚合函式的名稱(chēng)和聚合字段的名稱(chēng)得到的。你可以在指定注解時(shí)桨踪，為默認(rèn)名稱(chēng)提供一個(gè)別名：

>>> q = Book.objects.annotate(num_authors=Count('authors'))
>>> q[0].num_authors
2
>>> q[1].num_authors
1

與 aggregate() 不同的是老翘， annotate() 不是一個(gè)終止子句。annotate()子句的返回結(jié)果是一個(gè)查詢(xún)集 (QuerySet)；這個(gè) QuerySet可以用任何QuerySet方法進(jìn)行修改铺峭，包括 filter(), order_by(), 甚至是再次應(yīng)用annotate()墓怀。

有任何疑問(wèn)的話(huà)，請(qǐng)檢查 SQL query卫键！

要想弄清楚你的查詢(xún)到底發(fā)生了什么捺疼，可以考慮檢查你QuerySet的 query 屬性。

例如永罚，在annotate() 中混入多個(gè)聚合將會(huì)得出錯(cuò)誤的結(jié)果啤呼，因?yàn)槎鄠€(gè)表上做了交叉連接，導(dǎo)致了多余的行聚合呢袱。

連接和聚合

至此官扣，我們已經(jīng)了解了作用于單種模型實(shí)例的聚合操作， 但是有時(shí)羞福，你也想對(duì)所查詢(xún)對(duì)象的關(guān)聯(lián)對(duì)象進(jìn)行聚合惕蹄。

在聚合函式中指定聚合字段時(shí)，Django 允許你使用同樣的 雙下劃線(xiàn) 表示關(guān)聯(lián)關(guān)系治专，然后 Django 在就會(huì)處理要讀取的關(guān)聯(lián)表卖陵，并得到關(guān)聯(lián)對(duì)象的聚合。

例如张峰，要得到每個(gè)書(shū)店的價(jià)格區(qū)別泪蔫，可以使用如下注解：

>>> from django.db.models import Max, Min
>>> Store.objects.annotate(min_price=Min('books__price'), max_price=Max('books__price'))

這段代碼告訴 Django 獲取書(shū)店模型，并連接(通過(guò)多對(duì)多關(guān)系)圖書(shū)模型喘批，然后對(duì)每本書(shū)的價(jià)格進(jìn)行聚合撩荣，得出最小值和最大值。

同樣的規(guī)則也用于 aggregate() 子句饶深。如果你想知道所有書(shū)店中最便宜的書(shū)和最貴的書(shū)價(jià)格分別是多少：

>>> Store.objects.aggregate(min_price=Min('books__price'), max_price=Max('books__price'))

關(guān)系鏈可以按你的要求一直延伸餐曹。 例如，想得到所有作者當(dāng)中最小的年齡是多少敌厘，就可以這樣寫(xiě)：

>>> Store.objects.aggregate(youngest_age=Min('books__authors__age'))

遵循反向關(guān)系

和 跨關(guān)系查找的方法類(lèi)似台猴，作用在你所查詢(xún)的模型的關(guān)聯(lián)模型或者字段上的聚合和注解可以遍歷"反轉(zhuǎn)"關(guān)系。關(guān)聯(lián)模型的小寫(xiě)名稱(chēng)和雙下劃線(xiàn)也用在這里俱两。

例如饱狂，我們可以查詢(xún)所有出版商，并注上它們一共出了多少本書(shū)（注意我們?nèi)绾斡?'book'指定Publisher -> Book 的外鍵反轉(zhuǎn)關(guān)系）：

>>> from django.db.models import Count, Min, Sum, Avg
>>> Publisher.objects.annotate(Count('book'))

QuerySet結(jié)果中的每一個(gè)Publisher都會(huì)包含一個(gè)額外的屬性叫做book__count锋华。

我們也可以按照每個(gè)出版商嗡官，查詢(xún)所有圖書(shū)中最舊的那本：

>>> Publisher.objects.aggregate(oldest_pubdate=Min('book__pubdate'))

（返回的字典會(huì)包含一個(gè)鍵叫做 'oldest_pubdate'箭窜。如果沒(méi)有指定這樣的別名毯焕，它會(huì)更長(zhǎng)一些，像 'book__pubdate__min'。）

這不僅僅可以應(yīng)用掛在外鍵上面纳猫。還可以用到多對(duì)多關(guān)系上婆咸。例如，我們可以查詢(xún)每個(gè)作者芜辕，注上它寫(xiě)的所有書(shū)（以及合著的書(shū)）一共有多少頁(yè)（注意我們?nèi)绾问褂?'book'來(lái)指定Author -> Book的多對(duì)多的反轉(zhuǎn)關(guān)系）：

>>> Author.objects.annotate(total_pages=Sum('book__pages'))

（每個(gè)返回的QuerySet中的Author 都有一個(gè)額外的屬性叫做total_pages尚骄。如果沒(méi)有指定這樣的別名，它會(huì)更長(zhǎng)一些侵续，像 book__pages__sum倔丈。）

或者查詢(xún)所有圖書(shū)的平均評(píng)分，這些圖書(shū)由我們存檔過(guò)的作者所寫(xiě)：

>>> Author.objects.aggregate(average_rating=Avg('book__rating'))

（返回的字典會(huì)包含一個(gè)鍵叫做'average__rating'状蜗。如果沒(méi)有指定這樣的別名需五，它會(huì)更長(zhǎng)一些，像'book__rating__avg'轧坎。）

聚合和其他查詢(xún)集子句

filter() 和 exclude()

聚合也可以在過(guò)濾器中使用宏邮。 作用于普通模型字段的任何 filter()(或 exclude()) 都會(huì)對(duì)聚合涉及的對(duì)象進(jìn)行限制。

使用annotate() 子句時(shí)缸血，過(guò)濾器有限制注解對(duì)象的作用蜜氨。例如，你想得到以 "Django" 為書(shū)名開(kāi)頭的圖書(shū)作者的總數(shù)：

>>> from django.db.models import Count, Avg
>>> Book.objects.filter(name__startswith="Django").annotate(num_authors=Count('authors'))

使用aggregate()子句時(shí)捎泻，過(guò)濾器有限制聚合對(duì)象的作用飒炎。例如，你可以算出所有以 "Django" 為書(shū)名開(kāi)頭的圖書(shū)平均價(jià)格：

>>> Book.objects.filter(name__startswith="Django").aggregate(Avg('price'))

對(duì)注解過(guò)濾

注解值也可以被過(guò)濾笆豁。 像使用其他模型字段一樣厌丑，注解也可以在filter()和exclude() 子句中使用別名。

例如渔呵，要得到不止一個(gè)作者的圖書(shū)怒竿，可以用：

>>> Book.objects.annotate(num_authors=Count('authors')).filter(num_authors__gt=1)

這個(gè)查詢(xún)首先生成一個(gè)注解結(jié)果，然后再生成一個(gè)作用于注解上的過(guò)濾器扩氢。

annotate() 的順序

編寫(xiě)一個(gè)包含 annotate() 和 filter() 子句的復(fù)雜查詢(xún)時(shí)耕驰，要特別注意作用于 QuerySet的子句的順序。

當(dāng)一個(gè)annotate() 子句作用于某個(gè)查詢(xún)時(shí)录豺，要根據(jù)查詢(xún)的狀態(tài)才能得出注解值朦肘，而狀態(tài)由 annotate() 位置所決定。以這就導(dǎo)致filter() 和 annotate() 不能交換順序双饥，下面兩個(gè)查詢(xún)就是不同的：

>>> Publisher.objects.annotate(num_books=Count('book')).filter(book__rating__gt=3.0)

另一個(gè)查詢(xún)：

>>> Publisher.objects.filter(book__rating__gt=3.0).annotate(num_books=Count('book'))

兩個(gè)查詢(xún)都返回了至少出版了一本好書(shū)(評(píng)分大于 3 分)的出版商媒抠。 但是第一個(gè)查詢(xún)的注解包含其該出版商發(fā)行的所有圖書(shū)的總數(shù)；而第二個(gè)查詢(xún)的注解只包含出版過(guò)好書(shū)的出版商的所發(fā)行的圖書(shū)總數(shù)咏花。 在第一個(gè)查詢(xún)中趴生，注解在過(guò)濾器之前阀趴，所以過(guò)濾器對(duì)注解沒(méi)有影響。 在第二個(gè)查詢(xún)中苍匆，過(guò)濾器在注解之前刘急，所以，在計(jì)算注解值時(shí)浸踩，過(guò)濾器就限制了參與運(yùn)算的對(duì)象的范圍叔汁。

order_by()

注解可以用來(lái)做為排序項(xiàng)。 在你定義 order_by() 子句時(shí)检碗，你提供的聚合可以引用定義的任何別名做為查詢(xún)中 annotate()子句的一部分据块。

例如，根據(jù)一本圖書(shū)作者數(shù)量的多少對(duì)查詢(xún)集 QuerySet進(jìn)行排序：

>>> Book.objects.annotate(num_authors=Count('authors')).order_by('num_authors')

values()

通常折剃，注解會(huì)添加到每個(gè)對(duì)象上 —— 一個(gè)被注解的QuerySet會(huì)為初始QuerySet的每個(gè)對(duì)象返回一個(gè)結(jié)果集瑰钮。但是，如果使用了values()子句微驶，它就會(huì)限制結(jié)果中列的范圍浪谴，對(duì)注解賦值的方法就會(huì)完全不同。不是在原始的 QuerySet返回結(jié)果中對(duì)每個(gè)對(duì)象中添加注解因苹，而是根據(jù)定義在values() 子句中的字段組合對(duì)先結(jié)果進(jìn)行唯一的分組苟耻，再根據(jù)每個(gè)分組算出注解值， 這個(gè)注解值是根據(jù)分組中所有的成員計(jì)算而得的：

例如扶檐，考慮一個(gè)關(guān)于作者的查詢(xún)凶杖，查詢(xún)出每個(gè)作者所寫(xiě)的書(shū)的平均評(píng)分：

>>> Author.objects.annotate(average_rating=Avg('book__rating'))

這段代碼返回的是數(shù)據(jù)庫(kù)中所有的作者以及他們所著圖書(shū)的平均評(píng)分。

但是如果你使用了values()子句款筑，結(jié)果是完全不同的：

>>> Author.objects.values('name').annotate(average_rating=Avg('book__rating'))

在這個(gè)例子中智蝠，作者會(huì)按名稱(chēng)分組，所以你只能得到某個(gè)唯一的作者分組的注解值奈梳。 這意味著如果你有兩個(gè)作者同名杈湾，那么他們?cè)靖髯缘牟樵?xún)結(jié)果將被合并到同一個(gè)結(jié)果中；兩個(gè)作者的所有評(píng)分都將被計(jì)算為一個(gè)平均分攘须。

annotate() 的順序

和使用 filter() 子句一樣靡馁，作用于某個(gè)查詢(xún)的annotate() 和 values() 子句的使用順序是非常重要的秧饮。如果values() 子句在 annotate() 之前芒涡，就會(huì)根據(jù) values() 子句產(chǎn)生的分組來(lái)計(jì)算注解吁峻。

但是，如果 annotate() 子句在 values()子句之前捞魁，就會(huì)根據(jù)整個(gè)查詢(xún)集生成注解至会。在這種情況下，values() 子句只能限制輸出的字段范圍谱俭。

舉個(gè)例子奉件，如果我們互換了上個(gè)例子中 values()和 annotate() 子句的順序：

>>> Author.objects.annotate(average_rating=Avg('book__rating')).values('name', 'average_rating')

這段代碼將給每個(gè)作者添加一個(gè)唯一的字段宵蛀，但只有作者名稱(chēng)和average_rating 注解會(huì)返回在輸出結(jié)果中。

你也應(yīng)該注意到 average_rating 顯式地包含在返回的列表當(dāng)中瓶蚂。之所以這么做的原因正是因?yàn)関alues() 和 annotate() 子句。

如果 values() 子句在 annotate() 子句之前宣吱，注解會(huì)被自動(dòng)添加到結(jié)果集中窃这；但是，如果 values() 子句作用于annotate() 子句之后征候，你需要顯式地包含聚合列杭攻。

與默認(rèn)排序或order_by()交互

在查詢(xún)集中的order_by() 部分(或是在模型中默認(rèn)定義的排序項(xiàng)) 會(huì)在選擇輸出數(shù)據(jù)時(shí)被用到，即使這些字段沒(méi)有在values() 調(diào)用中被指定疤坝。這些額外的字段可以將相似的數(shù)據(jù)行分在一起兆解，也可以讓相同的數(shù)據(jù)行相分離。在做計(jì)數(shù)時(shí)跑揉，就會(huì)表現(xiàn)地格外明顯：

通過(guò)例子中的方法锅睛，假設(shè)有一個(gè)這樣的模型：

from django.db import models

class Item(models.Model):
    name = models.CharField(max_length=10)
    data = models.IntegerField()

    class Meta:
        ordering = ["name"]

關(guān)鍵的部分就是在模型默認(rèn)排序項(xiàng)中設(shè)置的name字段。如果你想知道每個(gè)非重復(fù)的data值出現(xiàn)的次數(shù)历谍，可以這樣寫(xiě)：

# Warning: not quite correct!
Item.objects.values("data").annotate(Count("id"))

...這部分代碼想通過(guò)使用它們公共的 data 值來(lái)分組 Item對(duì)象现拒，然后在每個(gè)分組中得到 id 值的總數(shù)。但是上面那樣做是行不通的望侈。這是因?yàn)槟J(rèn)排序項(xiàng)中的 name也是一個(gè)分組項(xiàng)印蔬，所以這個(gè)查詢(xún)會(huì)根據(jù)非重復(fù)的 (data, name) 進(jìn)行分組，而這并不是你本來(lái)想要的結(jié)果脱衙。所以侥猬，你應(yīng)該這樣改寫(xiě)：

Item.objects.values("data").annotate(Count("id")).order_by()

...這樣就清空了查詢(xún)中的所有排序項(xiàng)。 你也可以在其中使用 data 捐韩，這樣并不會(huì)有副作用退唠，這是因?yàn)椴樵?xún)分組中只有這么一個(gè)角色了。

這個(gè)行為與查詢(xún)集文檔中提到的 distinct() 一樣荤胁，而且生成規(guī)則也一樣：一般情況下铜邮，你不想在結(jié)果中由額外的字段扮演這個(gè)角色，那就清空排序項(xiàng)寨蹋，或是至少保證它僅能訪問(wèn) values()中的字段松蒜。

注意

你可能想知道為什么 Django 不刪除與你無(wú)關(guān)的列。主要原因就是要保證使用 distinct()和其他方法的一致性已旧。Django 永遠(yuǎn)不會(huì) 刪除你所指定的排序限制(我們不能改動(dòng)那些方法的行為秸苗，因?yàn)檫@會(huì)違背 API stability 原則)。

聚合注解

你也可以在注解的結(jié)果上生成聚合运褪。 當(dāng)你定義一個(gè) aggregate() 子句時(shí)惊楼，你提供的聚合會(huì)引用定義的任何別名做為查詢(xún)中 annotate() 子句的一部分玖瘸。

例如，如果你想計(jì)算每本書(shū)平均有幾個(gè)作者檀咙，你先用作者總數(shù)注解圖書(shū)集雅倒，然后再聚合作者總數(shù)，引入注解字段：

>>> from django.db.models import Count, Avg
>>> Book.objects.annotate(num_authors=Count('authors')).aggregate(Avg('num_authors'))
{'num_authors__avg': 1.66}