Frågeuttryck beskriver ett värde eller en beräkning som kan användas som en del av en uppdatering, ett skapande, ett filter, en ordning efter, en annotering eller ett aggregat. När ett uttryck ger ett booleskt värde kan det användas direkt i filter. Det finns ett antal inbyggda uttryck (dokumenteras nedan) som kan användas för att hjälpa dig att skriva frågor. Uttryck kan kombineras, eller i vissa fall nästlas, för att bilda mer komplexa beräkningar.
\nDjango stöder negation, addition, subtraktion, multiplikation, division, modulo aritmetik och power-operatorn på frågeuttryck med hjälp av Python-konstanter, variabler och till och med andra uttryck.
\nMånga av de uttryck som dokumenteras i detta avsnitt stöder en valfri parameter output_field. Om den anges kommer Django att ladda värdet i det fältet efter att ha hämtat det från databasen.
output_field tar en modellfältsinstans, som IntegerField() eller BooleanField(). Vanligtvis behöver fältet inte några argument, som max_length, eftersom fältargument avser datavalidering som inte kommer att utföras på uttryckets utdatavärde.
output_field krävs endast när Django inte automatiskt kan bestämma resultatets fälttyp, till exempel komplexa uttryck som blandar fälttyper. Om du till exempel lägger till en DecimalField() och en FloatField() krävs ett utmatningsfält, som output_field=FloatField().
output_field also allows using custom fields that perform type conversions\noutside a specific model field context. For example, if you frequently need to\nperform date arithmetic with timedelta, you can create a custom field that\nhandles the conversion, ensuring consistent results across databases. See\nSå här skapar du anpassade modellfält.
>>> from django.db.models import Count, F, Value\n>>> from django.db.models.functions import Length, Upper\n>>> from django.db.models.lookups import GreaterThan\n\n# Find companies that have more employees than chairs.\n>>> Company.objects.filter(num_employees__gt=F("num_chairs"))\n\n# Find companies that have at least twice as many employees\n# as chairs. Both the querysets below are equivalent.\n>>> Company.objects.filter(num_employees__gt=F("num_chairs") * 2)\n>>> Company.objects.filter(num_employees__gt=F("num_chairs") + F("num_chairs"))\n\n# How many chairs are needed for each company to seat all employees?\n>>> company = (\n... Company.objects.filter(num_employees__gt=F("num_chairs"))\n... .annotate(chairs_needed=F("num_employees") - F("num_chairs"))\n... .first()\n... )\n>>> company.num_employees\n120\n>>> company.num_chairs\n50\n>>> company.chairs_needed\n70\n\n# Create a new company using expressions.\n>>> company = Company.objects.create(name="Google", ticker=Upper(Value("goog")))\n>>> company.ticker\n'GOOG'\n\n# Annotate models with an aggregated value. Both forms\n# below are equivalent.\n>>> Company.objects.annotate(num_products=Count("products"))\n>>> Company.objects.annotate(num_products=Count(F("products")))\n\n# Aggregates can contain complex computations also\n>>> Company.objects.annotate(num_offerings=Count(F("products") + F("services")))\n\n# Expressions can also be used in order_by(), either directly\n>>> Company.objects.order_by(Length("name").asc())\n>>> Company.objects.order_by(Length("name").desc())\n# or using the double underscore lookup syntax.\n>>> from django.db.models import CharField\n>>> from django.db.models.functions import Length\n>>> CharField.register_lookup(Length)\n>>> Company.objects.order_by("name__length")\n\n# Boolean expression can be used directly in filters.\n>>> from django.db.models import Exists, OuterRef\n>>> Company.objects.filter(\n... Exists(Employee.objects.filter(company=OuterRef("pk"), salary__gt=10))\n... )\n\n# Lookup expressions can also be used directly in filters\n>>> Company.objects.filter(GreaterThan(F("num_employees"), F("num_chairs")))\n# or annotations.\n>>> Company.objects.annotate(\n... need_chairs=GreaterThan(F("num_employees"), F("num_chairs")),\n... )\nF()-uttryckLink to this heading#Ett F()-objekt representerar värdet av ett modellfält, transformerat värde av ett modellfält eller annoterad kolumn. Det gör det möjligt att referera till modellfältsvärden och utföra databasoperationer med hjälp av dem utan att faktiskt behöva dra ut dem från databasen till Python-minnet.
Istället använder Django objektet F() för att generera ett SQL-uttryck som beskriver den nödvändiga operationen på databasnivå.
Låt oss prova detta med ett exempel. Normalt kan man göra något liknande:
\n# Tintin filed a news story!\nreporter = Reporters.objects.get(name="Tintin")\nreporter.stories_filed += 1\nreporter.save()\nHär har vi hämtat värdet av reporter.stories_filed från databasen till minnet och manipulerat det med hjälp av välkända Python-operatorer, och sedan sparat objektet tillbaka till databasen. Men istället kunde vi också ha gjort:
from django.db.models import F\n\nreporter = Reporters.objects.get(name="Tintin")\nreporter.stories_filed = F("stories_filed") + 1\nreporter.save()\nÄven om reporter.stories_filed = F('stories_filed') + 1 ser ut som en normal Python-tilldelning av värde till ett instansattribut, är det i själva verket en SQL-konstruktion som beskriver en operation i databasen.
När Django stöter på en instans av F() åsidosätter den Pythons standardoperatorer för att skapa ett inkapslat SQL-uttryck; i det här fallet ett som instruerar databasen att öka databasfältet som representeras av reporter.stories_filed.
Oavsett vilket värde som finns eller fanns på reporter.stories_filed får Python aldrig veta något om det - det hanteras helt och hållet av databasen. Allt Python gör, genom Djangos F()-klass, är att skapa SQL-syntaxen för att hänvisa till fältet och beskriva operationen.
As well as being used in operations on single instances as above, F() can\nbe used with update() to perform bulk updates on a QuerySet. This\nreduces the two queries we were using above - the get() and the\nsave() - to just one:
reporter = Reporters.objects.filter(name="Tintin")\nreporter.update(stories_filed=F("stories_filed") + 1)\nWe can also use update() to increment\nthe field value on multiple objects - which could be very much faster than\npulling them all into Python from the database, looping over them, incrementing\nthe field value of each one, and saving each one back to the database:
Reporter.objects.update(stories_filed=F("stories_filed") + 1)\nF() kan därför erbjuda prestandafördelar genom:
att få databasen, snarare än Python, att göra jobbet
minska antalet förfrågningar som vissa operationer kräver
F()-uttryckLink to this heading#För strängbaserade fält, textbaserade fält och ArrayField kan du använda Pythons syntax för array-slicing. Indexen är 0-baserade. Argumentet step till slice och negativ indexering stöds inte. Till exempel:
>>> # Replacing a name with a substring of itself.\n>>> writer = Writers.objects.get(name="Priyansh")\n>>> writer.name = F("name")[1:5]\n>>> writer.save()\n>>> writer.name\n'riya'\nF()Link to this heading#En annan fördel med F() är att om databasen - snarare än Python - uppdaterar ett fälts värde undviks ett race condition.
Om två Python-trådar kör koden i det första exemplet ovan kan den ena tråden hämta, öka och spara ett fälts värde efter att den andra har hämtat det från databasen. Det värde som den andra tråden sparar kommer att baseras på det ursprungliga värdet; den första trådens arbete kommer att gå förlorat.
\nIf the database is responsible for updating the field, the process is more\nrobust: it will only ever update the field based on the value of the field in\nthe database when the save() or update() is executed, rather\nthan based on its value when the instance was retrieved.
F() assignments are refreshed after Model.save()Link to this heading#F() objects assigned to model fields are refreshed from the database on\nsave() on backends that support it without incurring a subsequent\nquery (SQLite, PostgreSQL, and Oracle) and deferred otherwise (MySQL or\nMariaDB). For example:
>>> reporter = Reporters.objects.get(name="Tintin")\n>>> reporter.stories_filed = F("stories_filed") + 1\n>>> reporter.save()\n>>> reporter.stories_filed # This triggers a refresh query on MySQL/MariaDB.\n14 # Assuming the database value was 13 when the object was saved.\nF() i filterLink to this heading#F() är också mycket användbart i QuerySet-filter, där de gör det möjligt att filtrera en uppsättning objekt mot kriterier baserade på deras fältvärden, snarare än på Python-värden.
Detta finns dokumenterat i Använda F()-uttryck i frågor.
\nF() med annotationerLink to this heading#F() kan användas för att skapa dynamiska fält i dina modeller genom att kombinera olika fält med aritmetik:
company = Company.objects.annotate(chairs_needed=F("num_employees") - F("num_chairs"))\nOm de fält som du kombinerar är av olika typer måste du tala om för Django vilken typ av fält som ska returneras. De flesta uttryck stöder output_field för detta fall, men eftersom F() inte gör det, måste du omsluta uttrycket med ExpressionWrapper:
from django.db.models import DateTimeField, ExpressionWrapper, F\n\nTicket.objects.annotate(\n expires=ExpressionWrapper(\n F("active_at") + F("duration"), output_field=DateTimeField()\n )\n)\nVid hänvisning till relationsfält som ForeignKey returnerar F() primärnyckelvärdet i stället för en modellinstans:
>>> car = Company.objects.annotate(built_by=F("manufacturer"))[0]\n>>> car.manufacturer\n<Manufacturer: Toyota>\n>>> car.built_by\n3\nF() för att sortera nollvärdenLink to this heading#Använd F() och nyckelordsargumentet nulls_first eller nulls_last till Expression.asc() eller desc() för att styra ordningsföljden för ett fälts null-värden. Som standard beror ordningsföljden på din databas.
Till exempel:, för att sortera företag som inte har kontaktats (last_contacted är null) efter företag som har kontaktats:
from django.db.models import F\n\nCompany.objects.order_by(F("last_contacted").desc(nulls_last=True))\nF() med logiska operationerLink to this heading#F()-uttryck som ger BooleanField kan logiskt negeras med inversionsoperatorn ~F(). Till exempel:, för att byta aktiveringsstatus för företag:
from django.db.models import F\n\nCompany.objects.update(is_active=~F("is_active"))\nFunc() uttryckLink to this heading#Func()-uttryck är bastypen för alla uttryck som involverar databasfunktioner som COALESCE och LOWER, eller aggregat som SUM. De kan användas direkt:
from django.db.models import F, Func\n\nqueryset.annotate(field_lower=Func(F("field"), function="LOWER"))\neller så kan de användas för att bygga upp ett bibliotek med databasfunktioner:
\nclass Lower(Func):\n function = "LOWER"\n\n\nqueryset.annotate(field_lower=Lower("field"))\nMen båda fallen kommer att resultera i en frågeuppsättning där varje modell är annoterad med ett extra attribut field_lower som produceras, ungefär, från följande SQL:
SELECT\n ...\n LOWER("db_table"."field") as "field_lower"\nSee Databasfunktioner for a list of built-in database\nfunctions.
\nAPI:et Func är uppbyggt enligt följande:
Ett klassattribut som beskriver den funktion som ska genereras. Specifikt kommer funktionen att interpoleras som funktion platshållare inom template. Standardvärdet är None.
Ett klassattribut, i form av en formatsträng, som beskriver den SQL som genereras för denna funktion. Standardvärdet är '%(function)s(%(expressions)s)'.
Om du konstruerar SQL som strftime('%W', 'date') och behöver ett bokstavligt %-tecken i frågan, fyrdubblar du det (%%%%) i attributet template eftersom strängen interpoleras två gånger: en gång under mallinterpolationen i as_sql() och en gång i SQL-interpolationen med frågeparametrarna i databasmarkören.
Ett klassattribut som anger det tecken som används för att sammanfoga listan med uttryck. Standardvärden är ', '.
Ett klassattribut som anger antalet argument som funktionen accepterar. Om detta attribut är inställt och funktionen anropas med ett annat antal uttryck, kommer TypeError att uppstå. Standardvärde är None.
Genererar SQL-fragmentet för databasfunktionen. Returnerar en tupel (sql, params), där sql är SQL-strängen och params är listan eller tupeln med frågeparametrar.
Metoderna as_vendor() bör använda parametrarna function, template, arg_joiner och alla andra **extra_context för att anpassa SQL efter behov. Ett exempel:
django/db/modeller/functions.pyclass ConcatPair(Func):\n ...\n function = "CONCAT"\n ...\n\n def as_mysql(self, compiler, connection, **extra_context):\n return super().as_sql(\n compiler,\n connection,\n function="CONCAT_WS",\n template="%(function)s('', %(expressions)s)",\n **extra_context\n )\nFör att undvika en SQL-injektionssårbarhet får extra_context inte innehålla otillförlitlig användarinmatning eftersom dessa värden interpoleras in i SQL-strängen i stället för att skickas som frågeparametrar, där databasdrivrutinen skulle undkomma dem.
Argumentet *expressions är en lista med positionella uttryck som funktionen ska tillämpas på. Uttrycken konverteras till strängar, sammanfogas med arg_joiner och interpoleras sedan in i mallen som platshållaren expressions.
Positionella argument kan vara uttryck eller Python-värden. Strängar antas vara kolumnreferenser och kommer att packas in i F() uttryck medan andra värden kommer att packas in i Value() uttryck.
De **extra kwargs är key=value par som kan interpoleras in i template attributet. För att undvika en SQL-injektionssårbarhet, extra får inte innehålla otillförlitlig användarinmatning eftersom dessa värden interpoleras in i SQL-strängen i stället för att skickas som frågeparametrar, där databasdrivrutinen skulle undkomma dem.
Nyckelorden function, template och arg_joiner kan användas för att ersätta attribut med samma namn utan att behöva definiera en egen klass. output_field kan användas för att definiera den förväntade returtypen.
Aggregate()Link to this heading#Ett aggregatuttryck är ett specialfall av ett Func()-uttryck som informerar frågan om att en GROUP BY-klausul krävs. Alla aggregate-funktioner, som Sum() och Count(), ärver från Aggregate().
Eftersom Aggregate är uttryck och omslagsuttryck kan du representera vissa komplexa beräkningar:
from django.db.models import Count\n\nCompany.objects.annotate(\n managers_required=(Count("num_employees") / 4) + Count("num_managers")\n)\nAPI:et för Aggregate är som följer:
Ett klassattribut, i form av en formatsträng, som beskriver den SQL som genereras för detta aggregat. Standardvärdet är '%(function)s(%(distinct)s%(expressions)s)'.
Ett klassattribut som beskriver den aggregerade funktion som ska genereras. Specifikt kommer funktionen att interpoleras som funktion platshållare inom template. Standardvärdet är None.
Standardvärdet är True eftersom de flesta aggregerade funktioner kan användas som källuttryck i Window.
Ett klassattribut som avgör om denna aggregatfunktion tillåter att ett argument med nyckelordet distinct skickas eller inte. Om det är satt till False (standard), kommer TypeError att uppstå om distinct=True skickas.
A class attribute determining whether or not this aggregate function\nallows passing a order_by keyword argument. If set to False\n(default), TypeError is raised if order_by is passed as a value\nother than None.
Standardvärdet är None eftersom de flesta aggregeringsfunktioner resulterar i NULL när de tillämpas på en tom resultatmängd.
De positionella argumenten expressions kan innehålla uttryck, transformationer av modellfältet eller namn på modellfält. De konverteras till en sträng och används som platshållare för expressions i template.
Argumentet distinct avgör om aggregatfunktionen ska anropas för varje distinkt värde i expressions (eller uppsättning värden, för flera expressions). Argumentet stöds endast av aggregat som har allow_distinct satt till True.
The filter argument takes a Q object that’s\nused to filter the rows that are aggregated. See Villkorlig aggregering\nand Filtrering av anteckningar for example usage.
The order_by argument behaves similarly to the field_names input of the\norder_by() function, accepting a field name (with an optional\n"-" prefix which indicates descending order) or an expression (or a tuple\nor list of strings and/or expressions) that specifies the ordering of the\nelements in the result.
Argumentet default tar ett värde som kommer att skickas tillsammans med aggregatet till Coalesce. Detta är användbart för att ange ett annat värde som ska returneras än None när frågeuppsättningen (eller grupperingen) inte innehåller några poster.
De **extra kwargs är nyckel=värde-par som kan interpoleras in i template-attributet.
Du kan också skapa dina egna aggregerade funktioner. Som ett minimum måste du definiera function, men du kan också helt anpassa den SQL som genereras. Här är ett kort exempel:
from django.db.models import Aggregate\n\n\nclass Sum(Aggregate):\n # Supports SUM(ALL field).\n function = "SUM"\n template = "%(function)s(%(all_values)s%(expressions)s)"\n allow_distinct = False\n arity = 1\n\n def __init__(self, expression, all_values=False, **extra):\n super().__init__(expression, all_values="ALL " if all_values else "", **extra)\nValue()Link to this heading#Ett Value()-objekt representerar den minsta möjliga komponenten i ett uttryck: ett enkelt värde. När du behöver representera värdet av ett heltal, en boolean eller en sträng i ett uttryck, kan du packa in värdet i ett Value().
Du kommer sällan att behöva använda Value() direkt. När du skriver uttrycket F('field') + 1 omsluter Django implicit 1 i en Value(), vilket gör att enkla värden kan användas i mer komplexa uttryck. Du kommer att behöva använda Value() när du vill skicka en sträng till ett uttryck. De flesta uttryck tolkar ett strängargument som namnet på ett fält, t.ex. Lower('name').
Argumentet value beskriver det värde som ska ingå i uttrycket, t.ex. 1, True eller None. Django vet hur man konverterar dessa Python-värden till deras motsvarande databastyp.
If no output_field is specified, it will be inferred from\nthe type of the provided value for many common types. For example, passing\nan instance of datetime.datetime as value defaults\noutput_field to DateTimeField.
ExpressionWrapper() uttryckLink to this heading#ExpressionWrapper omger ett annat uttryck och ger tillgång till egenskaper, t.ex. output_field, som kanske inte är tillgängliga för andra uttryck. ExpressionWrapper är nödvändig när man använder aritmetik på F()-uttryck med olika typer enligt beskrivningen i Använda F() med annotationer.
JSONNull() expressionLink to this heading#Specialized expression to represent JSON scalar null on a\nJSONField.
See Lagring av och frågor om None for usage examples.
\nConditional expressions allow you to use if … elif …\nelse logic in queries. Django natively supports SQL CASE\nexpressions. For more details see Villkorliga uttryck.
Subquery()Link to this heading#Du kan lägga till en explicit underfråga till en QuerySet med hjälp av uttrycket Subquery.
Till exempel: för att kommentera varje inlägg med e-postadressen till författaren till den nyaste kommentaren till det inlägget:
\n>>> from django.db.models import OuterRef, Subquery\n>>> newest = Comment.objects.filter(post=OuterRef("pk")).order_by("-created_at")\n>>> Post.objects.annotate(newest_commenter_email=Subquery(newest.values("email")[:1]))\nPå PostgreSQL ser SQL ut som:
\nSELECT "post"."id", (\n SELECT U0."email"\n FROM "comment" U0\n WHERE U0."post_id" = ("post"."id")\n ORDER BY U0."created_at" DESC LIMIT 1\n) AS "newest_commenter_email" FROM "post"\nAnvänd OuterRef när en queryset i en Subquery behöver referera till ett fält från den yttre queryn eller dess transform. Det fungerar som ett F-uttryck förutom att kontrollen för att se om det hänvisar till ett giltigt fält inte görs förrän den yttre frågeuppsättningen har lösts upp.
Instanser av OuterRef kan användas tillsammans med nästlade instanser av Subquery för att hänvisa till en innehållande frågeuppsättning som inte är den omedelbara föräldern. Till exempel: skulle denna frågeuppsättning behöva vara inom ett nästlat par av Subquery-instanser för att lösas korrekt:
>>> Book.objects.filter(author=OuterRef(OuterRef("pk")))\nDet finns tillfällen då en enda kolumn måste returneras från en Subquery, t.ex. för att använda en Subquery som mål för en __in-uppslagning. För att returnera alla kommentarer för inlägg som publicerats under den senaste dagen:
>>> from datetime import timedelta\n>>> from django.utils import timezone\n>>> one_day_ago = timezone.now() - timedelta(days=1)\n>>> posts = Post.objects.filter(published_at__gte=one_day_ago)\n>>> Comment.objects.filter(post__in=Subquery(posts.values("pk")))\nI det här fallet måste underfrågan använda values() för att bara returnera en enda kolumn: inläggets primärnyckel.
För att förhindra att en underfråga returnerar flera rader används en del ([:1]) av frågeuppsättningen:
>>> subquery = Subquery(newest.values("email")[:1])\n>>> Post.objects.annotate(newest_commenter_email=subquery)\nI det här fallet får subquery bara returnera en enda kolumn och en enda rad: e-postadressen till den senast skapade kommentaren.
\n(Att använda get() istället för en slice skulle misslyckas eftersom OuterRef inte kan lösas förrän queryset används inom en Subquery)
Existerar() underfrågorLink to this heading#Exists är en Subquery-underklass som använder en SQL EXISTS-sats. I många fall kommer den att fungera bättre än en subquery eftersom databasen kan stoppa utvärderingen av subquery när en första matchande rad hittas.
Till exempel: för att markera varje inlägg med om det har en kommentar från den senaste dagen eller inte:
\n>>> from django.db.models import Exists, OuterRef\n>>> from datetime import timedelta\n>>> from django.utils import timezone\n>>> one_day_ago = timezone.now() - timedelta(days=1)\n>>> recent_comments = Comment.objects.filter(\n... post=OuterRef("pk"),\n... created_at__gte=one_day_ago,\n... )\n>>> Post.objects.annotate(recent_comment=Exists(recent_comments))\nPå PostgreSQL ser SQL ut som:
\nSELECT "post"."id", "post"."published_at", EXISTS(\n SELECT (1) as "a"\n FROM "comment" U0\n WHERE (\n U0."created_at" >= YYYY-MM-DD HH:MM:SS AND\n U0."post_id" = "post"."id"\n )\n LIMIT 1\n) AS "recent_comment" FROM "post"\nDet är onödigt att tvinga Exists att hänvisa till en enda kolumn, eftersom kolumnerna kasseras och ett booleskt resultat returneras. På samma sätt, eftersom ordning är oviktigt inom en SQL EXISTS subquery och bara skulle försämra prestanda, tas det automatiskt bort.
Du kan ställa frågor med hjälp av NOT EXISTS med ~Exists().
Subquery()- eller Exists()-uttryckLink to this heading#Subquery() som returnerar ett booleskt värde och Exists() kan användas som ett villkor i When-uttryck, eller för att direkt filtrera en frågeuppsättning:
>>> recent_comments = Comment.objects.filter(...) # From above\n>>> Post.objects.filter(Exists(recent_comments))\nDetta säkerställer att subquery inte läggs till i SELECT-kolumnerna, vilket kan leda till bättre prestanda.
Subquery-uttryckLink to this heading#Aggregat kan användas i en Subquery, men de kräver en specifik kombination av filter(), values() och annotate() för att grupperingen av subquery ska bli korrekt.
Förutsatt att båda modellerna har ett längd-fält, för att hitta inlägg där inläggslängden är större än den totala längden på alla kombinerade kommentarer:
>>> from django.db.models import OuterRef, Subquery, Sum\n>>> comments = Comment.objects.filter(post=OuterRef("pk")).order_by().values("post")\n>>> total_comments = comments.annotate(total=Sum("length")).values("total")\n>>> Post.objects.filter(length__gt=Subquery(total_comments))\nDen inledande filter(...) begränsar underfrågan till de relevanta parametrarna. order_by() tar bort standard ordering (om någon) på Comment-modellen. values('post') aggregerar kommentarer efter Post. Slutligen utför annotate(...) aggregeringen. Den ordning i vilken dessa queryset-metoder tillämpas är viktig. I det här fallet, eftersom underfrågan måste begränsas till en enda kolumn, krävs values('total').
Detta är det enda sättet att utföra en aggregering inom en Subquery, eftersom användning av aggregate() försöker utvärdera queryset (och om det finns en OuterRef kommer detta inte att vara möjligt att lösa).
Ibland kan databasuttryck inte enkelt uttrycka en komplex WHERE klausul. I dessa kantfall använder du RawSQL -uttrycket. Till exempel:
>>> from django.db.models.expressions import RawSQL\n>>> queryset.annotate(val=RawSQL("select col from sometable where othercol = %s", (param,)))\nDessa extra uppslagningar kanske inte är portabla till olika databasmotorer (eftersom du uttryckligen skriver SQL-kod) och bryter mot DRY-principen, så du bör undvika dem om möjligt.
\nRawSQL-uttryck kan också användas som mål för __in-filter:
>>> queryset.filter(id__in=RawSQL("select id from sometable where col = %s", (param,)))\nFönsterfunktioner är ett sätt att tillämpa funktioner på partitioner. Till skillnad från en vanlig aggregeringsfunktion som beräknar ett slutresultat för varje uppsättning som definieras av group by, arbetar fönsterfunktioner med ramar och partitioner och beräknar resultatet för varje rad.
\nDu kan ange flera fönster i samma fråga, vilket i Django ORM skulle motsvara att inkludera flera uttryck i ett QuerySet.annotate()-anrop. ORM använder sig inte av namngivna fönster, utan de är en del av de valda kolumnerna.
\nStandardvärdet är %(expression)s OVER (%(window)s). Om endast argumentet expression anges, kommer window-satsen att vara tom.
Klassen Window är huvuduttrycket för en OVER-sats.
Argumentet expression är antingen en window function, en aggregate function, eller ett uttryck som är kompatibelt i en window clause.
The partition_by argument accepts an expression or a sequence of\nexpressions (column names should be wrapped in an F-object) that control\nthe partitioning of the rows. Partitioning narrows which rows are used to\ncompute the result set.
output_field anges antingen som ett argument eller genom ett uttryck.
\nArgumentet order_by accepterar ett uttryck som du kan anropa asc() och desc(), en sträng med ett fältnamn (med ett valfritt prefix "-" som anger fallande ordning), eller en tupel eller lista med strängar och/eller uttryck. Ordningsföljden styr i vilken ordning uttrycket tillämpas. Om du t.ex. summerar över raderna i en partition är det första resultatet värdet på den första raden, det andra är summan av den första och den andra raden.
The frame parameter specifies which other rows should be used in the\ncomputation. See Ramar for details.
Till exempel: för att kommentera varje film med det genomsnittliga betyget för filmer från samma studio i samma genre och utgivningsår:
\n>>> from django.db.models import Avg, F, Window\n>>> Movie.objects.annotate(\n... avg_rating=Window(\n... expression=Avg("rating"),\n... partition_by=[F("studio"), F("genre")],\n... order_by="released__year",\n... ),\n... )\nDetta gör att du kan kontrollera om en film har fått bättre eller sämre betyg än sina konkurrenter.
\nDu kanske vill använda flera uttryck över samma fönster, dvs. samma partition och ram. Du kan t.ex. ändra det föregående exemplet så att det även inkluderar det bästa och sämsta betyget i varje filmgrupp (samma studio, genre och utgivningsår) genom att använda tre fönsterfunktioner i samma fråga. Partitionen och ordningen från föregående exempel extraheras till en ordbok för att minska upprepning:
\n>>> from django.db.models import Avg, F, Max, Min, Window\n>>> window = {\n... "partition_by": [F("studio"), F("genre")],\n... "order_by": "released__year",\n... }\n>>> Movie.objects.annotate(\n... avg_rating=Window(\n... expression=Avg("rating"),\n... **window,\n... ),\n... best=Window(\n... expression=Max("rating"),\n... **window,\n... ),\n... worst=Window(\n... expression=Min("rating"),\n... **window,\n... ),\n... )\nFiltrering mot fönsterfunktioner stöds så länge som uppslagningar inte är disjunktiva (inte använder OR eller XOR som en koppling) och mot en frågeuppsättning som utför aggregering.
Exempelvis stöds inte en fråga som bygger på aggregering och som har ett filter med OR mot en fönsterfunktion och ett fält. Om kombinerade predikat tillämpas efter aggregering kan det leda till att rader som normalt inte ingår i grupper inkluderas:
>>> qs = Movie.objects.annotate(\n... category_rank=Window(Rank(), partition_by="category", order_by="-rating"),\n... scenes_count=Count("actors"),\n... ).filter(Q(category_rank__lte=3) | Q(title__contains="Batman"))\n>>> list(qs)\nNotImplementedError: Heterogeneous disjunctive predicates against window functions\nare not implemented when performing conditional aggregation.\nBland Djangos inbyggda databasbackends stöder MySQL, PostgreSQL och Oracle fönsteruttryck. Stödet för olika funktioner i fönsteruttryck varierar mellan de olika databaserna. Till exempel: kanske alternativen i asc() och desc() inte stöds. Konsultera dokumentationen för din databas vid behov.
För en fönsterram kan du välja antingen en intervallbaserad sekvens av rader eller en vanlig sekvens av rader.
\nDetta attribut är inställt på 'RANGE'.
PostgreSQL har begränsat stöd för ValueRange och stöder endast användning av standardstart- och slutpunkter, såsom CURRENT ROW och UNBOUNDED FOLLOWING.
Detta attribut är inställt på 'ROWS'.
Båda klasserna returnerar SQL med mallen:
\n%(frame_type)s BETWEEN %(start)s AND %(end)s\nMed argumentet exclusion kan du utesluta rader (CURRENT_ROW), grupper (GROUP) och band (TIES) från fönsterramarna i databaser som stöds:
%(frame_type)s BETWEEN %(start)s AND %(end)s EXCLUDE %(exclusion)s\nRamar begränsar de rader som används för att beräkna resultatet. De flyttas från en viss startpunkt till en viss angiven slutpunkt. Ramar kan användas med eller utan partitioner, men det är ofta en bra idé att ange en ordning för fönstret för att säkerställa ett deterministiskt resultat. I en ram är en peer i en ram en rad med ett likvärdigt värde, eller alla rader om det inte finns någon ordningsbestämmelse.
\nStandardstartpunkten för en ram är UNBOUNDED PRECEDING, vilket är den första raden i partitionen. Slutpunkten inkluderas alltid explicit i den SQL som genereras av ORM och är som standard UNBOUNDED FOLLOWING. Standardramen omfattar alla rader från partitionen till den sista raden i uppsättningen.
De accepterade värdena för argumenten start och end är None, ett heltal eller noll. Ett negativt heltal för start resulterar i N PRECEDING, medan None ger UNBOUNDED PRECEDING. I läget ROWS kan ett positivt heltal användas för start, vilket resulterar i N FOLLOWING. Positiva heltal accepteras för slut och resulterar i N FOLLOWING. I läget ROWS kan ett negativt heltal användas för end vilket resulterar i N PRECEDING. För både start och end kommer noll att returnera CURRENT ROW.
Det finns en skillnad i vad CURRENT ROW inkluderar. När det anges i läget ROWS börjar eller slutar ramen med den aktuella raden. När den anges i läget RANGE startar eller slutar ramen vid den första eller sista peer enligt orderklausulen. Således utvärderar RANGE CURRENT ROW uttrycket för rader som har samma värde som specificeras av ordningsföljden. Eftersom mallen innehåller både start- och slut-punkter kan detta uttryckas med:
ValueRange(start=0, end=0)\nOm en films ”jämlikar” beskrivs som filmer som släppts av samma studio i samma genre under samma år, kommenterar detta RowRange-exempel varje film med det genomsnittliga betyget för filmens två föregående och två efterföljande jämlikar:
>>> from django.db.models import Avg, F, RowRange, Window\n>>> Movie.objects.annotate(\n... avg_rating=Window(\n... expression=Avg("rating"),\n... partition_by=[F("studio"), F("genre")],\n... order_by="released__year",\n... frame=RowRange(start=-2, end=2),\n... ),\n... )\nOm databasen har stöd för det kan du ange start- och slutpunkter baserat på värden för ett uttryck i partitionen. Om fältet released i modellen Movie lagrar utgivningsmånaden för varje film, anger detta exempel på ValueRange för varje film det genomsnittliga betyget för andra filmer som släppts mellan tolv månader före och tolv månader efter varje film:
>>> from django.db.models import Avg, F, ValueRange, Window\n>>> Movie.objects.annotate(\n... avg_rating=Window(\n... expression=Avg("rating"),\n... partition_by=[F("studio"), F("genre")],\n... order_by="released__year",\n... frame=ValueRange(start=-12, end=12),\n... ),\n... )\nNedan hittar du tekniska implementeringsdetaljer som kan vara användbara för biblioteksförfattare. Det tekniska API:et och exemplen nedan hjälper till att skapa generiska frågeuttryck som kan utöka den inbyggda funktionaliteten som Django tillhandahåller.
\nFrågeuttryck implementerar query expression API, men exponerar också ett antal extra metoder och attribut som listas nedan. Alla frågeuttryck måste ärva från Expression() eller en relevant underklass.
När ett frågeuttryck omsluter ett annat uttryck är det ansvarigt för att anropa lämpliga metoder för det omslutna uttrycket.
\nTalar om för Django att detta uttryck kan användas i Field.db_default. Standardvärdet är False.
Talar om för Django att detta uttryck kan användas under en begränsningsvalidering. Uttryck med constraint_validation_compatible inställt på False får endast ha ett källuttryck. Standardvärdet är True.
Talar om för Django att detta uttryck innehåller ett aggregat och att en GROUP BY-klausul måste läggas till i frågan.
Talar om för Django att detta uttryck innehåller ett Window-uttryck. Det används till exempel för att inte tillåta fönsterfunktionsuttryck i frågor som modifierar data.
Talar om för Django att detta uttryck kan refereras till i QuerySet.filter(). Standardvärdet är True.
Talar om för Django att detta uttryck kan användas som källuttryck i Window. Standardvärdet är False.
Tells Django which value should be returned when the expression is used\nto apply a function over an empty result set. Defaults to\nNotImplemented which forces the expression to be computed on\nthe database.
Talar om för Django att detta uttryck innehåller en set-returneringsfunktion, vilket tvingar fram utvärdering av underfrågor. Det används t.ex. för att tillåta vissa Postgres set-returning-funktioner (t.ex. JSONB_PATH_QUERY, UNNEST, etc.) att hoppa över optimering och utvärderas korrekt när annotationer skapar rader själva. Standardvärde är False.
Talar om för Django att detta uttryck tillåter sammansatta uttryck, till exempel för att stödja sammansatta primärnycklar. Standardvärdet är False.
Ger möjlighet att göra förbehandling eller validering av uttrycket innan det läggs till i frågan. resolve_expression() måste också anropas på alla nästlade uttryck. En copy() av self bör returneras med alla nödvändiga transformationer.
query är implementeringen av backend-frågan.
allow_joins är en boolean som tillåter eller förnekar användning av joins i frågan.
reuse är en uppsättning återanvändbara joins för scenarier med flera joins.
summarize är en boolean som, när den är True, signalerar att den fråga som beräknas är en terminal aggregerad fråga.
for_save är en boolean som, när den är True, signalerar att den fråga som körs utför en skapelse eller uppdatering.
Returnerar en ordnad lista med inre uttryck. Till exempel:
\n>>> Sum(F("foo")).get_source_expressions()\n[F('foo')]\nTar emot en lista med uttryck och lagrar dem så att get_source_expressions() kan returnera dem.
Returnerar en klon (kopia) av self, med eventuella kolumnaliaser ommärkta. Kolumnaliaser byter namn när underförfrågningar skapas. relabeled_clone() bör också anropas på alla nästlade uttryck och tilldelas klonen.
change_map är en ordlista som mappar gamla alias till nya alias.
Exempel:
\ndef relabeled_clone(self, change_map):\n clone = copy.copy(self)\n clone.expression = self.expression.relabeled_clone(change_map)\n return clone\nEn hook som gör det möjligt för uttrycket att tvinga värde till en mer lämplig typ.
uttryck är detsamma som själv.
Responsible for returning the list of columns referenced by\nthis expression. get_group_by_cols() should be called on any\nnested expressions. F() objects, in particular, hold a reference\nto a column.
Returnerar det uttryck som är klart att sorteras i stigande ordning.
\nnulls_first och nulls_last definierar hur null-värden sorteras. Se Använda F() för att sortera nollvärden för exempel på användning.
Returnerar det uttryck som är klart att sorteras i fallande ordning.
\nnulls_first och nulls_last definierar hur null-värden sorteras. Se Använda F() för att sortera nollvärden för exempel på användning.
Returns self with any modifications required to reverse the sort\norder within an order_by call. As an example, an expression\nimplementing NULLS LAST would change its value to be\nNULLS FIRST. Modifications are only required for expressions that\nimplement sort order like OrderBy. This method is called when\nreverse() is called on a\nqueryset.
Du kan skriva dina egna query expression-klasser som använder och kan integreras med andra query expressions. Låt oss gå igenom ett exempel genom att skriva en implementation av SQL-funktionen COALESCE, utan att använda de inbyggda Func()-uttrycken.
SQL-funktionen COALESCE definieras som att den tar en lista med kolumner eller värden. Den returnerar den första kolumnen eller värdet som inte är NULL.
Vi börjar med att definiera den mall som ska användas för SQL-generering och en __init__()-metod för att ställa in några attribut:
from django.db.models import Expression\n\n\nclass Coalesce(Expression):\n template = "COALESCE( %(expressions)s )"\n\n def __init__(self, expressions, output_field):\n super().__init__(output_field=output_field)\n if len(expressions) < 2:\n raise ValueError("expressions must have at least 2 elements")\n for expression in expressions:\n if not hasattr(expression, "resolve_expression"):\n raise TypeError("%r is not an Expression" % expression)\n self.expressions = expressions\nVi gör en del grundläggande validering av parametrarna, inklusive att kräva minst 2 kolumner eller värden och säkerställa att de är uttryck. Vi kräver output_field här så att Django vet vilken typ av modellfält som ska tilldelas det slutliga resultatet.
\nNu implementerar vi förbehandling och validering. Eftersom vi inte har någon egen validering vid denna tidpunkt delegerar vi till de nästlade uttrycken:
\ndef resolve_expression(\n self, query=None, allow_joins=True, reuse=None, summarize=False, for_save=False\n):\n c = self.copy()\n c.is_summary = summarize\n for pos, expression in enumerate(self.expressions):\n c.expressions[pos] = expression.resolve_expression(\n query, allow_joins, reuse, summarize, for_save\n )\n return c\nDärefter skriver vi den metod som ansvarar för att generera SQL:
\ndef as_sql(self, compiler, connection, template=None):\n sql_expressions, sql_params = [], []\n for expression in self.expressions:\n sql, params = compiler.compile(expression)\n sql_expressions.append(sql)\n sql_params.extend(params)\n template = template or self.template\n data = {"expressions": ",".join(sql_expressions)}\n return template % data, tuple(sql_params)\n\n\ndef as_oracle(self, compiler, connection):\n """\n Example of vendor specific handling (Oracle in this case).\n Let's make the function name lowercase.\n """\n return self.as_sql(compiler, connection, template="coalesce( %(expressions)s )")\nmetoderna as_sql() kan stödja anpassade nyckelordsargument, vilket gör att metoderna as_vendorname() kan åsidosätta data som används för att generera SQL-strängen. Att använda as_sql() nyckelordsargument för anpassning är att föredra framför att mutera self inom as_vendorname()-metoder eftersom det senare kan leda till fel när det körs på olika databasbackends. Om din klass förlitar sig på klassattribut för att definiera data, överväg att tillåta åsidosättningar i din as_sql()-metod.
Vi genererar SQL för vart och ett av uttrycken med hjälp av metoden compiler.compile() och sammanfogar resultatet med kommatecken. Sedan fylls mallen i med våra data och SQL och parametrar returneras.
Vi har också definierat en anpassad implementering som är specifik för Oracle-backend. Funktionen as_oracle() kommer att anropas istället för as_sql() om Oracle-backend används.
Slutligen implementerar vi resten av de metoder som gör att vårt frågeuttryck kan fungera bra tillsammans med andra frågeuttryck:
\ndef get_source_expressions(self):\n return self.expressions\n\n\ndef set_source_expressions(self, expressions):\n self.expressions = expressions\nLåt oss se hur det fungerar:
\n>>> from django.db.models import F, Value, CharField\n>>> qs = Company.objects.annotate(\n... tagline=Coalesce(\n... [F("motto"), F("ticker_name"), F("description"), Value("No Tagline")],\n... output_field=CharField(),\n... )\n... )\n>>> for c in qs:\n... print("%s: %s" % (c.name, c.tagline))\n...\nGoogle: Do No Evil\nApple: AAPL\nYahoo: Internet Company\nDjango Software Foundation: No Tagline\nEftersom nyckelordsargumenten i en Func för __init__() (**extra) och as_sql() (**extra_context) interpoleras in i SQL-strängen i stället för att skickas som frågeparametrar (där databasdrivrutinen skulle undkomma dem), får de inte innehålla otillförlitlig användarinmatning.
Om till exempel substring är användartillhandahållen, är denna funktion sårbar för SQL-injektion:
from django.db.models import Func\n\n\nclass Position(Func):\n function = "POSITION"\n template = "%(function)s('%(substring)s' in %(expressions)s)"\n\n def __init__(self, expression, substring):\n # substring=substring is an SQL injection vulnerability!\n super().__init__(expression, substring=substring)\nDenna funktion genererar en SQL-sträng utan några parametrar. Eftersom substring skickas till super().__init__() som ett nyckelordsargument, interpoleras det till SQL-strängen innan frågan skickas till databasen.
Här är en korrigerad omskrivning:
\nclass Position(Func):\n function = "POSITION"\n arg_joiner = " IN "\n\n def __init__(self, expression, substring):\n super().__init__(substring, expression)\nOm substring istället skickas som ett positionellt argument kommer det att skickas som en parameter i databasfrågan.
Om du använder en databasbackend som använder en annan SQL-syntax för en viss funktion kan du lägga till stöd för den genom att apa till en ny metod till funktionens klass.
\nLåt oss säga att vi skriver en backend för Microsofts SQL Server som använder SQL LEN istället för LENGTH för funktionen Length. Vi kommer att apa patch en ny metod som heter as_sqlserver() på klassen Length:
from django.db.models.functions import Length\n\n\ndef sqlserver_length(self, compiler, connection):\n return self.as_sql(compiler, connection, function="LEN")\n\n\nLength.as_sqlserver = sqlserver_length\nDu kan också anpassa SQL genom att använda parametern template i as_sql().
Vi använder as_sqlserver() eftersom django.db.connection.vendor returnerar sqlserver för backend.
Tredjeparts backends kan registrera sina funktioner i toppnivån __init__.py-filen i backend-paketet eller i en toppnivå expressions.py-fil (eller paket) som importeras från toppnivån __init__.py.
För användarprojekt som vill patcha den backend som de använder bör den här koden finnas i en AppConfig.ready()-metod.