I ämnesguiden om Djangos databasabstraktions-API beskrivs hur du kan använda Django-frågor som skapar, hämtar, uppdaterar och tar bort enskilda objekt. Ibland behöver du dock hämta värden som härleds genom att sammanfatta eller aggregera en samling objekt. I den här ämnesguiden beskrivs hur aggregerade värden kan genereras och returneras med hjälp av Django-frågor.
\nI den här guiden hänvisar vi till följande modeller. Dessa modeller används för att spåra lagret för en serie onlinebokhandlar:
\nfrom django.db import models\n\n\nclass Author(models.Model):\n name = models.CharField(max_length=100)\n age = models.IntegerField()\n\n\nclass Publisher(models.Model):\n name = models.CharField(max_length=300)\n\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\n\nclass Store(models.Model):\n name = models.CharField(max_length=300)\n books = models.ManyToManyField(Book)\nHar du bråttom? Så här gör du vanliga aggregerade frågor, förutsatt att modellerna ovan används:
\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, provide default to be returned instead\n# of None if no books exist.\n>>> from django.db.models import Avg\n>>> Book.objects.aggregate(Avg("price", default=0))\n{'price__avg': 34.35}\n\n# Max price across all books, provide default to be returned instead of\n# None if no books exist.\n>>> from django.db.models import Max\n>>> Book.objects.aggregate(Max("price", default=0))\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... )\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\nQuerySetLink to this heading#Django erbjuder två sätt att generera aggregat. Det första sättet är att generera sammanfattningsvärden över en hel QuerySet. Säg till exempel att du vill beräkna genomsnittspriset för alla böcker som finns till försäljning. Djangos frågesyntax ger ett sätt att beskriva uppsättningen av alla böcker:
>>> Book.objects.all()\nVad vi behöver är ett sätt att beräkna sammanfattande värden över de objekt som tillhör detta QuerySet. Detta görs genom att lägga till en aggregate() klausul på QuerySet:
>>> from django.db.models import Avg\n>>> Book.objects.all().aggregate(Avg("price"))\n{'price__avg': 34.35}\nall() är överflödigt i detta exempel, så detta kan förenklas till:
>>> Book.objects.aggregate(Avg("price"))\n{'price__avg': 34.35}\nArgumentet till klausulen aggregate() beskriver det aggregerade värde som vi vill beräkna - i det här fallet genomsnittet av fältet price i modellen Book. En lista över de aggregatfunktioner som finns tillgängliga finns i QuerySet reference.
aggregate() är en terminalklausul för en QuerySet som, när den anropas, returnerar en ordbok med namn-värde-par. Namnet är en identifierare för aggregatvärdet; värdet är det beräknade aggregatet. Namnet genereras automatiskt från fältets namn och aggregatfunktionen. Om du manuellt vill ange ett namn för det aggregerade värdet kan du göra det genom att ange namnet när du anger aggregatklausulen:
>>> Book.objects.aggregate(average_price=Avg("price"))\n{'average_price': 34.35}\nOm du vill generera mer än ett aggregat lägger du till ytterligare ett argument i aggregate()-satsen. Så om vi också ville veta det högsta och lägsta priset för alla böcker skulle vi ställa frågan:
>>> 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')}\nQuerySetLink to this heading#Det andra sättet att generera sammanfattningsvärden är att generera en oberoende sammanfattning för varje objekt i en QuerySet. Om du t.ex. hämtar en lista med böcker kanske du vill veta hur många författare som har bidragit till varje bok. Varje bok har en många-till-många-relation med författaren; vi vill sammanfatta denna relation för varje bok i QuerySet.
Sammanfattningar per objekt kan genereras med hjälp av klausulen annotate(). När en annotate()-sats anges kommer varje objekt i QuerySet att annoteras med de angivna värdena.
Syntaxen för dessa annoteringar är identisk med den som används för aggregate()-klausulen. Varje argument till annotate() beskriver ett aggregat som ska beräknas. Till exempel, för att annotera böcker med antalet författare:
# 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\nPrecis som för aggregate() härleds namnet på annotationen automatiskt från namnet på aggregatfunktionen och namnet på det fält som ska aggregeras. Du kan åsidosätta detta standardnamn genom att ange ett alias när du specificerar annotationen:
>>> q = Book.objects.annotate(num_authors=Count("authors"))\n>>> q[0].num_authors\n2\n>>> q[1].num_authors\n1\nTill skillnad från aggregate() är annotate() inte en terminalsats. Resultatet av annotate()-satsen är en QuerySet; denna QuerySet kan modifieras med vilken annan QuerySet-operation som helst, inklusive filter(), order_by() eller till och med ytterligare anrop till annotate().
Att kombinera flera aggregeringar med annotate() kommer att ge fel resultat eftersom joins används istället för subqueries:
>>> 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\nFör de flesta aggregat finns det inget sätt att undvika detta problem, men Count-aggregatet har en distinct-parameter som kan hjälpa till:
>>> q = Book.objects.annotate(\n... Count("authors", distinct=True), Count("store", distinct=True)\n... )\n>>> q[0].authors__count\n2\n>>> q[0].store__count\n3\nHittills har vi behandlat aggregeringar över fält som tillhör den modell som efterfrågas. Ibland kommer dock det värde som du vill aggregera att tillhöra en modell som är relaterad till den modell som du frågar efter.
\nNär du anger fältet som ska aggregeras i en aggregatfunktion tillåter Django dig att använda samma double underscore notation som används när du hänvisar till relaterade fält i filter. Django kommer då att hantera eventuella tabelljoins som krävs för att hämta och aggregera det relaterade värdet.
\nFör att till exempel hitta prisintervallet för böcker som erbjuds i varje butik kan du använda annotationen:
\n>>> from django.db.models import Max, Min\n>>> Store.objects.annotate(min_price=Min("books__price"), max_price=Max("books__price"))\nDetta säger till Django att hämta Store-modellen, ansluta (genom många-till-många-relationen) till Book-modellen och aggregera på prisfältet i bokmodellen för att producera ett lägsta och högsta värde.
Samma regler gäller för klausulen aggregate(). Om du vill veta det lägsta och högsta priset för en bok som finns till försäljning i någon av butikerna kan du använda aggregatet:
>>> Store.objects.aggregate(min_price=Min("books__price"), max_price=Max("books__price"))\nJoin-kedjorna kan vara så djupa som du vill. Om du t.ex. vill få fram åldern på den yngsta författaren till en bok som finns till försäljning kan du ställa frågan:
\n>>> Store.objects.aggregate(youngest_age=Min("books__authors__age"))\nPå ett sätt som liknar Uppslagningar som sträcker sig över relationer kan aggregeringar och annoteringar av fält i modeller eller modeller som är relaterade till den modell du söker efter inkludera genomgång av ”omvända” relationer. Namnet med små bokstäver på relaterade modeller och dubbla understreck används även här.
\nVi kan till exempel be om alla förlag, annoterade med deras respektive totala boklagerräknare (notera hur vi använder 'book för att ange Publisher -> Book omvänd främmande nyckelhopp):
>>> from django.db.models import Avg, Count, Min, Sum\n>>> Publisher.objects.annotate(Count("book"))\n(Varje Publisher i den resulterande QuerySet kommer att ha ett extra attribut som heter book__count)
Vi kan också be om den äldsta boken av alla dessa som hanteras av varje förlag:
\n>>> Publisher.objects.aggregate(oldest_pubdate=Min("book__pubdate"))\n(Den resulterande ordboken kommer att ha en nyckel som heter 'oldest_pubdate'. Om inget sådant alias anges kommer det att vara det ganska långa 'book__pubdate__min')
Detta gäller inte bara för främmande nycklar. Det fungerar också med många-till-många-relationer. Vi kan till exempel be om varje författare, annoterad med det totala antalet sidor med tanke på alla böcker som författaren har (med)skrivit (notera hur vi använder 'book' för att specificera Author -> Book omvänd många-till-många hopp):
>>> Author.objects.annotate(total_pages=Sum("book__pages"))\n(Varje Author i den resulterande QuerySet kommer att ha ett extra attribut som heter total_pages. Om inget sådant alias anges kommer det att vara det ganska långa book__pages__sum)
Eller be om det genomsnittliga betyget för alla böcker skrivna av författare som vi har i arkivet:
\n>>> Author.objects.aggregate(average_rating=Avg("book__rating"))\n(Den resulterande ordboken kommer att ha en nyckel som heter 'average_rating'. Om inget sådant alias anges kommer det att vara det ganska långa 'book__rating__avg')
QuerySet-klausulerLink to this heading#filter() och exkludera()Link to this heading#Aggregat kan också delta i filter. Alla filter() (eller exclude()) som tillämpas på normala modellfält kommer att begränsa de objekt som beaktas för aggregering.
När ett filter används med en annotate()-sats begränsas de objekt för vilka en annotering beräknas. Du kan t.ex. generera en annoterad lista över alla böcker som har en titel som börjar med ”Django” med hjälp av frågan:
>>> from django.db.models import Avg, Count\n>>> Book.objects.filter(name__startswith="Django").annotate(num_authors=Count("authors"))\nNär ett filter används med en aggregate()-sats begränsar det de objekt över vilka aggregatet beräknas. Du kan t.ex. generera genomsnittspriset för alla böcker med en titel som börjar med ”Django” med hjälp av frågan:
>>> Book.objects.filter(name__startswith="Django").aggregate(Avg("price"))\nAnnoterade värden kan också filtreras. Aliaset för annoteringen kan användas i filter() och exclude()-klausuler på samma sätt som alla andra modellfält.
Om du t.ex. vill skapa en lista över böcker som har mer än en författare kan du ställa frågan:
\n>>> Book.objects.annotate(num_authors=Count("authors")).filter(num_authors__gt=1)\nDen här frågan genererar en annoterad resultatuppsättning och genererar sedan ett filter baserat på annoteringen.
\nOm du behöver två anteckningar med två separata filter kan du använda argumentet filter med valfritt aggregat. Till exempel, för att generera en lista över författare med ett antal högt rankade böcker:
>>> highly_rated = Count("book", filter=Q(book__rating__gte=7))\n>>> Author.objects.annotate(num_books=Count("book"), highly_rated_books=highly_rated)\nVarje Author i resultatmängden kommer att ha attributen num_books och highly_rated_books. Se även Villkorlig aggregering.
annotate() och filter() klausulerLink to this heading#När du utvecklar en komplex fråga som innehåller både annotate()- och filter()-klausuler ska du vara särskilt uppmärksam på i vilken ordning klausulerna tillämpas på QuerySet.
När en annotate()-klausul tillämpas på en fråga, beräknas annoteringen över frågans tillstånd fram till den punkt där annoteringen begärs. Den praktiska konsekvensen av detta är att filter() och annotate() inte är kommutativa operationer.
Givetvis:
\nFörlag A har två böcker med betyg 4 och 5.
Förlag B har två böcker med betyg 1 och 4.
Förlag C har en bok med betyg 1.
Här är ett exempel med aggregatet Count:
>>> a, b = Publisher.objects.annotate(num_books=Count("book", distinct=True)).filter(\n... book__rating__gt=3.0\n... )\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)\nBåda frågorna returnerar en lista med förlag som har minst en bok med ett betyg som överstiger 3,0, vilket innebär att förlag C utesluts.
\nI den första frågan föregår anteckningen filtret, så filtret har ingen effekt på anteckningen. distinct=True krävs för att undvika en query bug.
Den andra frågan räknar antalet böcker som har ett betyg som överstiger 3,0 för varje utgivare. Filtret föregår anteckningen, så filtret begränsar de objekt som beaktas vid beräkningen av anteckningen.
\nHär är ett annat exempel med aggregatet Avg:
>>> a, b = Publisher.objects.annotate(avg_rating=Avg("book__rating")).filter(\n... book__rating__gt=3.0\n... )\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(\n... avg_rating=Avg("book__rating")\n... )\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)\nDen första frågan gäller det genomsnittliga betyget för alla förlagets böcker för de förlag som har minst en bok med ett betyg som överstiger 3,0. I den andra frågan efterfrågas medelbetyget för ett förlags böcker för endast de betyg som överstiger 3,0.
\nDet är svårt att förstå hur ORM kommer att översätta komplexa querysets till SQL-frågor, så om du är osäker, inspektera SQL med str(queryset.query) och skriv många tester.
order_by()Link to this heading#Annoteringar kan användas som grund för beställning. När du definierar en order_by()-sats kan de aggregat du tillhandahåller referera till alla alias som definierats som en del av en annotate()-sats i frågan.
Om du t.ex. vill beställa ett QuerySet med böcker efter antalet författare som har bidragit till boken kan du använda följande fråga:
>>> Book.objects.annotate(num_authors=Count("authors")).order_by("num_authors")\nvärden()Link to this heading#Vanligtvis genereras annoteringar per objekt - en annoterad QuerySet returnerar ett resultat för varje objekt i den ursprungliga QuerySet. Men när en values()-klausul används för att begränsa de kolumner som returneras i resultatuppsättningen, är metoden för utvärdering av annoteringar något annorlunda. Istället för att returnera ett annoterat resultat för varje resultat i den ursprungliga QuerySet, grupperas de ursprungliga resultaten enligt de unika kombinationerna av de fält som anges i values()-klausulen. En annotering tillhandahålls sedan för varje unik grupp; annoteringen beräknas över alla medlemmar i gruppen.
Ett exempel är en författarfråga som försöker ta reda på det genomsnittliga betyget för böcker skrivna av varje författare:
\n>>> Author.objects.annotate(average_rating=Avg("book__rating"))\nDetta kommer att ge ett resultat för varje författare i databasen, kommenterat med deras genomsnittliga bokbetyg.
\nResultatet blir dock något annorlunda om du använder en values()-sats:
>>> Author.objects.values("name").annotate(average_rating=Avg("book__rating"))\nI det här exemplet kommer författarna att grupperas efter namn, så du får bara ett annoterat resultat för varje unikt författarnamn. Det innebär att om du har två författare med samma namn kommer deras resultat att slås samman till ett enda resultat i resultatet av frågan; genomsnittet beräknas som genomsnittet för de böcker som skrivits av båda författarna.
\nannotate() och values()Link to this heading#Precis som med filter()-klausulen har ordningen i vilken annotate() och values()-klausulerna tillämpas på en fråga betydelse. Om values()-satsen föregår annotate(), kommer annoteringen att beräknas med hjälp av den gruppering som beskrivs i values()-satsen.
Men om klausulen annotate() föregår klausulen values() genereras annoteringarna över hela frågeuppsättningen. I detta fall begränsar klausulen values() endast de fält som genereras vid utmatningen.
Om vi till exempel vänder på ordningen i klausulerna values() och annotate() från vårt tidigare exempel:
>>> Author.objects.annotate(average_rating=Avg("book__rating")).values(\n... "name", "average_rating"\n... )\nDetta kommer nu att ge ett unikt resultat för varje författare; dock kommer endast författarens namn och average_rating-annoteringen att returneras i utdata.
Du bör också notera att average_rating uttryckligen har inkluderats i listan över värden som skall returneras. Detta är nödvändigt på grund av ordningsföljden i klausulerna values() och annotate().
Om klausulen values() föregår klausulen annotate() läggs eventuella anteckningar automatiskt till i resultatuppsättningen. Men om values()-satsen tillämpas efter annotate()-satsen måste du uttryckligen inkludera aggregatkolumnen.
order_by()Link to this heading#Fält som nämns i order_by()-delen av en queryset används när utdata väljs, även om de inte annars anges i values()-anropet. Dessa extra fält används för att gruppera ”liknande” resultat tillsammans och de kan göra att annars identiska resultatrader ser ut att vara separata. Detta visar sig särskilt när man räknar saker.
Som exempel kan vi anta att du har en modell som ser ut så här:
\nfrom django.db import models\n\n\nclass Item(models.Model):\n name = models.CharField(max_length=10)\n data = models.IntegerField()\nOm du vill räkna hur många gånger varje distinkt data-värde förekommer i en ordnad frågeuppsättning kan du prova så här:
items = Item.objects.order_by("name")\n# Warning: not quite correct!\nitems.values("data").annotate(Count("id"))\n…som kommer att gruppera Item-objekten efter deras gemensamma data-värden och sedan räkna antalet id-värden i varje grupp. Förutom att det inte riktigt kommer att fungera. Ordningen efter namn kommer också att spela en roll i grupperingen, så den här frågan kommer att gruppera efter distinkta (data, namn) par, vilket inte är vad du vill. Istället bör du konstruera denna queryset:
items.values("data").annotate(Count("id")).order_by()\n…och rensar bort all ordning i frågan. Du kan också beställa efter, säg, data utan några skadliga effekter, eftersom det redan spelar en roll i frågan.
Detta beteende är detsamma som det som noteras i queryset-dokumentationen för distinct() och den allmänna regeln är densamma: normalt vill du inte att extra kolumner ska spela en roll i resultatet, så rensa bort ordningen, eller se åtminstone till att den är begränsad endast till de fält som du också väljer i ett values()-anrop.
Du kan också generera ett aggregat på resultatet av en annotation. När du definierar en aggregate()-sats kan de aggregat du tillhandahåller referera till alla alias som definierats som en del av en annotate()-sats i frågan.
Om du t.ex. vill beräkna det genomsnittliga antalet författare per bok måste du först anteckna författarantalet i bokuppsättningen och sedan aggregera författarantalet med hänvisning till anteckningsfältet:
\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}\nNär en aggregering tillämpas på en tom frågeuppsättning eller gruppering, standardiseras resultatet till dess parameter default, vanligtvis None. Detta beteende uppstår eftersom aggregeringsfunktioner returnerar NULL när den körda frågan inte returnerar några rader.
Du kan ange ett returvärde genom att ange argumentet default för de flesta aggregeringar. Men eftersom Count inte stöder argumentet default, kommer den alltid att returnera 0 för tomma frågeuppsättningar eller grupper.
Om man till exempel antar att ingen bok innehåller web i sitt namn, skulle beräkningen av det totala priset för denna bokuppsättning returnera None eftersom det inte finns några matchande rader att beräkna Sum-aggregeringen på:
>>> from django.db.models import Sum\n>>> Book.objects.filter(name__contains="web").aggregate(Sum("price"))\n{"price__sum": None}\nArgumentet default kan dock ställas in när man anropar Sum för att returnera ett annat standardvärde om inga böcker kan hittas:
>>> Book.objects.filter(name__contains="web").aggregate(Sum("price", default=0))\n{"price__sum": Decimal("0")}\nUnder huven implementeras argumentet default genom att aggregeringsfunktionen förpackas med Coalesce.
ONLY_FULL_GROUP_BY enabledLink to this heading#When using the values() clause to group query results for annotations in\nMySQL with the ONLY_FULL_GROUP_BY SQL mode enabled, you may need to apply\nAnyValue if the annotation includes a mix of\naggregate and non-aggregate expressions.
Take the following example:
\n>>> from django.db.models import F, Count, Greatest\n>>> Book.objects.values(greatest_pages=Greatest("pages", 600)).annotate(\n... num_authors=Count("authors"),\n... pages_per_author=F("greatest_pages") / F("num_authors"),\n... ).aggregate(Avg("pages_per_author"))\nThis creates groups of books based on the SQL column GREATEST(pages, 600).\nOne unique group consists of books with 600 pages or less, and other unique\ngroups will consist of books with the same pages. The pages_per_author\nannotation is composed of aggregate and non-aggregate expressions,\nnum_authors is an aggregate expression while greatest_page isn’t.
Since the grouping is based on the greatest_pages expression, MySQL may be\nunable to determine that greatest_pages (used in the pages_per_author\nexpression) is functionally dependent on the grouped column. As a result, it\nmay raise an error like:
OperationalError: (1055, "Expression #2 of SELECT list is not in GROUP BY\nclause and contains nonaggregated column 'book_book.pages' which is not\nfunctionally dependent on columns in GROUP BY clause; this is incompatible\nwith sql_mode=only_full_group_by")\nTo avoid this, you can wrap the non-aggregate expression with\nAnyValue.
>>> from django.db.models import AnyValue, F, Count, Greatest\n>>> Book.objects.values(\n... greatest_pages=Greatest("pages", 600),\n... ).annotate(\n... num_authors=Count("authors"),\n... pages_per_author=AnyValue(F("greatest_pages")) / F("num_authors"),\n... ).aggregate(Avg("pages_per_author"))\n{'pages_per_author__avg': 532.57143333}\nOther supported databases do not encounter the OperationalError in the\nexample above because they can detect the functional dependency. In general,\nAnyValue is useful when dealing with select list columns that involve\nnon-aggregate functions or complex expressions not recognized by the database\nas functionally dependent on the columns in the grouping clause.