Add docstring

Author: WaVEV

django_mongodb_backend/query.py

@@ -123,7 +123,13 @@ def extra_where(self, compiler, connection):  # noqa: ARG001
     raise NotSupportedError("QuerySet.extra() is not supported on MongoDB.")
 
 
-def join(self, compiler, connection, pushed_expressions=None):
+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.
+    """
+
     parent_template = "parent__field__"
 
     def _get_reroot_replacements(expressions):
@@ -182,12 +188,18 @@ def _get_reroot_replacements(expressions):
             extra.replace_expressions(replacements).as_mql(compiler, connection)
         )
 
-    if pushed_expressions and self.join_type == INNER:
-        rerooted_replacement = _get_reroot_replacements(pushed_expressions)
+    # 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.
+    if pushed_expression and self.join_type == INNER:
+        rerooted_replacement = _get_reroot_replacements(pushed_expression)
         extra_conditions.append(
-            pushed_expressions.replace_expressions(rerooted_replacement).as_mql(
-                compiler, connection
-            )
+            pushed_expression.replace_expressions(rerooted_replacement).as_mql(compiler, connection)
         )
 
     lookup_pipeline = [