doc enhancements + simpler test

Author: timgraham

docs/source/querysets.rst

@@ -24,10 +24,46 @@ Some MongoDB-specific ``QuerySet`` methods are available by adding a custom
 
 Similar to :meth:`QuerySet.raw()<django.db.models.query.QuerySet.raw>`, but
 instead of a raw SQL query, this method accepts a pipeline that will be passed
-to :meth:`pymongo.collection.Collection.aggregate`. The pipeline must return
-the necessary fields to construct model instances and may also return
-additional fields that will be added as annotations on the models.
+to :meth:`pymongo.collection.Collection.aggregate`.
 
 For example, you could write a custom match criteria::
 
-    Post.objects.raw_aggregate([{"$match": {"title": "MongoDB is fun!"}}])
+    Question.objects.raw_aggregate([{"$match": {"question_text": "What's up"}}])
+
+The pipeline may also return additional fields that will be added as
+annotations on the models::
+
+    >>> questions = Question.objects.raw_aggregate([{
+    ...     "$project": {
+    ...         "question_text": 1,
+    ...         "pub_date": 1,
+    ...         "year_published": {"$year": "$pub_date"}
+    ...     }
+    ... }])
+    >>> for q in questions:
+    ...     print(f"{q.question_text} was published in {q.year_published}.")
+    ...
+    What's up? was published in 2024.
+
+Fields may also be left out:
+
+    >>> Question.objects.raw_aggregate([{"$project": {"question_text": 1}}])
+
+The ``Question`` objects returned by this query will be deferred model instances
+(see :meth:`~django.db.models.query.QuerySet.defer()`). This means that the
+fields that are omitted from the query will be loaded on demand. For example::
+
+    >>> for q in Question.objects.raw_aggregate([{"$project": {"question_text": 1}}]):
+    >>>     print(
+    ...         q.question_text,  # This will be retrieved by the original query.
+    ...         q.pub_date,       # This will be retrieved on demand.
+    ...     )
+    ...
+    What's new 2023-09-03 12:00:00+00:00
+    What's up 2024-08-23 20:57:30+00:00
+
+From outward appearances, this looks like the query has retrieved both the
+question text and published date. However, this example actually issued three
+queries. Only the question texts were retrieved by the ``raw_aggregate()``
+query -- the published dates were both retrieved on demand when they were
+printed.

tests/raw_query_/test_raw_aggregate.py

@@ -207,31 +207,20 @@ def test_missing_fields_without_PK(self):
     def test_annotations(self):
         query = [
             {
-                "$lookup": {
-                    "from": "raw_query__book",
-                    "localField": "_id",
-                    "foreignField": "author_id",
-                    "as": "books",
-                }
-            },
-            {"$addFields": {"book_count": {"$size": "$books"}}},
-            {"$project": {"books": 0}},
-            {
-                "$group": {
-                    "_id": "$_id",
-                    "first_name": {"$first": "$first_name"},
-                    "last_name": {"$first": "$last_name"},
-                    "dob": {"$first": "$dob"},
-                    "book_count": {"$first": "$book_count"},
-                }
+                "$project": {
+                    "first_name": 1,
+                    "last_name": 1,
+                    "dob": 1,
+                    "birth_year": {"$year": "$dob"},
+                },
             },
             {"$sort": {"_id": 1}},
         ]
         expected_annotations = (
-            ("book_count", 3),
-            ("book_count", 0),
-            ("book_count", 1),
-            ("book_count", 0),
+            ("birth_year", 1950),
+            ("birth_year", 1920),
+            ("birth_year", 1986),
+            ("birth_year", 1932),
         )
         authors = Author.objects.order_by("pk")
         self.assertSuccessfulRawQuery(Author, query, authors, expected_annotations)