Une fois les modèles de données créés, Django offre automatiquement une API d’abstraction de base de données qui permet de créer, obtenir, mettre à jour et supprimer des objets. Ce document explique comment utiliser cette API. Consultez la référence des modèles de données pour des détails complets sur toutes les options d’interrogation des modèles.
\nÀ travers ce guide (et dans la référence), nous nous référons aux modèles suivants, qui forment une application de blog :
\nfrom datetime import date\n\nfrom django.db import models\n\nclass Blog(models.Model):\n name = models.CharField(max_length=100)\n tagline = models.TextField()\n\n def __str__(self):\n return self.name\n\nclass Author(models.Model):\n name = models.CharField(max_length=200)\n email = models.EmailField()\n\n def __str__(self):\n return self.name\n\nclass Entry(models.Model):\n blog = models.ForeignKey(Blog, on_delete=models.CASCADE)\n headline = models.CharField(max_length=255)\n body_text = models.TextField()\n pub_date = models.DateField()\n mod_date = models.DateField(default=date.today)\n authors = models.ManyToManyField(Author)\n number_of_comments = models.IntegerField(default=0)\n number_of_pingbacks = models.IntegerField(default=0)\n rating = models.IntegerField(default=5)\n\n def __str__(self):\n return self.headline\nPour représenter des données d’une table de base de données en objets Python, Django utilise un système intuitif : une classe de modèle représente une table de base de données, et une instance de cette classe représente un enregistrement particulier dans la table de base de données.
\nPour créer un objet, créez une instance de la classe de modèle en utilisant des paramètres nommés, puis appelez save() pour l’enregistrer dans la base de données.
En supposant que les modèles se trouvent dans un fichier mysite/blog/models.py, voici un exemple :
>>> from blog.models import Blog\n>>> b = Blog(name='Beatles Blog', tagline='All the latest Beatles news.')\n>>> b.save()\nCeci exécute une commande SQL INSERT en arrière-plan. Django ne sollicite pas la base de données tant que vous n’appelez pas explicitement save().
La méthode save() ne renvoie aucune valeur.
Pour enregistrer les modifications d’un objet existant dans la base de données, utilisez save().
Considérant une instance b5 d’un Blog ayant déjà été enregistrée dans la base de données, cet exemple modifie son nom et met à jour son enregistrement dans la base de données :
>>> b5.name = 'New name'\n>>> b5.save()\nCeci génère une commande SQL UPDATE en arrière-plan. Django ne sollicite pas la base de données tant que vous n’appelez pas explicitement save().
ForeignKey et ManyToManyFieldLien vers cette rubrique#La mise à jour d’un champ ForeignKey fonctionne exactement de la même façon que l’enregistrement d’un champ normal, attribuez un objet du bon type au champ en question. Cet exemple met à jour l’attribut blog d’une instance Entry nommée entry, en supposant que les instances appropriées de Entry et de Blog sont déjà enregistrées dans la base de données (afin de pouvoir être récupérées ci-dessous) :
>>> from blog.models import Blog, Entry\n>>> entry = Entry.objects.get(pk=1)\n>>> cheese_blog = Blog.objects.get(name="Cheddar Talk")\n>>> entry.blog = cheese_blog\n>>> entry.save()\nLa mise à jour d’un champ ManyToManyField fonctionne un peu différemment ; utilisez la méthode add() du champ pour ajouter un enregistrement à la relation. Cet exemple ajoute l’instance Author joe à l’objet entry:
>>> from blog.models import Author\n>>> joe = Author.objects.create(name="Joe")\n>>> entry.authors.add(joe)\nPour ajouter plusieurs enregistrements à un champ ManyToManyField d’un seul coup, indiquez plusieurs paramètres dans l’appel à add(), comme ceci :
>>> john = Author.objects.create(name="John")\n>>> paul = Author.objects.create(name="Paul")\n>>> george = Author.objects.create(name="George")\n>>> ringo = Author.objects.create(name="Ringo")\n>>> entry.authors.add(john, paul, george, ringo)\nDjango se plaint si vous essayez d’assigner ou d’ajouter un objet de type inapproprié.
\nPour extraire des objets de la base de données, construisez un QuerySet via un Manager de la classe de votre modèle.
Un QuerySet représente une collection d’objets de la base de données. Il peut comporter zéro, un ou plusieurs filtres. Les filtres réduisent les résultats de requêtes en fonction des paramètres donnés. En termes SQL, un QuerySet équivaut à une commande SELECT et un filtre correspond à une clause restrictive telle que WHERE ou LIMIT.
On obtient un QuerySet en utilisant le Manager du modèle. Chaque modèle a au moins un Manager ; il s’appelle objects par défaut. On y accède directement via la classe du modèle, comme ceci :
>>> Blog.objects\n<django.db.models.manager.Manager object at ...>\n>>> b = Blog(name='Foo', tagline='Bar')\n>>> b.objects\nTraceback:\n ...\nAttributeError: "Manager isn't accessible via Blog instances."\nLe Manager est la source principale des QuerySets d’un modèle. Par exemple, Blog.objects.all() renvoie un QuerySet contenant tous les objets Blog de la base de données.
La façon la plus simple d’obtenir des objets d’une table est de tous les sélectionner. Pour ce faire, utilisez la méthode all() d’un Manager:
>>> all_entries = Entry.objects.all()\nLa méthode all() renvoie un QuerySet de tous les objets dans la base de données.
Le QuerySet renvoyé par all() contient tous les objets de la table de la base de données. Mais le plus souvent, seul un sous-ensemble de tous les objets devra être sélectionné.
Pour créer un tel sous-ensemble, vous affinez le QuerySet initial en\ny ajoutant des filtres de conditions. Les deux façons les plus utilisées pour affiner un QuerySet sont :
filter(**kwargs)Renvoie un nouveau QuerySet contenant les objets qui répondent aux paramètres de recherche donnés.
exclude(**kwargs)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 dans les définitions de fonction ci-dessus) doivent être dans le format décrit dans Recherches dans les champs ci-dessous.
Par exemple, pour obtenir un QuerySet des articles de blog de l’année 2006, utilisez filter() comme ceci :
Entry.objects.filter(pub_date__year=2006)\nAvec la classe de gestionnaire par défaut, c’est équivalent à :
\nEntry.objects.all().filter(pub_date__year=2006)\nLe résultat de l’affinage d’un QuerySet est lui-même un QuerySet, il est donc possible d’enchaîner les filtrages successifs. Par exemple :
>>> Entry.objects.filter(\n... headline__startswith='What'\n... ).exclude(\n... pub_date__gte=datetime.date.today()\n... ).filter(\n... pub_date__gte=datetime.date(2005, 1, 30)\n... )\nÀ partir du QuerySet initial de toutes les lignes dans la base de données, le code ci-dessus ajoute un filtre, puis une exclusion, puis un autre filtre. Le résultat final est un QuerySet contenant tous les enregistrements ayant un titre (headline) commençant par « What », ayant été publiés entre le 30 janvier 2005 et aujourd’hui.
QuerySet filtrés sont uniquesLien vers cette rubrique#À chaque fois que vous affinez un QuerySet, vous obtenez un QuerySet tout neuf qui n’est lié d’aucune manière au QuerySet précédent. Chaque affinage crée un QuerySet séparé et distinct qui peut être stocké, utilisé et réutilisé.
Exemple :
\n>>> q1 = Entry.objects.filter(headline__startswith="What")\n>>> q2 = q1.exclude(pub_date__gte=datetime.date.today())\n>>> q3 = q1.filter(pub_date__gte=datetime.date.today())\nCes trois QuerySet sont séparés. Le premier est un QuerySet de base contenant tous les enregistrements qui contiennent un titre commençant par « What ». Le second est un sous-ensemble du premier, avec un critère supplémentaire qui exclut les enregistrements dont le champ pub_date est aujourd’hui ou dans le futur. Le troisième est un sous-ensemble du premier, avec un critère supplémentaire qui sélectionne uniquement les enregistrements dont le champ pub_date est aujourd’hui ou dans le futur. Le QuerySet initial (q1) n’est pas affecté par le processus d’affinage.
QuerySet sont différésLien vers cette rubrique#Les QuerySets sont différés (« lazy ») ; la création d’un QuerySet ne génère aucune activité au niveau de la base de données. Vous pouvez empiler les filtres toute la journée, Django ne lance aucune requête tant\nque le QuerySet n’est pas évalué. Regardez cet exemple :
>>> q = Entry.objects.filter(headline__startswith="What")\n>>> q = q.filter(pub_date__lte=datetime.date.today())\n>>> q = q.exclude(body_text__icontains="food")\n>>> print(q)\nMalgré le fait que ceci ressemble à trois interrogations de la base de données, en réalité une seule interrogation est faite, à la dernière ligne (print(q)). En général, les résultats d’un QuerySet ne sont récupérés de la base de données que lorsque vous les « demandez ». Lorsque cela arrive, le QuerySet est évalué en accédant à la base de données. Pour plus de détails sur le moment exact où l’évaluation a lieu, consultez Quand les objets QuerySet sont évalués.
get()Lien vers cette rubrique#filter() renvoie toujours un QuerySet, même si la requête ne renvoie qu’un seul objet ; dans ce cas, le QuerySet ne contiendra simplement qu’un seul élément.
Si vous savez qu’un seul objet correspondra à votre requête, vous pouvez utiliser la méthode get() d’un Manager qui renvoie directement l’objet :
>>> one_entry = Entry.objects.get(pk=1)\nN’importe quelle expression de recherche peut être utilisée avec get(), comme pour filter(). Voir Recherches dans les champs ci-dessous.
Notez qu’il y a une différence entre l’utilisation de get() et celle de filter() avec le segment [0]. Si aucun résultat ne correspond à la requête, get() génère une exception DoesNotExist. Cette exception est un attribut de la classe de modèle sur laquelle la requête est appliquée ; ainsi, dans le code ci-dessus, s’il n’existe pas d’objet Entry avec une clé primaire de 1, Django génère l’exception Entry.DoesNotExist.
De même, Django réagit si plus d’un élément correspond à la requête get(). Dans ce cas, il lève l’exception MultipleObjectsReturned qui est également un attribut de la classe de modèle elle-même.
QuerySetLien vers cette rubrique#La plupart du temps, vous utiliserez all(), get(), filter() et exclude() lorsque vous aurez besoin de sélectionner des objets dans la base de données. Cependant, c’est loin d’être tout ; consultez la référence de l’API QuerySet pour une liste complète des diverses méthodes de QuerySet.
QuerySetLien vers cette rubrique#Utilisez un sous-ensemble de la syntaxe Python de segmentation des listes pour restreindre un QuerySet à un certain nombre de résultats. C’est l’équivalent des clauses SQL LIMIT et OFFSET.
Par exemple, ceci renvoie les 5 premiers objets (LIMIT 5) :
>>> Entry.objects.all()[:5]\nCeci renvoie du sixième au dixième objet (OFFSET 5 LIMIT 5) :
>>> Entry.objects.all()[5:10]\nLes index négatifs (ex. : Entry.objects.all()[-1]) ne sont pas pris en charge.
De manière générale, la segmentation d’un QuerySet renvoie un nouveau QuerySet ; la requête n’est pas évaluée, sauf si vous utilisez le paramètre step de la syntaxe de segmentation de Python. Par exemple, ceci exécuterait effectivement la requête pour renvoyer une liste d’un objet sur 2 parmi les 10 premiers :
>>> Entry.objects.all()[:10:2]\nTout filtre ou tri subséquent d’un jeu de requête segmenté est interdit en raison de la nature ambiguë de son éventuel fonctionnement.
\nPour obtenir un seul objet plutôt qu’une liste (ex. : SELECT foo FROM bar LIMIT 1), utilisez un index au lieu d’un segment. Par exemple, ceci renvoie le premier objet Entry de la base de données, après avoir trié les objets alphabétiquement par titre (headline) :
>>> Entry.objects.order_by('headline')[0]\nC’est grossièrement équivalent à :
\n>>> Entry.objects.order_by('headline')[0:1].get()\nNotez toutefois que si aucun objet ne correspond à la requête, une exception IndexError est générée dans le premier cas, tandis que dans le second cas, c’est l’exception DoesNotExist qui sera générée. Voir get() pour plus de détails.
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.
Les paramètres nommés de base de ces requêtes prennent la forme champ__typerequete=valeur (il s’agit d’un double soulignement). Par exemple :
>>> Entry.objects.filter(pub_date__lte='2006-01-01')\npeut être grossièrement traduit en code SQL comme :
\nSELECT * FROM blog_entry WHERE pub_date <= '2006-01-01';\nLe champ indiqué dans une recherche doit correspondre au nom d’un champ de modèle. Il existe cependant une exception ; dans le cas d’une clé étrangère ForeignKey, vous pouvez indiquer le nom du champ additionné du suffixe _id. Dans ce cas, le paramètre valeur doit contenir la valeur brute de la clé primaire du modèle étranger. Par exemple :
>>> Entry.objects.filter(blog_id=4)\nSi vous fournissez un paramètre nommé non valide, une fonction de recherche signalera une exception TypeError.
L’API de base de données gère une vingtaine de types de recherche ; une référence complète se trouve dans la référence des recherches de champs. Pour vous donner une idée de ce qui est possible, voici quelques recherches parmi les plus fréquemment utilisées :
\nexactUne correspondance « exacte ». Par exemple :
\n>>> Entry.objects.get(headline__exact="Cat bites dog")\nProduit le code SQL ressemblant à :
\nSELECT ... WHERE headline = 'Cat bites dog';\nSi vous n’indiquez pas de type de recherche, c’est-à-dire si votre paramètre nommé ne contient pas de double soulignement, Django considère que le type de recherche est exact.
Par exemple, les deux lignes suivantes sont équivalentes :
\n>>> Blog.objects.get(id__exact=14) # Explicit form\n>>> Blog.objects.get(id=14) # __exact is implied\nIl s’agit d’un raccourci commode, puisque les recherches exact sont les cas les plus courants.
iexactUne recherche insensible à la casse. Ainsi, la requête :
\n>>> Blog.objects.get(name__iexact="beatles blog")\nAurait pour occurrence un Blog intitulé "Beatles Blog", "beatles blog" ou même "BeAtlES blOG".
containsTest d’inclusion sensible à la casse. Par exemple :
\nEntry.objects.get(headline__contains='Lennon')\nPourrait être traduit grosso modo par ce code SQL :
\nSELECT ... WHERE headline LIKE '%Lennon%';\nNotez que le titre (headline) 'Today Lennon honored' correspondrait à cette recherche, mais pas 'today lennon honored'.
Il existe aussi une version insensible à la casse, icontains.
startswith, endswithRecherche « commençant par » et « finissant par », respectivement. Il en existe aussi des versions insensibles à la casse : istartswith et iendswith.
Encore une fois, ce n’est qu’un survol. Une référence complète est disponible dans la référence des recherches de champ.
\nDjango offre une approche puissante et intuitive pour « suivre » les relations dans les recherches, se chargeant automatiquement des JOIN SQL en arrière-plan. Pour atteindre une relation, utilisez les noms de champ qui servent de relation vers d’autres modèles, séparés par des doubles soulignements, jusqu’à atteindre le champ souhaité.
Cet exemple sélectionne tous les objets Entry d’un Blog ayant pour name la valeur 'Beatles Blog':
>>> Entry.objects.filter(blog__name='Beatles Blog')\nCe mécanisme de traversée de relations peut être aussi profond que vous le souhaitez.
\nCeci fonctionne également dans le sens inverse. Même s’il peut être personnalisé, la manière par défaut de se référer à une relation « inverse » dans une expression de requête est d’utiliser le nom du modèle en minuscules.
Cet exemple sélectionne tous les objets Blog ayant au moins une Entry ayant un headline contenant 'Lennon':
>>> Blog.objects.filter(entry__headline__contains='Lennon')\nSi vous filtrez à travers plusieurs relations et qu’un des modèles intermédiaires n’a pas de valeur répondant à la condition du filtre, Django le traite comme s’il y avait là un objet vide (toutes les valeurs sont NULL), mais valide. C’est-à-dire qu’aucune erreur ne sera signalée. Par exemple, dans ce filtre :
Blog.objects.filter(entry__authors__name='Lennon')\n(partant du principe qu’il existe un modèle Author lié), s’il n’y a pas de author associé à une entry, ce sera traité comme s’il n’y avait pas non plus de name, plutôt que de signaler une erreur à cause de l”author manquant. Normalement, c’est bien le comportement souhaité. Le seul cas où ça pourrait porter à confusion, c’est quand vous utilisez isnull. Ainsi :
Blog.objects.filter(entry__authors__name__isnull=True)\nrenvoie les objets Blog ayant un author avec le name vide ainsi que tous ceux ayant un author vide dans l”entry. Si vous ne voulez pas de cette deuxième catégorie d’objets, vous pourriez écrire :
Blog.objects.filter(entry__authors__isnull=False, entry__authors__name__isnull=True)\nLors de la traversée d’un champ ManyToManyField ou d’un clé ForeignKey inverse (comme de Blog à Entry), le filtrage sur plusieurs attributs pose la question de savoir si chaque attribut doit correspondre pour chaque objet lié. On pourrait rechercher des blogs qui ont un article en 2008 avec « “Lennon” » dans son titre, ou plus simplement des blogs qui ont un article en 2008 de même que des articles plus vieux ou plus récentes qui contiennent « “Lennon” » dans leur titre.
Pour sélectionner tous les blogs contenant au moins un article en 2008 ayant « Lennon » dans son titre (le même article devant satisfaire les deux conditions), il faudrait écrire
\nBlog.objects.filter(entry__headline__contains='Lennon', entry__pub_date__year=2008)\nSinon, pour effectuer une requête plus permissive sélectionnant tous les blogs ayant un ou plusieurs articles avec « Lennon » dans leur titre et un ou plusieurs articles en 2008, on écrirait
\nBlog.objects.filter(entry__headline__contains='Lennon').filter(entry__pub_date__year=2008)\nSupposons qu’il n’y ait qu’un seul blog ayant à la fois des articles contenant « Lennon » et des articles de 2008, mais qu’aucun des articles de 2008 ne contienne « Lennon ». La première requête ne renverrait aucun blog, mais la seconde renverrait ce blog (et cela parce que les lignes sélectionnées par le second filtre ne sont pas forcément les mêmes que celles du premier filtre ; chaque instruction de filtrage agit sur les éléments Blog, pas sur les éléments Entry ). En résumé, si toutes les conditions doivent s’appliquer sur les mêmes objets liés, alors chaque filtre doit être contenu dans un même appel à filter().
Dans les exemples donnés jusqu’ici, nous avons construit des filtres comparant la valeur d’un champ de modèle avec une constante. Mais qu’en est-il si vous souhaitez comparer la valeur d’un champ de modèle avec un autre champ du même modèle ?
\nDjango propose les expressions F pour autoriser de telles comparaisons. Les instances de F() agissent comme des références vers un champ de modèle à l’intérieur d’une requête. Ces références peuvent ensuite être utilisées dans des filtres de requêtes pour comparer les valeurs de deux champs différents d’une même instance de modèle.
Par exemple, pour obtenir la liste de tous les articles de blogue ayant reçus plus de commentaires que de « pings », nous construisons un objet F() pour référencer le nombre de pings afin d’utiliser cet objet F() dans la requête :
>>> from django.db.models import F\n>>> Entry.objects.filter(number_of_comments__gt=F('number_of_pingbacks'))\nDjango prend en charge l’utilisation des opérateurs arithmétiques addition, soustraction, multiplication, division, modulo et puissance avec les objets F(), aussi bien avec des constantes qu’avec d’autres objets F(). Pour obtenir tous les articles de blogue avec plus de deux fois de commentaires que de pings, nous modifions ainsi la requête :
>>> Entry.objects.filter(number_of_comments__gt=F('number_of_pingbacks') * 2)\nPour trouver tous les articles où la notation de l’article est plus petite que la somme des pings et des commentaires, nous pourrions effectuer cette requête :
\n>>> Entry.objects.filter(rating__lt=F('number_of_comments') + F('number_of_pingbacks'))\nVous pouvez aussi employer la notation en double soulignement pour traverser les relations dans un objet F(). Un objet F() contenant un double soulignement produira toute jointure nécessaire pour accéder aux objets liés. Par exemple, pour obtenir tous les articles dont le nom de l’auteur est égal au nom du blogue, nous pourrions effectuer la requête :
>>> Entry.objects.filter(authors__name=F('blog__name'))\nPour les champs date et date/heure, il est possible d’ajouter ou de soustraire un objet timedelta. L’exemple suivant renvoie tous les articles modifiés plus de 3 jours après avoir été publiés :
>>> from datetime import timedelta\n>>> Entry.objects.filter(mod_date__gt=F('pub_date') + timedelta(days=3))\nLes objets F() prennent en charge les opérations bit à bit via .bitand(), .bitor(), .bitxor(), .bitrightshift() et .bitleftshift(). Par exemple :
>>> F('somefield').bitand(16)\nDjango prend en charge l’appel à des transformations dans les expressions.
\nPar exemple, pour trouver tous les objets Entry publiés la même année que leur date de dernière modification
>>> from django.db.models import F\n>>> Entry.objects.filter(pub_date__year=F('mod_date__year'))\nPour trouver l’année de publication la plus ancienne d’un élément, on peut lancer la requête
\n>>> from django.db.models import Min\n>>> Entry.objects.aggregate(first_published_year=Min('pub_date__year'))\nCette exemple cherche la valeur de l’élément le mieux noté et le nombre total de commentaires de tous les éléments pour chaque année
\n>>> from django.db.models import OuterRef, Subquery, Sum\n>>> Entry.objects.values('pub_date__year').annotate(\n... top_rating=Subquery(\n... Entry.objects.filter(\n... pub_date__year=OuterRef('pub_date__year'),\n... ).order_by('-rating').values('rating')[:1]\n... ),\n... total_comments=Sum('number_of_comments'),\n... )\npkLien vers cette rubrique#Pour des raisons pratiques, Django fournit un raccourci de recherche pk, signifiant « primary key » (clé primaire).
Dans le modèle d’exemple Blog, la clé primaire est le champ id. Ainsi, ces trois lignes sont équivalentes :
>>> Blog.objects.get(id__exact=14) # Explicit form\n>>> Blog.objects.get(id=14) # __exact is implied\n>>> Blog.objects.get(pk=14) # pk implies id__exact\nL’emploi de pk n’est pas limité aux requêtes __exact; toute expression de requête peut être combinée avec pk pour effectuer une requête sur la clé primaire d’un modèle :
# Get blogs entries with id 1, 4 and 7\n>>> Blog.objects.filter(pk__in=[1,4,7])\n\n# Get all blog entries with id > 14\n>>> Blog.objects.filter(pk__gt=14)\nLes recherches sur pk fonctionnent également en traversant les relations. Par exemple, ces trois lignes sont équivalentes :
>>> Entry.objects.filter(blog__id__exact=3) # Explicit form\n>>> Entry.objects.filter(blog__id=3) # __exact is implied\n>>> Entry.objects.filter(blog__pk=3) # __pk implies __id__exact\nLIKELien vers cette rubrique#Les recherches de champs produisant des instructions SQL LIKE (iexact, contains, icontains, startswith, istartswith, endswith et iendswith) échappent automatiquement les deux caractères à signification spéciale des instructions LIKE: le signe pour cent et le soulignement (dans une instruction LIKE, le signe pour cent est utilisé comme caractère de remplacement multiple alors qu’un soulignement est utilisé comme caractère de remplacement unique).
Cela signifie que les choses devraient fonctionner intuitivement, sans faille d’abstraction. Par exemple, pour obtenir la liste de tous les articles contenant un signe pour cent, indiquez le signe pour cent comme pour n’importe quel autre caractère :
\n>>> Entry.objects.filter(headline__contains='%')\nDjango se charge de l’échappement à votre place ; le code SQL résultant ressemblera à quelque chose comme :
\nSELECT ... WHERE headline LIKE '%\\%%';\nMême chose pour les soulignements. Aussi bien les signes pour cent que les soulignements sont gérés pour vous de manière transparente.
\nQuerySetLien vers cette rubrique#Chaque QuerySet contient un cache pour minimiser l’accès à la base de données. La compréhension de son fonctionnement vous permet d’écrire le code le plus efficace possible.
Pour un nouvel objet QuerySet, son cache est vide. À la première évaluation d’un QuerySet (et donc qu’une requête de base de données est effectuée), Django enregistre les résultats de la requête dans le cache de l’objet QuerySet et renvoie les résultats qui ont été explicitement demandés (par ex. l’élément suivant dans le cas d’une itération du QuerySet). Les évaluations suivantes de l’objet QuerySet réutilisent les résultats mis en cache.
Gardez à l’esprit ce comportement de mise en cache, car vous pourriez vous faire avoir si vous n’utilisez pas correctement l’objet QuerySet. Par exemple, le code suivant crée deux objets QuerySet, les évalue et les abandonne :
>>> print([e.headline for e in Entry.objects.all()])\n>>> print([e.pub_date for e in Entry.objects.all()])\nDans ce cas, la même requête de base de données est exécutée deux fois, ce qui double en pratique la charge sur la base de données. Il est également imaginable que les deux listes ne contiennent pas exactement les mêmes enregistrements de base de données, car un objet Entry pourrait avoir été ajouté ou supprimé dans la fraction de seconde entre les deux requêtes.
Pour éviter ce problème, stockez l’objet QuerySet et réutilisez-le :
>>> queryset = Entry.objects.all()\n>>> print([p.headline for p in queryset]) # Evaluate the query set.\n>>> print([p.pub_date for p in queryset]) # Reuse the cache from the evaluation.\nQuerySet ne sont pas mis en cacheLien vers cette rubrique#Les objets QuerySet ne mettent pas toujours leurs résultats en cache. Lorsque seule une partie d’un queryset est évaluée, le cache est consulté mais s’il n’est pas rempli, les éléments renvoyés par la requête suivante ne sont pas mis en cache. Spécifiquement, cela signifie que la restriction d’un jeu de requêtes en employant une segmentation ou un index de liste ne remplira par le cache.
Par exemple, l’interrogation répétée d’un objet QuerySet à l’aide d’un index effectue une requête dans la base de données à chaque fois :
>>> queryset = Entry.objects.all()\n>>> print(queryset[5]) # Queries the database\n>>> print(queryset[5]) # Queries the database again\nCependant, si le jeu de requête complet a déjà été évalué, le cache sera tout de même mis à contribution :
\n>>> queryset = Entry.objects.all()\n>>> [entry for entry in queryset] # Queries the database\n>>> print(queryset[5]) # Uses cache\n>>> print(queryset[5]) # Uses cache\nVoici quelques exemples d’autres actions qui déclenchent l’évaluation de tout l’objet QuerySet et qui par conséquent remplissent le cache :
>>> [entry for entry in queryset]\n>>> bool(queryset)\n>>> entry in queryset\n>>> list(queryset)\nSi vous écrivez des vues ou du code asynchrone, vous ne pouvez pas utiliser l’ORM pour des requêtes de la façon qui est décrite ci-dessus, car il n’est pas possible d’appeler du code synchrone bloquant à partir de code asynchrone, cela bloquerait la boucle événementielle (ou plus probablement Django le remarquera et générera l’exception SynchronousOnlyOperation pour que ce blocage ne se produise pas).
Heureusement, il est possible de faire de nombreuses requêtes en utilisant les API de requêtes asynchrones de Django. Toute méthode susceptible de bloquer, telle que get() ou delete(), possède une variante asynchrone (aget() ou adelete()), et quand vous passez en boucle sur les résultats, vous pouvez alors utiliser l’itération asynchrone (async for).
La manière par défaut de passer en boucle sur une requête - avec for - aboutit à une requête de base de données bloquante en arrière-plan du moment que Django charge les résultats au moment de l’itération. Pour corriger cela, vous pouvez exploiter async for:
async for entry in Authors.objects.filter(name__startswith="A"):\n ...\nSoyez bien conscient que vous ne pouvez pas non plus exécuter d’autres opérations qui aboutiraient à une itération du jeu de requête, comme par exemple le placer dans un appel à list() pour forcer son évaluation (vous pouvez cependant utiliser async for dans une compréhension de liste si vous le souhaitez).
Comme les méthodes de QuerySet telles que``filter()`` ou exclude() n’exécutent pas réellement de requête (elles préparent le jeu de requête à s’exécuter au moment de l’itération), vous pouvez les utiliser sans crainte dans du code asynchrone. Pour savoir quelles méthodes peuvent continuer à être utilisées telles quelles, et quelles sont celles qui possèdent une version asynchrone, lisez la section suivante.
QuerySet et méthodes de gestionnaireLien vers cette rubrique#Certaines méthodes de gestionnaires et de jeux de requêtes, comme get() et first(), forcent l’exécution immédiate de la requête et sont bloquantes. D’autres, comme filter() et exclude(), ne forcent pas d’exécution et peuvent donc être utilisées à partir de code asynchrone sans problème. Mais comment pouvez-vous faire cette distinction ?
Bien qu’il soit possible de faire des recherches pour savoir s’il existe une version préfixée par a de ces méthodes (par exemple, aget existe, mais pas afilter()), il existe une façon plus logique : examinez de quelle sorte de méthode il s’agit dans la référence de QuerySet.
Dans cette référence, vous trouverez les méthodes de QuerySet classées en deux catégories :
Les méthodes qui renvoient de nouveaux jeux de requête: celles-ci sont non bloquantes et ne possèdent pas de version asynchrone. Vous pouvez les utiliser librement dans toute situation, bien que pour defer() et only(), il est recommandé de lire les notes à leur sujet avant de les utiliser.
Les méthodes qui ne renvoient pas de nouveaux jeux de requête: celles-ci sont bloquantes et possèdent une version asynchrone. Le nom de la version asynchrone est indiqué dans leur documentation, même si le modèle standard est d’ajouter un préfixe a.
Avec cette distinction, vous pouvez savoir quand vous devez utiliser les versions asynchrones et quand ce n’est pas indiqué. Par exemple, voici une requête asynchrone valable
\nuser = await User.objects.filter(username=my_input).afirst()\nfilter() renvoie un jeu de requête et peut donc bien être utilisée dans un environnement asynchrone, alors que first() est immédiatement évaluée et renvoie une instance de modèle. Ainsi, nous la modifions en afirst() et utilisons await en préambule de toute l’expression afin de l’appeler d’une manière adéquate pour l’asynchrone.
Les transactions ne sont actuellement pas prises en charge pour les requêtes et mises à jour asynchrones. Si vous tentez de les utiliser quand même, vous obtiendrez des exceptions SynchronousOnlyOperation.
Si vous souhaitez utiliser une transaction, nous suggérons d’écrire le code ORM à l’intérieur d’une fonction synchrone séparée, puis de l’appeler en utilisant sync_to_async - voir Gestion du code asynchrone pour plus de détails.
JSONFieldLien vers cette rubrique#L’implémentation des interrogations est différente pour JSONField, principalement en raison de l’existence des transformations de clés. Pour le montrer, nous allons utiliser le modèle d’exemple suivant
from django.db import models\n\nclass Dog(models.Model):\n name = models.CharField(max_length=200)\n data = models.JSONField(null=True)\n\n def __str__(self):\n return self.name\nNoneLien vers cette rubrique#Comme pour les autres champs, le stockage de None comme valeur de champ enregistre une valeur SQL NULL. Même si ce n’est pas recommandé, il est possible de stocker la valeur scalaire null de JSON au lieu du NULL SQL en utilisant Value('null').
Quelle que soit la valeur stockée, lorsqu’elle est lue de la base de données, la représentation Python de la valeur scalaire null de JSON est la même que pour la valeur SQL NULL, c’est-à-dire None. Il peut donc être difficile de faire la distinction entre les deux.
Ceci ne s’applique qu’à None comme valeur de premier niveau du champ. Si None se trouve à l’intérieur d’une structure list ou dict, elle sera toujours interprétée comme un null de JSON.
Lors des requêtes, la valeur None sera toujours interprétée comme la valeur null de JSON. Pour savoir si un champ possède la valeur SQL NULL, utilisez isnull:
>>> Dog.objects.create(name='Max', data=None) # SQL NULL.\n<Dog: Max>\n>>> Dog.objects.create(name='Archie', data=Value('null')) # JSON null.\n<Dog: Archie>\n>>> Dog.objects.filter(data=None)\n<QuerySet [<Dog: Archie>]>\n>>> Dog.objects.filter(data=Value('null'))\n<QuerySet [<Dog: Archie>]>\n>>> Dog.objects.filter(data__isnull=True)\n<QuerySet [<Dog: Max>]>\n>>> Dog.objects.filter(data__isnull=False)\n<QuerySet [<Dog: Archie>]>\nSauf dans le cas où vous souhaitez vraiment travailler avec des valeurs SQL NULL, préférez le paramètre null=False et définissez une valeur par défaut convenable pour les valeurs vides, telle que default=dict.
Pour rechercher en fonction d’une clé de dictionnaire donnée, utilisez cette clé comme nom de requête :
\n>>> Dog.objects.create(name='Rufus', data={\n... 'breed': 'labrador',\n... 'owner': {\n... 'name': 'Bob',\n... 'other_pets': [{\n... 'name': 'Fishy',\n... }],\n... },\n... })\n<Dog: Rufus>\n>>> Dog.objects.create(name='Meg', data={'breed': 'collie', 'owner': None})\n<Dog: Meg>\n>>> Dog.objects.filter(data__breed='collie')\n<QuerySet [<Dog: Meg>]>\nIl est possible d’enchaîner plusieurs clés pour former une recherche de chemin :
\n>>> Dog.objects.filter(data__owner__name='Bob')\n<QuerySet [<Dog: Rufus>]>\nSi la clé est un entier, elle sera interprétée comme une transformation d’indice de tableau :
\n>>> Dog.objects.filter(data__owner__other_pets__0__name='Fishy')\n<QuerySet [<Dog: Rufus>]>\nSi la clé avec laquelle vous souhaitez rechercher entre en conflit avec le nom d’une recherche existante, utilisez la recherche contains à la place.
Pour rechercher des clés manquantes, utilisez l’expression de recherche isnull:
>>> Dog.objects.create(name='Shep', data={'breed': 'collie'})\n<Dog: Shep>\n>>> Dog.objects.filter(data__owner__isnull=True)\n<QuerySet [<Dog: Shep>]>\ncontainsLien vers cette rubrique#La recherche contains est surchargée pour les champs JSONField. Les objets renvoyés sont ceux pour qui le dictionnaire de paires clé-valeur est totalement contenu au premier niveau du champ. Par exemple :
>>> Dog.objects.create(name='Rufus', data={'breed': 'labrador', 'owner': 'Bob'})\n<Dog: Rufus>\n>>> Dog.objects.create(name='Meg', data={'breed': 'collie', 'owner': 'Bob'})\n<Dog: Meg>\n>>> Dog.objects.create(name='Fred', data={})\n<Dog: Fred>\n>>> Dog.objects.filter(data__contains={'owner': 'Bob'})\n<QuerySet [<Dog: Rufus>, <Dog: Meg>]>\n>>> Dog.objects.filter(data__contains={'breed': 'collie'})\n<QuerySet [<Dog: Meg>]>\ncontained_byLien vers cette rubrique#Il s’agit de l’inverse de la recherche contains, les objets renvoyés sont ceux pour qui les paires de clé-valeur forment un sous-ensemble des valeurs transmises. Par exemple :
>>> Dog.objects.create(name='Rufus', data={'breed': 'labrador', 'owner': 'Bob'})\n<Dog: Rufus>\n>>> Dog.objects.create(name='Meg', data={'breed': 'collie', 'owner': 'Bob'})\n<Dog: Meg>\n>>> Dog.objects.create(name='Fred', data={})\n<Dog: Fred>\n>>> Dog.objects.filter(data__contained_by={'breed': 'collie', 'owner': 'Bob'})\n<QuerySet [<Dog: Meg>, <Dog: Fred>]>\n>>> Dog.objects.filter(data__contained_by={'breed': 'collie'})\n<QuerySet [<Dog: Fred>]>\nhas_keyLien vers cette rubrique#Renvoie les objets où la clé donnée se trouve au premier niveau des données. Par exemple :
\n>>> Dog.objects.create(name='Rufus', data={'breed': 'labrador'})\n<Dog: Rufus>\n>>> Dog.objects.create(name='Meg', data={'breed': 'collie', 'owner': 'Bob'})\n<Dog: Meg>\n>>> Dog.objects.filter(data__has_key='owner')\n<QuerySet [<Dog: Meg>]>\nhas_keysLien vers cette rubrique#Renvoie les objets où toutes les clés données se trouvent au premier niveau des données. Par exemple :
\n>>> Dog.objects.create(name='Rufus', data={'breed': 'labrador'})\n<Dog: Rufus>\n>>> Dog.objects.create(name='Meg', data={'breed': 'collie', 'owner': 'Bob'})\n<Dog: Meg>\n>>> Dog.objects.filter(data__has_keys=['breed', 'owner'])\n<QuerySet [<Dog: Meg>]>\nhas_any_keysLien vers cette rubrique#Renvoie les objets où au moins une des clés données se trouve au premier niveau des données. Par exemple :
\n>>> Dog.objects.create(name='Rufus', data={'breed': 'labrador'})\n<Dog: Rufus>\n>>> Dog.objects.create(name='Meg', data={'owner': 'Bob'})\n<Dog: Meg>\n>>> Dog.objects.filter(data__has_any_keys=['owner', 'breed'])\n<QuerySet [<Dog: Rufus>, <Dog: Meg>]>\nQLien vers cette rubrique#Les requêtes à paramètres nommés (dans filter(), etc.) sont combinées par AND (ET). 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.
Un objet Q (django.db.models.Q) est un objet utilisé pour englober plusieurs paramètre nommés. Ces paramètre nommés sont indiqués comme pour les « Recherches dans les champs » ci-dessus.
Par exemple, cet objet Q représente une seule requête LIKE:
from django.db.models import Q\nQ(question__startswith='What')\nLes objets Q peuvent être combinés à l’aide des opérateurs &, | et ^. Lorsqu’un opérateur est utilisé avec deux objets Q, cela produit un nouvel objet Q.
Par exemple, cette ligne produit un seul objet Q représentant la combinaison par « OR » de deux requêtes "question__startswith":
Q(question__startswith='Who') | Q(question__startswith='What')\nC’est équivalent à la clause SQL WHERE ci-dessous :
WHERE question LIKE 'Who%' OR question LIKE 'What%'\nVous pouvez composer des instructions de complexité arbitraire en combinant des objets Q avec les opérateurs &, | et ^ et en les groupant par des parenthèses. De même, les objets Q peuvent être inversés par l’opérateur de négation ~, permettant à des requêtes combinées d’utiliser à la fois des requêtes normales et des requêtes inversées (NOT) :
Q(question__startswith='Who') | ~Q(pub_date__year=2005)\nChaque fonction de recherche acceptant des paramètres nommés (par ex. filter(), exclude(), get()) peut aussi recevoir un ou plusieurs objets Q comme paramètre positionnel (non nommé). Si vous indiquez plusieurs objets Q comme paramètres d’une fonction de recherche, les paramètres seront combinés avec « AND ». Par exemple :
Poll.objects.get(\n Q(question__startswith='Who'),\n Q(pub_date=date(2005, 5, 2)) | Q(pub_date=date(2005, 5, 6))\n)\n… se traduit grossièrement en SQL par :
\nSELECT * from polls WHERE question LIKE 'Who%'\n AND (pub_date = '2005-05-02' OR pub_date = '2005-05-06')\nLes fonctions de recherche peuvent mélanger l’utilisation d’objets Q et de paramètres nommés. Tous les paramètres fournis à une fonction de recherche (que ce soit des paramètres nommés ou des objets Q) sont combinés par l’opérateur « AND ». Cependant, si un objet Q est fourni, il doit précéder toute définition de paramètre nommé. Par exemple :
Poll.objects.get(\n Q(pub_date=date(2005, 5, 2)) | Q(pub_date=date(2005, 5, 6)),\n question__startswith='Who',\n)\n… correspond à une requête valable, équivalente à l’exemple précédent ; mais :
\n# INVALID QUERY\nPoll.objects.get(\n question__startswith='Who',\n Q(pub_date=date(2005, 5, 2)) | Q(pub_date=date(2005, 5, 6))\n)\n… n’est pas correct.
\n\n\nPour comparer deux instances de modèle, utilisez l’opérateur de comparaison standard de Python, le double signe égal : ==. En arrière-plan, ce sont les valeurs clés primaires des deux modèles qui sont comparées.
En utilisant l’exemple Entry ci-dessus, les deux instructions suivantes sont équivalentes :
>>> some_entry == other_entry\n>>> some_entry.id == other_entry.id\nSi la clé primaire d’un modèle ne s’appelle pas id, aucun problème. Les comparaisons utilisent toujours la clé primaire, quel que soit son nom. Par exemple, si un champ clé primaire d’un modèle s’appelle name, ces deux lignes sont équivalentes :
>>> some_obj == other_obj\n>>> some_obj.name == other_obj.name\nLa méthode de suppression se nomme delete(). Cette méthode supprime immédiatement l’objet et renvoie le nombre d’objets supprimés ainsi qu’un dictionnaire avec le nombre de suppressions par type d’objet. Exemple :
>>> e.delete()\n(1, {'blog.Entry': 1})\nIl est aussi possible de supprimer des objets groupés. Chaque QuerySet comporte une méthode delete() qui supprime tous les objets contenus dans l’objet QuerySet.
Par exemple, cette commande supprime tous les objets Entry dont l’année de pub_date est 2005 :
>>> Entry.objects.filter(pub_date__year=2005).delete()\n(5, {'webapp.Entry': 5})\nSachez toutefois que cette opération sera autant que possible exécutée purement au niveau SQL, ce qui signifie que les méthodes delete() des instances individuelles ne seront pas forcément appelées durant le processus. Si vous avez écrit une méthode delete() personnalisée dans une classe de modèle et que vous voulez être certain qu’elle soit appelée, vous devrez supprimer « manuellement » les instances de ce modèle (par ex. en itérant sur un objet QuerySet et en appelant explicitement delete() sur chaque instance) plutôt que d’employer la méthode de suppression groupée delete() de l’objet QuerySet.
Lorsque Django supprime un objet, il émule par défaut le comportement de la contrainte SQL ON DELETE CASCADE. En d’autres termes, tout objet possédant des clés étrangères vers l’objet en cours de suppression seront également supprimés. Par exemple :
b = Blog.objects.get(pk=1)\n# This will delete the Blog and all of its Entry objects.\nb.delete()\nCe comportement en cascade peut être personnalisé au moyen du paramètre on_delete de la classe ForeignKey.
Notez que delete() est la seule méthode de QuerySet qui n’est pas exposée sur un objet Manager. Il s’agit d’un mécanisme de sécurité pour vous empêcher d’exécuter accidentellement Entry.objects.delete() ce qui supprimerait toutes les lignes. Si vous souhaitez vraiment supprimer tous les objets, vous devez alors indiquer explicitement une requête contenant tous les objets :
Entry.objects.all().delete()\nMême s’il n’existe pas de méthode intégrée pour la copie d’instances de modèles, il est possible de créer facilement de nouvelles instances en copiant toutes les valeurs des champs d’une autre instance. Dans le cas le plus simple, on peut définir pk à None et _state.adding to True. En utilisant notre exemple de blogue :
blog = Blog(name='My blog', tagline='Blogging is easy')\nblog.save() # blog.pk == 1\n\nblog.pk = None\nblog._state.adding = True\nblog.save() # blog.pk == 2\nLes choses se compliquent lorsqu’il y a de l’héritage. Considérons une sous-classe de Blog:
class ThemeBlog(Blog):\n theme = models.CharField(max_length=200)\n\ndjango_blog = ThemeBlog(name='Django', tagline='Django is easy', theme='python')\ndjango_blog.save() # django_blog.pk == 3\nEn raison du fonctionnement de l’héritage, vous devez définir à None à la fois pk et id, ainsi que _state.adding à True:
django_blog.pk = None\ndjango_blog.id = None\ndjango_blog._state.adding = True\ndjango_blog.save() # django_blog.pk == 4\nCe processus ne copie pas les relations ne faisant pas partie de la table de base de données du modèle. Par exemple, Entry possède un champ ManyToManyField vers Author. Après avoir dupliqué un objet « entry », vous devez définir les relations plusieurs-à-plusieurs vers le nouvel objet :
entry = Entry.objects.all()[0] # some previous entry\nold_authors = entry.authors.all()\nentry.pk = None\nentry._state.adding = True\nentry.save()\nentry.authors.set(old_authors)\nPour un champ OneToOneField, vous devez dupliquer l’objet lié et l’attribuer au champ correspondant du nouvel objet pour éviter la rupture de la contrainte unique du champ un-à-un. Par exemple, en supposant que entry a déjà été dupliqué comme ci-dessus :
detail = EntryDetail.objects.all()[0]\ndetail.pk = None\ndetail._state.adding = True\ndetail.entry = entry\ndetail.save()\nIl peut arriver que vous souhaitiez définir la valeur d’un certain champ pour tous les objets d’un QuerySet. C’est faisable à l’aide de la méthode update(). Par exemple :
# Update all the headlines with pub_date in 2007.\nEntry.objects.filter(pub_date__year=2007).update(headline='Everything is the same')\nSeuls les champs qui ne sont pas des relations et les champs ForeignKey peuvent être mis à jour avec cette méthode. Pour mettre à jour un champ qui ne représente pas une relation, indiquez la nouvelle valeur sous forme de constante. Pour mettre à jour un champ ForeignKey, indiquez la nouvelle valeur sous forme d’une instance de modèle vers laquelle le champ devra pointer. Par exemple :
>>> b = Blog.objects.get(pk=1)\n\n# Change every Entry so that it belongs to this Blog.\n>>> Entry.objects.update(blog=b)\nLa méthode update() est appliquée immédiatement et renvoie le nombre de lignes correspondant à la requête (ce qui ne correspond pas toujours au nombre de lignes mises à jour si certaines lignes ont déjà la bonne valeur). La seule restriction sur l’objet QuerySet mis à jour est qu’il ne peut accéder qu’à une seule table de base de données, la table principale du modèle. Vous pouvez filtrer selon des champs liés, mais vous ne pouvez mettre à jour des colonnes que dans la table principale du modèle. Exemple :
>>> b = Blog.objects.get(pk=1)\n\n# Update all the headlines belonging to this Blog.\n>>> Entry.objects.filter(blog=b).update(headline='Everything is the same')\nSoyez conscient que la méthode update() est directement convertie en instruction SQL. Il s’agit d’une opération groupée pour des mises à jour directes. Elle ne fait appel à aucune méthode save() des modèles, n’émet aucun signal pre_save ou post_save (qui sont des conséquences de l’appel à save()) et ne respecte pas l’option de champ auto_now. Si vous souhaitez enregistrer chaque élément d’un objet QuerySet tout en garantissant que la méthode save() de chaque instance est appelée, vous n’avez pas besoin d’une fonction particulière pour cela. Effectuez une boucle et appelez save() pour chaque objet :
for item in my_queryset:\n item.save()\nLes appels à update peuvent aussi utiliser les expressions F pour mettre à jour un champ en fonction de la valeur d’un autre champ du modèle. C’est particulièrement utile pour incrémenter des compteurs en fonction de leur valeur actuelle. Par exemple, pour incrémenter le nombre de pings de chaque article d’un blogue :
>>> Entry.objects.update(number_of_pingbacks=F('number_of_pingbacks') + 1)\nCependant, au contraire des objets F() dans les clauses filter() et exclude(), il n’est pas autorisé d’introduire des jointures lors de l’utilisation de F() dans des mises à jour ; seuls des champs du modèle en cours de mise à jour peuvent être référencés. Si vous essayez d’introduire une jointure avec un objet F(), une erreur FieldError sera générée :
# This will raise a FieldError\n>>> Entry.objects.update(headline=F('blog__name'))\nSi vous rencontrez le besoin de devoir écrire une requête SQL trop complexe pour l’abstraction de base de données de Django, il peut être nécessaire d’écrire le code SQL à la main. Django offre quelques options pour l’écriture de requêtes SQL brutes ; voir Lancement de requêtes SQL brutes.
\nFinalement, il est important de noter que la couche de base de données de Django n’est qu’une interface vers votre base de données. Vous pouvez accéder à votre base de données par d’autres outils, langages de programmation ou environnements de base de données ; il n’y a rien de spécifique à Django en ce qui concerne la base de données.
\n