Rewrite documentation with MkDocs

docs/howto/querysets.md

@@ -0,0 +1,280 @@
+L'ORM de Django est puissant, très puissant, non par parce qu'il
+est performant (après tout, ce n'est qu'une interface, le gros du boulot,
+c'est la db qui le fait), mais parce qu'il permet d'écrire
+de manière relativement simple un grand panel de requêtes.
+
+De manière générale, puisqu'un ORM est un système
+consistant à manipuler avec un code orienté-objet
+une db relationnelle (c'est-à-dire deux paradigmes
+qui ne fonctionnent absolument pas pareil),
+on rencontre un des deux problèmes suivants :
+
+- soit l'ORM n'offre pas assez d'abstraction,
+  auquel cas, quand on veut faire des requêtes
+  plus complexes qu'un `select` avec un `where`,
+  on s'emmêle les pinceaux et on se dit que
+  ça aurait été plus simple de le faire directement
+  en SQL.
+- soit l'ORM offre trop d'abstraction,
+  auquel cas, on a tendance à ne pas prêter
+  assez attention aux requêtes envoyées en base
+  de données et on finit par se rendre compte
+  que les temps d'attente explosent
+  parce qu'on envoie trop de requêtes.
+
+Django est dans ce deuxième cas.
+
+C'est pourquoi nous ne parlerons pas ici
+de son fonctionnement exact ni de toutes les fonctions
+que l'on peut utiliser 
+(la doc officielle fait déjà ça mieux que nous),
+mais plutôt des pièges courants
+et des astuces pour les éviter.
+
+## Les `N+1 queries`
+
+### Le problème
+
+Normalement, quand on veut récupérer une liste,
+on fait une requête et c'est fini.
+Mais des fois, ça n'est pas si simple.
+Par exemple, supposons que nous voulons
+récupérer les 100 utilisateurs les plus riches,
+avec leurs informations client :
+
+```python
+from core.models import User
+
+for user in User.objects.order_by("-customer__amount")[:100]:
+    print(user.customer.amount)
+```
+
+Combien de requêtes le bout de code suivant effectue-t-il ?
+101\.
+En deux pauvres lignes de code, nous avons demandé
+à la base de données d'effectuer 101 requêtes.
+Une requête toute seule n'est déjà une opération anodine,
+alors je vous laisse imaginer ce que ça donne pour 101.
+
+Si vous ne comprenez pourquoi ce nombre, c'est très simple :
+
+- Une requête pour sélectionner nos 100 utilisateurs
+- Une requête supplémentaire pour récupérer les informations
+  client de chaque utilisateur, soit 100 requêtes.
+
+En effet, les informations client sont stockées dans une
+autre table, mais le fait d'établir un lien de clef
+étrangère permet de manipuler `customer`
+comme si c'était un membre à part entière de `User`.
+
+Il est à noter cependant, que Django n'effectue une requête
+que pour le premier accès à un membre d'une relation
+de clef étrangère.
+Toutes les fois suivantes, l'objet est déjà là,
+et django le récupère :
+
+```python
+from core.models import User
+
+# l'utilisateur le plus riche
+user = User.objects.order_by("-customer__amount").first()  # <-- requête db
+print(user.customer.amount)  # <-- requête db
+print(user.customer.account_id)  # on a déjà récupéré `customer`, donc pas de requête
+```
+
+Ce n'est donc pas gravissime si vous faites cette
+erreur quand vous manipulez un seul objet.
+En revanche, quand vous en manipulez plusieurs,
+il faut régler le problème.
+Pour ça, il y a plusieurs méthodes, en fonction de votre cas.
+
+### `select_related`
+
+La méthode la plus basique consiste à annoter le queryset,
+avec la méthode `select_related()`.
+En faisant ça, Django fera une jointure sur l'autre table
+et demandera des informations en plus
+à la db lors de la requête.
+
+De la sorte, lorsque vous appellerez le membre relié,
+les informations seront déjà là.
+
+```python
+from core.models import User
+
+richest = User.objects.order_by("-customer__amount")
+for user in richest.select_related("customer")[:100]:
+    print(user.customer)
+```
+
+Le code ci-dessus effectue une seule requête.
+Chaque fois qu'on veut accéder à `customer`, c'est bon,
+ça a déjà été récupéré à travers le `annotate`.
+
+### `prefetch_related`
+
+Maintenant, un cas plus compliqué.
+Supposons que vous ne vouliez pas récupérer des informations
+reliées par une relation One-to-One,
+mais par une relation One-to-Many.
+
+Par exemple, un utilisateur a un seul compte client,
+mais il peut avoir plusieurs cotisations à son actif.
+Et dans ces cas-là, `annotate` ne marche plus.
+En effet, s'il peut exister plusieurs cotisations,
+comment savoir laquelle on veut ?
+
+Il faut alors utiliser un `prefetch_related`.
+C'est un mécanisme un peu différent :
+au lieu de faire une jointure et d'ajouter les informations
+voulues dans la même requête, Django va effectuer
+une deuxième requête pour récupérer les éléments de l'autre table,
+puis, à partir de ces éléments, peupler la relation
+de son côté.
+
+C'est un mécanisme qui peut être un peu coûteux en mémoire
+et qui demande une deuxième requête,
+mais qui reste quand même largement préférable
+à faire N requêtes en plus.
+
+```python
+from core.models import User
+
+for user in User.objects.prefetch_related("subscriptions")[:100]:
+    # c'est bon, la méthode prefetch a récupéré en avance les `subscriptions`
+    print(user.subscriptions.all())
+```
+
+!!! danger
+
+    La méthode `prefetch_related` ne marche que si vous
+    utilisez la méthode `all()` pour accéder au membre.
+    Si vous utilisez une autre méthode (comme `filter` ou `annotate`),
+    alors Django effectuera une nouvelle requête,
+    et vous retomberez dans le problème initial.
+
+    ```python
+    from core.models import User
+    from django.db.models import Count
+    
+    for user in User.objects.prefetch_related("subscriptions")[:100]:
+        # Le prefetch_related ne marche plus !
+        print(user.subscriptions.annotate(count=Count("*")))
+    ```
+
+### Récupérer ce dont vous avez besoin
+
+Des fois (souvent, même), penser explicitement
+à la jointure est le meilleur choix.
+
+En effet, vous remarquerez que dans tous
+les exemples précédents, nous n'utilisions
+qu'une partie des informations 
+(par exemple, nous ne récupérions que la somme
+d'argent sur les comptes, et éventuellement le numéro de compte).
+
+Nous pouvons utiliser la méthode `annotate`
+pour spécifier explicitement les données que l'on veut
+joindre à notre requête.
+
+Quand nous voulions récupérer les informations utilisateur,
+nous aurions tout aussi bien pu écrire :
+
+```python
+from core.models import User
+from django.db.models import F
+
+richest = User.objects.order_by("-customer__amount")
+for user in richest.annotate(amount=F("customer__amount"))[:100]:
+    print(user.amount)
+```
+
+On aurait même pu réorganiser ça :
+```python
+
+from core.models import User
+from django.db.models import F
+
+richest = User.objects.annotate(amount=F("customer__amount")).order_by("-amount")
+for user in richest[:100]:
+    print(user.amount)
+```
+
+Ça peut sembler moins bien qu'un `select_related`, comme ça.
+Des fois, c'est en effet moins bien, et des fois c'est mieux.
+La comparaison est plus évidente avec le `prefetch_related`.
+
+En effet, quand nous voulions récupérer
+le nombre de cotisations des utilisateurs,
+le `prefetch_related` ne marchait plus.
+Pourtant, nous voulions récupérer une seule information.
+
+Il aurait donc été suffisant d'écrire :
+```python
+from core.models import User
+from django.db.models import Count
+
+for user in User.objects.annotate(nb_subscriptions=Count("subscriptions"))[:100]:
+    # Et là ça marche, en une seule requête.
+    print(user.nb_subscriptions)
+```
+
+Faire une jointure, c'est normal en SQL.
+Et pourtant avec Django on les oublie trop facilement.
+Posez-vous toujours la question des données que vous pourriez
+avoir besoin d'annoter, et vous éviterez beaucoup d'ennuis.
+
+## Les aggrégations manquées
+
+Il arrive souvent que l'on veuille une information qui
+porte sur un ensemble d'objets de notre db.
+
+Imaginons par exemple que nous voulons connaitre
+la somme totale des ventes faites à un comptoir.
+
+Nous avons tous suivi nos cours de programmation,
+nous écrivons donc instinctivement :
+
+```python
+from counter.models import Counter
+
+foyer = Counter.objects.get(name="Foyer")
+total_amount = sum(
+    sale.amount * sale.unit_price
+    for sale in foyer.sellings.all()
+)
+```
+
+On pourrait penser qu'il n'y a pas de problème.
+Après tout, on ne fait qu'une seule requête.
+Eh bien si, il y a un problème :
+on fait beaucoup de choses en trop.
+
+Concrètement, on demande à la base de données
+de renvoyer toutes les informations,
+ce qui rallonge inutilement la durée
+de l'échange entre le serveur et la db,
+puis on perd du temps à convertir ces informations
+en objets Python (opération qui a un coût également),
+et enfin on reperd du temps à calculer en Python
+quelque chose que la db aurait pu calculer
+à notre plus bien plus vite.
+
+Nous aurions dû aggréger la requête,
+avec la méthode `aggregate` :
+
+```python
+from counter.models import Counter
+from django.db.models import Sum, F
+
+foyer = Counter.objects.get(name="Foyer")
+total_amount = (
+    foyer.sellings.aggregate(amount=Sum(F("amount") * F("unit_price"), default=0))
+)["amount__sum"]
+```
+
+En effectuant cette requête, la base de données nous renverra exactement
+l'information dont nous avons besoin.
+Et de notre côté, nous n'aurons pas à faire de traitement en plus.
+
+