Référence de l’API QuerySetLien vers cette rubrique#

filter()Lien vers cette rubrique#

filter(*args, **kwargs)Lien vers cette définition#

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.

If you need to execute more complex queries (for example, queries with OR statements), you can use Objets Q() (*args).

exclude()Lien vers cette rubrique#

exclude(*args, **kwargs)Lien vers cette définition#

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")

En termes SQL, cela donne :

SELECT ...
WHERE NOT (pub_date > '2005-1-3' AND headline = 'Hello')

Cet 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")

En termes SQL, cela donne :

SELECT ...
WHERE NOT pub_date > '2005-1-3'
AND NOT headline = 'Hello'

Notez que le second exemple est plus restrictif.

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).

annotate()Lien vers cette rubrique#

annotate(*args, **kwargs)Lien vers cette définition#

Annotates each object in the QuerySet with the provided list of query expressions or Objets Q(). Each object can be annotated with:

• une valeur simple, via Value() ;

• une référence à un champ du modèle (ou tout modèle lié), via F() ;

• une valeur booléenne, via Q() ; ou

• un résultat d’un expression d’agrégat (moyennes, sommes, etc.) calculée sur les objets qui sont liés aux 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.

Les 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é.

Par 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 :

>>> from django.db.models import Count
>>> q = Blog.objects.annotate(Count("entry"))
# The name of the first blog
>>> q[0].name
'Blogasaurus'
# The number of entries on the first blog
>>> q[0].entry__count
42

Le 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"))
# The number of entries on the first blog, using the name provided
>>> q[0].number_of_entries
42

Pour une présentation approfondie de l’agrégation, consultez le guide thématique sur l’agrégation.

alias()Lien vers cette rubrique#

alias(*args, **kwargs)Lien vers cette définition#

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 :

>>> from django.db.models import Count
>>> blogs = Blog.objects.alias(entries=Count("entry")).filter(entries__gt=5)

alias() can be used in conjunction with annotate(), exclude(), filter(), order_by(), and update(). To use an aliased expression with other methods (e.g. aggregate()), you must promote it to an annotation:

Blog.objects.alias(entries=Count("entry")).annotate(
    entries=F("entries"),
).aggregate(Sum("entries"))

filter() and order_by() can take expressions directly, but expression construction and usage often does not happen in the same place (for example, QuerySet method creates expressions, for later use in views). alias() allows building complex expressions incrementally (possibly spanning multiple methods and modules), referring to the expression parts by their aliases, and only using annotate() for the final result.

order_by()Lien vers cette rubrique#

order_by(*fields)Lien vers cette définition#

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 :

Entry.objects.filter(pub_date__year=2005).order_by("-pub_date", "headline")

Les 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("?")

Note : 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")

Si 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")

… est identique à :

Entry.objects.order_by("blog__id")

Si Blog comportait ordering = ['name'], alors le premier jeu de requête serait identique à :

Entry.objects.order_by("blog__name")

Il 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())

asc() 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.

Vous 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())

Si 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")

reverse()Lien vers cette rubrique#

reverse()Lien vers cette définition#

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 :

my_queryset.reverse()[:5]

Notez 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#

distinct(*fields)Lien vers cette définition#

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) :

>>> Author.objects.distinct()
<QuerySet [...]>
>>> Entry.objects.order_by("pub_date").distinct("pub_date")
<QuerySet [...]>
>>> Entry.objects.order_by("blog").distinct("blog")
<QuerySet [...]>
>>> Entry.objects.order_by("author", "pub_date").distinct("author", "pub_date")
<QuerySet [...]>
>>> Entry.objects.order_by("blog__name", "mod_date").distinct("blog__name", "mod_date")
<QuerySet [...]>
>>> Entry.objects.order_by("author", "pub_date").distinct("author")
<QuerySet [...]>

values()Lien vers cette rubrique#

values(*fields, **expressions)Lien vers cette définition#

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.

Cet exemple compare les dictionnaires de values() avec des objets de modèle normaux :

# This list contains a Blog object.
>>> Blog.objects.filter(name__startswith="Beatles")
<QuerySet [<Blog: Beatles Blog>]>

# This list contains a dictionary.
>>> Blog.objects.filter(name__startswith="Beatles").values()
<QuerySet [{'id': 1, 'name': 'Beatles Blog', 'tagline': 'All the latest Beatles news.'}]>

La 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 :

>>> Blog.objects.values()
<QuerySet [{'id': 1, 'name': 'Beatles Blog', 'tagline': 'All the latest Beatles news.'}]>
>>> Blog.objects.values("id", "name")
<QuerySet [{'id': 1, 'name': 'Beatles Blog'}]>

La méthode values() accepte également des paramètres nommés facultatifs, **expressions, qui sont transmis par annotate():

>>> from django.db.models.functions import Lower
>>> Blog.objects.values(lower_name=Lower("name"))
<QuerySet [{'lower_name': 'beatles blog'}]>

Vous pouvez utiliser les requêtes intégrées ou personnalisées dans les tris. Par exemple :

>>> from django.db.models import CharField
>>> from django.db.models.functions import Lower
>>> CharField.register_lookup(Lower)
>>> Blog.objects.values("name__lower")
<QuerySet [{'name__lower': 'beatles blog'}]>

Une 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
>>> Blog.objects.values("entry__authors", entries=Count("entry"))
<QuerySet [{'entry__authors': 1, 'entries': 20}, {'entry__authors': 1, 'entries': 13}]>
>>> Blog.objects.values("entry__authors").annotate(entries=Count("entry"))
<QuerySet [{'entry__authors': 1, 'entries': 33}]>

Quelques subtilités qui valent la peine d’être mentionnées :

• Si 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 :

  Python console

  >>> Entry.objects.values()
  <QuerySet [{'blog_id': 1, 'headline': 'First Entry', ...}, ...]>
  
  >>> Entry.objects.values("blog")
  <QuerySet [{'blog': 1}, ...]>
  
  >>> Entry.objects.values("blog_id")
  <QuerySet [{'blog_id': 1}, ...]>
  

• Lors 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 :

  Python console

  >>> from django.db.models import CharField, Count
  >>> from django.db.models.functions import Lower
  >>> CharField.register_lookup(Lower)
  >>> Blog.objects.values("entry__authors__name__lower").annotate(entries=Count("entry"))
  <QuerySet [{'entry__authors__name__lower': 'test author', 'entries': 33}]>
  >>> Blog.objects.values(entry__authors__name__lower=Lower("entry__authors__name")).annotate(
  ...     entries=Count("entry")
  ... )
  <QuerySet [{'entry__authors__name__lower': 'test author', 'entries': 33}]>
  >>> Blog.objects.annotate(entry__authors__name__lower=Lower("entry__authors__name")).values(
  ...     "entry__authors__name__lower"
  ... ).annotate(entries=Count("entry"))
  <QuerySet [{'entry__authors__name__lower': 'test author', 'entries': 33}]>
  

C’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.

Enfin, 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")
Blog.objects.order_by("id").values()

Les 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")
<QuerySet [{'name': 'My blog', 'entry__headline': 'An entry'},
     {'name': 'My blog', 'entry__headline': 'Another entry'}, ...]>

values_list()Lien vers cette rubrique#

values_list(*fields, flat=False, named=False)Lien vers cette définition#

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")
<QuerySet [(1, 'First entry'), ...]>
>>> from django.db.models.functions import Lower
>>> Entry.objects.values_list("id", Lower("headline"))
<QuerySet [(1, 'first entry'), ...]>

Si 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 à un seul élément. Cet exemple devrait éclairer la différence :

>>> Entry.objects.values_list("id").order_by("id")
<QuerySet[(1,), (2,), (3,), ...]>

>>> Entry.objects.values_list("id", flat=True).order_by("id")
<QuerySet [1, 2, 3, ...]>

C’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)
<QuerySet [Row(id=1, headline='First entry'), ...]>

L’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é.

Si 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)
'First entry'

values() 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")
<QuerySet [('Noam Chomsky', 'Impressions of Gaza'),
 ('George Orwell', 'Why Socialists Do Not Believe in Fun'),
 ('George Orwell', 'In Defence of English Cooking'),
 ('Don Quixote', None)]>

Les 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")
<QuerySet [('Noam Chomsky',), ('George Orwell',), (None,)]>

dates()Lien vers cette rubrique#

dates(field, kind, order='ASC')Lien vers cette définition#

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 :

>>> Entry.objects.dates("pub_date", "year")
[datetime.date(2005, 1, 1)]
>>> Entry.objects.dates("pub_date", "month")
[datetime.date(2005, 2, 1), datetime.date(2005, 3, 1)]
>>> Entry.objects.dates("pub_date", "week")
[datetime.date(2005, 2, 14), datetime.date(2005, 3, 14)]
>>> Entry.objects.dates("pub_date", "day")
[datetime.date(2005, 2, 20), datetime.date(2005, 3, 20)]
>>> Entry.objects.dates("pub_date", "day", order="DESC")
[datetime.date(2005, 3, 20), datetime.date(2005, 2, 20)]
>>> Entry.objects.filter(headline__contains="Lennon").dates("pub_date", "day")
[datetime.date(2005, 3, 20)]

datetimes()Lien vers cette rubrique#

datetimes(field_name, kind, order='ASC', tzinfo=None)Lien vers cette définition#

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.

none()Lien vers cette rubrique#

none()Lien vers cette définition#

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 :

>>> Entry.objects.none()
<QuerySet []>
>>> from django.db.models.query import EmptyQuerySet
>>> isinstance(Entry.objects.none(), EmptyQuerySet)
True

all()Lien vers cette rubrique#

all()Lien vers cette définition#

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#

union(*other_qs, all=False)Lien vers cette définition#

Utilise l’opérateur SQL UNION pour combiner les résultats de deux QuerySet ou plus. Par exemple :

>>> qs1.union(qs2, qs3)

L’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")
>>> qs2 = Entry.objects.values_list("headline")
>>> qs1.union(qs2).order_by("name")

De 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#

intersection(*other_qs)Lien vers cette définition#

Utilise l’opérateur SQL INTERSECT pour renvoyer les éléments communs à deux ou plusieurs QuerySet. Par exemple :

>>> qs1.intersection(qs2, qs3)

Voir union() concernant quelques restrictions.

difference()Lien vers cette rubrique#

difference(*other_qs)Lien vers cette définition#

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)

Voir union() concernant quelques restrictions.

fetch_mode()Lien vers cette rubrique#

fetch_mode(mode)Lien vers cette définition#

Returns a QuerySet that sets the given fetch mode for all model instances created by this QuerySet. The fetch mode controls on-demand loading of fields when they are accessed, such as for foreign keys and deferred fields. For example, to use the FETCH_PEERS mode to batch-load all related objects on first access:

from django.db import models

books = Book.objects.fetch_mode(models.FETCH_PEERS)

See more in the fetch mode topic guide.

select_related()Lien vers cette rubrique#

select_related(*fields)Lien vers cette définition#

Returns a QuerySet that will join in the named foreign-key relationships, selecting additional related objects when it executes its query. This method can be a performance booster, fetching data ahead of time rather than triggering on-demand loading through the model instances” fetch mode, at the cost of a more complex initial query.

Les exemples suivants illustrent la différence entre les requêtes simples et les requêtes select_related(). Voici la requête standard :

# Hits the database.
e = Entry.objects.get(id=5)

# Hits the database again to get the related Blog object.
b = e.blog

Et voici la requête select_related:

# Hits the database.
e = Entry.objects.select_related("blog").get(id=5)

# Doesn't hit the database, because e.blog has been prepopulated
# in the previous query.
b = e.blog

You can use select_related() with any queryset. The order of chaining with other methods isn’t important. For example, these querysets are equivalent:

Entry.objects.filter(pub_date__gt=timezone.now()).select_related("blog")
Entry.objects.select_related("blog").filter(pub_date__gt=timezone.now())

Vous pouvez suivre les clés étrangères de la même manière que dans les requêtes. Si vous avez les modèles suivants :

from django.db import models


class City(models.Model):
    # ...
    pass


class Person(models.Model):
    # ...
    hometown = models.ForeignKey(
        City,
        on_delete=models.SET_NULL,
        blank=True,
        null=True,
    )


class Book(models.Model):
    # ...
    author = models.ForeignKey(Person, on_delete=models.CASCADE)

Alors un appel à Book.objects.select_related('author__hometown').get(id=4) mettra en cache l’objet Person lié et l’objet City lié :

# Hits the database with joins to the author and hometown tables.
b = Book.objects.select_related("author__hometown").get(id=4)
p = b.author  # Doesn't hit the database.
c = p.hometown  # Doesn't hit the database.

# Without select_related()...
b = Book.objects.get(id=4)  # Hits the database.
p = b.author  # Hits the database.
c = p.hometown  # Hits the database.

Vous pouvez faire référence à toute relation ForeignKey ou OneToOneField dans la liste des champs transmis à select_related().

Il est également possible de se référer à la liaison inverse d’un champ OneToOneField dans la liste des champs transmis à select_related — c’est-à-dire qu’il est possible d’accéder à un champ OneToOneField depuis les deux côtés de la relation, et non seulement depuis l’objet dans lequel il est défini. Au lieu d’indiquer le nom du champ, il faut alors utiliser le nom related_name du champ à partir de l’objet lié.

Si vous avez besoin d’effacer la liste des champs liés ajoutée par de précédents appels à select_related sur un QuerySet, vous pouvez passer None comme paramètre :

>>> without_relations = queryset.select_related(None)

L’enchaînement d’appels à select_related fonctionne de manière semblable à d’autres méthodes, c’est-à-dire que select_related('foo', 'bar') est équivalent à select_related('foo').select_related('bar').

Dans certaines situations, il peut être souhaitable d’appeler select_related() avec beaucoup d’objets liés ou avec des relations qu’on ne connaît pas d’avance. Dans ce cas, il est possible d’appeler select_related() sans paramètre. Toutes les relations de clé étrangère non nulles seront suivies, mais les clés étrangères pouvant être nulles doivent être indiquées explicitement. Ce n’est pas recommandé dans la plupart des cas car par rapport aux besoins réels, la requête sous-jacente sera certainement plus complexe et les données récupérées plus nombreuses.

prefetch_related()Lien vers cette rubrique#

prefetch_related(*lookups)Lien vers cette définition#

Returns a QuerySet that will automatically retrieve the given lookups, each in one extra batch query. Prefetching is a way to optimize database access when you know you’ll be accessing related objects later, so you can avoid triggering the on-demand loading behavior of the model instances” fetch mode.

This method has a similar purpose to select_related(), in that both are designed to eagerly fetch related objects. However, they work in different ways.

select_related fonctionne en créant une jointure SQL et en incluant les champs de l’objet lié dans l’instruction SELECT. Pour cette raison, select_related récupère les objets liés dans la même requête de base de données. Cependant, pour éviter le jeu de requête bien plus grand qui résulterait de jointures par des liaisons « plusieurs », select_related se limite aux relations univaluées, les clés étrangères et les liaisons un-à-un.

prefetch_related, de son côté, effectue une requête séparée pour chaque relation et procède à la réconciliation des données dans le code Python. Cela lui permet de précharger les objets plusieurs-à-plusieurs, plusieurs-à-un et GenericRelation, ce qui n’est pas possible avec select_related, en plus des liaisons de clé étrangère et un-à-un qui sont prises en charge par select_related. Il permet également de précharger les liaisons GenericForeignKey, cependant, le jeu de requête de chaque type ContentType doit être fourni dans le paramètre querysets de GenericPrefetch.

Par exemple, supposons que vous ayez ces modèles :

from django.db import models


class Topping(models.Model):
    name = models.CharField(max_length=30)


class Pizza(models.Model):
    name = models.CharField(max_length=50)
    toppings = models.ManyToManyField(Topping)

    def __str__(self):
        return "%s (%s)" % (
            self.name,
            ", ".join(topping.name for topping in self.toppings.all()),
        )

et que vous exécutez :

>>> Pizza.objects.all()
<QuerySet [<Pizza: Hawaiian (ham, pineapple)>, <Pizza: Seafood (prawns, smoked salmon)>, ...]>

Le problème de ce code est que chaque fois que Pizza.__str__() fait appel à self.toppings.all(), il doit interroger la base de données, ce qui fait que Pizza.objects.all() lance une requête sur la table Toppings pour chaque objet du QuerySet des pizzas.

Nous pouvons réduire cela à deux seules requêtes en utilisant prefetch_related:

>>> Pizza.objects.prefetch_related("toppings")

Cette syntaxe sous-entend que self.toppings.all() est demandé pour chaque Pizza; dès cet instant, chaque fois que self.toppings.all() est appelé, au lieu de recourir à la base de données pour obtenir les objets, Django les retrouve dans un QuerySet préchargé en cache qui a été rempli par une seule requête.

C’est-à-dire que tous les Toppings appropriés auront été récupérés par une seule requête et qu’ils auront été utilisés pour créer des instances QuerySet dont le cache est prérempli par les résultats appropriés ; ces instances sont ensuite exploitées lors des appels à self.toppings.all().

Les requêtes supplémentaires dans prefetch_related() sont exécutées après que le QuerySet a commencé à être évalué et que la requête de base a été exécutée.

