Highlight select_related and prefetch_related usage in documentation (#7610)

* docs updated to highlight use of select_related and prefetch related to avoid n+1 problems

* Apply suggestions from code review

cosmetic changes

Co-authored-by: Xavier Ordoquy <[email protected]>

* cosmetic changes

Co-authored-by: Xavier Ordoquy <[email protected]>

Author: thetarby

docs/api-guide/fields.md

@@ -78,7 +78,14 @@ Defaults to `False`
 
 ### `source`
 
-The name of the attribute that will be used to populate the field.  May be a method that only takes a `self` argument, such as `URLField(source='get_absolute_url')`, or may use dotted notation to traverse attributes, such as `EmailField(source='user.email')`. When serializing fields with dotted notation, it may be necessary to provide a `default` value if any object is not present or is empty during attribute traversal.
+The name of the attribute that will be used to populate the field.  May be a method that only takes a `self` argument, such as `URLField(source='get_absolute_url')`, or may use dotted notation to traverse attributes, such as `EmailField(source='user.email')`. 
+
+When serializing fields with dotted notation, it may be necessary to provide a `default` value if any object is not present or is empty during attribute traversal. Beware of possible n+1 problems when using source attribute if you are accessing a relational orm model. For example:
+
+    class CommentSerializer(serializers.Serializer):
+        email = serializers.EmailField(source="user.email")
+
+would require user object to be fetched from database when it is not prefetched. If that is not wanted, be sure to be using `prefetch_related` and `select_related` methods appropriately. For more information about the methods refer to [django documentation][django-docs-select-related].
 
 The value `source='*'` has a special meaning, and is used to indicate that the entire object should be passed through to the field.  This can be useful for creating nested representations, or for fields which require access to the complete object in order to determine the output representation.
 
@@ -855,3 +862,4 @@ The [django-rest-framework-hstore][django-rest-framework-hstore] package provide
 [django-hstore]: https://github.com/djangonauts/django-hstore
 [python-decimal-rounding-modes]: https://docs.python.org/3/library/decimal.html#rounding-modes
 [django-current-timezone]: https://docs.djangoproject.com/en/stable/topics/i18n/timezones/#default-time-zone-and-current-time-zone
+[django-docs-select-related]: https://docs.djangoproject.com/en/3.1/ref/models/querysets/#django.db.models.query.QuerySet.select_related

docs/api-guide/generic-views.md

@@ -96,6 +96,12 @@ For example:
         user = self.request.user
         return user.accounts.all()
 
+---
+
+**Note:** If the serializer_class used in the generic view spans orm relations, leading to an n+1 problem, you could optimize your queryset in this method using `select_related` and `prefetch_related`. To get more information about n+1 problem and use cases of the mentioned methods refer to related section in [django documentation][django-docs-select-related].
+
+---
+
 #### `get_object(self)`
 
 Returns an object instance that should be used for detail views.  Defaults to using the `lookup_field` parameter to filter the base queryset.
@@ -389,3 +395,4 @@ The following third party packages provide additional generic view implementatio
 [UpdateModelMixin]: #updatemodelmixin
 [DestroyModelMixin]: #destroymodelmixin
 [django-rest-multiple-models]: https://github.com/MattBroach/DjangoRestMultipleModels
+[django-docs-select-related]: https://docs.djangoproject.com/en/3.1/ref/models/querysets/#django.db.models.query.QuerySet.select_related

docs/api-guide/relations.md

@@ -17,6 +17,37 @@ Relational fields are used to represent model relationships.  They can be applie
 
 ---
 
+---
+
+**Note:** REST Framework does not attempt to automatically optimize querysets passed to serializers in terms of `select_related` and `prefetch_related` since it would be too much magic. A serializer with a field spanning an orm relation through its source attribute could require an additional database hit to fetch related object from the database. It is the programmer's responsibility to optimize queries to avoid additional database hits which could occur while using such a serializer.
+
+For example, the following serializer would lead to a database hit each time evaluating the tracks field if it is not prefetched:
+
+    class AlbumSerializer(serializers.ModelSerializer):
+        tracks = serializers.SlugRelatedField(
+            many=True,
+            read_only=True,
+            slug_field='title'
+        )
+
+        class Meta:
+            model = Album
+            fields = ['album_name', 'artist', 'tracks']
+    
+    # For each album object, tracks should be fetched from database
+    qs = Album.objects.all()
+    print(AlbumSerializer(qs, many=True).data)
+
+If `AlbumSerializer` is used to serialize a fairly large queryset with `many=True` then it could be a serious performance problem. Optimizing the queryset passed to `AlbumSerializer` with:
+
+    qs = Album.objects.prefetch_related('tracks')
+    # No additional database hits required
+    print(AlbumSerializer(qs, many=True).data)
+
+would solve the issue.
+
+---
+
 #### Inspecting relationships.
 
 When using the `ModelSerializer` class, serializer fields and relationships will be automatically generated for you. Inspecting these automatically generated fields can be a useful tool for determining how to customize the relationship style.