edits

Author: timgraham

django_mongodb_backend/compiler.py

@@ -550,24 +550,25 @@ def get_combinator_queries(self):
 
     def get_lookup_pipeline(self):
         result = []
+        # To improve join performance, push conditions (filters) from the
+        # WHERE ($match) clause to the JOIN ($lookup) clause.
         where = self.get_where()
-        promote_filters = defaultdict(list)
+        pushed_filters = defaultdict(list)
         for expr in where.children if where and where.connector == AND else ():
             # Only basic lookups are pushed, no subqueries or complex
-            # conditions. To avoid duplication across subqueries,
-            # only the LHS target table is used.
+            # conditions. To avoid duplication across subqueries, only the LHS
+            # target table is used.
             if (
                 isinstance(expr, Lookup)
                 and isinstance(expr.lhs, Col)
                 and (is_direct_value(expr.rhs) or isinstance(expr.rhs, Value | Col))
             ):
-                promote_filters[expr.lhs.alias].append(expr)
-
+                pushed_filters[expr.lhs.alias].append(expr)
         for alias in tuple(self.query.alias_map):
             if not self.query.alias_refcount[alias] or self.collection_name == alias:
                 continue
             result += self.query.alias_map[alias].as_mql(
-                self, self.connection, WhereNode(promote_filters[alias], connector=AND)
+                self, self.connection, WhereNode(pushed_filters[alias], connector=AND)
             )
         return result
 

django_mongodb_backend/query.py

@@ -123,14 +123,14 @@ def extra_where(self, compiler, connection):  # noqa: ARG001
     raise NotSupportedError("QuerySet.extra() is not supported on MongoDB.")
 
 
-def join(self, compiler, connection, pushed_expression=None):
-    """
-    Generate a MongoDB $lookup stage for a join. Optionally accepts a
-    pushed_expression, which is a filter expression involving fields from the
-    joined collection, and can be pushed into the lookup pipeline for
-    optimization.
+def join(self, compiler, connection, pushed_filter_expression=None):
     """
+    Generate a MongoDB $lookup stage for a join.
 
+    `pushed_filter_expression` is a Where expression involving fields from the
+    joined collection which can be pushed from the WHERE ($match) clause to the
+    JOIN ($lookup) clause to improve performance.
+    """
     parent_template = "parent__field__"
 
     def _get_reroot_replacements(expression):
@@ -176,34 +176,32 @@ def _get_reroot_replacements(expression):
             self.parent_alias, lhs, compiler.collection_name, rhs
         )
         lhs_fields.append(lhs.as_mql(compiler, connection))
-        # In the lookup stage, the reference to this column doesn't include
-        # the collection name.
+        # In the lookup stage, the reference to this column doesn't include the
+        # collection name.
         rhs_fields.append(rhs.as_mql(compiler, connection))
     # Handle any join conditions besides matching field pairs.
     extra = self.join_field.get_extra_restriction(self.table_alias, self.parent_alias)
-
     extra_conditions = []
     if extra:
         replacements = _get_reroot_replacements(extra)
         extra_conditions.append(
             extra.replace_expressions(replacements).as_mql(compiler, connection)
         )
-
-    # pushed_expression is a filter expression from the outer WHERE clause
-    # that involves fields from the joined (right-hand) table and possibly the
-    # outer (left-hand) table.
-    # If it can be safely evaluated within the $lookup pipeline
-    # (e.g., field comparisons like right.status = left.id), it is
-    # "pushed down" into the join's $match stage to reduce the volume of
-    # joined documents. This only applies to inner joins, as pushing
-    # filters into a left join can change the semantics of the result.
-    # LEFT JOINs may rely on null checks to detect missing RHS.
-    if pushed_expression and self.join_type == INNER:
-        rerooted_replacement = _get_reroot_replacements(pushed_expression)
+    # pushed_filter_expression is a filter expression from the outer WHERE
+    # clause that involves fields from the joined (right-hand) table and
+    # possibly the outer (left-hand) table. If it can be safely evaluated
+    # within the $lookup pipeline (e.g., field comparisons like
+    # right.status = left.id), it is "pushed" into the join's $match stage to
+    # reduce the volume of joined documents. This only applies to INNER JOINs,
+    # as pushing filters into a LEFT JOIN can change the semantics of the
+    # result. LEFT JOINs may rely on null checks to detect missing RHS.
+    if pushed_filter_expression and self.join_type == INNER:
+        rerooted_replacement = _get_reroot_replacements(pushed_filter_expression)
         extra_conditions.append(
-            pushed_expression.replace_expressions(rerooted_replacement).as_mql(compiler, connection)
+            pushed_filter_expression.replace_expressions(rerooted_replacement).as_mql(
+                compiler, connection
+            )
         )
-
     lookup_pipeline = [
         {
             "$lookup": {