[1.8.x] Refs #14645 -- Documented bug with exclude() and multi-value relations

entry that contains a tag with a name of *"music"* and a status of *"public"*.

To handle both of these situations, Django has a consistent way of processing

:meth:`~django.db.models.query.QuerySet.filter` and

:meth:`~django.db.models.query.QuerySet.exclude` calls. Everything inside a

:meth:`~django.db.models.query.QuerySet.filter` calls. Everything inside a

single :meth:`~django.db.models.query.QuerySet.filter` call is applied

simultaneously to filter out items matching all those requirements. Successive

:meth:`~django.db.models.query.QuerySet.filter` calls further restrict the set

may not be the same as the entries in the first filter. We are filtering the

``Blog`` items with each filter statement, not the ``Entry`` items.

All of this behavior also applies to

:meth:`~django.db.models.query.QuerySet.exclude`: all the conditions in a

single :meth:`~django.db.models.query.QuerySet.exclude` statement apply to a

single instance (if those conditions are talking about the same multi-valued

relation). Conditions in subsequent

:meth:`~django.db.models.query.QuerySet.filter` or

:meth:`~django.db.models.query.QuerySet.exclude` calls that refer to the same

relation may end up filtering on different linked objects.

.. note::

    The behavior of :meth:`~django.db.models.query.QuerySet.filter` for queries

    that span multi-value relationships, as described above, is not implemented

    equivalently for :meth:`~django.db.models.query.QuerySet.exclude`. Instead,

    the conditions in a single :meth:`~django.db.models.query.QuerySet.exclude`

    call will not necessarily refer to the same item.

    For example, the following query would exclude blogs that contain *both*

    entries with *"Lennon"* in the headline *and* entries published in 2008::

        Blog.objects.exclude(

            entry__headline__contains='Lennon',

            entry__pub_date__year=2008,

        )

    However, unlike the behavior when using

    :meth:`~django.db.models.query.QuerySet.filter`, this will not limit blogs

    based on entries that satisfying both conditions. In order to do that, i.e.

    to select all blogs that do not contain entries published with *"Lennon"*

    that were published in 2008, you need to make two queries::

        Blog.objects.exclude(

            entry=Entry.objects.filter(

                headline__contains='Lennon',

                pub_date__year=2008,

            ),

        )

.. _using-f-expressions-in-filters: