QuerySetLien vers cette rubrique#Ce document détaille l’API des objets QuerySet. Il augmente les contenus présentés dans les guides des modèles et des requêtes de base de données, il est donc conseillé de lire et de comprendre ces derniers avant de lire celui-ci.
Tout au long de cette référence, nous utiliserons les modèles d’exemple Weblog présentés dans le guide des requêtes de base de données.
\nQuerySet sont évaluésLien vers cette rubrique#En interne, un objet QuerySet peut être construit, filtré, segmenté ou transmis sans devoir accéder à la base de données. Aucune activité de base de données n’est effectivement créée tant qu’une action ne provoque pas l’évaluation du jeu de requête.
Un QuerySet est évalué dans les contextes suivants :
Itération. Un QuerySet est itérable, et il exécute sa requête de base de données lors de la première itération. Par exemple, ceci affiche le titre de tous les articles de la base de données :
for e in Entry.objects.all():\n print(e.headline)\nNote : ne faites pas cela si vous voulez uniquement savoir s’il existe au moins un résultat. Il est plus efficace d’utiliser exists().
Segmentation. Comme expliqué dans Limitation des QuerySet, un QuerySet peut être segmenté par la syntaxe de segmentation de liste de Python. La segmentation d’un QuerySet non évalué renvoie habituellement un autre objet QuerySet non évalué, mais Django exécute la requête de base de données si vous employez le paramètre step de la syntaxe de segmentation, et dans ce cas, une liste est renvoyée. La segmentation d’un QuerySet qui a été évalué renvoie également une liste.
Notez également que bien que la segmentation d’un objet QuerySet non évalué renvoie un autre QuerySet non évalué, sa modification ultérieure (par ex. par l’ajout de filtres ou en modifiant l’ordre de tri) n’est plus permise, car cela se traduirait difficilement en termes SQL et la signification d’une telle opération ne serait pas claire non plus.
« Pickling »/mise en cache. Consultez la section suivante pour plus de détails sur les implications du « pickling » des objets QuerySets. L’élément important dans la perspective de cette section est que les résultats sont lus à partir de la base de données.
repr(). Un QuerySet est évalué lorsqu’on l’inclut dans un appel repr(). Ceci pour des raisons pratiques dans l’interpréteur interactif Python, afin de pouvoir visualiser immédiatement les résultats en utilisant l’API de manière interactive.
len(). Un QuerySet est évalué lorsqu’on l’inclut dans un appel len(). Ceci renvoie comme prévu la longueur de la liste résultante.
Note : si vous avez seulement besoin de connaître le nombre d’enregistrements du résultat (et que vous n’avez pas besoin des objets eux-mêmes), il est bien plus efficace de gérer la comptabilisation au niveau de la base de données en utilisant le code SQL SELECT COUNT(*). Django fournit une méthode count() précisément pour cette raison.
list(). Force l’évaluation d’un QuerySet lorsqu’on l’inclut dans un appel list(). Par exemple :
entry_list = list(Entry.objects.all())\nbool(). Le test d’un QuerySet dans un contexte booléen, comme par exemple en employant bool(), or, and ou if, va provoquer l’exécution de la requête. S’il existe au moins un résultat, le QuerySet renverra True, sinon False. Par exemple :
if Entry.objects.filter(headline="Test"):\n print("There is at least one Entry with the headline Test")\nNote : si tout ce qui vous intéresse est de déterminer s’il existe au moins un résultat (et que vous n’avez pas besoin des objets eux-mêmes), il est plus efficace d’utiliser exists().
QuerySet et « pickling »Lien vers cette rubrique#Si vous transformez un QuerySet par pickle, cela force tous les résultats à être chargés en mémoire avant le processus de pickling. Cette opération précède généralement une mise en cache, et lorsque le jeu de requête est récupéré du cache, il est souhaitable que les résultats soient disponibles et prêts à être utilisés (une lecture depuis la base de données peut prendre du temps, ce qui annulerait l’avantage du cache). Cela signifie que lorsqu’un objet QuerySet est reconstruit depuis sa représentation « pickle », il contient les résultats du moment où il a été transformé par « pickle », et non pas les résultats du moment actuel en base de données.
Si vous ne vouliez que mettre en « pickle » les informations utiles pour recréer le QuerySet à partir de la base de données au moment voulu, fournissez à pickle l’attribut query de QuerySet. Vous pouvez ensuite recréer le QuerySet original (sans chargement des résultats) en écrivant du code semblable à ceci :
>>> import pickle\n>>> query = pickle.loads(s) # Assuming 's' is the pickled string.\n>>> qs = MyModel.objects.all()\n>>> qs.query = query # Restore the original 'query'.\nL’attribut query est un objet opaque. Il constitue la représentation interne de la construction de la requête et ne fait pas partie de l’API publique. Cependant, la sérialisation et la désérialisation « pickle » du contenu de cet attribut est une opération sûre (et totalement acceptable).
QuerySetLien vers cette rubrique#Voici la déclaration formelle d’un QuerySet:
Normalement, lorsqu’on manipule un QuerySet, on le fait en enchaînant des filtres. Pour accomplir cela, la plupart des méthodes de QuerySet renvoient de nouveaux objets QuerySet. Ces méthodes sont décrites en détails plus loin dans cette section.
La classe QuerySet possède deux attributs publics qu’il est possible d’utiliser pour introspection :
True si le QuerySet est trié, c’est-à-dire qu’il comporte une clause order_by() ou un tri par défaut au niveau du modèle. Sinon, la valeur est False.
La base de données utilisée si la requête est exécutée tout de suite.
\nQuerySetLien vers cette rubrique#Django fournit un grand nombre de méthodes d’affinage des QuerySet qui modifient soit le type de résultats renvoyés par le QuerySet ou sa façon d’exécuter la requête SQL.
filter()Lien vers cette rubrique#Renvoie un nouveau QuerySet contenant les objets qui répondent aux paramètres de recherche donnés.
Les paramètres de recherche (**kwargs) doivent être dans le format décrit dans Recherches dans les champs ci-dessous. Plusieurs paramètres sont combinés via AND dans l’instruction SQL sous-jacente.
Si vous avez besoin d’exécuter des requêtes plus complexes (par exemple des requêtes contenant des instruction avec OR (OU)), vous pouvez utiliser des objets Q (*args).
exclude()Lien vers cette rubrique#Renvoie un nouveau QuerySet contenant les objets qui ne répondent pas aux paramètres de recherche donnés.
Les paramètres de recherche (**kwargs) doivent être dans le format décrit dans Recherches dans les champs ci-dessous. Plusieurs paramètres sont combinés via AND dans l’instruction SQL sous-jacente, et le tout est englobé dans un NOT().
Cet exemple exclut tous les éléments dont pub_date est postérieure à 2005-1-3 ET dont headline contient « Hello » :
Entry.objects.exclude(pub_date__gt=datetime.date(2005, 1, 3), headline='Hello')\nEn termes SQL, cela donne :
\nSELECT ...\nWHERE NOT (pub_date > '2005-1-3' AND headline = 'Hello')\nCet exemple exclut tous les éléments dont pub_date est postérieure à 2005-1-3 OU dont headline contient « Hello »
Entry.objects.exclude(pub_date__gt=datetime.date(2005, 1, 3)).exclude(headline='Hello')\nEn termes SQL, cela donne :
\nSELECT ...\nWHERE NOT pub_date > '2005-1-3'\nAND NOT headline = 'Hello'\nNotez que le second exemple est plus restrictif.
\nSi vous avez besoin d’exécuter des requêtes plus complexes (par exemple des requêtes contenant des instruction avec OR (OU)), vous pouvez utiliser des objets Q (*args).
annotate()Lien vers cette rubrique#Annote chaque objet du QuerySet avec la liste fournie d”expressions de requêtes. Une expression peut être une valeur simple, une référence à un champ du modèle (ou de tout modèle lié) ou une expression d’agrégation (moyennes, sommes, etc.) qui a été calculée sur les objets en liaison avec les objets du QuerySet.
Chaque paramètre d’annotate() est une annotation qui sera ajoutée à chaque objet du QuerySet renvoyé.
Les fonctions d’agrégation fournies par Django sont décrites plus loin dans Fonctions d’agrégation.
\nLes annotations spécifiées par des paramètres nommés utilisent la clé comme alias d’annotation. Les paramètres anonymes seront dotés d’un alias généré automatiquement sur la base du nom de la fonction d’agrégation et du champ de modèle sur lequel porte l’agrégation. Seules les expressions d’agrégation qui font référence à un seul champ peuvent constituer des paramètres anonymes. Tout le reste doit se présenter sous la forme d’un paramètre nommé.
\nPar exemple, si vous avez affaire à une liste de blogs, il peut être intéressant de déterminer le nombre d’articles écrits dans chaque blog :
\n>>> from django.db.models import Count\n>>> q = Blog.objects.annotate(Count('entry'))\n# The name of the first blog\n>>> q[0].name\n'Blogasaurus'\n# The number of entries on the first blog\n>>> q[0].entry__count\n42\nLe modèle Blog ne définit pas d’attribut entry__count par lui-même, mais en utilisant un paramètre nommé pour définir la fonction d’agrégation, vous pouvez contrôler le nom de l’annotation :
>>> q = Blog.objects.annotate(number_of_entries=Count('entry'))\n# The number of entries on the first blog, using the name provided\n>>> q[0].number_of_entries\n42\nPour une présentation approfondie de l’agrégation, consultez le guide thématique sur l’agrégation.
\nalias()Lien vers cette rubrique#Semblable à annotate(), mais au lieu d’annoter les objets de QuerySet, enregistre l’expression pour être réutilisée avec d’autres méthodes QuerySet. Cela est utile lorsque le résultat de l’expression lui-même n’est pas utile au final, mais uniquement employé pour filtrer, trier ou comme faisant partie d’une expression complexe. Le fait de ne pas sélectionner cette valeur non utile enlève du travail redondant au niveau de la base de données et devrait aboutir à de meilleures performances.
Par exemple, si vous souhaitez trouver des blogs avec mois de 5 articles, mais que le nombre exact d’articles ne vous intéresse pas, vous pourriez écrire ceci
\n>>> from django.db.models import Count\n>>> blogs = Blog.objects.alias(entries=Count('entry')).filter(entries__gt=5)\nalias() peut être utilisé conjointement avec annotate(), exclude(), filter(), order_by() et update(). Pour utiliser une expression avec alias avec d’autres méthodes (par ex. aggregate()), vous devez la promouvoir en tant qu’annotation
Blog.objects.alias(entries=Count('entry')).annotate(\n entries=F('entries'),\n).aggregate(Sum('entries'))\nfilter() et order_by() peuvent accepter directement des expressions, mais la construction et l’utilisation des expressions n’interviennent souvent pas à la même place (par exemple, la méthode QuerySet crée les expressions pour utilisation ultérieure dans les vues). alias() permet de construire des expressions complexes de manière incrémentale, recouvrant potentiellement plusieurs méthodes et modules, de se référer aux parties d’expression par leurs alias et d’utiliser uniquement annotate() pour le résultat final.
order_by()Lien vers cette rubrique#Par défaut, les résultats renvoyés par un QuerySet sont triés selon le tuple de tri défini par l’option ordering de la classe Meta du modèle. Vous pouvez surcharger cela pour chaque QuerySet en utilisant la méthode order_by.
Exemple :
\nEntry.objects.filter(pub_date__year=2005).order_by('-pub_date', 'headline')\nLes résultats ci-dessus seront triés par pub_date dans l’ordre chronologique inverse, puis par headline dans l’ordre alphabétique. Le signe moins devant "-pub_date" indique l”inversion de l’ordre de tri. Pour trier de manière aléatoire, utilisez "?" comme ceci :
Entry.objects.order_by('?')\nNote : les requêtes order_by('?') peuvent être coûteuses et lentes, en fonction du moteur de base de données utilisé.
Pour trier selon un champ d’un autre modèle, utilisez la même syntaxe que lorsque vous interrogez la base de données en traversant des relations. C’est-à-dire, le nom du champ suivi d’un double soulignement (__), suivi du nom du champ du nouveau modèle, et ainsi de suite pour autant de modèles que vous souhaitez combiner. Par exemple :
Entry.objects.order_by('blog__name', 'headline')\nSi vous essayez de trier selon un champ qui constitue une relation vers un autre modèle, Django utilise le tri par défaut du modèle lié, ou trie selon la clé primaire du modèle lié si aucun attribut Meta.ordering n’est présent. Par exemple, comme le modèle Blog ne possède par d’ordre de tri par défaut :
Entry.objects.order_by('blog')\n… est identique à :
\nEntry.objects.order_by('blog__id')\nSi Blog comportait ordering = ['name'], alors le premier jeu de requête serait identique à :
Entry.objects.order_by('blog__name')\nIl est aussi possible de trier par des expressions de requête en appelant asc() ou desc() sur l’expression :
Entry.objects.order_by(Coalesce('summary', 'headline').desc())\nasc() et desc() possèdent des paramètres (nulls_first and nulls_last) qui contrôlent la manière dont sont triées les valeurs nulles.
Soyez prudent lorsque vous triez selon des champs de modèles liés et que vous utilisez également distinct(). Consultez la note dans distinct() pour une explication sur l’impact possible du tri selon des modèles liés sur les résultats attendus.
Il n’est pas possible d’indiquer si le tri doit être sensible à la casse ou non. Dans cette optique, Django trie les résultats en fonction du comportement habituel de tri du moteur de base de données.
\nVous pouvez trier selon un champ converti en minuscules avec Lower, ce qui aboutira à un tri insensible à la casse :
Entry.objects.order_by(Lower('headline').desc())\nSi vous ne voulez pas qu’une requête soit triée, même pas selon le tri par défaut, appelez order_by() sans paramètre.
Vous pouvez savoir si une requête est triée ou pas en interrogeant l’attribut QuerySet.ordered, qui vaut True lorsque le QuerySet a été trié d’une manière ou d’une autre.
Chaque appel à order_by() efface tout ordre de tri préexistant. Par exemple, cette requête sera triée par pub_date et non pas par headline:
Entry.objects.order_by('headline').order_by('pub_date')\nreverse()Lien vers cette rubrique#Utilisez la méthode reverse() pour inverser l’ordre dans lequel les éléments d’un jeu de requête sont renvoyés. En appelant reverse() une seconde fois, l’ordre est rétabli selon l’ordre initial normal.
Pour récupérer les cinq « derniers » éléments d’un jeu de requête, vous pourriez écrire cela :
\nmy_queryset.reverse()[:5]\nNotez que ce n’est pas tout à fait la même chose que de segmenter à partir de la fin d’une liste en Python. L’exemple ci-dessus renvoie en premier le dernier élément, puis l’avant-dernier et ainsi de suite. Si nous avions une liste Python et que nous avions appliqué list[-5:], nous aurions obtenu les 5 derniers éléments. Django ne prend pas en charge ce mode d’accès avec les jeux de requête (segmentation à partir de la fin), car il n’est pas possible de le faire efficacement en SQL.
Signalons également que reverse() ne devrait généralement être appelé que pour un QuerySet dont l’ordre de tri est défini (par exemple, lors d’une requête sur un modèle définissant un tri par défaut ou en appelant order_by()). Si un QuerySet donné ne comporte pas d’ordre de tri, l’appel reverse() sur cet objet n’a pas d’effet réel (le tri n’étant pas défini avant l’appel à reverse(), il ne le sera pas plus après).
distinct()Lien vers cette rubrique#Renvoie un nouveau QuerySet utilisant SELECT DISTINCT dans sa requête SQL. Les lignes dupliquées sont alors supprimées des résultats de la requête.
Par défaut, un QuerySet n’élimine pas les lignes dupliquées. En pratique, c’est rarement un problème, car les requêtes simples comme Blog.objects.all() n’introduisent pas la possibilité de lignes de résultats dupliquées. Cependant, si la requête s’étend sur plusieurs tables, il est possible d’obtenir des résultats dupliqués lors de l’évaluation du QuerySet. C’est alors que distinct() devient utile.
Avec PostgreSQL uniquement, vous pouvez transmettre des paramètres positionnels (*fields) afin de préciser les noms des champs sur lesquels l’instruction DISTINCT s’applique. Cela produit une requête SQL du genre SELECT DISTINCT ON. Voici la différence. Pour un appel distinct() normal, la base de données compare chaque champ de chaque ligne pour déterminer quelles lignes sont distinctes. Lors d’un appel distinct() qui spécifie des noms de champs, la base de données ne compare que les champs indiqués pour déterminer les lignes distinctes.
Exemples (à partir du deuxième exemple, cela ne fonctionne qu’avec PostgreSQL) :
\n>>> Author.objects.distinct()\n[...]\n\n>>> Entry.objects.order_by('pub_date').distinct('pub_date')\n[...]\n\n>>> Entry.objects.order_by('blog').distinct('blog')\n[...]\n\n>>> Entry.objects.order_by('author', 'pub_date').distinct('author', 'pub_date')\n[...]\n\n>>> Entry.objects.order_by('blog__name', 'mod_date').distinct('blog__name', 'mod_date')\n[...]\n\n>>> Entry.objects.order_by('author', 'pub_date').distinct('author')\n[...]\nvalues()Lien vers cette rubrique#Renvoie un QuerySet qui renvoie des dictionnaires lorsqu’on l’utilise de manière itérable, au lieu d’instances de modèles.
Chacun de ces dictionnaires représente un objet, les clés correspondant aux noms d’attributs des objets de modèle.
\nCet exemple compare les dictionnaires de values() avec des objets de modèle normaux :
# This list contains a Blog object.\n>>> Blog.objects.filter(name__startswith='Beatles')\n<QuerySet [<Blog: Beatles Blog>]>\n\n# This list contains a dictionary.\n>>> Blog.objects.filter(name__startswith='Beatles').values()\n<QuerySet [{'id': 1, 'name': 'Beatles Blog', 'tagline': 'All the latest Beatles news.'}]>\nLa méthode values() accepte des paramètres positionnels facultatifs, *fields, qui définissent les noms de champs auxquels l’instruction SELECT se limitera. Si vous renseignez ces paramètres, chaque dictionnaire du résultat ne contiendra que les clés/valeurs des champs qui ont été indiqués. Si aucun de ces paramètres n’est présent, chaque dictionnaire du résultat contiendra une clé et une valeur pour tous les champs de la table de base de données correspondante.
Exemple :
\n>>> Blog.objects.values()\n<QuerySet [{'id': 1, 'name': 'Beatles Blog', 'tagline': 'All the latest Beatles news.'}]>\n>>> Blog.objects.values('id', 'name')\n<QuerySet [{'id': 1, 'name': 'Beatles Blog'}]>\nLa méthode values() accepte également des paramètres nommés facultatifs, **expressions, qui sont transmis par annotate():
>>> from django.db.models.functions import Lower\n>>> Blog.objects.values(lower_name=Lower('name'))\n<QuerySet [{'lower_name': 'beatles blog'}]>\nVous pouvez utiliser les requêtes intégrées ou personnalisées dans les tris. Par exemple
\n>>> from django.db.models import CharField\n>>> from django.db.models.functions import Lower\n>>> CharField.register_lookup(Lower)\n>>> Blog.objects.values('name__lower')\n<QuerySet [{'name__lower': 'beatles blog'}]>\nUne agrégation à l’intérieur d’une clause values() est appliquée avant les autres paramètres dans la même clause. Si vous avez besoin de grouper selon une autre valeur, ajoutez-la plutôt à une clause values() précédente. Par exemple :
>>> from django.db.models import Count\n>>> Blog.objects.values('entry__authors', entries=Count('entry'))\n<QuerySet [{'entry__authors': 1, 'entries': 20}, {'entry__authors': 1, 'entries': 13}]>\n>>> Blog.objects.values('entry__authors').annotate(entries=Count('entry'))\n<QuerySet [{'entry__authors': 1, 'entries': 33}]>\nQuelques subtilités qui valent la peine d’être mentionnées :
\nSi un champ appelé foo est un champ ForeignKey, l’appel values() par défaut renvoie une clé de dictionnaire nommée foo_id, car il s’agit du nom interne de l’attribut de modèle stockant la valeur réelle (l’attribut foo se référant au modèle lié). Lorsque vous appelez values() et que vous indiquez des noms de champs, vous pouvez mentionner foo ou foo_id et vous obtiendrez le même résultat (la clé de dictionnaire correspond au nom du champ que vous avez mentionné).
Par exemple :
\n>>> Entry.objects.values()\n<QuerySet [{'blog_id': 1, 'headline': 'First Entry', ...}, ...]>\n\n>>> Entry.objects.values('blog')\n<QuerySet [{'blog': 1}, ...]>\n\n>>> Entry.objects.values('blog_id')\n<QuerySet [{'blog_id': 1}, ...]>\nLors d’une utilisation combinée de values() et de distinct(), soyez conscient que le tri peut affecter les résultats. Consultez la note dans distinct() pour plus de détails.
Si vous utilisez une clause values() après un appel à extra(), tout champ mentionné dans un paramètre select de extra() doit être explicitement inclus dans l’appel à values(). Lors de tout appel à extra() après un appel à values(), les champs sélectionnés supplémentaires sont ignorés.
Les appels à only() et defer() après values() n’ont pas de sens, et si vous le faites, vous obtiendrez une exception TypeError.
La combinaison de transformations et d’agrégats nécessite l’emploi de deux appels à annotate(), soit explicitement ou sous forme de paramètres nommés à meth:values. Comme ci-dessus, si la transformation a été inscrite pour le type de champ adéquat, le premier appel à annotate() peut être omis, ce qui signifie que les deux exemples suivants sont équivalents
>>> from django.db.models import CharField, Count\n>>> from django.db.models.functions import Lower\n>>> CharField.register_lookup(Lower)\n>>> Blog.objects.values('entry__authors__name__lower').annotate(entries=Count('entry'))\n<QuerySet [{'entry__authors__name__lower': 'test author', 'entries': 33}]>\n>>> Blog.objects.values(\n... entry__authors__name__lower=Lower('entry__authors__name')\n... ).annotate(entries=Count('entry'))\n<QuerySet [{'entry__authors__name__lower': 'test author', 'entries': 33}]>\n>>> Blog.objects.annotate(\n... entry__authors__name__lower=Lower('entry__authors__name')\n... ).values('entry__authors__name__lower').annotate(entries=Count('entry'))\n<QuerySet [{'entry__authors__name__lower': 'test author', 'entries': 33}]>\nC’est utile lorsque vous savez que vous n’aurez besoin que d’un petit nombre des champs disponibles et que vous n’aurez pas besoin des fonctionnalités d’un objet d’instance de modèle. Il est plus efficace de ne sélectionner que les champs dont vous aurez besoin.
\nEnfin, notez que vous pouvez appeler filter(), order_by(), etc. après l’appel à values(), ce qui signifie que ces deux appels sont identiques :
Blog.objects.values().order_by('id')\nBlog.objects.order_by('id').values()\nLes concepteurs de Django préfèrent placer en premier les méthodes affectant le code SQL, suivies (facultativement) par toute méthode affectant le format (comme values()), mais ce n’est pas essentiel. C’est l’occasion de mettre en évidence votre individualisme.
Vous pouvez aussi faire référence à des modèles liés par des relations inverses au travers d’attributs OneToOneField, ForeignKey et ManyToManyField:
>>> Blog.objects.values('name', 'entry__headline')\n<QuerySet [{'name': 'My blog', 'entry__headline': 'An entry'},\n {'name': 'My blog', 'entry__headline': 'Another entry'}, ...]>\nvalues_list()Lien vers cette rubrique#Semblable à values(), sauf qu’au lieu de renvoyer des dictionnaires, ce sont des tuples qui sont renvoyés lors de l’itération des résultats. Chaque tuple contient les valeurs des champs ou expressions dans la position respective de leur apparition dans l’appel à values_list() — premier champ comme premier élément, etc. Par exemple :
>>> Entry.objects.values_list('id', 'headline')\n<QuerySet [(1, 'First entry'), ...]>\n>>> from django.db.models.functions import Lower\n>>> Entry.objects.values_list('id', Lower('headline'))\n<QuerySet [(1, 'first entry'), ...]>\nSi vous n’indiquez qu’un seul champ, il est aussi possible d’indiquer le paramètre flat. S’il vaut True, cela signifie que les résultats renvoyés sont des valeurs uniques au lieu de tuples simples. Cet exemple devrait éclairer la différence :
>>> Entry.objects.values_list('id').order_by('id')\n<QuerySet[(1,), (2,), (3,), ...]>\n\n>>> Entry.objects.values_list('id', flat=True).order_by('id')\n<QuerySet [1, 2, 3, ...]>\nC’est une erreur d’indiquer le paramètre flat lorsqu’il y a plus d’un champ.
Vous pouvez passer named=True pour obtenir les résultats sous forme de namedtuple():
>>> Entry.objects.values_list('id', 'headline', named=True)\n<QuerySet [Row(id=1, headline='First entry'), ...]>\nL’emploi d’un tuple nommé peut rendre les résultats plus lisibles, aux dépends d’une petite perte de performance pour la transformation des résultats en tuple nommé.
\nSi vous n’indiquez aucune valeur dans values_list(), tous les champs du modèle sont pris en compte dans le résultat, dans leur ordre de déclaration.
Un besoin fréquent est d’obtenir une valeur de champ spécifique d’une certaine instance de modèle. Pour faire cela, utilisez values_list() suivie d’un appel à get():
>>> Entry.objects.values_list('headline', flat=True).get(pk=1)\n'First entry'\nvalues() et values_list() doivent toutes deux être considérées comme des optimisations pour un cas d’utilisation spécifique : récupérer un sous-ensemble de données sans la surcharge de création des instances de modèles. Cette métaphore ne vaut plus lorsqu’on a affaire à des relations plusieurs-à-plusieurs ou multivaluées d’une autre manière. (comme la relation un-à-plusieurs d’une clé étrangère inverse) car la supposition « une ligne, un objet » ne tient plus.
Par exemple, remarquez le comportement lorsqu’une requête traverse un champ ManyToManyField:
>>> Author.objects.values_list('name', 'entry__headline')\n<QuerySet [('Noam Chomsky', 'Impressions of Gaza'),\n ('George Orwell', 'Why Socialists Do Not Believe in Fun'),\n ('George Orwell', 'In Defence of English Cooking'),\n ('Don Quixote', None)]>\nLes auteurs avec plusieurs Entry apparaissent plusieurs fois et les auteurs sans Entry possèdent None comme valeur de ce champ.
De la même façon, lors d’une requête par clé étrangère inverse, None apparaît pour les entrées sans auteur :
>>> Entry.objects.values_list('authors')\n<QuerySet [('Noam Chomsky',), ('George Orwell',), (None,)]>\ndates()Lien vers cette rubrique#Renvoie un QuerySet dont l’évaluation produit une liste d’objets datetime.date représentant toutes les dates disponibles d’un type particulier dans le contenu QuerySet.
field doit être le nom d’un champ DateField du modèle. kind doit être soit "year", "month", "week" ou "day". Chaque objet datetime.date de la liste de résultats est « tronqué » selon le type donné.
"year" renvoie une liste de toutes les valeurs d’années distinctes pour le champ.
"month" renvoie une liste de toutes les valeurs d’années/mois distinctes pour le champ.
"week" renvoie une liste de toutes les valeurs d’années/semaines distinctes pour le champ. Toutes les dates sont un lundi.
"day" renvoie une liste de toutes les valeurs d’années/mois/jours distinctes pour le champ.
order, dont la valeur par défaut est 'ASC', doit contenir soit 'ASC' (chronologique), soit 'DESC' (chronologique inverse). Cela indique comment trier les résultats.
Exemples :
\n>>> Entry.objects.dates('pub_date', 'year')\n[datetime.date(2005, 1, 1)]\n>>> Entry.objects.dates('pub_date', 'month')\n[datetime.date(2005, 2, 1), datetime.date(2005, 3, 1)]\n>>> Entry.objects.dates('pub_date', 'week')\n[datetime.date(2005, 2, 14), datetime.date(2005, 3, 14)]\n>>> Entry.objects.dates('pub_date', 'day')\n[datetime.date(2005, 2, 20), datetime.date(2005, 3, 20)]\n>>> Entry.objects.dates('pub_date', 'day', order='DESC')\n[datetime.date(2005, 3, 20), datetime.date(2005, 2, 20)]\n>>> Entry.objects.filter(headline__contains='Lennon').dates('pub_date', 'day')\n[datetime.date(2005, 3, 20)]\ndatetimes()Lien vers cette rubrique#Renvoie un QuerySet dont l’évaluation produit une liste d’objets datetime.datetime représentant toutes les dates disponibles d’un type particulier dans le contenu QuerySet.
field_name doit correspondre au nom d’un champ DateTimeField de votre modèle.
kind doit être soit "year", "month", "week", "day", "hour", "minute" ou "second". Chaque objet datetime.datetime de la liste de résultats est « tronqué » selon le type donné.
order, dont la valeur par défaut est 'ASC', doit contenir soit 'ASC' (chronologique), soit 'DESC' (chronologique inverse). Cela indique comment trier les résultats.
tzinfo définit le fuseau horaire dans lequel les dates/heures sont converties avant leur troncature. En effet, un date/heure peut être représentée différemment en fonction du fuseau horaire actif. Ce paramètre doit être un objet datetime.tzinfo. S’il vaut None, Django utilise le fuseau horaire actuel. Il n’a aucun effet lorsque USE_TZ vaut False.
is_dst indique si pytz doit interpréter les heures non existantes et ambiguës dans les transitions de changements d’heures saisonniers. Par défaut (lorsque is_dst=None), pytz génère une exception pour de telles heures.
none()Lien vers cette rubrique#L’appel à none() crée un jeu de requête qui ne renvoie jamais aucun objet et qui ne génère pas de requête lorsqu’on accède à ses résultats. Un jeu de requête qs.none() est une instance de EmptyQuerySet.
Exemples :
\n>>> Entry.objects.none()\n<QuerySet []>\n>>> from django.db.models.query import EmptyQuerySet\n>>> isinstance(Entry.objects.none(), EmptyQuerySet)\nTrue\nall()Lien vers cette rubrique#Renvoie une copie du QuerySet actuel (ou d’une sous-classe QuerySet). Cela peut être utile dans les situations où il peut être possible de recevoir soit un gestionnaire de modèle, soit un QuerySet, et que les résultats doivent passer encore par d’autres filtres. Après avoir appelé all() sur l’un des types d’objet, vous obtenez dans tous les cas un QuerySet en retour.
Lorsqu’un résultat QuerySet est évalué, il met normalement ses résultats en cache. Si les données dans la base de données peuvent avoir été modifiées depuis l’évaluation d’un QuerySet, vous pouvez obtenir des résultats mis à jour de la même requête en appelant all() sur un QuerySet déjà évalué.
union()Lien vers cette rubrique#Utilise l’opérateur SQL UNION pour combiner les résultats de deux QuerySet ou plus. Par exemple :
>>> qs1.union(qs2, qs3)\nL’opérateur UNION ne sélectionne que les valeurs distinctes par défaut. Pour autoriser des valeurs dupliquées, utilisez le paramètre all=True.
union(), intersection() et difference() renvoient des instances de modèles du type du premier jeu de requête, même si les paramètres sont des jeux de requête d’autres modèles. Il est possible de transmettre des modèles différents pour autant que la liste de SELECT soit la même pour tous les jeux de requête (au moins les types, les noms n’étant pas un problème si les types correspondent dans le même ordre). Dans de telles situations, vous devez utiliser les noms de colonnes du premier jeu de requête dans les méthodes QuerySet appliquées au résultat obtenu. Par exemple
>>> qs1 = Author.objects.values_list('name')\n>>> qs2 = Entry.objects.values_list('headline')\n>>> qs1.union(qs2).order_by('name')\nDe plus, seules les opérations LIMIT, OFFSET, COUNT(*), ORDER BY et les indications de colonnes (c’est-à-dire la segmentation, le compte count(), exists(), le tri order_by() et values()/values_list()) sont autorisés sur le jeu de requête résultant. D’autre part, les bases de données définissent des restrictions quant aux opérations autorisées dans les requêtes combinées. Par exemple, la plupart des bases de données ne permettent pas les instructions LIMIT ou OFFSET dans les requêtes combinées.
intersection()Lien vers cette rubrique#Utilise l’opérateur SQL INTERSECT pour renvoyer les éléments communs à deux ou plusieurs QuerySet. Par exemple :
>>> qs1.intersection(qs2, qs3)\nVoir union() concernant quelques restrictions.
difference()Lien vers cette rubrique#Utilise l’opérateur SQL EXCEPT pour ne conserver que les éléments présents dans un QuerySet mais pas dans d’autres QuerySet. Par exemple :
>>> qs1.difference(qs2, qs3)\nVoir union() concernant quelques restrictions.
extra()Lien vers cette rubrique#Il peut arriver parfois que la syntaxe de requête de Django ne puisse pas exprimer facilement une clause WHERE complexe. Pour ces cas extrêmes, Django fournit le modificateur de QuerySet extra(), un point d’entrée pour injecter des clauses spécifiques dans le code SQL généré par un QuerySet.
Par définition, ces expressions extra 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.
Indiquez un ou plusieurs des paramètres params, select, where ou tables. Aucun n’est obligatoire, mais vous devez en indiquer au moins un.
select
Le paramètre select vous permet d’indiquer des champs supplémentaires dans la clause SELECT. Ce doit être un dictionnaire faisant correspondre des noms d’attributs à des clauses SQL utilisées pour calculer l’attribut concerné.
Exemple :
\nEntry.objects.extra(select={'is_recent': "pub_date > '2006-01-01'"})\nAvec ceci, chaque objet Entry possède un attribut supplémentaire, is_recent, une valeur booléenne indiquant si le champ pub_date de l’objet est plus grand que le 1er janvier 2006.
Django insère l’extrait SQL donné directement dans l’instruction SELECT. Le code SQL résultant de l’exemple ci-dessus ressemblerait donc à ceci :
SELECT blog_entry.*, (pub_date > '2006-01-01') AS is_recent\nFROM blog_entry;\nL’exemple suivant est plus pointu ; il effectue une sous-requête pour donner à chaque objet Blog du résultat un attribut entry_count, un nombre entier comptant les objets Entry associés :
Blog.objects.extra(\n select={\n 'entry_count': 'SELECT COUNT(*) FROM blog_entry WHERE blog_entry.blog_id = blog_blog.id'\n },\n)\nDans ce cas particulier, nous exploitons le fait que la requête contiendra déjà la table blog_blog dans sa clause FROM.
Le code SQL résultant de l’exemple ci-dessus donnerait :
\nSELECT blog_blog.*, (SELECT COUNT(*) FROM blog_entry WHERE blog_entry.blog_id = blog_blog.id) AS entry_count\nFROM blog_blog;\nNotez que les parenthèses exigées par la plupart des moteurs de base de données autour des sous-requêtes ne sont pas obligatoires dans les clauses select de Django. Signalons aussi que certains moteurs de base de données tels que certaines versions de MySQL ne prennent pas en charge les sous-requêtes.
Dans certains cas exceptionnels, il peut être souhaitable de transmettre des paramètres aux fragments SQL dans extra(select=...). Pour faire cela, utilisez le paramètre select_params.
Ceci fonctionnera, par exemple :
\nBlog.objects.extra(\n select={'a': '%s', 'b': '%s'},\n select_params=('one', 'two'),\n)\nSi vous avez besoin d’utiliser un %s littéral à l’intérieur de la chaîne de sélection, utilisez la séquence %%s.
where / tables
Il est possible de définir des clauses SQL WHERE explicites — peut-être pour effectuer des jointures non explicites — en utilisant where. Des tables peuvent être manuellement ajoutées à la clause SQL FROM par le paramètre tables.
where et tables acceptent tous deux une liste de chaînes de caractères. Tous les paramètres where sont combinés avec les autres critères de recherche par l’opérateur « ET ».
Exemple :
\nEntry.objects.extra(where=["foo='a' OR bar = 'a'", "baz = 'a'"])\n…peut être (grossièrement) traduit en code SQL comme :
\nSELECT * FROM blog_entry WHERE (foo='a' OR bar='a') AND (baz='a')\nSoyez prudent en utilisant le paramètre tables si celui-ci contient des tables déjà utilisées dans le requête. Lorsque vous ajoutez des tables supplémentaires par le paramètre tables, Django suppose que vous voulez que cette table soit ajoutée une fois de plus, si elle s’y trouve déjà. Cela pose un problème, car le nom de table recevra alors un alias. Si une table apparaît plusieurs fois dans une instruction SQL, son nom est remplacé par un alias à partir de la deuxième occurrence, afin que la base de données puisse les différencier. Si alors dans le paramètre where supplémentaire, vous vous référez à la table que vous avez explicitement ajoutée, vous obtiendrez des erreurs.
En temps normal, seules les tables qui ne font pas encore partie de la requête devraient être ajoutées. Cependant, si le cas ci-dessus se présente, il existe des solutions. Regardez premièrement si vous pouvez éviter d’inclure la table supplémentaire et utiliser celle qui se trouve déjà dans la requête. Si ce n’est pas possible, placez l’appel extra() au début de la construction du jeu de requête afin que la table concernée soit la première occurrence. Finalement, si aucune autre solution ne fonctionne, examinez la requête générée et réécrivez le contenu where afin d’utiliser l’alias attribué à la table supplémentaire. L’alias sera toujours le même tant que vous construisez le jeu de requête de la même manière, il est donc possible de se fier à la stabilité du nom d’alias.
order_by
Si vous avez besoin de trier les résultats de requête à l’aide de nouveaux champs ou tables que vous avez inclus par extra(), utilisez le paramètre order_by de extra() et complétez-le par une liste de chaînes. Celles-ci doivent correspondre soit à des champs de modèles (comme pour la méthode order_by() habituelle des jeux de requête) sous la forme nom_table.nom_colonne, soit à un alias d’une colonne définie dans le paramètre select de extra().
Par exemple :
\nq = Entry.objects.extra(select={'is_recent': "pub_date > '2006-01-01'"})\nq = q.extra(order_by = ['-is_recent'])\nCe code place en premier dans les résultats tous les éléments pour lesquels is_recent vaut True (dans un tri descendant, True apparaît avant False).
Par ailleurs, cela montre aussi que vous pouvez appelez extra() plusieurs fois en obtenant le comportement attendu (ajout successif de nouvelles contraintes).
params
Le paramètre where décrit ci-dessus peut utiliser des chaînes de substitution de base de données comme en Python standard, '%s', pour indiquer au moteur de base de données des paramètres qu’il faut automatiquement placer entre guillemets. Le paramètre params est une liste de paramètres supplémentaires à utiliser dans la substitution.
Exemple :
\nEntry.objects.extra(where=['headline=%s'], params=['Lennon'])\nUtilisez toujours params au lieu d’insérer des valeurs directement dans la clause where, parce que params garantit que les valeurs seront mises correctement entre guillemets en fonction de la base de données utilisée. Par exemple, les guillemets dans les chaînes seront échappés correctement.
Faux :
\nEntry.objects.extra(where=["headline='Lennon'"])\nJuste :
\nEntry.objects.extra(where=['headline=%s'], params=['Lennon'])\ndefer()Lien vers cette rubrique#Dans certaines situations complexes de structures de données, des modèles peuvent contenir un grand nombre de champs, et certains champs contenir beaucoup de données (par exemple pour les champs texte) ; parfois, la conversion de certaines valeurs en objet Python est coûteuse en performances. Si vous utilisez les résultats d’une requête dans une situation où vous n’êtes pas certain d’avoir besoin de certains champs lors de la requête initiale pour obtenir les données, vous pouvez indiquer à Django de ne pas les récupérer de la base de données.
\nCeci se fait en indiquant les noms des champs à ne pas charger dans defer():
Entry.objects.defer("headline", "body")\nUn jeu de requête comportant des champs différés renvoie tout de même des instances de modèles. Chaque champ différé sera récupéré de la base de données si vous y faites référence (un à la fois, pas tous les champs différés d’un coup).
\nOn peut appeler plusieurs fois defer(). Chaque appel ajoute les nouveaux champs à l’ensemble des champs différés :
# Defers both the body and headline fields.\nEntry.objects.defer("body").filter(rating=5).defer("headline")\nL’ordre dans lequel les champs sont ajoutés à l’ensemble différé n’a pas d’importance. L’appel à defer() avec un nom de champ qui a déjà été indiqué comme différé ne pose pas de problème (le champ sera toujours considéré comme différé).
Vous pouvez différer le chargement de champs dans des modèles liés (si les modèles liés sont chargés par select_related()) en utilisant la notation standard de double soulignement pour séparer les champs liés :
Blog.objects.select_related().defer("entry__headline", "entry__body")\nSi vous souhaitez effacer l’ensemble des champs différés, indiquez None comme paramètre à defer():
# Load all fields immediately.\nmy_queryset.defer(None)\nCertains champs d’un modèle ne seront pas différés, même si vous demandez de le faire. Le chargement de la clé primaire ne peut jamais être différé. Si vous utilisez select_related() pour récupérer des modèles liés, vous ne devriez pas différer le chargement du champ qui fait la liaison entre le modèle principal et le modèle lié, sous peine d’obtenir une erreur.
only()Lien vers cette rubrique#La méthode only() est plus ou moins le contraire de defer(). Il s’agit de l’appeler en indiquant les champs qui ne doivent pas être différés lors du chargement d’un modèle (tous les autres le seront). Si vous avez un modèle dont presque tous les champs doivent être différés, le code peut parfois être simplifié en indiquant l’ensemble complémentaire des champs.
Supposons qu’un modèle possède les champs name, age et biography. Les deux requêtes suivantes sont identiques en terme de champs différés :
Person.objects.defer("age", "biography")\nPerson.objects.only("name")\nÀ chaque appel de only(), l’ensemble des champs à charger immédiatement est remplacé. Le nom de la méthode est mnémonique : seuls (only en anglais) ces champs sont chargés immédiatement ; les autres sont différés. Ainsi, quand only() est appelé plusieurs fois successivement, seuls les champs du dernier appel sont pris en compte :
# This will defer all fields except the headline.\nEntry.objects.only("body", "rating").only("headline")\nComme defer() se comporte de manière incrémentale (ajoutant les champs à la liste différée), vous pouvez combiner les appels à only() et defer() et tout devrait se passer comme prévu :
# Final result is that everything except "headline" is deferred.\nEntry.objects.only("headline", "body").defer("body")\n\n# Final result loads headline and body immediately (only() replaces any\n# existing set of fields).\nEntry.objects.defer("body").only("headline", "body")\nTous les avertissements de la note de la documentation de defer() s’appliquent également à only(). Utilisez-la prudemment et seulement après avoir épuisé les autres options possibles.
L’utilisation d”only() en omettant un champ demandé par select_related() constitue aussi une erreur.
using()Lien vers cette rubrique#Cette méthode sert à contrôler la base de données qui sera la cible d’évaluation du QuerySet dans le cas où plusieurs bases de données sont définies. Le seul paramètre admis par cette méthode est l’alias d’une base de données, tel que défini dans DATABASES.
Par exemple :
\n# queries the database with the 'default' alias.\n>>> Entry.objects.all()\n\n# queries the database with the 'backup' alias\n>>> Entry.objects.using('backup')\nselect_for_update()Lien vers cette rubrique#Renvoie un jeu de requête qui verrouille les lignes jusqu’à la fin de la transaction, générant une instruction SQL SELECT ... FOR UPDATE pour les bases de données qui la prennent en charge.
Par exemple :
\nfrom django.db import transaction\n\nentries = Entry.objects.select_for_update().filter(author=request.user)\nwith transaction.atomic():\n for entry in entries:\n ...\nLorsque le jeu de requête est évalué (for entry in entries dans ce cas), toutes les lignes de base de données correspondantes sont verrouillées jusqu’à la fin du bloc transactionnel, ce qui veut dire que d’autres transactions ne pourront ni modifier ni verrouiller elles-mêmes ces lignes.
Normalement, si une autre transaction a déjà verrouillé l’une des lignes sélectionnées, la requête est bloquée en attendant que le verrou soit levé. Si ce n’est pas ce que vous voulez, appelez select_for_update(nowait=True). L’appel est alors non bloquant. Si un verrou est déjà posé par une autre transaction sur un des éléments à sélectionner, une exception DatabaseError est générée lors de l’évaluation du jeu de requête. Il est aussi possible d’ignorer les lignes verrouillées en utilisant plutôt select_for_update(skip_locked=True). Les paramètres nowait et skip_locked sont mutuellement exclusifs ; s’ils sont les deux activés lors de l’appel à select_for_update(), une erreur ValueError sera produite.
Par défaut, select_for_update() verrouille toutes les lignes qui sont sélectionnées par la requête. Par exemple, les lignes des objets liés mentionnés dans select_related() sont verrouillés en plus des lignes du modèle du jeu de requête. Si ce n’est pas souhaité, indiquez les objets liés que vous voulez verrouiller dans select_for_update(of=(...)) en utilisant la même syntaxe de noms de champs que pour select_related(). Utilisez la valeur 'self' pour vous référer au modèle du jeu de requête.
Avec PostgreSQL uniquement, vous pouvez passer no_key=True afin d’acquérir un verrou plus faible, qui permet quand même la création de lignes qui ne font que référencer les lignes verrouillées (au travers d’une clé étrangère, par exemple). La documentation PostgreSQL contient plus de détails au sujet des modes de verrouillage au niveau ligne.
Il n’est pas possible d’utiliser select_for_update() sur des relations pouvant être nulles
>>> Person.objects.select_related('hometown').select_for_update()\nTraceback (most recent call last):\n...\ndjango.db.utils.NotSupportedError: FOR UPDATE cannot be applied to the nullable side of an outer join\nPour éviter cette restriction, vous pouvez exclure les objets nuls si vous n’en avez pas besoin
\n>>> Person.objects.select_related('hometown').select_for_update().exclude(hometown=None)\n<QuerySet [<Person: ...)>, ...]>\nEn ce moment, les moteurs de base de données postgresql, oracle et mysql prennent en charge select_for_update(). Cependant, MariaDB 10.3+ ne gère que le paramètre nowait et MySQL 8.0.1+ gère les paramètres nowait, skip_locked et of. Le paramètre no_key n’est pris en charge que par PostgreSQL.
Si vous passez nowait=True, skip_locked=True, no_key=True ou of à select_for_update() et que le moteur de base de données ne prend pas en charge ces options, comme pour MySQL, une exception NotSupportedError est générée. Ceci évite que du code soit bloqué de manière inattendue.
L’évaluation d’un jeu de requête avec select_for_update() en mode autocommit avec les bases de données qui prennent en charge SELECT ... FOR UPDATE est une erreur TransactionManagementError, car dans ce cas-là, les lignes ne sont pas verrouillées. Si c’était permis, ce serait un vecteur de corruption de données qui pourrait facilement être provoqué par l’appel de code conçu pour être exécuté dans une transaction en dehors d’une transaction.
L’emploi de select_for_update() avec des moteurs qui ne prennent pas en charge SELECT ... FOR UPDATE (comme pour SQLite) n’aura aucun effet. SELECT ... FOR UPDATE ne sera pas ajouté à la requête et aucune erreur ne sera produite si select_for_update() est utilisé en mode autocommit.
raw()Lien vers cette rubrique#Accepte une requête SQL brute, l’exécute et renvoie une instance django.db.models.query.RawQuerySet. Il est possible alors d’effectuer une boucle sur cette instance RawQuerySet tout comme pour un objet QuerySet normal afin d’accéder aux instances d’objets.
Voir Lancement de requêtes SQL brutes pour plus d’informations.
\n\n\nQuerySetLien vers cette rubrique#Les jeux de requête combinés doivent utiliser le même modèle.
\n&)Lien vers cette rubrique#Combine deux requêtes QuerySet en utilisant l’opérateur SQL AND (ET).
Les requêtes suivantes sont équivalentes
\nModel.objects.filter(x=1) & Model.objects.filter(y=2)\nModel.objects.filter(x=1, y=2)\nfrom django.db.models import Q\nModel.objects.filter(Q(x=1) & Q(y=2))\nÉquivalent SQL :
\nSELECT ... WHERE x=1 AND y=2\n|)Lien vers cette rubrique#Combine deux requêtes QuerySet en utilisant l’opérateur SQL OR (OU).
Les requêtes suivantes sont équivalentes
\nModel.objects.filter(x=1) | Model.objects.filter(y=2)\nfrom django.db.models import Q\nModel.objects.filter(Q(x=1) | Q(y=2))\nÉquivalent SQL :
\nSELECT ... WHERE x=1 OR y=2\nQuerySetLien vers cette rubrique#Les méthodes de QuerySet suivantes évaluent le QuerySet et renvoie quelque chose d’autre qu’un QuerySet.
Ces méthodes n’utilisent pas de cache (voir Mise en cache et objets QuerySet). Elles accèdent à la base de données lors de chaque appel.
\nget()Lien vers cette rubrique#Renvoie l’objet correspondant aux paramètres de recherche indiqués, qui doivent être dans le format décrit dans Recherches dans les champs. Vous devriez utiliser des critères qui sont garantis comme uniques, tels que des clés primaires ou des champs disposant d’une contrainte d’unicité. Par exemple
\nEntry.objects.get(id=1)\nEntry.objects.get(Q(blog=blog) & Q(entry_number=1))\nSi vous pensez qu’une requête ne contient déjà qu’une seule ligne, vous pouvez utiliser get() sans paramètre pour obtenir l’objet correspondant à cette ligne :
Entry.objects.filter(pk=1).get()\nSi get() ne trouve aucun objet, il génère l’exception Model.DoesNotExist:
Entry.objects.get(id=-999) # raises Entry.DoesNotExist\nSi get() trouve plus qu’un objet, il génère une exception Model.MultipleObjectsReturned:
Entry.objects.get(name='A Duplicated Name') # raises Entry.MultipleObjectsReturned\nCes deux classes d’exceptions sont des attributs de la classe de modèle et sont spécifiques à ces modèles. Si vous souhaitez intercepter de telles exceptions provenant de plusieurs appels get() pour différents modèles, vous pouvez utiliser leur classe de base générique. Par exemple, vous pouvez utiliser django.core.exceptions.ObjectDoesNotExist pour intercepter les exceptions DoesNotExist de modèles différents
from django.core.exceptions import ObjectDoesNotExist\n\ntry:\n blog = Blog.objects.get(id=1)\n entry = Entry.objects.get(blog=blog, entry_number=1)\nexcept ObjectDoesNotExist:\n print("Either the blog or entry doesn't exist.")\ncreate()Lien vers cette rubrique#Une méthode d’agrément pour la création d’un objet et son enregistrement en une seule méthode. Ainsi :
\np = Person.objects.create(first_name="Bruce", last_name="Springsteen")\net :
\np = Person(first_name="Bruce", last_name="Springsteen")\np.save(force_insert=True)\nsont équivalents.
\nLe paramètre force_insert est documenté ailleurs, mais il indique qu’un nouvel objet sera toujours créé. Vous n’avez normalement pas à vous préoccuper de ce paramètre. Cependant, si le modèle contient une valeur de clé primaire que vous avez définie manuellement et que cette valeur existe déjà en base de données, l’appel à create() échoue avec l’erreur IntegrityError car les clés primaires doivent rester uniques. Soyez prêt à traiter l’exception si vous définissez manuellement des clés primaires.
get_or_create()Lien vers cette rubrique#Une méthode utile pour rechercher un objet correspondant aux paramètres kwargs indiqués (qui peuvent être vides si le modèle contient des valeurs par défaut pour tous les champs), et qui crée un objet si nécessaire.
Renvoie un tuple (objet, créé) où objet est l’objet chargé ou créé et créé est une valeur booléenne indiquant si un nouvel objet a été créé.
L’idée est d’éviter la création d’objets dupliqués lorsque des requêtes sont exécutées en parallèle ; ceci est une sorte de raccourci pour éviter des lignes de code redondantes. Par exemple :
\ntry:\n obj = Person.objects.get(first_name='John', last_name='Lennon')\nexcept Person.DoesNotExist:\n obj = Person(first_name='John', last_name='Lennon', birthday=date(1940, 10, 9))\n obj.save()\nIci, il est possible que plusieurs requêtes parallèles tentent d’enregistrer une Person avec les même paramètres. Pour éviter cette situation de concurrence, l’exemple ci-dessus peut être réécrit en utilisant get_or_create(), comme ceci :
obj, created = Person.objects.get_or_create(\n first_name='John',\n last_name='Lennon',\n defaults={'birthday': date(1940, 10, 9)},\n)\nTout paramètre nommé transmis à get_or_create() — excepté le paramètre facultatif appelé defaults — seront utilisés dans un appel à get(). Si un objet est trouvé, get_or_create() renvoie un tuple composé de cet objet ainsi que de False.
Vous pouvez indiquer des conditions plus complexes pour l’objet à trouver en chaînant get_or_create() avec filter() et en utilisant des objets Q. Par exemple, pour récupérer Robert ou Bob Marley si l’un des deux existe et pour créer le dernier dans le cas contraire
from django.db.models import Q\n\nobj, created = Person.objects.filter(\n Q(first_name='Bob') | Q(first_name='Robert'),\n).get_or_create(last_name='Marley', defaults={'first_name': 'Bob'})\nSi plusieurs objets ont été trouvés, get_or_create() génère MultipleObjectsReturned. SI un objet n’a pas été trouvé, get_or_create() crée une instance d’objet et l’enregistre, renvoyant un tuple composé de ce nouvel objet et de True. Le nouvel objet sera créé en suivant grossièrement cet algorithme
params = {k: v for k, v in kwargs.items() if '__' not in k}\nparams.update({k: v() if callable(v) else v for k, v in defaults.items()})\nobj = self.model(**params)\nobj.save()\nEn français, cela veut dire qu’on commence par tout paramètre nommé autre que 'defaults' et qui ne contient pas de double soulignement (ce qui indiquerait une recherche non exacte). Puis on ajoute le contenu de 'defaults', surchargeant d’éventuels paramètres existants, et on utilise le résultat comme paramètres nommés de la classe de modèle. Si defaults contient des éléments exécutables, ils sont évalués. Comme déjà dit, il s’agit d’une simplification de l’algorithme réel, mais tous les éléments importants sont là. L’implémentation réelle contient quelques contrôles d’erreur supplémentaires et traite quelques conditions extrêmes ; si cela vous intéresse, lisez le code.
Si vous avez un champ nommé defaults et que vous voulez l’utiliser comme recherche exacte dans get_or_create(), indiquez 'defaults__exact', comme ceci :
Foo.objects.get_or_create(defaults__exact='bar', defaults={'defaults': 'baz'})\nLe comportement d’erreur de la méthode get_or_create() est semblable à celui de create() lorsque vous définissez des clés primaires manuellement. Si un objet doit être créé et que la clé primaire existe déjà en base de données, une exception IntegrityError est générée.
Pour terminer, un mot sur l’utilisation de get_or_create() dans les vues Django. Faites attention de ne l’utiliser que dans des requêtes POST, sauf si vous avez des bonnes raisons de faire autrement. Les requêtes GET ne sont pas censées modifier des données. Il faudrait toujours utiliser POST lorsqu’une requête sur une page provoque des effets de bord sur les données. Pour plus de détails, lisez Safe methods dans la spécification HTTP.
update_or_create()Lien vers cette rubrique#Une méthode utilitaire pour mettre à jour un objet avec les paramètres kwargs donnés, en créant un nouvel objet si nécessaire. Le paramètre defaults est un dictionnaire de paires (champ, valeur) utilisé pour mettre à jour l’objet. Les valeurs dans defaults peuvent être exécutables.
Renvoie un tuple (objet, créé) où objet est l’objet créé ou mis à jourcréé et créé est une valeur booléenne indiquant si un nouvel objet a été créé.
La méthode update_or_create essaie de récupérer un objet de la base de données en fonction des paramètres kwargs indiqués. Si une correspondance est trouvée, elle met à jour les champs transmis dans le dictionnaire defaults.
L’intention est de fournir un raccourci à la place de code répétitif. Par exemple :
\ndefaults = {'first_name': 'Bob'}\ntry:\n obj = Person.objects.get(first_name='John', last_name='Lennon')\n for key, value in defaults.items():\n setattr(obj, key, value)\n obj.save()\nexcept Person.DoesNotExist:\n new_values = {'first_name': 'John', 'last_name': 'Lennon'}\n new_values.update(defaults)\n obj = Person(**new_values)\n obj.save()\nCe schéma devient tendancieux au fur et à mesure que le nombre de champs d’un modèle augmente. L’exemple ci-dessus peut être réécrit en utilisant update_or_create() comme ceci :
obj, created = Person.objects.update_or_create(\n first_name='John', last_name='Lennon',\n defaults={'first_name': 'Bob'},\n)\nPour une description détaillée sur la manière dont les noms transmis dans kwargs sont résolus, voir get_or_create().
Comme expliqué plus haut pour get_or_create(), cette méthode est sujette à un conflit de concurrence qui peut aboutir à l’insertion simultanée de plusieurs lignes si l’unicité n’est pas garantie au niveau de la base de données.
Comme get_or_create() et create(), si vous définissez des clés primaires manuellement et qu’un objet doit être créé mais que la clé primaire existe déjà en base de données, une exception IntegrityError est générée.
bulk_create()Lien vers cette rubrique#Cette méthode insère la liste d’objets indiquée dans la base de données de manière efficace (généralement par une seule requête, quel que soit le nombre d’objets concernés) et renvoie les objets créés dans une liste, dans le même ordre que dans l’argument :
\n>>> objs = Entry.objects.bulk_create([\n... Entry(headline='This is a test'),\n... Entry(headline='This is only a test'),\n... ])\nCette méthode présente toutefois quelques inconvénients :
\nLa méthode save() de chaque modèle n’est pas appelée et les signaux pre_save et post_save ne sont pas envoyés.
Elle ne fonctionne pas avec des modèles enfants dans un contexte d’héritage multitable.
Si la clé primaire du modèle est un champ AutoField, l’attribut clé primaire ne peut être obtenu qu’avec certaines bases de données (actuellement PostgreSQL et MariaDB 10.5+). Avec les autres bases de données, il ne sera pas défini.
Elle ne fonctionne pas avec les relations plusieurs-à-plusieurs.
Elle force objs à être une liste, ce qui évalue entièrement objs s’il s’agit d’un générateur. Ce forçage permet d’inspecter tous les objets afin que tout objet ayant une clé primaire définie manuellement soit inséré en premier. Si vous souhaitez insérer des objets en lots sans évaluer d’abord le générateur entier, vous pouvez utiliser cette technique tant que les objets n’ont aucune clé primaire définie manuellement
from itertools import islice\n\nbatch_size = 100\nobjs = (Entry(headline='Test %s' % i) for i in range(1000))\nwhile True:\n batch = list(islice(objs, batch_size))\n if not batch:\n break\n Entry.objects.bulk_create(batch, batch_size)\nLe paramètre batch_size permet de contrôler le nombre d’objets créés dans une seule requête. Par défaut, tous les objets sont créés en une seule instruction, à l’exception de SQLite où par défaut, le nombre maximum de 999 variables par requête est appliqué.
Pour les bases de données qui le gèrent (toutes à l’exception d’Oracle), la définition du paramètre ignore_conflicts à True indique à la base de données d’ignorer les échecs d’insertion de lignes qui ne respectent pas les contraintes telles que les valeurs uniques dupliquées. L’activation de ce paramètre désactive la possibilité de définir la clé primaire sur chaque instance de modèle (dans le cas où la base de données le gère normalement).
bulk_update()Lien vers cette rubrique#Cette méthode met à jour efficacement les champs donnés sur les instances de modèles fournies, en général avec une seule requête
\n>>> objs = [\n... Entry.objects.create(headline='Entry 1'),\n... Entry.objects.create(headline='Entry 2'),\n... ]\n>>> objs[0].headline = 'This is entry 1'\n>>> objs[1].headline = 'This is entry 2'\n>>> Entry.objects.bulk_update(objs, ['headline'])\nQuerySet.update() est utilisé pour enregistrer les modifications, c’est donc plus efficace que de boucler sur la liste des modèles et d’appeler save() sur chacun d’entre eux, mais cela comporte quelques inconvénients :
Il n’est pas possible de mettre à jour la clé primaire des modèles.
La méthode save() des modèles n’est pas appelée et les signaux pre_save et post_save ne sont pas envoyés.
SI la mise à jour concerne un grand nombre de colonnes pour un grand nombre de lignes, le code SQL produit peut devenir très volumineux. Évitez cela en indiquant une valeur batch_size appropriée.
La mise à jour de champs définis sur des instances parentes dans un contexte d’héritage multitable va générer une requête supplémentaire par parent.
Lorsqu’un lot individuel contient des doublons, seule la première instance du lot produira une mise à jour.
Le paramètre batch_size permet de contrôler le nombre d’objets enregistrés dans une seule requête. Par défaut, tous les objets sont enregistrés en une seule instruction, à l’exception de SQLite et Oracle qui ont des restrictions sur le nombre de variables utilisables dans une requête.
count()Lien vers cette rubrique#Renvoie un nombre entier représentant le nombre d’objets de base de données correspondant au QuerySet.
Exemple :
\n# Returns the total number of entries in the database.\nEntry.objects.count()\n\n# Returns the number of entries whose headline contains 'Lennon'\nEntry.objects.filter(headline__contains='Lennon').count()\nUn appel à count() génère une instruction SELECT COUNT(*) en arrière-plan, il est donc conseiller de toujours utiliser count() plutôt que de charger tous les résultats en objets Python et d’appeler len() sur cette liste d’objets (sauf dans le cas où vous avez de toute façon besoin de charger les objets en mémoire, auquel cas len() sera plus rapide).
Notez que si vous souhaitez obtenir le nombre d’élément d’un QuerySet et que vous allez aussi exploiter ses instances de modèles (par exemple dans une itération), il est probablement plus efficace d’utiliser len(queryset) qui ne produira pas de requête de base de données supplémentaire comme le ferait count().
Si le jeu de requête a déjà été pleinement récupéré, count() calculera la longueur sur ce résultat et n’effectuera pas de requête supplémentaire en base de données.
in_bulk()Lien vers cette rubrique#Accepte une liste de valeurs de champs (id_list) ainsi que le nom field_name correspondant à ces valeurs et renvoie un dictionnaire faisant correspondre chaque valeur à une instance d’objet ayant la valeur de champ donnée. Aucune exception django.core.exceptions.ObjectDoesNotExist n’est produite par in_bulk, c’est-à-dire que les valeurs de id_list qui ne correspondent à aucune instance seront simplement ignorées. Si id_list n’est pas fourni, tous les objets du jeu de requête sont renvoyés. field_name doit être un champ unique ou un champ distinct (si la méthode distinct() ne contient qu’un seul champ). field_name représente la clé primaire par défaut.
Exemple :
\n>>> Blog.objects.in_bulk([1])\n{1: <Blog: Beatles Blog>}\n>>> Blog.objects.in_bulk([1, 2])\n{1: <Blog: Beatles Blog>, 2: <Blog: Cheddar Talk>}\n>>> Blog.objects.in_bulk([])\n{}\n>>> Blog.objects.in_bulk()\n{1: <Blog: Beatles Blog>, 2: <Blog: Cheddar Talk>, 3: <Blog: Django Weblog>}\n>>> Blog.objects.in_bulk(['beatles_blog'], field_name='slug')\n{'beatles_blog': <Blog: Beatles Blog>}\n>>> Blog.objects.distinct('name').in_bulk(field_name='name')\n{'Beatles Blog': <Blog: Beatles Blog>, 'Cheddar Talk': <Blog: Cheddar Talk>, 'Django Weblog': <Blog: Django Weblog>}\nEn passant une liste vide à in_bulk(), le résultat est un dictionnaire vide.
iterator()Lien vers cette rubrique#Évalue le QuerySet (en exécutant la requête) et renvoie un itérateur (voir PEP 234) sur les résultats. Un QuerySet met typiquement en cache interne ses résultats afin que d’éventuelles autres évaluations ne produisent pas de requête supplémentaire. Au contraire, iterator() lit directement les résultats, sans rien mettre dans le cache du QuerySet (en interne, l’itérateur par défaut appelle iterator() et met en cache la valeur renvoyée). Pour un QuerySet renvoyant un grand nombre d’objets que vous ne devez accéder qu’une seule fois, cela peut amener à de meilleures performances et à une utilisation bien moindre de la mémoire.
Notez que l’utilisation de iterator() sur un QuerySet ayant déjà été évalué force une nouvelle évaluation en répétant la requête.
De plus, l’utilisation de``iterator()`` ignore d’éventuels appels précédents à prefetch_related(), car il n’est pas logique de combiner ces deux optimisations.
En fonction du moteur de base de données, les résultats de requête seront soit chargés entièrement en mémoire, soit livrés en flux depuis la base de données en utilisant des curseurs côté serveur.
\nOracle et PostgreSQL utilisent des curseurs côté serveur pour livrer en flux les résultats de la base de données sans charger l’entier du jeu de résultats en mémoire.
\nLe pilote de base de données Oracle utilise toujours des curseurs côté serveur.
\nAvec les curseurs côté serveur, le paramètre chunk_size indique le nombre de résultats à mettre en cache au niveau du pilote de base de données. L’obtention de blocs plus gros diminue le nombre d’aller-retours entre le pilote de base de données et la base de données, au détriment de la mémoire.
Avec PostgreSQL, les curseurs côté serveur ne sont utilisés que si le réglage DISABLE_SERVER_SIDE_CURSORS vaut False. Lisez Transactions groupées et curseurs côté serveur si vous utilisez un concentrateur de connexions configuré en mode concentration de transaction. Lorsque les curseurs côté serveur sont désactivés, le comportement est le même que pour les bases de données qui ne prennent pas en charge ces curseurs.
MySQL ne prend pas en charge la diffusion de résultats, ce qui signifie que le pilote Python de cette base de données charge l’entier du jeu de résultats en mémoire. Ce jeu de résultats est ensuite transformé en objets lignes Python par l’adaptateur de base de données à l’aide de la méthode fetchmany() définie dans la PEP 249.
SQLite peut récupérer des résultats par lots avec fetchmany(), mais comme SQLite ne fournit pas d’isolation entre les requêtes à l’intérieur d’une connexion, soyez prudent lorsque vous écrivez dans la table qui est actuellement parcourue. Voir Isolation lors de l’utilisation de QuerySet.iterator() pour plus d’informations.
Le paramètre chunk_size contrôle la taille des lots que Django récupère du pilote de base de données. Des lots plus gros diminuent la surcharge de communication avec le pilote de base de données au détriment d’une légère augmentation de la consommation mémoire.
La valeur par défaut de chunk_size, 2000, provient d’un calcul sur la liste de diffusion psycopg:
\n\nEn imaginant des lignes de 10-20 colonnes avec un mélange de données textuelles et numériques, 2000 va récupérer moins de 100 Ko de données, ce qui paraît un bon compromis entre le nombre de lignes transférées et les données à laisser tomber dans le cas d’une sortie prématurée de la boucle.
\n
latest()Lien vers cette rubrique#Renvoie le dernier objet de la table, en fonction du ou des champs indiqués.
\nCet exemple renvoie le dernier objet Entry de la table, selon le champ pub_date:
Entry.objects.latest('pub_date')\nIl est aussi possible de choisir le dernier en fonction de plusieurs champs. Par exemple, pour choisir un Entry avec la date d’expiration la plus ancienne lorsque deux entrées ont la même date pub_date:
Entry.objects.latest('pub_date', '-expire_date')\nLe signe moins dans '-expire_date' indique que l’on veut trier expire_date dans l’ordre décroissant. Comme latest() obtient le dernier résultat, c’est l”Entry avec la date expire_date la plus ancienne qui est choisie.
Si la classe Meta d’un modèle définit get_latest_by, il est possible d’omettre tout paramètre dans earliest() et latest(). Les champs définis dans get_latest_by seront utilisés par défaut.
Comme get(), earliest() et latest() génèrent DoesNotExist si aucun objet ne correspond aux paramètres donnés.
Notez que earliest() et latest() n’existent que par commodité et pour une meilleure lisibilité.
earliest()Lien vers cette rubrique#Fonctionne comme latest(), mais dans le sens inverse.
first()Lien vers cette rubrique#Renvoie le premier objet du jeu de requête, ou None si la requête est vide. Si l’objet QuerySet n’est pas trié, la requête est automatiquement triée selon la clé primaire. Cela peut affecter les résultats d’agrégats comme expliqué dans Interaction avec order_by().
Exemple :
\np = Article.objects.order_by('title', 'pub_date').first()\nNotez que first() est une méthode d’agrément ; l’extrait de code suivant est équivalent à l’exemple ci-dessus :
try:\n p = Article.objects.order_by('title', 'pub_date')[0]\nexcept IndexError:\n p = None\nlast()Lien vers cette rubrique#Fonctionne comme first(), mais renvoie le dernier objet du jeu de requête.
aggregate()Lien vers cette rubrique#Renvoie un dictionnaire de valeurs agrégées (moyennes, sommes, etc.) calculées dans le QuerySet. Chaque paramètre d”aggregate() définit une valeur qui sera incluse dans le dictionnaire renvoyé.
Les fonctions d’agrégation fournies par Django sont décrites plus loin dans Fonctions d’agrégation. Comme les agrégations sont aussi des expressions de requête, il est possible de combiner des agrégations avec d’autres agrégations ou valeurs afin de créer des agrégations complexes.
\nLes agrégations spécifiées par des paramètres nommés utilisent la clé comme nom d’annotation. Les paramètres anonymes seront dotés d’un nom généré automatiquement sur la base du nom de la fonction d’agrégation et du champ de modèle sur lequel porte l’agrégation. Les agrégations complexes ne peuvent pas utiliser de paramètres anonymes et doivent indiquer un paramètre nommé jouant le rôle d’alias.
\nPar exemple, si vous avez affaire à des articles de blog, il peut être intéressant de déterminer le nombre d’auteurs ayant écrits des articles :
\n>>> from django.db.models import Count\n>>> q = Blog.objects.aggregate(Count('entry'))\n{'entry__count': 16}\nEn utilisant un paramètre nommé pour définir la fonction d’agrégation, vous pouvez contrôler le nom de la valeur d’agrégation dans le résultat :
\n>>> q = Blog.objects.aggregate(number_of_entries=Count('entry'))\n{'number_of_entries': 16}\nPour une présentation approfondie de l’agrégation, consultez le guide thématique sur l’agrégation.
\nexists()Lien vers cette rubrique#Renvoie True si le QuerySet contient au moins un résultat, sinon False. Cette méthode s’efforce de lancer la requête la plus simple et rapide possible, mais la requête exécutée est quasi identique à celle du QuerySet normal.
exists() est utile pour des recherches liées à l’appartenance d’objets dans un QuerySet et à l’existence d’au moins un objet dans un QuerySet, particulièrement dans le contexte de QuerySet volumineux.
La méthode la plus efficace pour déterminer si un modèle avec un champ unique (par ex. sa clé primaire) est présent dans un QuerySet est :
entry = Entry.objects.get(pk=123)\nif some_queryset.filter(pk=entry.pk).exists():\n print("Entry contained in queryset")\nCe qui sera plus rapide que l’exemple suivant qui demande l’évaluation et l’itération de la totalité du jeu de requête :
\nif entry in some_queryset:\n print("Entry contained in QuerySet")\nEt pour savoir si un jeu de requête contient au moins un élément :
\nif some_queryset.exists():\n print("There is at least one object in some_queryset")\nCe qui sera plus rapide que :
\nif some_queryset:\n print("There is at least one object in some_queryset")\n…mais pas de beaucoup (plus le jeu de requête est potentiellement volumineux, plus le gain sera élevé).
\nDe plus, si some_queryset n’a pas encore été évalué mais que vous savez qu’il le sera à un moment donné, l’appel à some_queryset.exists() effectue du travail en plus (une requête pour le contrôle d’existence, plus une autre plus tard au moment de charger les résultats) par rapport à bool(some_queryset), qui récupère les résultats et vérifie ensuite s’il y en a au moins un.
update()Lien vers cette rubrique#Effectue une requête de mise à jour SQL pour les champs indiqués et renvoie le nombre de lignes affectées (qui n’est pas forcément égal au nombre de lignes mises à jour dans la mesure où certaines lignes possèdent déjà la nouvelle valeur).
\nPar exemple, pour désactiver les commentaires pour tous les articles de blog publiés en 2010, vous pourriez écrire cela :
\n>>> Entry.objects.filter(pub_date__year=2010).update(comments_on=False)\n(En supposant que votre modèle Entry contienne les champs pub_date et comments_on.)
Vous pouvez mettre à jour plusieurs champs ; il n’y a pas de limite. Dans l’exemple suivant, nous mettons à jour les champs comments_on et headline:
>>> Entry.objects.filter(pub_date__year=2010).update(comments_on=False, headline='This is old')\nLa méthode update() est appliquée immédiatement et la seule restriction sur le QuerySet de mise à jour est qu’il ne peut mettre à jour que des colonnes de la table principale du modèle, pas dans des modèles liés. Par exemple, ceci n’est pas possible :
>>> Entry.objects.update(blog__name='foo') # Won't work!\nLe filtrage basé sur des champs liés est cependant toujours possible :
\n>>> Entry.objects.filter(blog__id=1).update(comments_on=True)\nVous ne pouvez pas appeler update() sur un QuerySet qui a subi une segmentation ou qui ne peut plus être filtré pour une autre raison.
La méthode update() renvoie le nombre de lignes affectées :
>>> Entry.objects.filter(id=64).update(comments_on=True)\n1\n\n>>> Entry.objects.filter(slug='nonexistent-slug').update(comments_on=True)\n0\n\n>>> Entry.objects.filter(pub_date__year=2010).update(comments_on=False)\n132\nSi vous n’avez qu’une ligne à mettre à jour et que vous n’avez rien à faire de spécial avec l’objet modèle, l’approche la plus efficace est d’appeler update(), plutôt que de charger en mémoire l’objet modèle. Par exemple, au lieu de faire cela :
e = Entry.objects.get(id=10)\ne.comments_on = False\ne.save()\n…faites ceci :
\nEntry.objects.filter(id=10).update(comments_on=False)\nL’utilisation d”update() permet aussi d’éviter une situation de concurrence où le contenu en base de données pourrait être modifié dans le court intervalle entre le chargement de l’objet et l’appel à save().
Finalement, réalisez que update() effectue la mise à jour au niveau SQL et par conséquent, n’appelle pas la méthode save() des modèles et n’émet pas non plus les signaux pre_save et post_save (qui sont une conséquence de l’appel à Model.save()). Si vous souhaitez mettre à jour un certain nombre d’objets d’un modèle possédant une méthode save() personnalisée, passez-les dans une boucle en appelant save(), comme ceci :
for e in Entry.objects.filter(pub_date__year=2010):\n e.comments_on = False\n e.save()\nL’enchaînement de order_by() avec update() n’est pris en charge que pour MariaDB et MySQL et est ignoré pour les autres bases de données. Ceci peut être utile pour mettre à jour un champ unique dans l’ordre qui est indiqué sans conflit. Par exemple
Entry.objects.order_by('-number').update(number=F('number') + 1)\ndelete()Lien vers cette rubrique#Effectue une requête de suppression SQL de toutes les lignes de QuerySet et renvoie le nombre d’objets supprimés ainsi qu’un dictionnaire avec le nombre de suppressions par type d’objet.
La suppression delete() s’applique immédiatement. Vous ne pouvez pas appeler delete() sur un QuerySet qui a subi une segmentation ou qui ne peut plus être filtré pour une autre raison.
Par exemple, pour supprimer tous les articles d’un blog particulier :
\n>>> b = Blog.objects.get(pk=1)\n\n# Delete all the entries belonging to this Blog.\n>>> Entry.objects.filter(blog=b).delete()\n(4, {'weblog.Entry': 2, 'weblog.Entry_authors': 2})\nPar défaut, les champs ForeignKey de Django émulent le comportement de la contrainte SQL ON DELETE CASCADE. En d’autres termes, tout objet possédant des clés étrangères vers les objets en cours de suppression seront également supprimés. Par exemple :
>>> blogs = Blog.objects.all()\n\n# This will delete all Blogs and all of their Entry objects.\n>>> blogs.delete()\n(5, {'weblog.Blog': 1, 'weblog.Entry': 2, 'weblog.Entry_authors': 2})\nCe comportement en cascade peut être personnalisé par le paramètre on_delete de ForeignKey.
La méthode delete() supprime en vrac et n’appelle pas la méthode delete() des modèles. Par contre, elle émet les signaux pre_delete et post_delete pour tous les objets supprimés (y compris les suppressions en cascade).
Django a besoin de charger les objets en mémoire pour envoyer les signaux et gérer les suppressions en cascade. Cependant, s’il n’y a pas d’objets en cascade ni de signaux, Django se permet de choisir une voie rapide et de supprimer les objets sans les charger en mémoire. Pour des grosses suppressions, cela peut réduire considérablement la consommation mémoire. Le nombre de requêtes exécutées peut également être plus faible.
\nLes clés étrangères dont le paramètre on_delete vaut DO_NOTHING (ne rien faire) n’empêchent pas la suppression accélérée.
Notez que les requêtes générées lors de la suppression d’objets constituent un détail d’implémentation susceptible d’être modifié.
\nas_manager()Lien vers cette rubrique#Méthode de classe qui renvoie une instance de Manager avec une copie des méthodes de QuerySet. Voir Création d’objet Manager avec des méthodes de QuerySet pour plus de détails.
explain()Lien vers cette rubrique#Renvoie une chaîne contenant le plan d’exécution de la requête QuerySet, qui présente comment la base de données va exécuter la requête, y compris les index ou jointures qui seraient utilisés. La connaissance de ces détails peut aider à améliorer les performances des requêtes lentes.
Par exemple, avec PostgreSQL
\n>>> print(Blog.objects.filter(title='My Blog').explain())\nSeq Scan on blog (cost=0.00..35.50 rows=10 width=12)\n Filter: (title = 'My Blog'::bpchar)\nLe résultat diffère significativement entre les base de données.
\nexplain() est pris en charge par tous les moteurs de base de données intégrés à l’exception d’Oracle car une implémentation pour ce dernier n’est pas évidente.
Le paramètre format modifie le format de sortie par rapport au format par défaut des bases de données, qui est habituellement sous forme de texte. PostgreSQL prend en charge les formats 'TEXT', 'JSON', 'YAML' et 'XML'. MariaDB et MySQL prennent en charge les formats 'TEXT' (aussi appelé 'TRADITIONAL') et 'JSON'. MySQL 8.0.16+ prend aussi en charge un format 'TREE' amélioré, qui est semblable au format de sortie 'TEXT' de PostgreSQL et qui est utilisé par défaut s’il est pris en charge.
Certaines bases de données acceptent des options pouvant renvoyer plus d’informations sur la requête. Passez ces options sous forme de paramètres nommés. Par exemple, avec PostgreSQL
\n>>> print(Blog.objects.filter(title='My Blog').explain(verbose=True, analyze=True))\nSeq Scan on public.blog (cost=0.00..35.50 rows=10 width=12) (actual time=0.004..0.004 rows=10 loops=1)\n Output: id, title\n Filter: (blog.title = 'My Blog'::bpchar)\nPlanning time: 0.064 ms\nExecution time: 0.058 ms\nAvec certaines bases de données, des options peuvent produire l’exécution de la requête, ce qui pourrait avoir des effets non désirables sur la base de données. Par exemple, l’option ANALYZE prise en charge par MariaDB, MySQL 8.0.18+ et PostgreSQL pourrait aboutir à des modifications de données s’il existe des déclencheurs (triggers) ou si une fonction est appelée, même pour une requête SELECT.
La recherche dans les champs est ce qui constitue le cœur des clauses SQL WHERE. La syntaxe s’exprime par des paramètres nommés dans les méthodes filter(), exclude() et get() de QuerySet.
Pour une introduction sur ce sujet, consultez la documentation sur les requêtes de modèles et de base de données.
\nLes recherches fournies par Django sont présentées ci-dessous. Il est également possible d’écrire des recherches personnalisées pour les champs de modèles.
\nPar commodité, lorsqu’aucune recherche particulière n’est indiquée (comme dans Entry.objects.get(id=14)), Django suppose que la recherche souhaitée est exact.
exactLien vers cette rubrique#Correspondance exacte. Si la valeur fournie pour la comparaison vaut None, elle sera interprétée comme un NULL SQL (voir isnull pour plus de détails).
Exemples :
\nEntry.objects.get(id__exact=14)\nEntry.objects.get(id__exact=None)\nÉquivalence en SQL :
\nSELECT ... WHERE id = 14;\nSELECT ... WHERE id IS NULL;\niexactLien vers cette rubrique#Correspondance exacte insensible à la casse. Si la valeur fournie pour la comparaison vaut None, elle sera interprétée comme un NULL SQL (voir isnull pour plus de détails).
Exemple :
\nBlog.objects.get(name__iexact='beatles blog')\nBlog.objects.get(name__iexact=None)\nÉquivalence en SQL :
\nSELECT ... WHERE name ILIKE 'beatles blog';\nSELECT ... WHERE name IS NULL;\nNotez que 'Beatles Blog', 'beatles blog', 'BeAtLes BLoG', etc. correspondent tous à la première recherche.
containsLien vers cette rubrique#Test d’inclusion sensible à la casse.
\nExemple :
\nEntry.objects.get(headline__contains='Lennon')\nÉquivalent SQL :
\nSELECT ... WHERE headline LIKE '%Lennon%';\nNotez que le titre (headline) 'Lennon honored today' correspondrait à cette recherche, mais pas 'lennon honored today'.
icontainsLien vers cette rubrique#Test d’inclusion insensible à la casse.
\nExemple :
\nEntry.objects.get(headline__icontains='Lennon')\nÉquivalent SQL :
\nSELECT ... WHERE headline ILIKE '%Lennon%';\ninLien vers cette rubrique#Dans un itérable donné ; souvent une liste, un tuple ou un jeu de requête. Ce n’est pas courant, mais des chaînes (qui sont aussi des itérables) sont acceptées.
\nExemples :
\nEntry.objects.filter(id__in=[1, 3, 4])\nEntry.objects.filter(headline__in='abc')\nÉquivalence en SQL :
\nSELECT ... WHERE id IN (1, 3, 4);\nSELECT ... WHERE headline IN ('a', 'b', 'c');\nVous pouvez également utiliser un jeu de requête pour évaluer dynamiquement la liste des valeurs au lieu de fournir une liste de valeurs littérales :
\ninner_qs = Blog.objects.filter(name__contains='Cheddar')\nentries = Entry.objects.filter(blog__in=inner_qs)\nCe jeu de requête sera évalué sous forme d’instruction de sous-sélection :
\nSELECT ... WHERE blog.id IN (SELECT id FROM ... WHERE NAME LIKE '%Cheddar%')\nSi vous fournissez un QuerySet résultant d’un appel à values() ou à values_list() comme valeur d’une requête __in, vous devez vous assurer que vous extrayez un seul champ du résultat. Par exemple, ceci fonctionnera (filtrage sur les noms de blogs) :
inner_qs = Blog.objects.filter(name__contains='Ch').values('name')\nentries = Entry.objects.filter(blog__name__in=inner_qs)\nCet exemple générera une exception, car la requête imbriquée extrait deux valeurs de champ, alors qu’il n’en faut qu’une seule :
\n# Bad code! Will raise a TypeError.\ninner_qs = Blog.objects.filter(name__contains='Ch').values('name', 'id')\nentries = Entry.objects.filter(blog__name__in=inner_qs)\ngtLien vers cette rubrique#Plus grand que.
\nExemple :
\nEntry.objects.filter(id__gt=4)\nÉquivalent SQL :
\nSELECT ... WHERE id > 4;\ngteLien vers cette rubrique#Plus grand ou égal à.
\nltLien vers cette rubrique#Plus petit que.
\nlteLien vers cette rubrique#Plus petit ou égal à.
\nstartswithLien vers cette rubrique#Commence par (sensible à la casse).
\nExemple :
\nEntry.objects.filter(headline__startswith='Lennon')\nÉquivalent SQL :
\nSELECT ... WHERE headline LIKE 'Lennon%';\nSQLite ne prend pas en charge les instructions LIKE sensibles à la casse ; startswith se comporte comme istartswith pour SQLite.
istartswithLien vers cette rubrique#Commence par (non sensible à la casse).
\nExemple :
\nEntry.objects.filter(headline__istartswith='Lennon')\nÉquivalent SQL :
\nSELECT ... WHERE headline ILIKE 'Lennon%';\nendswithLien vers cette rubrique#Se termine par (sensible à la casse).
\nExemple :
\nEntry.objects.filter(headline__endswith='Lennon')\nÉquivalent SQL :
\nSELECT ... WHERE headline LIKE '%Lennon';\niendswithLien vers cette rubrique#Se termine par (non sensible à la casse).
\nExemple :
\nEntry.objects.filter(headline__iendswith='Lennon')\nÉquivalent SQL :
\nSELECT ... WHERE headline ILIKE '%Lennon'\nrangeLien vers cette rubrique#Test d’intervalle (inclusif).
\nExemple :
\nimport datetime\nstart_date = datetime.date(2005, 1, 1)\nend_date = datetime.date(2005, 3, 31)\nEntry.objects.filter(pub_date__range=(start_date, end_date))\nÉquivalent SQL :
\nSELECT ... WHERE pub_date BETWEEN '2005-01-01' and '2005-03-31';\nVous pouvez utiliser range partout là ou vous pouvez utiliser BETWEEN en SQL — pour les dates, les nombres et même les caractères.
dateLien vers cette rubrique#Pour les champs date/heure, force la valeur à une date. Cette expression peut être suivie d’autres expressions de champs. Accepte une valeur date.
\nExemple :
\nEntry.objects.filter(pub_date__date=datetime.date(2005, 1, 1))\nEntry.objects.filter(pub_date__date__gt=datetime.date(2005, 1, 1))\n(Nous n’avons pas inclus de code SQL équivalent pour cette recherche car l’implémentation de la requête correspondante varie beaucoup selon le moteur de base de données.)
\nLorsque USE_TZ vaut True, les champs sont convertis dans le fuseau horaire en cours avant le filtrage. Cela nécessite la présence des définitions de fuseaux horaires dans la base de données.
yearLien vers cette rubrique#Pour les champs date et date/heure, une correspondance exacte de l’année. Cette expression peut être suivie d’autres expressions de champs. Accepte une année comme nombre entier.
\nExemple :
\nEntry.objects.filter(pub_date__year=2005)\nEntry.objects.filter(pub_date__year__gte=2005)\nÉquivalent SQL :
\nSELECT ... WHERE pub_date BETWEEN '2005-01-01' AND '2005-12-31';\nSELECT ... WHERE pub_date >= '2005-01-01';\n(La syntaxe SQL exacte varie d’un moteur de base de données à l’autre.)
\nLorsque USE_TZ vaut True, les champs date/heure sont convertis dans le fuseau horaire en cours avant le filtrage. Cela nécessite la présence des définitions de fuseaux horaires dans la base de données.
iso_yearLien vers cette rubrique#Pour les champs date et date/heure, une correspondance exacte de l’année avec numéros de semaine ISO 8601. Cette expression peut être suivie d’autres expressions de champs. Accepte une année comme nombre entier.
\nExemple :
\nEntry.objects.filter(pub_date__iso_year=2005)\nEntry.objects.filter(pub_date__iso_year__gte=2005)\n(La syntaxe SQL exacte varie d’un moteur de base de données à l’autre.)
\nLorsque USE_TZ vaut True, les champs date/heure sont convertis dans le fuseau horaire en cours avant le filtrage. Cela nécessite la présence des définitions de fuseaux horaires dans la base de données.
monthLien vers cette rubrique#Pour les champs date et date/heure, une correspondance exacte du mois. Cette expression peut être suivie d’autres expressions de champs. Accepte un nombre entier, de 1 (janvier) à 12 (décembre).
\nExemple :
\nEntry.objects.filter(pub_date__month=12)\nEntry.objects.filter(pub_date__month__gte=6)\nÉquivalent SQL :
\nSELECT ... WHERE EXTRACT('month' FROM pub_date) = '12';\nSELECT ... WHERE EXTRACT('month' FROM pub_date) >= '6';\n(La syntaxe SQL exacte varie d’un moteur de base de données à l’autre.)
\nLorsque USE_TZ vaut True, les champs date/heure sont convertis dans le fuseau horaire en cours avant le filtrage. Cela nécessite la présence des définitions de fuseaux horaires dans la base de données.
dayLien vers cette rubrique#Pour les champs date et date/heure, une correspondance exacte du jour. Cette expression peut être suivie d’autres expressions de champs. Accepte un jour comme nombre entier.
\nExemple :
\nEntry.objects.filter(pub_date__day=3)\nEntry.objects.filter(pub_date__day__gte=3)\nÉquivalent SQL :
\nSELECT ... WHERE EXTRACT('day' FROM pub_date) = '3';\nSELECT ... WHERE EXTRACT('day' FROM pub_date) >= '3';\n(La syntaxe SQL exacte varie d’un moteur de base de données à l’autre.)
\nNotez que cela correspond à tout élément dont le champ pub_date est égal au troisième jour du mois, comme le 3 janvier, le 3 juillet, etc.
Lorsque USE_TZ vaut True, les champs date/heure sont convertis dans le fuseau horaire en cours avant le filtrage. Cela nécessite la présence des définitions de fuseaux horaires dans la base de données.
weekLien vers cette rubrique#Pour des champs date et date/heure, renvoie le numéro de semaine (1-52 ou 53) selon ISO-8601, c’est-à-dire que les semaines commencent un lundi et que la première semaine contient le premier jeudi de l’année.
\nExemple :
\nEntry.objects.filter(pub_date__week=52)\nEntry.objects.filter(pub_date__week__gte=32, pub_date__week__lte=38)\n(Nous n’avons pas inclus de code SQL équivalent pour cette recherche car l’implémentation de la requête correspondante varie beaucoup selon le moteur de base de données.)
\nLorsque USE_TZ vaut True, les champs date/heure sont convertis dans le fuseau horaire en cours avant le filtrage. Cela nécessite la présence des définitions de fuseaux horaires dans la base de données.
week_dayLien vers cette rubrique#Pour les champs date et date/heure, une correspondance exacte du « jour de la semaine ». Cette expression peut être suivie d’autres expressions de champs.
\nAccepte un nombre entier représentant le jour de la semaine, de 1 (dimanche) à 7 (samedi).
\nExemple :
\nEntry.objects.filter(pub_date__week_day=2)\nEntry.objects.filter(pub_date__week_day__gte=2)\n(Nous n’avons pas inclus de code SQL équivalent pour cette recherche car l’implémentation de la requête correspondante varie beaucoup selon le moteur de base de données.)
\nNotez que cela correspond à tout élément dont le champ pub_date est un lundi (jour 2 de la semaine), sans tenir compte du mois ou de l’année. Les jours de la semaine sont indexés de 1 (dimanche) à 7 (samedi).
Lorsque USE_TZ vaut True, les champs date/heure sont convertis dans le fuseau horaire en cours avant le filtrage. Cela nécessite la présence des définitions de fuseaux horaires dans la base de données.
iso_week_dayLien vers cette rubrique#Pour les champs date et date/heure, une correspondance exacte du jour de la semaine ISO 8601. Cette expression peut être suivie d’autres expressions de champs.
\nAccepte un nombre entier représentant le jour de la semaine, de 1 (lundi) à 7 (dimanche).
\nExemple :
\nEntry.objects.filter(pub_date__iso_week_day=1)\nEntry.objects.filter(pub_date__iso_week_day__gte=1)\n(Nous n’avons pas inclus de code SQL équivalent pour cette recherche car l’implémentation de la requête correspondante varie beaucoup selon le moteur de base de données.)
\nNotez que cela correspond à tout élément dont le champ pub_date est un lundi (jour 2 de la semaine), sans tenir compte du mois ou de l’année. Les jours de la semaine sont indexés de 1 (lundi) à 7 (dimanche).
Lorsque USE_TZ vaut True, les champs date/heure sont convertis dans le fuseau horaire en cours avant le filtrage. Cela nécessite la présence des définitions de fuseaux horaires dans la base de données.
quarterLien vers cette rubrique#Pour les champs date et date/heure, une correspondance de « trimestre annuel ». Cette expression peut être suivie d’autres expressions de champs. Accepte une valeur nombre entier entre 1 et 4 représentant le trimestre de l’année.
\nExemple pour obtenir les lignes du deuxième trimestre (1er avril au 30 juin)
\nEntry.objects.filter(pub_date__quarter=2)\n(Nous n’avons pas inclus de code SQL équivalent pour cette recherche car l’implémentation de la requête correspondante varie beaucoup selon le moteur de base de données.)
\nLorsque USE_TZ vaut True, les champs date/heure sont convertis dans le fuseau horaire en cours avant le filtrage. Cela nécessite la présence des définitions de fuseaux horaires dans la base de données.
timeLien vers cette rubrique#Pour les champs date/heure, force la valeur à une heure. Cette expression peut être suivie d’autres expressions de champs. Accepte une valeur datetime.time.
Exemple :
\nEntry.objects.filter(pub_date__time=datetime.time(14, 30))\nEntry.objects.filter(pub_date__time__range=(datetime.time(8), datetime.time(17)))\n(Nous n’avons pas inclus de code SQL équivalent pour cette recherche car l’implémentation de la requête correspondante varie beaucoup selon le moteur de base de données.)
\nLorsque USE_TZ vaut True, les champs sont convertis dans le fuseau horaire en cours avant le filtrage. Cela nécessite la présence des définitions de fuseaux horaires dans la base de données.
hourLien vers cette rubrique#Pour les champs date/heure et heure, une correspondance exacte de l’heure. Cette expression peut être suivie d’autres expressions de champs. Accepte un nombre entier entre 0 et 23.
\nExemple :
\nEvent.objects.filter(timestamp__hour=23)\nEvent.objects.filter(time__hour=5)\nEvent.objects.filter(timestamp__hour__gte=12)\nÉquivalent SQL :
\nSELECT ... WHERE EXTRACT('hour' FROM timestamp) = '23';\nSELECT ... WHERE EXTRACT('hour' FROM time) = '5';\nSELECT ... WHERE EXTRACT('hour' FROM timestamp) >= '12';\n(La syntaxe SQL exacte varie d’un moteur de base de données à l’autre.)
\nLorsque USE_TZ vaut True, les champs date/heure sont convertis dans le fuseau horaire en cours avant le filtrage. Cela nécessite la présence des définitions de fuseaux horaires dans la base de données.
minuteLien vers cette rubrique#Pour les champs date/heure et heure, une correspondance exacte de la minute. Cette expression peut être suivie d’autres expressions de champs. Accepte un nombre entier entre 0 et 59.
\nExemple :
\nEvent.objects.filter(timestamp__minute=29)\nEvent.objects.filter(time__minute=46)\nEvent.objects.filter(timestamp__minute__gte=29)\nÉquivalent SQL :
\nSELECT ... WHERE EXTRACT('minute' FROM timestamp) = '29';\nSELECT ... WHERE EXTRACT('minute' FROM time) = '46';\nSELECT ... WHERE EXTRACT('minute' FROM timestamp) >= '29';\n(La syntaxe SQL exacte varie d’un moteur de base de données à l’autre.)
\nLorsque USE_TZ vaut True, les champs date/heure sont convertis dans le fuseau horaire en cours avant le filtrage. Cela nécessite la présence des définitions de fuseaux horaires dans la base de données.
secondLien vers cette rubrique#Pour les champs date/heure et heure, une correspondance exacte de la seconde. Cette expression peut être suivie d’autres expressions de champs. Accepte un nombre entier entre 0 et 59.
\nExemple :
\nEvent.objects.filter(timestamp__second=31)\nEvent.objects.filter(time__second=2)\nEvent.objects.filter(timestamp__second__gte=31)\nÉquivalent SQL :
\nSELECT ... WHERE EXTRACT('second' FROM timestamp) = '31';\nSELECT ... WHERE EXTRACT('second' FROM time) = '2';\nSELECT ... WHERE EXTRACT('second' FROM timestamp) >= '31';\n(La syntaxe SQL exacte varie d’un moteur de base de données à l’autre.)
\nLorsque USE_TZ vaut True, les champs date/heure sont convertis dans le fuseau horaire en cours avant le filtrage. Cela nécessite la présence des définitions de fuseaux horaires dans la base de données.
isnullLien vers cette rubrique#Accepte True ou False, ce qui correspond respectivement aux instructions SQL IS NULL et IS NOT NULL.
Exemple :
\nEntry.objects.filter(pub_date__isnull=True)\nÉquivalent SQL :
\nSELECT ... WHERE pub_date IS NULL;\nregexLien vers cette rubrique#Recherche par expression régulière, sensible à la casse.
\nLa syntaxe d’expression régulière est celle du moteur de base de données utilisé. Pour SQLite qui ne prend pas en charge nativement les expressions régulières, cette fonctionnalité est fournie par une fonction (Python) REGEXP définie par l’utilisateur, et la syntaxe d’expression régulière est par conséquent celle du module re de Python.
Exemple :
\nEntry.objects.get(title__regex=r'^(An?|The) +')\nÉquivalence en SQL :
\nSELECT ... WHERE title REGEXP BINARY '^(An?|The) +'; -- MySQL\n\nSELECT ... WHERE REGEXP_LIKE(title, '^(An?|The) +', 'c'); -- Oracle\n\nSELECT ... WHERE title ~ '^(An?|The) +'; -- PostgreSQL\n\nSELECT ... WHERE title REGEXP '^(An?|The) +'; -- SQLite\nIl est recommandé d’utiliser des chaînes brutes (par ex. r'foo' au lieu de 'foo') pour transmettre des expressions régulières.
iregexLien vers cette rubrique#Recherche par expression régulière, insensible à la casse.
\nExemple :
\nEntry.objects.get(title__iregex=r'^(an?|the) +')\nÉquivalence en SQL :
\nSELECT ... WHERE title REGEXP '^(an?|the) +'; -- MySQL\n\nSELECT ... WHERE REGEXP_LIKE(title, '^(an?|the) +', 'i'); -- Oracle\n\nSELECT ... WHERE title ~* '^(an?|the) +'; -- PostgreSQL\n\nSELECT ... WHERE title REGEXP '(?i)^(an?|the) +'; -- SQLite\nDjango fournit les fonctions d’agrégation suivantes dans le module django.db.models. Pour plus de détails sur l’usage de ces fonctions, consultez le guide thématique sur l’agrégation. Consultez la documentation de Aggregate pour apprendre à créer vos propres agrégations.
Toutes les agrégations partagent les paramètres suivants :
\nexpressionsLien vers cette rubrique#Des chaînes référençant des champs du modèle, des transformations du champ ou des expressions de requête.
\n\noutput_fieldLien vers cette rubrique#Un paramètre facultatif représentant le champ de modèle de la valeur renvoyée.
\n\nfilterLien vers cette rubrique#Un objet Q facultatif utilisé pour filtrer les lignes qui ont été agrégées.
Voir Agrégation conditionnelle et Filtrage sur les annotations pour des exemples d’utilisation.
\n**extraLien vers cette rubrique#Paramètres nommés qui peuvent fournir du contexte supplémentaire pour le code SQL généré par l’agrégation.
\nAvgLien vers cette rubrique#Renvoie la valeur moyenne de l’expression indiquée, qui doit être de type numérique, sauf si vous indiquez un champ output_field différent.
Alias par défaut : <champ>__avg
Type de la valeur renvoyée : float si la valeur d’entrée est int, sinon identique au champ de départ, ou output_field s’il est indiqué
Accepte un paramètre facultatif :
\nSi distinct=True, Avg renvoie la valeur moyenne de valeurs uniques. Cela correspond au code SQL AVG(DISTINCT <field>). La valeur par défaut est False.
CountLien vers cette rubrique#Renvoie le nombre d’objets liés au travers de l’expression indiquée.
\nAlias par défaut : <champ>__count
Type de la valeur renvoyée : int
Accepte un paramètre facultatif :
\nSi distinct=True, le dénombrement ne tient compte que des instances uniques. Cela correspond au code SQL COUNT(DISTINCT <field>). La valeur par défaut est False.
MaxLien vers cette rubrique#Renvoie la valeur maximale de l’expression donnée.
\nAlias par défaut : <champ>__max
Type de la valeur renvoyée : identique au champ de départ, ou output_field s’il est indiqué
MinLien vers cette rubrique#Renvoie la valeur minimale de l’expression donnée.
\nAlias par défaut : <champ>__min
Type de la valeur renvoyée : identique au champ de départ, ou output_field s’il est indiqué
StdDevLien vers cette rubrique#Renvoie la déviation standard des données contenues dans l’expression donnée.
\nAlias par défaut : <champ>__stddev
Type de la valeur renvoyée : float si la valeur d’entrée est int, sinon identique au champ de départ, ou output_field s’il est indiqué
Accepte un paramètre facultatif :
\nPar défaut, StdDev renvoie la déviation standard de population. Cependant, si sample=True, la valeur renvoyée sera la déviation standard d’échantillon.
SumLien vers cette rubrique#Calcule la somme de toutes les valeurs de l’expression donnée.
\nAlias par défaut : <champ>__sum
Type de la valeur renvoyée : identique au champ de départ, ou output_field s’il est indiqué
Accepte un paramètre facultatif :
\nSi distinct=True, Sum renvoie la somme des valeurs uniques. Cela correspond au code SQL SUM(DISTINCT <field>). La valeur par défaut est False`.
VarianceLien vers cette rubrique#Renvoie la variance des données de l’expression donnée.
\nAlias par défaut : <champ>__variance
Type de la valeur renvoyée : float si la valeur d’entrée est int, sinon identique au champ de départ, ou output_field s’il est indiqué
Accepte un paramètre facultatif :
\nPar défaut, Variance renvoie la variance de population. Cependant, si sample=True, la valeur renvoyée sera la variance d’échantillon.