[3.1.x] Fixed #31894 -- Added note about using JSONField key lookups with QuerySet.exclude() in docs.

Backport of 17407eca59b0572228067cdee51433f49a1e0adb from master

1 files changed, 8 insertions, 0 deletions

diff --git a/docs/topics/db/queries.txt b/docs/topics/db/queries.txt
index f10d92576d..5e0ea8fa3e 100644
--- a/docs/topics/db/queries.txt
+++ b/docs/topics/db/queries.txt
@@ -910,6 +910,14 @@ To query for missing keys, use the ``isnull`` lookup::
     :lookup:`istartswith`, :lookup:`lt`, :lookup:`lte`, :lookup:`gt`, and
     :lookup:`gte`, as well as with :ref:`containment-and-key-lookups`.
 
+.. note::
+
+    Due to the way in which key-path queries work,
+    :meth:`~django.db.models.query.QuerySet.exclude` and
+    :meth:`~django.db.models.query.QuerySet.filter` are not guaranteed to
+    produce exhaustive sets. If you want to include objects that do not have
+    the path, add the ``isnull`` lookup.
+
 .. warning::
 
     Since any string could be a key in a JSON object, any lookup other than