Les expressions de requête décrivent une valeur ou un calcul pouvant faire partie d’une mise à jour, d’une création, d’un filtre, d’un tri, d’une annotation ou d’une agrégation. Il existe un certain nombre d’expressions intégrées (documentées ci-dessous) pouvant aider à construire des requêtes. Les expressions peuvent être combinées, ou même imbriquées dans certains cas, afin de former des calculs plus complexes.
\nDjango prend en charge la négation, l’addition, la soustraction, la multiplication, la division, l’arithmétique modulo ainsi que l’opérateur de puissance pour les expressions de requête, à l’aide de constantes Python, de variables et même d’autres expressions.
\n\nfrom django.db.models import Count, F, Value\nfrom django.db.models.functions import Length, Upper\n\n# Find companies that have more employees than chairs.\nCompany.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.\nCompany.objects.filter(num_employees__gt=F('num_chairs') * 2)\nCompany.objects.filter(\n 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 = Company.objects.filter(\n... num_employees__gt=F('num_chairs')).annotate(\n... chairs_needed=F('num_employees') - F('num_chairs')).first()\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# Be sure to refresh it if you need to access the field.\n>>> company.refresh_from_db()\n>>> company.ticker\n'GOOG'\n\n# Annotate models with an aggregated value. Both forms\n# below are equivalent.\nCompany.objects.annotate(num_products=Count('products'))\nCompany.objects.annotate(num_products=Count(F('products')))\n\n# Aggregates can contain complex computations also\nCompany.objects.annotate(num_offerings=Count(F('products') + F('services')))\n\n# Expressions can also be used in order_by(), either directly\nCompany.objects.order_by(Length('name').asc())\nCompany.objects.order_by(Length('name').desc())\n# or using the double underscore lookup syntax.\nfrom django.db.models import CharField\nfrom django.db.models.functions import Length\nCharField.register_lookup(Length)\nCompany.objects.order_by('name__length')\nF()Lien vers cette rubrique#Un objet F() représente la valeur d’un champ de modèle ou d’une colonne annotée. Il permet de se référer à des valeurs de champs de modèles et d’effectuer avec elles des opérations en base de données sans avoir à les récupérer préalablement de la base de données vers la mémoire Python.
Au lieu de cela, Django utilise un objet F() pour générer une expression SQL qui décrit l’opération requise au niveau de la base de données.
Il est plus simple de faire comprendre cela par un exemple. Normalement, on peut faire quelque chose comme ceci :
\n# Tintin filed a news story!\nreporter = Reporters.objects.get(name='Tintin')\nreporter.stories_filed += 1\nreporter.save()\nIci, nous avons obtenu en mémoire la valeur de reporter.stories_filed à partir de la base de données et nous l’avons manipulée avec des opérateurs Python familiers. Nous avons ensuite enregistré l’objet modifié en base de données. Cependant, nous aurions tout aussi bien pu écrire :
from django.db.models import F\n\nreporter = Reporters.objects.get(name='Tintin')\nreporter.stories_filed = F('stories_filed') + 1\nreporter.save()\nMême si reporter.stories_filed = F('stories_filed') + 1 apparaît comme une attribution normale de valeur à un attribut d’instance en Python, il s’agit en réalité d’une construction SQL décrivant une opération en base de données.
Lorsque Django rencontre une instance de F(), il surcharge les opérateurs Python standards pour créer une expression SQL encapsulée ; dans ce cas, une instruction qui demande à la base de données d’incrémenter le champ de base de données représenté par reporter.stories_filed.
Quelle que soit la valeur que contenait reporter.stories_filed, Python n’a jamais besoin de la connaître, car tout se passe en base de données. Tout ce que Python fait à travers la classe F() de Django est de créer la syntaxe SQL pour se référer au champ et décrire l’opération.
Pour accéder à la nouvelle valeur qui a été enregistrée de cette manière, l’objet doit être rechargé :
\nreporter = Reporters.objects.get(pk=reporter.pk)\n# Or, more succinctly:\nreporter.refresh_from_db()\nEn plus d’être utilisée dans les opérations sur des instances uniques comme ci-dessus, F() peut être utilisée sur des jeux QuerySets d’instances d’objets, avec update(). Cela permet de réduire les deux requêtes utilisées ci-dessus, get() et save(), à une seule :
reporter = Reporters.objects.filter(name='Tintin')\nreporter.update(stories_filed=F('stories_filed') + 1)\nNous pouvons aussi utiliser update() pour incrémenter la valeur du champ sur plusieurs objets, ce qui peut être beaucoup plus rapide que de récupérer toutes les valeurs en Python depuis la base de données, de les passer en boucle en incrémentant la valeur des champs pour chacun, et de les réenregistrer individuellement dans la base de données :
Reporter.objects.all().update(stories_filed=F('stories_filed') + 1)\nF() peut donc offrir des avantages de performance en :
faisant travailler la base de données plutôt que le code Python ;
réduisant le nombre de requêtes de certaines opérations.
F()Lien vers cette rubrique#Un autre bénéfice notable de F() est que de faire mettre à jour la valeur d’un champ par la base de données plutôt qu’en Python évite un conflit de concurrence.
Si deux fils d’exécution Python exécutent le code du premier exemple ci-dessus, un des fils pourrait obtenir, incrémenter et enregistrer une valeur de champ après que l’autre fil l’ait obtenu de la base de données. La valeur enregistrée par le second fil d’exécution sera basé sur la valeur d’origine ; le travail du premier fil d’exécution sera tout simplement perdu.
\nSi c’est la base de données qui est responsable de la mise à jour du champ, le processus est plus robuste : la valeur du champ sera toujours mise à jour en fonction de sa valeur en base de données au moment même de l’appel à save() ou update(), et non pas en fonction de la valeur obtenue au moment de la création de l’instance de modèle.
F() persistent après Model.save()Lien vers cette rubrique#Les objets F() attribués aux champs de modèles persistent après l’enregistrement de l’instance de modèle et seront appliqués pour chaque save(). Par exemple :
reporter = Reporters.objects.get(name='Tintin')\nreporter.stories_filed = F('stories_filed') + 1\nreporter.save()\n\nreporter.name = 'Tintin Jr.'\nreporter.save()\nstories_filed sera mis à jour deux fois dans ce cas. SI la valeur initiale est 1, la valeur finale sera 3. Cette persistance peut être évitée en rechargeant le modèle après son enregistrement, par exemple en utilisant refresh_from_db().
F() dans les filtresLien vers cette rubrique#F() est aussi très utile dans les filtres QuerySet, là où il est possible de filtrer un jeu d’objets en fonction de critères basés sur les valeurs des champs, plutôt que sur des valeurs Python.
Cette utilisation est documentée dans Expressions F() dans les requêtes.
\nF() avec les annotationsLien vers cette rubrique#F() peut être utilisée pour créer des champs dynamiques pour les modèles en combinant plusieurs champs de manière arithmétique :
company = Company.objects.annotate(\n chairs_needed=F('num_employees') - F('num_chairs'))\nSi les champs que vous combinez sont de types différents, il est nécessaire d’indiquer à Django le type de champ qui en résultera. Comme F() ne prend pas directement en charge output_field, il faut envelopper l’expression dans 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()))\nLorsqu’elle fait référence à des champs relationnels tels qu’une clé ForeignKey, F() renvoie la valeur de clé primaire plutôt qu’une instance de modèle :
>> car = Company.objects.annotate(built_by=F('manufacturer'))[0]\n>> car.manufacturer\n<Manufacturer: Toyota>\n>> car.built_by\n3\nF() pour trier les valeurs nullesLien vers cette rubrique#Utilisez F() et les paramètres nommés nulls_first ou nulls_last des expressions Expression.asc() ou desc() pour contrôler le tri des valeurs nulles d’un champ. Par défaut, l’ordre dépend de la base de données.
Par exemple, pour trier les entreprises qui n’ont pas été contactées (last_contacted est nul) après les entreprises qui ont été contactées
from django.db.models import F\nCompany.object.order_by(F('last_contacted').desc(nulls_last=True))\nFunc()Lien vers cette rubrique#Les expressions Func() sont le type de base de toutes les expressions qui impliquent des fonctions de base de données telles que COALESCE et LOWER, ou des agrégations comme SUM. Elles peuvent être utilisées directement :
from django.db.models import F, Func\n\nqueryset.annotate(field_lower=Func(F('field'), function='LOWER'))\nou elles peuvent être utilisées pour bâtir une bibliothèque de fonctions de base de données :
\nclass Lower(Func):\n function = 'LOWER'\n\nqueryset.annotate(field_lower=Lower('field'))\nMais dans les deux cas, chaque modèle du jeu de requête résultant sera annoté avec un attribut supplémentaire field_lower dont le contenu correspondra plus ou moins au code SQL suivant :
SELECT\n ...\n LOWER("db_table"."field") as "field_lower"\nVoir Fonctions de base de données pour une liste de fonctions de base de données intégrées.
\nL’API Func se présente comme suit :
Un attribut de classe décrivant la fonction qui sera générée. Plus précisément, function sera inséré par le substituant function à l’intérieur de template. Sa valeur par défaut est None.
Un attribut de classe, sous forme de chaîne de format, qui décrit le code SQL généré pour cette fonction. Sa valeur par défaut est '%(function)s(%(expressions)s)'.
SI vous construisez du code SQL tel que strftime('%W', 'date') et que vous avez besoin d’un caractère littéral % dans la requête, vous devez le quadrupler (%%%%) dans l’attribut template car la chaîne est interpolée deux fois : une fois pendant l’interpolation du gabarit dans as_sql(), et une autre fois dans l’interpolation SQL avec les paramètres de requête dans le curseur de base de données.
Un attribut de classe qui précise la séquence de caractères utilisée pour joindre les éléments de la liste d”expressions. Sa valeur par défaut est ', '.
Un attribut de classe qui indique le nombre de paramètres acceptés par la fonction. Si cet attribut est défini et que la fonction est appelée avec un nombre d’expressions différent, une exception TypeError sera générée. La valeur par défaut est None.
Produit le code SQL pour la fonction de base de données.
\nLes méthodes as_vendor() devraient utiliser les paramètres function, template, arg_joiner et tout autre paramètre **extra_context pour adapter le code SQL en cas de besoin. Par exemple :
class ConcatPair(Func):\n ...\n function = 'CONCAT'\n ...\n\n def as_mysql(self, compiler, connection, **extra_context):\n return super().as_sql(\n compiler, connection,\n function='CONCAT_WS',\n template="%(function)s('', %(expressions)s)",\n **extra_context\n )\nPour éviter une vulnérabilité d’injection SQL, extra_context ne doit pas contenir de contenu non sûr provenant des utilisateurs car ces valeurs sont insérées dans la chaîne SQL et non passées comme paramètres de requête, auquel cas le pilote de base de données les aurait échappés.
Le paramètre *expressions est une liste d’expressions positionnelles auxquelles la fonction s’applique. Les expressions sont converties en chaînes, jointes par arg_joiner, puis insérées dans template par le substituant expressions.
Les paramètres positionnels peuvent être des expressions ou des valeurs Python. Les chaînes sont censées être des références de colonnes et seront enveloppées dans des expressions F() alors que les autres valeurs sont enveloppées dans des expressions Value().
Les paramètres nommés **extra sont des paires clé=valeur qui peuvent être insérées dans l’attribut template. Pour éviter une vulnérabilité d’injection SQL, extra ne doit pas contenir de contenu non sûr provenant des utilisateurs car ces valeurs sont insérées dans la chaîne SQL et non passées comme paramètres de requête, auquel cas le pilote de base de données les aurait échappés.
Les mots-clés function, template et arg_joiner peuvent être utilisés pour remplacer les attributs de même nom sans avoir besoin de définir une classe spécifique. output_field peut être utilisé pour définir le type de la valeur renvoyée.
Aggregate()Lien vers cette rubrique#Une expression d’agrégation est un cas particulier d’une expression Func() qui informe la requête qu’une clause GROUP BY est nécessaire. Toutes les fonctions d’agrégation comme Sum() et Count() héritent de Aggregate().
Comme les Aggregate sont des des expressions et enveloppent des expressions, il est possible de représenter des calculs complexes :
from django.db.models import Count\n\nCompany.objects.annotate(\n managers_required=(Count('num_employees') / 4) + Count('num_managers'))\nL’API Aggregate se présente comme suit :
Un attribut de classe, sous forme de chaîne de format, qui décrit le code SQL généré pour cette agrégation. Sa valeur par défaut est '%(function)s(%(distinct)s%(expressions)s)'.
Un attribut de classe décrivant la fonction d’agrégation qui sera générée. Plus précisément, function sera inséré par le substituant function à l’intérieur de template. Sa valeur par défaut est None.
Vaut True par défaut car la plupart des fonctions d’agrégat peuvent être utilisées comme expression source dans Window.
Un attribut de classe déterminant si cette fonction d’agrégat permet de passer un paramètre nommé distinct. Si défini à False (par défaut), TypeError est générée si distinct=True est transmis.
Les paramètres positionnels expressions peuvent inclure des expressions ou des noms de champs de modèle. Ils seront convertis en texte et utilisé comme substituant expressions à l’intérieur de template.
Le paramètre output_field doit être une instance de champ de modèle, comme IntegerField() ou BooleanField(), dans laquelle Django chargera la valeur après qu’elle aura été reçue de la base de données. Aucun paramètre n’est habituellement nécessaire lors de la création de l’instance du champ de modèle car aucun paramètre lié à la validation de données (max_length, max_digits, etc.) ne sera appliqué à la valeur résultante de l’expression.
Notez que output_field n’est obligatoire que lorsque Django est incapable de déterminer le type de champ du résultat. Les expressions complexes qui mélangent des types de champs doivent définir avec output_field le type de résultat attendu. Par exemple, l’addition d’un IntegerField() et d’un FloatField() va probablement demander la définition de output_field=FloatField().
Le paramètre distinct détermine si la fonction d’agrégat doit être invoquée pour chaque valeur distincte de expressions (ou ensemble de valeurs, en cas d’expressions multiples). Le paramètre n’est pris en charge que pour les agrégats qui possèdent allow_distinct à True.
Le paramètre filter accepte un objet Q utilisé pour filtrer les lignes agrégées. Voir Agrégation conditionnelle et Filtrage sur les annotations pour des exemples d’utilisation.
Les paramètres nommés **extra sont des paires clé=valeur qui peuvent être insérées par interpolation dans l’attribut template.
La création de ses propres agrégations est très facile. Il faut définir au minimum function, mais vous pouvez aussi personnaliser complètement le code SQL produit. Voici un court exemple :
from django.db.models import Aggregate\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\n def __init__(self, expression, all_values=False, **extra):\n super().__init__(\n expression,\n all_values='ALL ' if all_values else '',\n **extra\n )\nValue()Lien vers cette rubrique#Un objet Value() représente le composant le plus petit possible d’une expression : une simple valeur. Lorsque vous avez besoin de représenter la valeur d’un nombre entier, d’un booléen ou d’une chaîne à l’intérieur d’une expression, vous pouvez insérer cette valeur dans un objet Value().
Il est rarement nécessaire de faire appel directement à Value(). Lorsque vous écrivez l’expression F('champ') + 1, Django insère implicitement le 1 dans un objet Value(), ce qui permet d’utiliser des valeurs simples dans des expressions plus complexes. Value() devra être utilisé lors du passage d’une chaîne à une expression. La plupart des expressions interprètent un paramètre textuel comme le nom d’un champ, comme par exemple Lower('name').
Le paramètre value décrit la valeur à inclure dans l’expression, comme 1, True ou None. Django sait comment convertir ces valeurs Python dans le bon type de la base de données correspondante.
Le paramètre output_field doit être une instance de champ de modèle, comme IntegerField() ou BooleanField(), dans laquelle Django chargera la valeur après qu’elle aura été reçue de la base de données. Aucun paramètre n’est habituellement nécessaire lors de la création de l’instance du champ de modèle car aucun paramètre lié à la validation de données (max_length, max_digits, etc.) ne sera appliqué à la valeur résultante de l’expression.
ExpressionWrapper()Lien vers cette rubrique#ExpressionWrapper ne fait qu’entourer une autre expression et permet d’accéder aux propriétés, telles que output_field, qui pourraient ne pas être disponibles dans d’autres expressions. ExpressionWrapper est nécessaire lorsqu’on utilise de l’arithmétique avec les expressions F() avec différents types, comme décrit dans Utilisation de F() avec les annotations.
Les expressions conditionnelles permettent d’utiliser de la logique if … elif … else dans les requêtes. Django prend nativement en charge les expressions SQL CASE. Pour plus de détails, consultez Expressions conditionnelles.
Subquery()Lien vers cette rubrique#Il est possible d’ajouter des sous-requêtes explicites à un objet QuerySet en utilisant l’expression Subquery.
Par exemple, pour annoter chaque post avec l’adresse de courriel de l’auteur du commentaire le plus récent de ce post:
>>> 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]))\nAvec PostgreSQL, le code SQL ressemble à ceci :
\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"\nUtilisez OuterRef lorsqu’un jeu de requête dans une Subquery a besoin de se référer à un champ de la requête parente. Il se comporte comme une expression F sauf que le contrôle vérifiant s’il se réfère à un champ valable n’est pas effectué avant que la requête parente ne soit résolue.
Des instances de OuterRef peuvent être utilisées en lien avec des instances imbriquées de Subquery pour se référer à un jeu de requête supérieur qui n’est pas le parent immédiat. Par exemple, ce jeu de requête devrait se trouver dans une paire imbriquée d’instances Subquery pour être résolu correctement :
>>> Book.objects.filter(author=OuterRef(OuterRef('pk')))\nDans certaines circonstances, une seule colonne doit être renvoyée d’une sous-requête Subquery, par exemple quand on veut utiliser la sous-requête comme cible d’une recherche __in. Pour renvoyer tous les commentaires de posts publiés durant les dernières 24 heures :
>>> 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')))\nDans ce cas, la sous-requête doit utiliser values() pour ne renvoyer qu’une seule colonne : la clé primaire du post.
Pour empêcher une sous-requête de renvoyer plusieurs lignes, une segmentation ([:1]) du résultat de requête est appliquée :
>>> subquery = Subquery(newest.values('email')[:1])\n>>> Post.objects.annotate(newest_commenter_email=subquery)\nDans ce cas, la sous-requête ne doit renvoyer qu’une seule colonne et une seule ligne : l’adresse électronique du commentaire créé le plus récent.
\n(L’utilisation de get() à la place d’une segmentation ne fonctionnerait pas car OuterRef ne peut pas être résolu tant que le résultat de requête n’est pas utilisé dans une sous-requête Subquery.)
Exists()Lien vers cette rubrique#Exists est une sous-classe de Subquery utilisant une instruction SQL EXISTS. Dans bien des cas, la performance sera meilleure qu’une sous-requête car la base de données est capable de stopper l’évaluation de la sous-requête dès qu’une première ligne correspondante est trouvée.
Par exemple, pour annoter chaque post avec une indication de la présence ou non d’un commentaire durant la journée écoulée :
>>> 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))\nAvec PostgreSQL, le code SQL ressemble à ceci :
\nSELECT "post"."id", "post"."published_at", EXISTS(\n SELECT U0."id", U0."post_id", U0."email", U0."created_at"\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) AS "recent_comment" FROM "post"\nIl n’est pas nécessaire de forcer Exists à se référer à une seule colonne, car les colonnes sont ignorées et un résultat booléen est renvoyé. De même, comme le tri ne joue pas de rôle dans une sous-requête SQL EXISTS et ne ferait que baisser la performance, il est automatiquement enlevé.
Il est possible d’effectuer un NOT EXISTS avec ~Exists().
SubqueryLien vers cette rubrique#Il n’est pas possible de filtrer directement en utilisant Subquery et Exists, par ex. :
>>> Post.objects.filter(Exists(recent_comments))\n...\nTypeError: 'Exists' object is not iterable\nPour filtrer une expression de sous-requête, vous devez commencer par annoter le jeu de requête, puis filtrer sur la base de cette annotation :
\n>>> Post.objects.annotate(\n... recent_comment=Exists(recent_comments),\n... ).filter(recent_comment=True)\nSubqueryLien vers cette rubrique#Il est possible d’utiliser des agrégats dans une sous-requête, mais cela nécessite une combinaison spécifique de filter(), values() et annotate() afin d’obtenir un groupement correct dans la sous-requête.
En supposant que les deux modèles ont un champ length, voici comment trouver les posts dont la longueur est plus grande que la longueur totale de tous les commentaires ensemble :
>>> 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))\nLe premier filter(...) limite la sous-requête aux paramètres qui nous intéressent. order_by() enlève le tri ordering par défaut (le cas échéant) du modèle Comment, values('post') agrège les commentaires par Post. Pour terminer, annotate(...) effectue l’agrégation. L’ordre dans lequel sont appliqués ces méthodes de requête est important. Dans ce cas, comme la sous-requête doit être limitée à une seule colonne, values('total') est obligatoire.
Il s’agit de la seule manière d’effectuer une agrégation à l’intérieur d’une sous-requête, car aggregate() procède à l’évaluation du jeu de requête (et lorsqu’il existe une OuterRef, celle-ci ne pourrait pas être résolue).
Parfois, les expressions de base de données ne peuvent pas facilement exprimer une clause WHERE complexe. Dans ces cas limites, utilisez l’expression RawSQL. Par exemple :
>>> from django.db.models.expressions import RawSQL\n>>> queryset.annotate(val=RawSQL("select col from sometable where othercol = %s", (someparam,)))\nCes expressions brutes ne sont pas toujours portables entre moteurs de base de données (parce que vous écrivez du code SQL explicitement) et elles violent le principe DRY (ne pas se répéter), il s’agit donc de les éviter autant que possible.
\n\nLes fonctions de fenêtrage fournissent une méthode pour appliquer des fonctions aux partitions. Au contraire d’une fonction d’agrégat normale qui calcule le résultat final pour chaque ensemble défini par la clause de groupement, les fonctions de fenêtrage opèrent sur des intervalles (frames) et des partitions, et calculent le résultat pour chaque ligne.
\nVous pouvez définir plusieurs fenêtres dans la même requête, ce qui dans le contexte de l’ORM Django serait équivalent à inclure plusieurs expressions dans un appel à QuerySet.annotate(). L’ORM n’emploie pas les fenêtres nommées, elles font en fait partie des colonnes sélectionnées.
\nVaut False par défaut. Le standard SQL interdit le référencement de fonctions de fenêtrage dans la clause WHERE et Django génère une exception lors de la construction d’un QuerySet qui tenterait de faire cela.
Vaut par défaut %(expression)s OVER %(window)s. Si seul le paramètre expression est donné, la clause de fenêtrage sera vide.
La classe Window est l’expression principale d’une clause OVER.
Le paramètre expression est soit une fonction de fenêtrage, une fonction d’agrégat ou une expression compatible avec une clause de fenêtrage.
Le paramètre partition_by est une liste d’expressions (les noms de colonnes doivent être enveloppés dans des objets F) qui contrôlent le partitionnement des lignes. Le partitionnement limite les lignes utilisées pour calculer le jeu de résultats.
Le champ output_field est défini soit comme paramètre, soit par l’expression.
Le paramètre order_by accepte une suite d’expressions sur lesquelles vous pouvez appeler asc() et desc(). Ce tri contrôle l’odre dans lequel l’expression est appliquée. Par exemple, si vous faites la somme des lignes dans une partition, le premier résultat est simplement la valeur de la première ligne, le deuxième est la somme des première et deuxième lignes.
Le paramètre frame indique quelles autres lignes devraient être utilisées dans le calcul. Voir Portées (frames) pour plus de détails.
Par exemple, pour annoter chaque film avec la note moyenne des films du même studio dans le même genre et la même année
\n>>> from django.db.models import Avg, F, Window\n>>> from django.db.models.functions import ExtractYear\n>>> Movie.objects.annotate(\n>>> avg_rating=Window(\n>>> expression=Avg('rating'),\n>>> partition_by=[F('studio'), F('genre')],\n>>> order_by=ExtractYear('released').asc(),\n>>> ),\n>>> )\nCela rend simplement possible la comparaison de la note d’un film par rapport à ses semblables.
\nIl peut être intéressant d’appliquer plusieurs expressions sur la même fenêtre, c-à-d sur les mêmes partition et intervalle. Par exemple, l’exemple précédent pourrait être modifié pour inclure également la meilleure et la pire note dans chaque groupe de films (mêmes studio, genre et date de sortie) en utilisant trois fonctions de fenêtrage dans la même requête. La partition et le tri de l’exemple précédent sont extraits dans un dictionnaire pour réduire la répétition
\n>>> from django.db.models import Avg, F, Max, Min, Window\n>>> from django.db.models.functions import ExtractYear\n>>> window = {\n>>> 'partition_by': [F('studio'), F('genre')],\n>>> 'order_by': ExtractYear('released').asc(),\n>>> }\n>>> Movie.objects.annotate(\n>>> avg_rating=Window(\n>>> expression=Avg('rating'), **window,\n>>> ),\n>>> best=Window(\n>>> expression=Max('rating'), **window,\n>>> ),\n>>> worst=Window(\n>>> expression=Min('rating'), **window,\n>>> ),\n>>> )\nParmi les moteurs de base de données inclus dans Django, MySQL 8.0.2+, PostgreSQL et Oracle prennent en charge les expressions de fenêtrage. La prise en charge des diverses fonctionnalités des expressions de fenêtrage varie en fonction des bases de données. Par exemple, les options dans asc() et desc() ne sont pas toujours prises en charge. Consultez la documentation de votre base de données si nécessaire.
Pour une portée de fenêtre, vous pouvez choisir soit une suite de lignes basée sur des intervalles, soit une suite de lignes normale.
\nCet attribut est défini à 'RANGE'.
PostgreSQL ne prend en charge ValueRange que de manière limitée et ne gère que les points de début et de fin standard, tels que CURRENT ROW et UNBOUNDED FOLLOWING.
Cet attribut est défini à 'ROWS'.
Les deux classes renvoient du SQL selon le gabarit
\n%(frame_type)s BETWEEN %(start)s AND %(end)s\nLes portées réduisent le nombre de lignes utilisées pour calculer le résultat. Elles ciblent un point de départ donné jusqu’à un point d’arrivée. Les portées peuvent être utilisées avec ou sans partition, mais il est généralement utile d’indiquer un tri de la fenêtre pour s’assurer d’un résultat déterministe. Dans une portée, un pair est une ligne de valeur équivalente, ou toutes les lignes si aucune clause de tri n’est présente.
\nLe point de départ par défaut d’une portée est UNBOUNDED PRECEDING qui correspond à la première ligne de la partition. Le point d’arrivée est toujours explicitement inclus dans le code SQL généré par l’ORM et vaut par défaut UNBOUNDED FOLLOWING. La portée par défaut contient toutes les lignes de la partition jusqu’à la dernière ligne du jeu de données.
Les valeurs acceptées des paramètres start et end sont None, un nombre entier ou zéro. Un nombre négatif pour start produit N preceding, alors que None produit UNBOUNDED PRECEDING. Pour start comme pour end, zéro renvoie CURRENT ROW. Des nombres entiers positifs sont acceptés pour end.
Il y a une différence dans ce que CURRENT ROW contient. Lorsqu’il est défini en mode ROWS, l’intervalle commence et se termine avec la ligne en cours. Lorsqu’il est défini en mode RANGE, l’intervalle commence et se termine à la première ou à la dernière ligne du groupe en fonction de la clause de tri. Ainsi, RANGE CURRENT ROW évalue l’expression pour les lignes qui ont la même valeur définie par le tri. Comme le gabarit contient à la fois les points start et end, cela peut être exprimé par
ValueRange(start=0, end=0)\nSi les « semblables » d’un film sont définis comme les films publiés par le même studio dans le même genre et la même année, cet exemple RowRange annote chaque film avec la note moyenne des deux films précédents et des deux films suivants le film concerné
>>> from django.db.models import Avg, F, RowRange, Window\n>>> from django.db.models.functions import ExtractYear\n>>> Movie.objects.annotate(\n>>> avg_rating=Window(\n>>> expression=Avg('rating'),\n>>> partition_by=[F('studio'), F('genre')],\n>>> order_by=ExtractYear('released').asc(),\n>>> frame=RowRange(start=-2, end=2),\n>>> ),\n>>> )\nSi la base de données le gère, vous pouvez définir les points de départ et de fin sur la base des valeurs d’une expression dans la partition. Si le champ released du model Movie stocke le mois de publication de chaque film, cet exemple ValueRange annote chaque film avec la note moyenne des films semblables publiés entre douze mois avant et douze mois après chaque film.
>>> from django.db.models import Avg, ExpressionList, 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=F('released').asc(),\n>>> frame=ValueRange(start=-12, end=12),\n>>> ),\n>>> )\nVous trouverez ci-après des détails d’implémentation technique pouvant être utiles aux auteurs de bibliothèques. L’API technique et les exemples qui suivent aident à créer des expressions de requête génériques pouvant étendre les fonctionnalités intégrées que Django propose.
\nLes expressions de requête implémentent l”API d’expressions de requête, mais exposent également un certain nombre de méthodes et d’attributs supplémentaires énumérés ci-dessous. Toutes les expressions de requête doivent hériter de Expression() ou d’une sous-classe appropriée.
Lorsqu’une expression de requête englobe une autre expression, elle est responsable d’appeler les méthodes appropriées de l’expression englobée.
\nIndique à Django que cette expression contient une agrégation et qu’une clause GROUP BY doit être ajoutée à la requête.
Indique à Django que cette expression contient une expression Window. C’est par exemple utilisé pour interdire les expressions de fonction de fenêtrage dans les requêtes qui modifient des données.
Indique à Django que cette expression peut être référencée dans QuerySet.filter(). Vaut True par défaut.
Indique à Django que cette expression peut être utilisée comme expression source dans Window. Vaut False par défaut.
Offre l’opportunité d’effectuer un éventuel pré-traitement ou validation de l’expression avant que celle-ci ne soit ajoutée à la requête. resolve_expression() doit aussi être appelée pour toute expression imbriquée. Une copie copy() de self devrait être renvoyée avec les éventuelles transformations nécessaires.
query est l’implémentation de la requête en fonction du moteur de base de données.
allow_joins est une valeur booléenne permettant ou interdisant l’utilisation de jointures dans la requête.
reuse est un ensemble de jointures réutilisables dans des scénarios de jointures multiples.
summarize est une valeur booléenne qui, quand elle vaut True, signale que la requête en cours de calcul est une requête d’agrégation terminale.
for_save est une valeur booléenne qui, quand elle vaut True, signale que la requête en cours d’exécution effectue une création ou une mise à jour.
Renvoie une liste triée d’expressions internes. Par exemple :
\n>>> Sum(F('foo')).get_source_expressions()\n[F('foo')]\nAccepte une liste d’expressions et les stocke afin que get_source_expressions() puisse les restituer.
Renvoie un clone (copie) de self, sachant que tout alias de colonne aura été renommé. Les alias de colonnes sont renommés lorsque des sous-requêtes sont créées. relabeled_clone() doit également être appelée pour toute expression imbriquée et attribuée au clone.
change_map est un dictionnaire faisant correspondre les anciens alias aux nouveaux.
Exemple :
\ndef relabeled_clone(self, change_map):\n clone = copy.copy(self)\n clone.expression = self.expression.relabeled_clone(change_map)\n return clone\nUn point d’entrée permettant à l’expression de forcer value à un type plus approprié.
Responsable du renvoi de la liste des colonnes référencées par cette expression. get_group_by_cols() doit être appelée sur toute expression imbriquée. Les objets F() en particulier détiennent une référence sur une colonne.
Renvoie l’expression prête à être triée dans l’ordre croissant.
\nnulls_first et nulls_last définissent comment les valeurs nulles sont triées. Voir Utilisation de F() pour trier les valeurs nulles pour un exemple d’utilisation.
Renvoie l’expression prête à être triée dans l’ordre décroissant.
\nnulls_first et nulls_last définissent comment les valeurs nulles sont triées. Voir Utilisation de F() pour trier les valeurs nulles pour un exemple d’utilisation.
Renvoie self avec toute modification nécessaire pour inverser l’ordre de tri à l’intérieur d’un appel order_by. Comme exemple, une expression implémentant NULLS LAST changerait sa valeur pour devenir NULLS FIRST. Les modifications sont uniquement requises pour les expressions qui implémentent l’ordre de tri telles que OrderBy. Cette méthode est appelée lorsque reverse() est appelée sur un jeu de requête (QuerySet).
Vous pouvez écrire vos propres classes d’expression de requête qui utilisent et peuvent s’intégrer avec d’autres expressions de requête. Prenons un exemple en écrivant une implémentation de la fonction SQL COALESCE, sans utiliser les expressions Func() intégrées.
La fonction SQL COALESCE est définie comme acceptant une liste de colonnes ou de valeurs. Elle renvoie la première colonne ou valeur qui n’est pas NULL.
Commençons par définir le gabarit à utiliser pour la génération du SQL ainsi qu’une méthode __init__() pour définir quelques attributs :
import copy\nfrom django.db.models import Expression\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\nNous effectuons quelques validations de base sur les paramètres, y compris le minimum de 2 colonnes ou valeurs, et nous nous assurons qu’il s’agisse bien d’expressions. output_field est ici obligatoire afin que Django sache à quel type de champ de modèle attribuer l’éventuel résultat.
Nous implémentons maintenant le prétraitement et la validation. Comme nous n’avons aucune validation propre à ce stade, nous ne faisons que la déléguer aux expressions imbriquées :
\ndef resolve_expression(self, query=None, allow_joins=True, reuse=None, summarize=False, for_save=False):\n c = self.copy()\n c.is_summary = summarize\n for pos, expression in enumerate(self.expressions):\n c.expressions[pos] = expression.resolve_expression(query, allow_joins, reuse, summarize, for_save)\n return c\nEnsuite, nous écrivons la méthode responsable de la génération du code 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, params\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 )')\nLes méthodes as_sql() savent gérer des paramètres nommés personnalisés, permettantaux méthodes as_nomfournisseur() de remplacer des données utilisées pour générer la chaîne SQL. Il est préférable d’utiliser des paramètres nommés pour as_sql() pour la personnalisation que de transformer self dans les méthodes as_nomfournisseur() car cela peut produire des erreurs lors du fonctionnement sur d’autres moteurs de base de données. Si votre classe s’appuie sur des attributs de classe pour définir des données, considérez la possibilité de permettre des surcharges dans votre méthode as_sql().
Nous générons le code SQL pour chacune des expressions en utilisant la méthode compiler.compile() et en combinant les résultats avec des virgules. Puis le gabarit est complété avec nos données et le code SQL est renvoyé avec ses paramètres.
Nous avons également défini une implémentation personnalisée spécifique au moteur Oracle. La fonction as_oracle() sera appelée à la place de as_sql() quand le moteur Oracle est en fonction.
Finalement, nous implémentons les autres méthodes qui permettent à notre expression de requête de collaborer harmonieusement avec d’autres expressions de requête :
\ndef get_source_expressions(self):\n return self.expressions\n\ndef set_source_expressions(self, expressions):\n self.expressions = expressions\nVoyons comment cela fonctionne :
\n>>> from django.db.models import F, Value, CharField\n>>> qs = Company.objects.annotate(\n... tagline=Coalesce([\n... F('motto'),\n... F('ticker_name'),\n... F('description'),\n... Value('No Tagline')\n... ], output_field=CharField()))\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\nComme les paramètres nommés d’une fonction Func pour __init__() (**extra) et as_sql() (**extra_context) sont interpolés pour former une chaîne SQL et non pas transmis comme paramètres de requête (où le pilote de base de données se serait chargé de les échapper), ils ne doivent pas contenir des données non sûres soumises par des utilisateurs.
Par exemple, si le contenu de substring provient d’un utilisateur, cette fonction est vulnérable à l’injection SQL
from django.db.models import Func\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 a SQL injection vulnerability!\n super().__init__(expression, substring=substring)\nCette fonction produit une chaîne SQL sans paramètre. Comme substring est transmis à super().__init__() comme paramètre nommé, il est interpolé dans la chaîne SQL avant que la requête soit envoyée à la base de données.
Voici une réécriture corrigée
\nclass Position(Func):\n function = 'POSITION'\n arg_joiner = ' IN '\n\n def __init__(self, expression, substring):\n super().__init__(substring, expression)\nQuand substring est transmis sous forme de paramètre positionnel, il est ensuite transmis comme paramètre à la requête de base de données.
Si vous utilisez un moteur de base de données qui utilise une syntaxe SQL différente pour certaines fonctions, vous pouvez ajouter sa prise en charge en greffant une nouvelle méthode dans la classe de la fonction.
\nAdmettons que nous écrivons un moteur pour SQL Server de Microsoft qui utilise l’instruction SQL LEN au lieu de LENGTH pour la fonction Length. Nous allons greffer une nouvelle méthode appelée as_sqlserver() dans la classe Length:
from django.db.models.functions import Length\n\ndef sqlserver_length(self, compiler, connection):\n return self.as_sql(compiler, connection, function='LEN')\n\nLength.as_sqlserver = sqlserver_length\nIl est aussi possible de personnaliser le code SQL en utilisant le paramètre template de as_sql().
Nous utilisons as_sqlserver() parce que django.db.connection.vendor renvoie sqlserver comme moteur.
Les moteurs tiers peuvent inscrire leurs fonctions dans le fichier __init__.py de premier niveau du paquet de moteur ou dans un fichier (ou paquet) expressions.py de premier niveauqui est lui-même importé depuis __init__.py.
Pour les projets d’utilisateurs qui souhaitent adapter le moteur qu’ils utilisent, ce code devrait se trouver dans une méthode AppConfig.ready().