Fixed #26379 - Documented that first filter() chained to a RelatedManager is sticky. by annalauraw · Pull Request #20085 · django/django

annalauraw · 2025-11-12T15:22:00Z

Trac ticket number

Branch description

Document that first filter() chained to a RelatedManager is sticky. Add heading "Filters on RelatedManager" to docs/topics/db/queries.txt. Document the sticky filter behaviour with a query example based on the models Author and Entry at the top of the docs page.

Checklist

This PR targets the main branch.
The commit message is written in past tense, mentions the ticket number, and ends with a period.
I have checked the "Has patch" ticket flag in the Trac system.
I have added or updated relevant tests.
I have added or updated relevant docs, including release notes if applicable.
I have attached screenshots in both light and dark modes for any UI changes.

jacobtylerwalls

Great start @annalauraw. I agreed with your hesitance to get too digressive here. Just a few questions.

docs/topics/db/queries.txt

jacobtylerwalls · 2025-11-12T21:28:45Z

docs/topics/db/queries.txt

+Filters on RelatedManager
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When calling ``filter()`` on a


Curious, does exclude() behave the same? We have one weirdness doc'd here:

django/docs/topics/db/queries.txt

Lines 660 to 664 in a1ce852

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.

It is probably coherent to talk about exclude() in this context as well. I tried exclude() with our so-far example: https://dryorm.xterm.info/ebqiqyqf. I suppose this behaviour can be called "different from filter()", since e2 is returned despite having taylor as a co-author. i need some time to understand the underlying SQL WHERE clause...

Ah, okay. I feel like that's the same class of behavior as what I linked to as "one weirdness" above. Simon discusses this in his "What the JOIN?" talk at 39:41, "when negating against a multi-valued relationship..." and calls it a "subquery pushdown".

I don't feel like we have to document the weirdness in detail twice, but I'm open to a sentence that clarifies or maybe links to the other section with details 🤔

After looking into the exclude() behaviour a bit deeper, I would say that in this case, it behaves similarly to filter(), although implemented differently:

single exclude(): co-authored entry is not excluded despite matching the exclude criteria

double exclude(): co-authored entry is excluded as expected

https://dryorm.xterm.info/t6p0rdrc

I see. Just like the filter() example, the sticky scenario is excluding on something that logically can't exist (a single row referring to both authors). I like how you got this expressed without drowning in details 👍

docs/topics/db/queries.txt

jacobtylerwalls · 2025-11-12T21:47:12Z

docs/topics/db/queries.txt

+:class:`~django.db.models.fields.related.RelatedManager`, be aware that the
+first method call is "sticky". Consider the following example:


There could be an alternative here that leaves the reader in a bit less suspense, not needing to read to the end to finally find out what "sticky" is. Having sat with this, can you think of anything? Maybe:

be aware that the first filter call reuses the blah blah blah—in other words, it's "sticky".

I will try. I really struggled with a concise explanation and felt the need to move to the example as quickly as possible.

That's fair!

New version reads well here.

…ion is sticky.

jacobtylerwalls

Thanks for the PR, @annalauraw, this looks great!

jacobtylerwalls · 2025-11-17T19:00:52Z

docs/topics/db/queries.txt

+between one author and one entry - can fulfill the query condition (entries
+that are co-authored by ``anna`` and ``gloria``). You can circumvent this
+behavior by chaining two consecutive ``filter()`` calls, resulting in two
+separate joins and thus a more permissive filter.


This reads perfectly, thank you ⭐

jacobtylerwalls · 2025-11-17T19:04:14Z

docs/topics/db/queries.txt

+    >>> anna.entry_set.filter().filter(authors__name="Gloria")
+    <QuerySet [<Entry: Supporting social movements with drums>]>
+
+.. note::


We avoid bare notes in favor of an admonition:: my heading so that we can use a heading (I'll add one for you).

jacobtylerwalls · 2025-11-17T19:16:57Z

docs/topics/db/queries.txt

+Filters on RelatedManager
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When calling ``filter()`` on a


I see. Just like the filter() example, the sticky scenario is excluding on something that logically can't exist (a single row referring to both authors). I like how you got this expressed without drowning in details 👍

jacobtylerwalls · 2025-11-17T19:17:29Z

docs/topics/db/queries.txt

+:class:`~django.db.models.fields.related.RelatedManager`, be aware that the
+first method call is "sticky". Consider the following example:


New version reads well here.

annalauraw · 2025-11-18T06:49:37Z

Thank you so much @jacobtylerwalls, that was a great review experience!

annalauraw force-pushed the ticket_26379 branch from 4104dfd to 9519364 Compare November 12, 2025 15:28

jacobtylerwalls added the Djangonauts 🚀 label Nov 12, 2025

jacobtylerwalls reviewed Nov 12, 2025

View reviewed changes

annalauraw force-pushed the ticket_26379 branch from 0758729 to 5f9b419 Compare November 15, 2025 11:40

Fixed #26379 -- Doc'd that the first filter() on a many-to-many relat…

1d446db

…ion is sticky.

jacobtylerwalls force-pushed the ticket_26379 branch from 5f9b419 to 1d446db Compare November 17, 2025 19:23

jacobtylerwalls approved these changes Nov 17, 2025

View reviewed changes

jacobtylerwalls merged commit 3c005b5 into django:main Nov 17, 2025
30 checks passed

	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.

		:class:`~django.db.models.fields.related.RelatedManager`, be aware that the
		first method call is "sticky". Consider the following example:

Uh oh!

Comments

Conversation

annalauraw commented Nov 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Trac ticket number

Branch description

Checklist

Uh oh!

jacobtylerwalls left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jacobtylerwalls left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

annalauraw commented Nov 18, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

annalauraw commented Nov 12, 2025 •

edited

Loading