Notez qu’il n’existe aucun mécanisme pour empêcher une autre requête de base de données de modifier les éléments entre l’exécution de la requête principale et les requêtes supplémentaires, ce qui pourrait conduire à un résultat incohérent. Par exemple, si une Pizza est supprimée après que la requête principale a été exécutée, ses garnitures ne seront pas renvoyées dans la requête supplémentaire et il pourrait sembler que la pizza n’a pas de garniture.

>>> Pizza.objects.prefetch_related("toppings")
#  "Hawaiian" Pizza was deleted in another shell.
<QuerySet [<Pizza: Hawaiian ()>, <Pizza: Seafood (prawns, smoked salmon)>]>

Si vous disposez d’une série d’instances de modèles, vous pouvez précharger les attributs liés de ces instances en utilisant la fonction prefetch_related_objects().

Notez que le cache des résultats du QuerySet principal et tous les objets liés visés sera alors complètement chargé en mémoire. Cela change du comportement habituel de l’objet QuerySet qui essaie autant que possible de ne pas charger tous les objets en mémoire tant qu’ils ne sont pas nécessaires, même après qu’une première requête a été exécutée en base de données.

Il est aussi possible d’utiliser la syntaxe de jointure normale pour se référer à des champs liés de champs liés. Supposons qu’un modèle supplémentaire est ajouté à l’exemple précédent :

class Restaurant(models.Model):
    pizzas = models.ManyToManyField(Pizza, related_name="restaurants")
    best_pizza = models.ForeignKey(
        Pizza, related_name="championed_by", on_delete=models.CASCADE
    )

Toutes les expressions suivantes sont admises :

>>> Restaurant.objects.prefetch_related("pizzas__toppings")

Cela va précharger toutes les pizzas appartenant aux restaurants ainsi que toutes les garnitures (toppings) de ces pizzas. Au total, 3 requêtes de base de données seront générées : une pour les restaurants, une pour les pizzas et une pour les garnitures.

>>> Restaurant.objects.prefetch_related("best_pizza__toppings")

Cette requête récupère la meilleure pizza et toutes les garnitures de la meilleure pizza de chaque restaurant. Cela se fera en 3 requêtes de base de données, une pour les restaurants, une pour les « meilleures pizzas » et une pour les garnitures.

La relation best_pizza pourrait aussi être récupérée par select_related pour réduire le nombre de requêtes à 2 :

>>> Restaurant.objects.select_related("best_pizza").prefetch_related("best_pizza__toppings")

Comme le préchargement a lieu après la requête principale (qui inclut les jointures requises par select_related), il est capable de détecter que les objets best_pizza ont déjà été récupérés, et il évitera de les récupérer une fois de plus.

L’enchaînement d’appels à prefetch_related accumule les liaisons à précharger. Pour effacer tout comportement lié à prefetch_related, passez None en paramètre :

>>> non_prefetched = qs.prefetch_related(None)

Une différence à signaler lors de l’utilisation de prefetch_related est que les objets créés par une requête peuvent être partagés entre les différents objets auxquels ils sont liés, c’est-à-dire qu’une même instance de modèle Python peut apparaître à plus d’un endroit dans l’arborescence des objets renvoyés. Cela se produit normalement avec les relations de clé étrangère. Ce comportement ne pose généralement pas de problème et permet d’économiser à la fois de la mémoire et du temps processeur.

Même si prefetch_related prend en charge le préchargement des relations GenericForeignKey, le nombre de requêtes dépend des données. Comme un champ GenericForeignKey peut référencer des données de tables différentes, il sera nécessaire d’effectuer une requête par table référencée, au lieu d’une seule requête pour tous les éléments. Il pourrait aussi y avoir des requêtes supplémentaires pour la table ContentType si les lignes concernées n’ont pas déjà été obtenues.

Dans la plupart des cas, prefetch_related est implémenté par une requête SQL utilisant l’opérateur « IN ». Cela implique que pour un grand QuerySet, cela peut générer une grande clause « IN », ce qui, en fonction de la base de données, peut poser en soi des problèmes de performance au moment d’analyser ou d’exécuter la requête SQL. Évaluez toujours les performances en fonction de votre cas d’utilisation !

Si vous utilisez iterator() pour exécuter la requête, les appels à prefetch_related() ne seront respectés que si une valeur est fournie pour chunk_size.

Vous pouvez utiliser l’objet Prefetch pour contrôler de manière plus fine l’opération de préchargement.

Dans sa forme la plus simple, Prefetch est équivalent aux recherches traditionnelles basées sur les chaînes :

>>> from django.db.models import Prefetch
>>> Restaurant.objects.prefetch_related(Prefetch("pizzas__toppings"))

Vous pouvez préciser un jeu de requête personnalisé par le paramètre facultatif queryset. Cela peut par exemple être utilisé pour modifier l’ordre de tri par défaut du jeu de requête :

>>> Restaurant.objects.prefetch_related(
...     Prefetch("pizzas__toppings", queryset=Toppings.objects.order_by("name"))
... )

Ou pour appeler select_related() lorsque c’est nécessaire afin de réduire encore plus le nombre de requêtes :

>>> Pizza.objects.prefetch_related(
...     Prefetch("restaurants", queryset=Restaurant.objects.select_related("best_pizza"))
... )

Vous pouvez aussi attribuer le résultat du préchargement à un attribut personnalisé au moyen du paramètre facultatif to_attr. Le résultat sera directement stocké dans une liste.

Cela permet de précharger plusieurs fois la même relation avec un QuerySet différent ; par exemple :

>>> vegetarian_pizzas = Pizza.objects.filter(vegetarian=True)
>>> Restaurant.objects.prefetch_related(
...     Prefetch("pizzas", to_attr="menu"),
...     Prefetch("pizzas", queryset=vegetarian_pizzas, to_attr="vegetarian_menu"),
... )

Les recherches créées avec un paramètre to_attr personnalisé peuvent toujours être traversées comme de coutume par d’autres recherches :

