Fixed #16063 -- Adjusted admin changelist searches spanning multi-valued relationships.

This reduces the likelihood of admin searches issuing queries with
excessive joins.

3 files changed, 54 insertions, 0 deletions

diff --git a/docs/ref/contrib/admin/index.txt b/docs/ref/contrib/admin/index.txt
index 5caea603c1..ac8f44b765 100644
--- a/docs/ref/contrib/admin/index.txt
+++ b/docs/ref/contrib/admin/index.txt
@@ -1185,6 +1185,22 @@ subclass::
     :meth:`ModelAdmin.get_search_results` to provide additional or alternate
     search behavior.
 
+    .. versionchanged:: 4.1
+
+        Searches using multiple search terms are now applied in a single call
+        to ``filter()``, rather than in sequential ``filter()`` calls.
+
+        For multi-valued relationships, this means that rows from the related
+        model must match all terms rather than any term. For example, if
+        ``search_fields`` is set to ``['child__name', 'child__age']``, and a
+        user searches for ``'Jamal 17'``, parent rows will be returned only if
+        there is a relationship to some 17-year-old child named Jamal, rather
+        than also returning parents who merely have a younger or older child
+        named Jamal in addition to some other 17-year-old.
+
+        See the :ref:`spanning-multi-valued-relationships` topic for more
+        discussion of this difference.
+
 .. attribute:: ModelAdmin.search_help_text
 
     .. versionadded:: 4.0
@@ -1403,6 +1419,22 @@ templates used by the :class:`ModelAdmin` views:
     field, for example ``... OR UPPER("polls_choice"."votes"::text) = UPPER('4')``
     on PostgreSQL.
 
+    .. versionchanged:: 4.1
+
+        Searches using multiple search terms are now applied in a single call
+        to ``filter()``, rather than in sequential ``filter()`` calls.
+
+        For multi-valued relationships, this means that rows from the related
+        model must match all terms rather than any term. For example, if
+        ``search_fields`` is set to ``['child__name', 'child__age']``, and a
+        user searches for ``'Jamal 17'``, parent rows will be returned only if
+        there is a relationship to some 17-year-old child named Jamal, rather
+        than also returning parents who merely have a younger or older child
+        named Jamal in addition to some other 17-year-old.
+
+        See the :ref:`spanning-multi-valued-relationships` topic for more
+        discussion of this difference.
+
 .. method:: ModelAdmin.save_related(request, form, formsets, change)
 
     The ``save_related`` method is given the ``HttpRequest``, the parent
diff --git a/docs/releases/4.1.txt b/docs/releases/4.1.txt
index 3fdd7f53c6..5f184d2349 100644
--- a/docs/releases/4.1.txt
+++ b/docs/releases/4.1.txt
@@ -290,6 +290,26 @@ Dropped support for MariaDB 10.2
 Upstream support for MariaDB 10.2 ends in May 2022. Django 4.1 supports MariaDB
 10.3 and higher.
 
+Admin changelist searches spanning multi-valued relationships changes
+---------------------------------------------------------------------
+
+Admin changelist searches using multiple search terms are now applied in a
+single call to ``filter()``, rather than in sequential ``filter()`` calls.
+
+For multi-valued relationships, this means that rows from the related model
+must match all terms rather than any term. For example, if ``search_fields``
+is set to ``['child__name', 'child__age']``, and a user searches for
+``'Jamal 17'``, parent rows will be returned only if there is a relationship to
+some 17-year-old child named Jamal, rather than also returning parents who
+merely have a younger or older child named Jamal in addition to some other
+17-year-old.
+
+See the :ref:`spanning-multi-valued-relationships` topic for more discussion of
+this difference. In Django 4.0 and earlier,
+:meth:`~django.contrib.admin.ModelAdmin.get_search_results` followed the
+second example query, but this undocumented behavior led to queries with
+excessive joins.
+
 Miscellaneous
 -------------
 
diff --git a/docs/topics/db/queries.txt b/docs/topics/db/queries.txt
index c24c06da68..eb68c7b4da 100644
--- a/docs/topics/db/queries.txt
+++ b/docs/topics/db/queries.txt
@@ -525,6 +525,8 @@ those latter objects, you could write::
 
     Blog.objects.filter(entry__authors__isnull=False, entry__authors__name__isnull=True)
 
+.. _spanning-multi-valued-relationships:
+
 Spanning multi-valued relationships
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~