Comments and docstring

Author: WaVEV

django_mongodb_backend/compiler.py

@@ -38,6 +38,7 @@ def __init__(self, *args, **kwargs):
         self.subqueries = []
         # Atlas search stage.
         self.search_pipeline = []
+        # The aggregation has no group-by fields and needs wrapping.
         self.wrap_for_global_aggregation = False
 
     def _get_group_alias_column(self, expr, annotation_group_idx):
@@ -236,6 +237,7 @@ def _build_aggregation_pipeline(self, ids, group):
         pipeline = []
         if not ids:
             pipeline.append({"$group": {"_id": None, **group}})
+            # If ids is empty, a global group-by is applied
             self.wrap_for_global_aggregation = True
         else:
             group["_id"] = ids

django_mongodb_backend/query.py

@@ -93,15 +93,19 @@ def get_pipeline(self):
         if self.aggregation_pipeline:
             pipeline.extend(self.aggregation_pipeline)
         if self.wrap_for_global_aggregation:
+            # Use $collStats as a pivot to guarantee a single input document
             pipeline = [
                 {"$collStats": {}},
+                # Wrap the actual aggregation inside a lookup so its result
+                # always appears as a one document array
                 {
                     "$lookup": {
                         "from": self.compiler.collection_name,
                         "as": "__wrapped",
                         "pipeline": pipeline,
                     }
                 },
+                # Use {} If the inner aggregation returns nothing, otherwise unwrap
                 {
                     "$replaceWith": {
                         "$cond": [{"$eq": ["$__wrapped", []]}, {}, {"$first": "$__wrapped"}]