>>> vegetarian_pizzas = Pizza.objects.filter(vegetarian=True)
>>> Restaurant.objects.prefetch_related(
...     Prefetch("pizzas", queryset=vegetarian_pizzas, to_attr="vegetarian_menu"),
...     "vegetarian_menu__toppings",
... )

L’utilisation de to_attr est recommandée lors d’un filtrage restrictif du résultat préchargé car c’est moins ambigu que de stocker un résultat filtré dans le cache du gestionnaire de liaison :

>>> queryset = Pizza.objects.filter(vegetarian=True)
>>>
>>> # Recommended:
>>> restaurants = Restaurant.objects.prefetch_related(
...     Prefetch("pizzas", queryset=queryset, to_attr="vegetarian_pizzas")
... )
>>> vegetarian_pizzas = restaurants[0].vegetarian_pizzas
>>>
>>> # Not recommended:
>>> restaurants = Restaurant.objects.prefetch_related(
...     Prefetch("pizzas", queryset=queryset),
... )
>>> vegetarian_pizzas = restaurants[0].pizzas.all()

Le préchargement personnalisé fonctionne aussi avec des liaisons avant simples telles que des relations ForeignKey ou OneToOneField. Généralement, il faut plutôt utiliser select_related() pour de telles relations, mais il existe certaines situations où le préchargement avec un jeu QuerySet personnalisé est utile :

• Vous souhaitez utiliser un QuerySet qui effectue lui aussi un préchargement sur des modèles liés.

• Vous souhaitez précharger uniquement un sous-ensemble d’objets liés.

• You want to use performance optimization techniques like deferring fields, for example, via defer() or only():

  Python console

  >>> queryset = Pizza.objects.only("name")
  >>>
  >>> restaurants = Restaurant.objects.prefetch_related(
  ...     Prefetch("best_pizza", queryset=queryset)
  ... )
  

Lors de l’utilisation de plusieurs bases de données, Prefetch respecte votre choix de base de données. Si la requête interne ne suggère pas de base de données, ce sera la base de données choisie pour la requête externe qui sera utilisée. Toutes les expressions suivantes sont valables :

>>> # Both inner and outer queries will use the 'replica' database
>>> Restaurant.objects.prefetch_related("pizzas__toppings").using("replica")
>>> Restaurant.objects.prefetch_related(
...     Prefetch("pizzas__toppings"),
... ).using("replica")
>>>
>>> # Inner will use the 'replica' database; outer will use 'default' database
>>> Restaurant.objects.prefetch_related(
...     Prefetch("pizzas__toppings", queryset=Toppings.objects.using("replica")),
... )
>>>
>>> # Inner will use 'replica' database; outer will use 'cold-storage' database
>>> Restaurant.objects.prefetch_related(
...     Prefetch("pizzas__toppings", queryset=Toppings.objects.using("replica")),
... ).using("cold-storage")

extra()Lien vers cette rubrique#

extra(select=None, where=None, params=None, tables=None, order_by=None, select_params=None)Lien vers cette définition#

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 :

  Code

  Entry.objects.extra(select={"is_recent": "pub_date > '2006-01-01'"})
  

  Avec 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 :

  SQL

  SELECT blog_entry.*, (pub_date > '2006-01-01') AS is_recent
  FROM blog_entry;
  

  L’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 :

  Code

  Blog.objects.extra(
      select={
          "entry_count": "SELECT COUNT(*) FROM blog_entry WHERE blog_entry.blog_id = blog_blog.id"
      },
  )
  

  Dans 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 :

  SQL

  SELECT blog_blog.*, (SELECT COUNT(*) FROM blog_entry WHERE blog_entry.blog_id = blog_blog.id) AS entry_count
  FROM blog_blog;
  

  Notez 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.

  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 :

  Code

  Blog.objects.extra(
      select={"a": "%s", "b": "%s"},
      select_params=("one", "two"),
  )
  

  Si 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 :

  Code

  Entry.objects.extra(where=["foo='a' OR bar = 'a'", "baz = 'a'"])
  

  …peut être (grossièrement) traduit en code SQL comme :

  SQL

  SELECT * FROM blog_entry WHERE (foo='a' OR bar='a') AND (baz='a')
  

  Soyez 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 :

  Code

  q = Entry.objects.extra(select={"is_recent": "pub_date > '2006-01-01'"})
  q = q.extra(order_by=["-is_recent"])
  

  Ce 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 :

  Code

  Entry.objects.extra(where=["headline=%s"], params=["Lennon"])
  

  Utilisez 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 :

  Code

  Entry.objects.extra(where=["headline='Lennon'"])
  

  Juste :

  Code

  Entry.objects.extra(where=["headline=%s"], params=["Lennon"])
  

defer()Lien vers cette rubrique#

defer(*fields)Lien vers cette définition#

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.

Ceci se fait en indiquant les noms des champs à ne pas charger dans defer():

Entry.objects.defer("headline", "body")

Un 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).

On 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.
Entry.objects.defer("body").filter(rating=5).defer("headline")

L’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")

Si vous souhaitez effacer l’ensemble des champs différés, indiquez None comme paramètre à defer():

# Load all fields immediately.
my_queryset.defer(None)

Certains 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.

De même, l’appel à defer() (ou à sa contrepartie only()) incluant un argument provenant d’une agrégation (par ex. un résultat de annotate()) ne fait pas de sens : une exception sera alors produite. Les valeurs agrégées seront toujours récupérées dans le jeu de requête résultant.

only()Lien vers cette rubrique#

only(*fields)Lien vers cette définition#

La méthode only() est essentiellement l’inverse de defer(). Seuls les champs passés à cette méthode et qui ne sont pas encore marqués comme différés sont immédiatement chargés lors de l’évaluation de la requête.

Si vous avez un modèle dont presque tous les champs ont besoin d’être différés, l’utilisation de only() pour indiquer l’ensemble complémentaire des champs peut aboutir à du code plus simple.

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")
Person.objects.only("name")

