Fixed #36881 -- Corrected documentation for ModelAdmin.search_fields.

1 files changed, 23 insertions, 9 deletions

diff --git a/docs/ref/contrib/admin/index.txt b/docs/ref/contrib/admin/index.txt
index 846ac0973b..ef448c6f79 100644
--- a/docs/ref/contrib/admin/index.txt
+++ b/docs/ref/contrib/admin/index.txt
@@ -1244,8 +1244,11 @@ subclass::
     This should be set to a list of field names that will be searched whenever
     somebody submits a search query in that text box.
 
-    These fields should be some kind of text field, such as ``CharField`` or
-    ``TextField``. You can also perform a related lookup on a ``ForeignKey`` or
+    These fields are typically text fields such as ``CharField`` or
+    ``TextField``, but non-text fields like ``IntegerField`` can also be
+    searched. Adding an explicit lookup, such as ``age__exact``, lets the
+    search use that lookup directly instead of casting the value to text. You
+    can also perform a related lookup on a ``ForeignKey`` or
     ``ManyToManyField`` with the lookup API "follow" notation::
 
         search_fields = ["foreign_key__related_fieldname"]
@@ -1257,17 +1260,23 @@ subclass::
         search_fields = ["user__email"]
 
     When somebody does a search in the admin search box, Django splits the
-    search query into words and returns all objects that contain each of the
-    words, case-insensitive (using the :lookup:`icontains` lookup), where each
-    word must be in at least one of ``search_fields``. For example, if
-    ``search_fields`` is set to ``['first_name', 'last_name']`` and a user
-    searches for ``john lennon``, Django will do the equivalent of this SQL
-    ``WHERE`` clause:
+    search query into search terms and returns all objects that contain each
+    of them in at least one of ``search_fields``. By default, the
+    :lookup:`icontains` lookup is used for text fields. For non-text fields
+    with an explicit lookup (e.g., ``age__exact``), the specified lookup is
+    used, and search terms that are invalid for that field type are skipped.
+
+    For example, if ``search_fields`` is set to
+    ``['first_name', 'last_name', 'age__exact']`` and a user searches for
+    ``john 25``, Django will do the equivalent of this SQL ``WHERE`` clause:
 
     .. code-block:: sql
 
         WHERE (first_name ILIKE '%john%' OR last_name ILIKE '%john%')
-        AND (first_name ILIKE '%lennon%' OR last_name ILIKE '%lennon%')
+        AND (first_name ILIKE '%25%' OR last_name ILIKE '%25%' OR age = 25)
+
+    Note that ``john`` is not searched on ``age`` because it's not a valid
+    integer, while ``25`` is searched on all three fields.
 
     The search query can contain quoted phrases with spaces. For example, if a
     user searches for ``"john winston"`` or ``'john winston'``, Django will do
@@ -1298,6 +1307,11 @@ subclass::
     :meth:`ModelAdmin.get_search_results` to provide additional or alternate
     search behavior.
 
+    .. versionchanged:: 6.1
+
+        On earlier versions, search terms invalid for a given field type were
+        not skipped.
+
 .. attribute:: ModelAdmin.search_help_text
 
     Set ``search_help_text`` to specify a descriptive text for the search box