Une vue Django qui liste des articles de blog avec le nom de leur auteur et le nombre de commentaires associés paraît triviale à écrire, et elle le reste jusqu'à ce que la base de données contienne plus de quelques dizaines de lignes. Le QuerySet affiché dans la vue ne contient qu'une seule ligne de code, mais le nombre réel de requêtes SQL exécutées pendant le rendu du template peut être dix ou cent fois supérieur à ce que cette ligne laisse penser. Le piège est d'autant plus sournois en Django que le QuerySet est paresseux par construction : rien n'indique, à la lecture du code de la vue, à quel moment précis chaque requête part réellement.
Le mécanisme : évaluation paresseuse et descripteurs de relation
Un QuerySet Django ne touche pas la base de données tant qu'il n'est pas itéré, converti en liste, ou évalué par un slicing avec pas. Article.objects.all() ne déclenche aucune requête ; c'est le for article in articles du template qui en déclenche une. Jusqu'ici, rien de problématique : une seule requête suffit pour récupérer tous les articles. Le problème apparaît sur l'accès à une relation à l'intérieur de la boucle.
# views.py
def article_list(request):
articles = Article.objects.all()
return render(request, "blog/list.html", {"articles": articles})
<!-- blog/list.html -->
{% for article in articles %}
<h2>{{ article.title }}</h2>
<p>par {{ article.author.full_name }}</p>
<p>{{ article.comments.count }} commentaires</p>
{% endfor %}
article.author est un descripteur de relation ForeignKey. La première fois qu'on y accède sur une instance donnée, Django exécute une requête SELECT * FROM auteurs WHERE id = %s et met le résultat en cache sur l'instance. Comme chaque article est une instance distincte, ce cache ne profite jamais à l'itération suivante : avec 50 articles, on obtient 1 requête pour la liste, 50 requêtes pour les auteurs, et 50 requêtes supplémentaires pour le comptage des commentaires, soit 101 requêtes pour afficher une page.
Diagnostiquer avant d'optimiser
django-debug-toolbar reste l'outil de référence en développement : son panneau SQL affiche le nombre exact de requêtes par page, leur temps d'exécution, et surtout les requêtes dupliquées, surlignées comme telles.
Pour un diagnostic en ligne de commande ou dans un shell, django.db.connection.queries liste les requêtes exécutées depuis le dernier reset, à condition que DEBUG = True :
from django.db import connection, reset_queries
reset_queries()
list(Article.objects.all())
print(len(connection.queries)) # 1
for article in Article.objects.all():
article.author.full_name
print(len(connection.queries)) # 1 (liste) + N (auteurs)
Dans les tests, assertNumQueries transforme ce diagnostic en garde-fou permanent contre les régressions, bien plus fiable qu'une relecture manuelle du code :
from django.test.utils import CaptureQueriesContext
from django.db import connection
def test_article_list_does_not_trigger_n_plus_1(self):
ArticleFactory.create_batch(10)
with self.assertNumQueries(3): # liste + auteurs + commentaires
response = self.client.get(reverse("blog:article_list"))
self.assertEqual(response.status_code, 200)
Un test qui échoue parce que le compteur passe de 3 à 13 après un changement anodin dans un template est un signal immédiat, bien avant que la lenteur ne soit constatée en production.
La correction : select_related pour le "un", prefetch_related pour le "plusieurs"
Django propose deux méthodes distinctes, et le choix entre les deux dépend de la cardinalité de la relation, pas d'une préférence stylistique.
select_related s'applique aux relations à un seul objet (ForeignKey, OneToOneField) et fonctionne par JOIN SQL : une seule requête ramène les articles et leurs auteurs en une fois.
articles = Article.objects.select_related("author").all()
prefetch_related s'applique aux relations à plusieurs objets (ManyToManyField, ou relation inverse de ForeignKey comme comments) et fonctionne par requête séparée suivie d'une jointure effectuée côté Python : un JOIN SQL dupliquerait une ligne d'article par commentaire, ce que Django évite précisément en émettant deux requêtes distinctes puis en regroupant les résultats en mémoire.
articles = (
Article.objects
.select_related("author")
.prefetch_related("comments")
.all()
)
Pour le comptage de commentaires, annotate(Count(...)) évite même la deuxième requête en le calculant directement en SQL via une agrégation :
from django.db.models import Count
articles = (
Article.objects
.select_related("author")
.annotate(comment_count=Count("comments"))
)
<p>{{ article.comment_count }} commentaires</p>
On passe ainsi de 101 requêtes à 1 ou 2, selon que le comptage est fait par agrégation ou par prefetch_related.
Les compromis entre select_related et prefetch_related
Ces deux outils ne sont pas interchangeables et chacun a un coût propre.
Un select_related trop profond sur plusieurs hops (select_related("author__company__country")) produit un JOIN SQL unique mais large, avec potentiellement beaucoup de colonnes redondantes transférées pour chaque ligne. Au-delà de deux ou trois niveaux, le gain d'une requête unique peut être annulé par le volume de données transférées ; mesurer plutôt que supposer reste nécessaire.
Un prefetch_related sur une relation volumineuse (un article avec dix mille commentaires) charge l'intégralité de la relation en mémoire même si le template n'en affiche que les cinq premiers. Pour restreindre ce chargement, l'objet Prefetch permet de personnaliser le QuerySet préchargé :
from django.db.models import Prefetch
articles = Article.objects.prefetch_related(
Prefetch(
"comments",
queryset=Comment.objects.filter(is_approved=True).order_by("-created_at")[:5],
to_attr="recent_comments",
)
)
to_attr matérialise le résultat dans un nouvel attribut plutôt que de remplacer le manager par défaut, ce qui évite qu'un accès ultérieur à article.comments.all() ailleurs dans le code ne déclenche une nouvelle requête non préchargée par erreur.
Restreindre les colonnes avec only() ou exclure celles inutiles avec defer() réduit le volume transféré sur des modèles avec des colonnes volumineuses (un champ TextField de description longue qu'une vue de liste n'affiche jamais, par exemple).
Quand select_related et prefetch_related ne suffisent pas
Les relations génériques (GenericForeignKey) de django.contrib.contenttypes ne peuvent pas être optimisées par select_related, car Django ne connaît pas le modèle cible au moment de construire le JOIN. La bibliothèque django-generic-relations ou un préchargement manuel groupé par content_type reste nécessaire pour éviter un N+1 sur ce type de relation.
Les agrégations imbriquées (le nombre de commentaires approuvés uniquement, par exemple) demandent un Count avec un filtre conditionnel plutôt qu'un simple annotate, pour éviter que Django ne génère un JOIN qui fausse le compte total :
from django.db.models import Count, Q
articles = Article.objects.annotate(
approved_comment_count=Count("comments", filter=Q(comments__is_approved=True))
)
Pour des tableaux de bord agrégés sur de gros volumes, même un ORM bien optimisé reste limité par le nombre de requêtes à la demande. Une vue matérialisée PostgreSQL rafraîchie périodiquement, ou une colonne dénormalisée mise à jour par signal Django à l'écriture, déplace le coût de calcul du moment de la lecture vers le moment de l'écriture, ce qui est souvent le bon compromis pour un trafic de lecture dominant.
Automatiser la détection en dehors des tests écrits à la main
assertNumQueries protège les vues couvertes par un test explicite, mais une application Django comporte toujours des chemins non couverts, notamment dans l'administration ou des vues ajoutées rapidement sous pression. La bibliothèque nplusone détecte les patterns de N+1 à l'exécution, en observant les accès à des relations non préchargées, et peut être branchée comme middleware en développement :
# settings.py
MIDDLEWARE = [
# ...
"nplusone.ext.django.NPlusOneMiddleware",
]
NPLUSONE_LOGGER = logging.getLogger("nplusone")
NPLUSONE_LOG_LEVEL = logging.WARNING
NPLUSONE_RAISE = DEBUG # lève une exception en local, log seulement ailleurs
Avec NPLUSONE_RAISE activé en local, une relation accédée sans avoir été préchargée lève immédiatement une exception avec la pile d'appels exacte, au lieu d'un simple ralentissement silencieux détectable seulement avec django-debug-toolbar ouvert au bon moment. C'est un filet de sécurité complémentaire à assertNumQueries : ce dernier vérifie un contrat connu à l'avance sur une vue donnée, tandis que nplusone détecte un pattern générique sur des chemins de code qu'aucun test n'a encore couverts.
Il faut toutefois rester attentif à un piège propre à Django : le cache de relation posé par select_related ou prefetch_related vit sur l'instance Python, pas dans un cache partagé entre requêtes HTTP. Chaque requête entrante repart avec des instances fraîches et aucun chargement préalable, contrairement à un cache applicatif (Redis, Memcached) qui persisterait entre deux requêtes différentes. Confondre les deux mène à l'hypothèse erronée qu'une relation "déjà vue" par une requête précédente n'a pas besoin d'être rechargée dans la suivante.
En bref
Le choix entre select_related et prefetch_related n'est pas une question de préférence mais de cardinalité de la relation : JOIN pour le "un", requête séparée et jointure Python pour le "plusieurs". assertNumQueries dans les tests transforme ce choix en contrat vérifiable automatiquement, ce qui évite qu'une modification de template six mois plus tard ne réintroduise silencieusement le même N+1 que celui corrigé aujourd'hui.