À 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.
Entry.objects.only("body", "rating").only("headline")

Comme 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.
Entry.objects.only("headline", "body").defer("body")

# Final result loads headline immediately.
Entry.objects.defer("body").only("headline", "body")

Tous 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.

Utiliser only() en omettant un champ demandé dans select_related() est aussi une erreur. D’un autre côté, appeler only() sans argument va renvoyer tous les champs (y compris les annotations) récupérés par le jeu de requête.

Comme pour defer(), vous ne pouvez pas accéder aux champs non chargés à partir de code asynchrone et vous attendre à ce qu’ils soient chargés. Vous obtiendrez plutôt une exception SynchronousOnlyOperation. Assurez-vous que tous les champs auxquels vous pourriez accéder soient compris dans votre appel à only().

using()Lien vers cette rubrique#

using(alias)Lien vers cette définition#

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 :

# queries the database with the 'default' alias.
>>> Entry.objects.all()

# queries the database with the 'backup' alias
>>> Entry.objects.using("backup")

select_for_update()Lien vers cette rubrique#

select_for_update(nowait=False, skip_locked=False, of=(), no_key=False)Lien vers cette définition#

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 :

from django.db import transaction

entries = Entry.objects.select_for_update().filter(author=request.user)
with transaction.atomic():
    for entry in entries:
        ...

Lorsque 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()
Traceback (most recent call last):
...
django.db.utils.NotSupportedError: FOR UPDATE cannot be applied to the nullable side of an outer join

Pour éviter cette restriction, vous pouvez exclure les objets nuls si vous n’en avez pas besoin :

>>> Person.objects.select_related("hometown").select_for_update().exclude(hometown=None)
<QuerySet [<Person: ...>, ...]>

The postgresql, oracle, and mysql database backends support select_for_update(). However, MariaDB only supports the nowait and skip_locked arguments, and MySQL supports the nowait, skip_locked, and of arguments. The no_key argument is only supported on 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#

raw(raw_query, params=(), translations=None, using=None)Lien vers cette définition#

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.

AND (&)Lien vers cette rubrique#

Combine deux objets QuerySet en utilisant l’opérateur SQL AND d’une manière semblable au chaînage des filtres.

Les requêtes suivantes sont équivalentes

Model.objects.filter(x=1) & Model.objects.filter(y=2)
Model.objects.filter(x=1).filter(y=2)

Équivalent SQL :

SELECT ... WHERE x=1 AND y=2

OR (|)Lien vers cette rubrique#

Combine deux requêtes QuerySet en utilisant l’opérateur SQL OR (OU).

Les requêtes suivantes sont équivalentes

Model.objects.filter(x=1) | Model.objects.filter(y=2)
from django.db.models import Q

Model.objects.filter(Q(x=1) | Q(y=2))

Équivalent SQL :

SELECT ... WHERE x=1 OR y=2

| n’est pas une opération commutative, dans la mesure où des requêtes apparemment équivalentes peuvent aboutir à des requêtes différentes.

XOR (^)Lien vers cette rubrique#

Combine deux objets QuerySet en utilisant l’opérateur SQL XOR (ou exclusif). Une expression XOR renvoie les lignes qui correspondent à un nombre impair d’opérandes.

Les requêtes suivantes sont équivalentes

Model.objects.filter(x=1) ^ Model.objects.filter(y=2)
from django.db.models import Q

Model.objects.filter(Q(x=1) ^ Q(y=2))

Équivalent SQL :

SELECT ... WHERE x=1 XOR y=2

get()Lien vers cette rubrique#

get(*args, **kwargs)Lien vers cette définition#

aget(*args, **kwargs)Lien vers cette définition#

Version asynchrone: aget()

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

Entry.objects.get(id=1)
Entry.objects.get(Q(blog=blog) & Q(entry_number=1))

Si 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()

Si get() ne trouve aucun objet, il génère l’exception Model.DoesNotExist:

Entry.objects.get(id=-999)  # raises Entry.DoesNotExist

Si get() trouve plus qu’un objet, il génère une exception Model.MultipleObjectsReturned:

Entry.objects.get(name="A Duplicated Name")  # raises Entry.MultipleObjectsReturned

Ces 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

try:
    blog = Blog.objects.get(id=1)
    entry = Entry.objects.get(blog=blog, entry_number=1)
except ObjectDoesNotExist:
    print("Either the blog or entry doesn't exist.")

create()Lien vers cette rubrique#

create(**kwargs)Lien vers cette définition#

acreate(**kwargs)Lien vers cette définition#

Version asynchrone: acreate()

Une méthode d’agrément pour la création d’un objet et son enregistrement en une seule méthode. Ainsi :

p = Person.objects.create(first_name="Bruce", last_name="Springsteen")

et :

p = Person(first_name="Bruce", last_name="Springsteen")
p.save(force_insert=True)

sont équivalents.

Le 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#

get_or_create(defaults=None, **kwargs)Lien vers cette définition#

aget_or_create(defaults=None, **kwargs)Lien vers cette définition#

Version asynchrone: aget_or_create()

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 :

try:
    obj = Person.objects.get(first_name="John", last_name="Lennon")
except Person.DoesNotExist:
    obj = Person(first_name="John", last_name="Lennon", birthday=date(1940, 10, 9))
    obj.save()

Ici, 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(
    first_name="John",
    last_name="Lennon",
    defaults={"birthday": date(1940, 10, 9)},
)

Tout 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.

You can specify more complex conditions for the retrieved object by chaining get_or_create() with filter() and using Objets Q(). For example, to retrieve Robert or Bob Marley if either exists, and create the latter otherwise:

from django.db.models import Q

obj, created = Person.objects.filter(
    Q(first_name="Bob") | Q(first_name="Robert"),
).get_or_create(last_name="Marley", defaults={"first_name": "Bob"})

Si 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}
params.update({k: v() if callable(v) else v for k, v in defaults.items()})
obj = self.model(**params)
obj.save()

En 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"})

Le 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#

update_or_create(defaults=None, create_defaults=None, **kwargs)Lien vers cette définition#

aupdate_or_create(defaults=None, create_defaults=None, **kwargs)Lien vers cette définition#

Version asynchrone: aupdate_or_create()

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. Les paramètres create_defaults et defaults sont tous deux des dictionnaires de paires (champ, valeur). Leurs valeurs peuvent être des objets exécutables. defaults est utilisé pour mettre à jour l’objet, alors que create_defaults est utilisé pour l’opération de création. Si create_defaults n’est pas renseigné, ce sont les valeurs de defaults qui sont utilisées pour la création.

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 :

defaults = {"first_name": "Bob"}
create_defaults = {"first_name": "Bob", "birthday": date(1940, 10, 9)}
try:
    obj = Person.objects.get(first_name="John", last_name="Lennon")
    for key, value in defaults.items():
        setattr(obj, key, value)
    obj.save()
except Person.DoesNotExist:
    new_values = {"first_name": "John", "last_name": "Lennon"}
    new_values.update(create_defaults)
    obj = Person(**new_values)
    obj.save()

Ce 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(
    first_name="John",
    last_name="Lennon",
    defaults={"first_name": "Bob"},
    create_defaults={"first_name": "Bob", "birthday": date(1940, 10, 9)},
)

Pour 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#

bulk_create(objs, batch_size=None, ignore_conflicts=False, update_conflicts=False, update_fields=None, unique_fields=None)Lien vers cette définition#

abulk_create(objs, batch_size=None, ignore_conflicts=False, update_conflicts=False, update_fields=None, unique_fields=None)Lien vers cette définition#

Version asynchrone: abulk_create()

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 :

>>> objs = Entry.objects.bulk_create(
...     [
...         Entry(headline="This is a test"),
...         Entry(headline="This is only a test"),
...     ]
... )

Cette méthode présente toutefois quelques inconvénients :

• The model’s save() method will not be called, and the pre_save and post_save signals will not be sent.

• Elle ne fonctionne pas avec des modèles enfants dans un contexte d’héritage multitable.

• If the model’s primary key is an AutoField or has a db_default value, and ignore_conflicts is False, the primary key attribute can only be retrieved on certain databases (currently PostgreSQL, MariaDB, and SQLite). On other databases, it will not be set.

• 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

  Code

  from itertools import islice
  
  batch_size = 100
  objs = (Entry(headline="Test %s" % i) for i in range(1000))
  while True:
      batch = list(islice(objs, batch_size))
      if not batch:
          break
      Entry.objects.bulk_create(batch, batch_size)
  

Le paramètre batch_size permet de contrôler le nombre d’objets créés dans une seule requête. Par défaut, les objets sont créés en lots en fonction du nombre maximal pris en charge par la base de données (SQLite et Oracle limitent le nombre de paramètres autorisés dans une requête).

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.

Pour les bases de données qui le prennent en charge (toutes sauf Oracle), la définition de update_conflicts à True indique à la base de données de mettre à jour les champs dans update_fields lorsque l’insertion d’une ligne échoue en cas de conflit. Avec PostgreSQL et SQLite, en plus de update_fields, il est requis de fournir une liste de champs unique_fields potentiellement en conflit.

L’activation du paramètre ignore_conflicts 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#

bulk_update(objs, fields, batch_size=None)Lien vers cette définition#

abulk_update(objs, fields, batch_size=None)Lien vers cette définition#

Version asynchrone: abulk_update()

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, et renvoie le nombre d’objets mis à jour :

>>> objs = [
...     Entry.objects.create(headline="Entry 1"),
...     Entry.objects.create(headline="Entry 2"),
... ]
>>> objs[0].headline = "This is entry 1"
>>> objs[1].headline = "This is entry 2"
>>> Entry.objects.bulk_update(objs, ["headline"])
2

QuerySet.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.

• Each model’s save() method isn’t called, and the pre_save and post_save signals aren’t sent.

• 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.

• Lors de la mise à jour d’un grand nombre d’objets, sachez que bulk_update() prépare toutes les clauses WHEN de chaque objet dans tous les lots avant d’exécuter la première requête. Cela pourrait surcharger la mémoire. Pour réduire cette utilisation de la mémoire, vous pouvez utiliser une approche telle que celle-ci :

  Code

  from itertools import islice
  
  batch_size = 100
  ids_iter = iter(range(1000))
  while ids := list(islice(ids_iter, batch_size)):
      batch = Entry.objects.filter(id__in=ids)
      for entry in batch:
          entry.headline = f"Updated headline {entry.pk}"
      Entry.objects.bulk_update(batch, ["headline"], batch_size=batch_size)
  

• 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 nombre d’objets mis à jour renvoyé par la fonction peut être plus petit que le nombre d’objets transmis. Cela peut être dû à des objets transmis à double et qui sont mis à jour dans le même lot ou à des conditions de concurrence faisant que certains objets n’existent plus en base de données.

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#

count()Lien vers cette définition#

acount()Lien vers cette définition#

Version asynchrone: acount()

Renvoie un nombre entier représentant le nombre d’objets de base de données correspondant au QuerySet.

Exemple :

# Returns the total number of entries in the database.
Entry.objects.count()

# Returns the number of entries whose headline contains 'Lennon'
Entry.objects.filter(headline__contains="Lennon").count()

Un 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#

in_bulk(id_list=None, *, field_name='pk')Lien vers cette définition#

ain_bulk(id_list=None, *, field_name='pk')Lien vers cette définition#

Version asynchrone: ain_bulk()

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 :

>>> Blog.objects.in_bulk([1])
{1: <Blog: Beatles Blog>}
>>> Blog.objects.in_bulk([1, 2])
{1: <Blog: Beatles Blog>, 2: <Blog: Cheddar Talk>}
>>> Blog.objects.in_bulk([])
{}
>>> Blog.objects.in_bulk()
{1: <Blog: Beatles Blog>, 2: <Blog: Cheddar Talk>, 3: <Blog: Django Weblog>}
>>> Blog.objects.in_bulk(["beatles_blog"], field_name="slug")
{'beatles_blog': <Blog: Beatles Blog>}
>>> Blog.objects.distinct("name").in_bulk(field_name="name")
{'Beatles Blog': <Blog: Beatles Blog>, 'Cheddar Talk': <Blog: Cheddar Talk>, 'Django Weblog': <Blog: Django Weblog>}

En passant une liste vide à in_bulk(), le résultat est un dictionnaire vide.

iterator()Lien vers cette rubrique#

iterator(chunk_size=None)Lien vers cette définition#

aiterator(chunk_size=None)Lien vers cette définition#

Version asynchrone: aiterator()

Evaluates the QuerySet (by performing the query) and returns an iterator over the results, or an asynchronous iterator if you call its asynchronous version aiterator.

A QuerySet typically caches its results internally so that repeated evaluations do not result in additional queries. In contrast, iterator() will read results directly, without doing any caching at the QuerySet level. For a QuerySet which returns a large number of objects that you only need to access once, this can result in better performance and a significant reduction in memory.

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.

iterator() est compatible avec les appels précédents à prefetch_related() tant que chunk_size est bien indiqué. Les grosses quantités de valeurs nécessiteront moins de requêtes pour obtenir le préchargement, mais aux dépends d’une plus grande consommation de mémoire.

Pour certaines bases de données (par ex. Oracle, SQLite), le nombre maximal de termes dans une clause SQL IN peut être limité. C’est pourquoi il faudrait respecter cette limite de nombre de valeurs. En particulier, lors du préchargement traversant deux ou plusieurs relations, la taille chunk_size devrait rester assez modeste pour que le nombre de résultats prévus pour chaque relation préchargée reste bien sous cette limite.

Tant que la requête QuerySet ne précharge pas d’objets liés, l’absence de valeur de chunk_size signifie que Django utilisera une valeur implicite par défaut de 2000.

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.

latest()Lien vers cette rubrique#

latest(*fields)Lien vers cette définition#

alatest(*fields)Lien vers cette définition#

Version asynchrone: alatest()

Renvoie le dernier objet de la table, en fonction du ou des champs indiqués.

Cet exemple renvoie le dernier objet Entry de la table, selon le champ pub_date:

Entry.objects.latest("pub_date")

Il 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")

Le 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#

earliest(*fields)Lien vers cette définition#

aearliest(*fields)Lien vers cette définition#

Version asynchrone: aearliest()

Fonctionne comme latest(), mais dans le sens inverse.

first()Lien vers cette rubrique#

first()Lien vers cette définition#

afirst()Lien vers cette définition#

Version asynchrone: afirst()

Returns the first object matched by the queryset, or None if there is no matching object. If the QuerySet has no ordering defined (and has not had ordering forcibly cleared by calling order_by() with no arguments), then the queryset is automatically ordered by the primary key. This can affect aggregation results as described in Interaction avec order_by().

Exemple :

p = Article.objects.order_by("title", "pub_date").first()

Notez que first() est une méthode d’agrément ; l’extrait de code suivant est équivalent à l’exemple ci-dessus :

try:
    p = Article.objects.order_by("title", "pub_date")[0]
except IndexError:
    p = None

last()Lien vers cette rubrique#

last()Lien vers cette définition#

alast()Lien vers cette définition#

Version asynchrone: alast()

Fonctionne comme first(), mais renvoie le dernier objet du jeu de requête.

aggregate()Lien vers cette rubrique#

aggregate(*args, **kwargs)Lien vers cette définition#

aaggregate(*args, **kwargs)Lien vers cette définition#

Version asynchrone: aaggregate()

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.

Les 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.

Par 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 :

>>> from django.db.models import Count
>>> Blog.objects.aggregate(Count("entry__authors"))
{'entry__authors__count': 16}

En 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 :

>>> Blog.objects.aggregate(number_of_authors=Count("entry__authors"))
{'number_of_authors': 16}

Pour une présentation approfondie de l’agrégation, consultez le guide thématique sur l’agrégation.

exists()Lien vers cette rubrique#

exists()Lien vers cette définition#

aexists()Lien vers cette définition#

Version asynchrone: aexists()

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’existence d’au moins un objet dans un QuerySet, particulièrement dans le contexte de QuerySet volumineux.

Pour savoir si un jeu de requête contient au moins un élément :

if some_queryset.exists():
    print("There is at least one object in some_queryset")

Ce qui sera plus rapide que :

if some_queryset:
    print("There is at least one object in some_queryset")

…mais pas de beaucoup (plus le jeu de requête est potentiellement volumineux, plus le gain sera élevé).

De 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.

contains()Lien vers cette rubrique#

contains(obj)Lien vers cette définition#

acontains(obj)Lien vers cette définition#

Version asynchrone: acontains()

Renvoie True si la requête QuerySet contient obj, sinon False. Cette méthode s’efforce de lancer la requête la plus simple et rapide possible.

contains() est utile pour vérifier l’appartenance d’un objet à une requête QuerySet, particulièrement dans le contexte de QuerySet volumineuses.

Pour savoir si un jeu de requête contient un certain élément :

if some_queryset.contains(obj):
    print("Entry contained in queryset")

Ce sera plus rapide que l’exemple suivant qui demande l’évaluation et l’itération de la totalité du jeu de requête :

if obj in some_queryset:
    print("Entry contained in queryset")

Comme pour exists(), si some_queryset n’a pas encore été évalué mais que vous savez qu’il le sera à un moment donné, l’appel à some_queryset.contains(obj) va produire une requête supplémentaire dans la base de données, ce qui aboutit généralement à des performances moins bonnes.

update()Lien vers cette rubrique#

update(**kwargs)Lien vers cette définition#