Auto-prefetching with model field fetch modes in Django 6.1 with Jacob Walls

This video features Jacob Walls at DjangoCon US 2026 in Chicago, Illinois, USA.

Auto-prefetching with model field fetch modes in Django 6.1 with Jacob Walls
0:24:07
Published October 26, 2026
194 views

New in Django 6.1, model field fetch modes provide a way to avoid the deluge of queries from accessing un-fetched objects during a loop (also known as the "N+1 queries" problem). You may be familiar with how Django's prefetch_related() and select_related() methods can prevent these queries, but unlike those tools, the "fetch peers" mode does not require maintaining a list of fields to fetch. This can significantly improve project maintenance, especially when QuerySets are constructed at some distance from where they are used.

In this talk, we'll cover what's new about fetch modes, what tradeoffs are entailed, how to configure fetch modes per-model via managers, and how to use the "raise" mode to surface issues in development or put guardrails around performance-intensive sections of code.

This talk was presented by Jacob Walls at DjangoCon US 2026 in Chicago, Illinois, USA
https://2026.djangocon.us/talks/auto-prefetching-with-model-field-fetch-modes-in-django-6-1/

Transcript

4,655 words · auto-generated · en Show

Automatically transcribed, so expect mistakes in names and technical terms.

0:15

Speaker 1: Thanks so much. Thanks for coming to this talk. A word about me before we get started. Uh it's my handle on GitHub and it's my avatar where I'm squinting into the sunlight. My background is in music composition and technology. Uh that's how I got hooked on programming. My f the first niches that I worked on or worked in as a professional programmer were in music education and music technology. Um and I've been a Django contributor and user since around 2020. Those periods actually overlapped pretty neatly. So I highly, highly recommend if you have even the smallest inkling in contributing. It's an amazing experience because it can really level up your um your knowledge as a Django user. And I've had the privilege of working as a Django fellow since this time last year in 2025, where I have the ability to spend paid working time maintaining the framework, doing pull request reviews and

1:00

Speaker 1: security triage, that kind of thing. And it's been a pleasure to work alongside my brilliant colleagues Natalia and Sarah. So in this talk, I'm going to talk about the background for this new feature in Django 6. 1, model field fetch modes. You heard about it this morning in Karen's keynote. I'm going to talk about the the problem that it addresses and the most closely analogous tool Django already has for this problem. And I'm going to show you what that closely related tool, Select Related, has in terms of pain points. um that motivated this new tool. I'm going to talk briefly what the thr about what the three fetch modes are in Django 6. 1. I don't want to hold you in too much suspense, so we'll do the quick version now. Fetch 1 is what you're used to in Django's ORM for the last 21 years. Um there's serial fetching for any deferred field that you access during a loop.

1:47

Speaker 1: Fetch peers is what's new. And it's a way to instruct Django, hey, I'm likely to process all of the instances in this loop the same way. So please fetch them all before I need them. So you can avoid serial processing or serial fetching. And then fetch raise is an interesting tool that you can use to raise an exception at the moment that you would have encountered an N plus one queries problem. You can tell Django to raise an exception, so you can do something interesting with it. catch it in some outer layer. It's great both for debugging, but you could also use it in production if you want to be absolutely sure that you don't have some sort of catastrophic performance problem. I'm gonna talk briefly about how we got here, because this has a this feature request has a long history. It's kind of interesting. And I want to give you my my mental model for when to use the fetch

2:33

Speaker 1: peers fetch mode and when not to. It's tempting to think the new shiny thing is something you want to apply, sprinkle all over your code. But there are some questions to ask before you use it. If you want to use this uh any of these fetch modes on all of the query sets that pertain to one of your models, there's a syntax for just declaring that once on your model. And I'm going to show an extension. We're only shipping three fetch modes, but there's nothing to stop you from writing a fourth if you have a different side effect that you'd like to perform besides raising an exception, for instance. So I'm gonna walk you through that as well. Okay. So uh all of that is to say this talk is just about adding some nuance around this feature. Um I gave a version of this talk um

3:19

Speaker 1: at Django Cont. Europe earlier this year and it was is had the interesting experience of three questions during the QA were all a form of the same question. Can I please have a global setting to turn this on everywhere? So I've tried to work my answer to that question into this talk and the answer boils down to nuance. There's a I think there's a reason that you might be sympathetic to once you once you hear it. But on the flip side, I don't think what you see today is going to be the last word on the subject. I think there will be feature development in this area to continue fleshing out this feature. Okay. So just a quick introduction to the so-called N plus one queries problem if it's something that you haven't worked with or seen before. The simplest version of the N plus one queries problem is presented in this snippet. I have books and I have authors.

4:05

Speaker 1: Let's say that there's just a single value relationship there, no co-authors to worry about. On line one, I'm fetching a set of books. On line two, I'm evaluating that set. And then on line three, I only have a single book in hand, and I'm dotting into dot author. Django's default behavior is to defer that relation. So when I get to line three, the author has not been fetched from the database Because I have book on one side of the dot, an author on the other side of the dot, that's one book, that's one author, it's not mysterious at all what's going to happen. One author is going to be fetched for that one book. But if you have more loop iterations, that'll be more queries for single authors for single books. You would never if you you would never write that by hand in SQL, right? If you had as n because as n grows large, that's a lot of SQL, right? But with an ORM you can end up in the situation

4:51

Speaker 1: and it's a situation to avoid as n becomes large. So the reason it's called n plus one is you have n books plus that one query at the top of the snippet. The performance of dynamic web applications often hinges on the database, the network latency of going to and from the database. Uh i y sometimes this is not a problem. If this lookup is fast, if n is small, you can get away with it. But often you end up in situations where this becomes a p a problem. uh that you need to avoid when using the ORM. So what have the last 21 years looked like? Django has shipped two helpers to get you out of the situation, and my mental model for these two helpers usually correspond to whether the relationship that's been deferred is single-valued or multi-valued. So for the single-valued situation, just fetching a single author for a single book, the traditional tool you would use is select

5:39

Speaker 1: related. It takes a list of relation names. And it joins all those relations together so that in a single query you can get all the data you need for the other relations. In the multi-value direction, you would reach for prefetch related. It also takes a list of relation names. And it does an additional query per relation that you pass in. And what it does is it adds a where clause to just stuff in the results of the first query. So it's multiple queries, but it's still a lot better than n plus one. Footnote, prefetch rel this is my mental model, but prefetch related also works in the single-valued relation direction. So for my example of book and author, there's nothing stopping you from calling prefetch related and passing in author as the relation name. Uh again, two queries is still a lot better than n plus

6:25

Speaker 1: one. Uh Tim McCurk has a great uh talk from DjangoCon US. last year where he walks through some of the motivations for why you might want to use prefetch related even when you have a single valued relationship. Maybe your table is wide or maybe the joint is expensive for some obscure reason in the query planner. I'm not going to go into that. Go watch his talk But I'm pointing this out because this is kind of the strategy of the fetch-peers-fetch mode. The fetch-peers-fetch mode does an on-demand pre-fetch for single-valued relations. So that's my mental model for this. It's like pre-fetch related for this But in cases where you would have traditionally used select related for single-valued relationships. That's the use case. What's the pain point that this is addressing? Everything I just showed you required passing in a list of relation names.

7:13

Speaker 1: What if you forget one? Code changes, right? What if you have not enough specified or what do you have too many specified? You have to keep the relation names in sync with your use of the query set. And that can become a problem as the distance between Your definition of the query set and its use grows. And that little snippet, it was not a problem. But what if you're not responsible for the query set? What if you're writing code that's just consuming Somebody else's um somebody else's algorithm, or what if you're writing a reusable app and you don't exactly know where your query set came from What if you have several templates between the query set and its eventual use? What if the query set is being handed down through several layers of serialization? This is where the pain points start to hit. Because it's it's um yeah very easy for the list of relation names to become um

7:58

Speaker 1: not maintained Also, a failure mode is just finding out after the fact. Sometimes you don't find out about this problem until you look at Django debug toolbar or until you're looking at sentry reports. So these are all addressed by having strategies for fetching a model field or not. Other ORMs have things like strategies for fetching, and so we're just calling them fetch modes. Um what should the basic question is what should take place when a deferred field is loaded? We've given you a new query set method called fetch mode And you can supply a fetch mode to that method to it to give your instruction, how should this query set behave when a related, when a deferred field is about to be accessed. So fetch one is the status quo. And fetch peers is how you can instruct Django, fetch the deferred fields for all instances that came from the same query set.

8:46

Speaker 1: And it kind of presumes that all instances should be processed the same way. And fetch raise raise fetch raise instead will at the moment that an N plus one query problem would have happened, raises an exception instead. Okay, so just to reiterate, the fetch beers fetch mode avoids n plus one queries in this snippet because it acts like prefetch related for single-valued relationships potentially replacing select related. The follow-up queries are on demand and you don't have to maintain a list of fields. What can you use it with? You can use it with foreign keys, because those are single-valued. You can use it with one-to-one field, which is just a special case of foreign key, as well as the reverse accessor on the one-to-one field.

9:32

Speaker 1: Uh generic relations for generic foreign keys, another special case of foreign key you can use it with. And you can use it for things besides relations. You can use it for fields. Django eagerly fetches fields on a model. But if you have decided to introduce laziness by deferring some of them, but then your code changes its mind and tries to access them later, you're also in a deferred situation where Django needs to know what to do when encountering um Uh when your code decides to load those fields anyway. And it works at all depths. So you can specify on the original query set what fetch strategy to what fetch mode to use. And as long as you're traveling in the single valued relation direction, it will cascade down to everything else in the tree that you might be trying to dot into. So You dot into book. author, and then you've got another foreign key to ghostwriter, book.

10:18

Speaker 1: author. ghostwriter. Just one instruction will cascade down throughout all the single-valued relations in your tree. Notice I keep hammering on single-valued related managers are in charge of fetching the multi-valued relationships. Those are not affected. Um the rationale for that is that in this snippet, like let's say we're going in the other direction. Let's say I want to iterate authors and go back to books. That's a multi-valued relationship. And to do that, I access an author and I call its related manager. books. all. books is a related manager. It's in charge of deciding how to fetch. the books. You can imagine some incon you can imagine some conflicting instructions here. If we tried to cascade that instruction about how to fetch down to all the related managers, we might be clashing with instructions that the book manager has about how to fetch

11:06

Speaker 1: The book manager is the one that's in charge of the fetch strategy for the books. So just to reiterate, the cascade behavior I described is only for the single value direction. I've also shown you how to inspect the the um the instruction that you've given. So you can dot into the underscore state on a model instance and get some information about what fetch mode was specified. And even in this snippet, it will show that the fetch peer strategy was requested. But I'm just cautioning you that It will not have an effect on the book manager because once again, it's for single-valued relationships. The book manager is the one in charge of providing the instructions about how to fetch. How did we get here? This feature was requ well, prefetch related landed in Django 1. 4, if I'm not mistaken.

11:52

Speaker 1: And then very next year there was discussion on the Django developers mailing list about hey, how can we get more automatic behavior without having to specify a list of relation names. The ticket was accepted in 2017 after being shepherded by Gordon Wrigley, who's the original author of the Django Auto Prefetch package. Um there was some more discussion of this feature, I'm sure, at many Django Cons, but the evidence that I saw when watching prior talks was in Simon Charette's 2022 keynote at DjangoCon US. He referred to this feature as one of the major missing features in the ORM. So personally I'm just excited to see something that's come up so many times finally land. In Django, it landed last fall in a pull request authored by Adam Johnson and others, who who main Adam maintained that original package by Gordon. And

12:37

Speaker 1: the final release came out this month Okay, so now I want it to give you yeah. Now I want to give you the um the Burst your bubble just a little bit. I want to give you my mental model for when you might not want to use fetch peers. It can amplify existing overfetching. So on line one, I'm using the fetch peers fetch mode. On line two, I'm getting all of the books, I'm stuffing them into a list, and then I'm throwing away all of the rest except the first one. If I'm using fetch one, that's not so bad, because then book. author only fetches one author. If I'm using fetch peers, that's going to fetch all of the other authors I don't care about for all of the other books that I don't care about. This is not a situation where you want to use fetch peers. Luckily there's a solution and it's more about

13:24

Speaker 1: using like more idiomatic Django here is to just not call list, is to just slice into that query set and Be explicit about the only book that you want. Maybe you want to do dot first instead of slice, I don't know, what I don't know your data model. But um so this is one thing to think about when you start using the fetch mode. Make sure you're not gonna amplify any existing overfetching A second reason you might prefer fetch one is when serial processing matters. So in this snippet it starts similarly. I'm gonna try to use the fetch peers fetch mode. I'm gonna iterate some books. And on line three, I'm going to do something that affects authors. Maybe it fires off a query set update and updates multiple authors in some sort of batch. I go down to line six the first time through the loop, I'm good. The fetch peers fetch mode is lazy, so I get a fresh query for the author on line six, and I'm caught up with all of the updates.

14:13

Speaker 1: But then the next iteration through the loop The author has already been fetched for all the other books in the query set. All the peers have already had their author fetched. Now on line three I do something affecting authors. What do I expect in line six? So if you're going to start using fetch peers, I implore you to look at your code and make sure that you don't have like do something affecting authors and it's going to change some assumptions about um When your data is fetched. Along the same lines, if you're using the fetch peers fetch mode, you're doubling down on lazy data fetching. So remember I said these additional queries are on demand. They happen at the moment you would have dotted into book. author. What if there's a lot of code in between that? At the top of the snippet, I've defined my query set. Then let's say a bunch of stuff happens. Maybe some other request comes in and fires off that author

14:59

Speaker 1: dot delete. Now at the bottom, more time has intervened, and now I'm finally dotting into book. author. Do I need to be prepared to catch author does not exist? This is not a problem you would have had with select related because it's all joined together from the get-go. Prefetch related, interestingly, also has this small window because it's multiple consecutive queries. It's probably a matter of milliseconds only, but theoretically something could have happened, something interesting could have happened between those two queries But with fetch peers, you're spreading that window wider, right? So just something to think about. If you use fetch peers, you're doubling down on lazy data fetching. Make sure that your code can support that. Okay, those were my three questions for you. Will I amplify overfetching? Will I violate any assumptions of serial processing, and will I need to catch any exceptions?

15:48

Speaker 1: Um and then the fetch raise mode. Like I said, this is useful in development if you want to debug your code. It's also useful in production if you want to prevent like catastrophic, you know, dot child dot child dot child dot child dot child. You'd rather raise an exception and catch it somewhere than have catastrophic traffic in your database. Okay, that's the syntax for avoiding repeating yourself all over the place. Django has a documented pattern for um defining the behavior of model um of query sets that come from models and you use a model manager to do that. So this example is in the docs. The only twist that I've given is I've called the manager fetch peers manager instead of book manager Just to show you that you could reuse this manager on multiple models. So if you have 100 models, we're not forcing you to define 100 model managers.

16:34

Speaker 1: You could reuse it. Because all that it's doing is just saying use the fetch peers mode. Uh some of you might have custom query sets and you may say, oh dang, I I prefer custom query sets instead of custom model managers. Now you're telling me I need a custom model manager. There is a syntax for having both. uh showing that on the last line of the snippet. Um look into the from query set method in Django. Um it allows you to have your cake and eat it too by having reusable query methods like Def Search on a book query set. That's specific to book, but also reusing a generic model manager that you could reuse with all of your models. Okay, so showing the slide again and talking about my experience giving a version of this talk at DjangoCon Europe and getting the question about, okay, it sounds great, Jacob.

17:20

Speaker 1: Can I have a setting for this? The reason I suspect that Django didn't ship this immediately is because if you just let's say you had a global setting to make fetch peers the default everywhere all the time, you've changed those three questions into not just will I amplify any overfetching Will my dependencies amplify any overfetching? Will my dependencies violate any assumption of serial processing? Will my dependencies need to catch object that does not exist? If you change the default fetch mode, you're making that decision for all of your dependencies And they may not be fetch peers friendly or they may not be fetch one explicit. By not providing this setting immediately, we're giving Django applications time to become fetch peers friendly or fetch one explicit. And then we can revisit this question of You know, should we have a setting?

18:06

Speaker 1: Okay, Jacob, but I simply must have a setting. Uh you can do it with uh Patching Django, you've seen other talks of this conference that patch Django and the app config ready method. We've made it relatively easy for you to do this. It's not documented, but there's just one constant you have to override. There's the default fetch mode constant on the query submodule. And I have this sort of sad comment, ready or not, force all dependencies to default to fetch peers. Okay. And then finally an extension. Um obviously you may be thinking raising an exception sounds great, but Jacob, could I please just have a warning instead? Um it's not so difficult to do. The problem is what should happen after the warning. Should we fall back to the fetch one strategy or should we fall back to the fetch peer strategy? And so we ended, you know, what we've offered for you is that you can define what the fallback strategy is.

18:53

Speaker 1: So here it's just defined with inheritance. You can write a fetch mode, define what the fallback strategy is by inheriting from it And then perform a side effect. So in this case, emit a warning before delegating to fetch one. You do your warning, and then you just call the superclass. You can imagine doing all kinds of things other than warnings, like doing things with your instrumentation or or whatnot. Okay, I would love for you to play with this feature at the Sprints. I would love for you to test it out in your own projects, provide usability feedback, help us with the docs. Some of this material from this talk should probably end up in the docs in some form. I'd love to get some eyes on that. And you know, honestly, we should start dog fooding this in places in Django. We need to evaluate the admin. Are there places where the admin should be fetch peers friendly or fetch one

19:41

Speaker 1: explicit? Django Project. com, similar question. Are there places where we could be using fetch peers or be fetch one explicit? It's exciting time, so I hope you'll grab me if you're interested in that. Thank you.

20:02

Speaker 2: Thanks, Jacob. That's this is really exciting. Quick question. Say you have a base manager, your query set, and you've chosen fetch peers. And down the stack, maybe in your view, you want to switch to raises. Is that possible and how does that kind of work?

20:23

Speaker 1: Yes. Um great question. So one of the s the slide that had the table and this showed all the three fetch modes was underneath a um a query set method like filter. So just like you can do dot filter, you can do dot fetch mode and iterate over that. So I can iterate over so so if your question is maybe I've got I want to override the default behavior from the model manager. Yes, you override that by calling the fetch mode method.

20:55

Speaker 3: If you've already got a rather mature code base that is thoroughly populated with select-related, prefetch related. Is there any advantage to changing to using a different fetch mode?

21:10

Speaker 1: Great question. Um my first A suggestion would be to in development only turn on the fetch raise mode. And it's like turning on a blacklight and seeing if there are any problems in your code that you didn't know about. Sorry, no, not I just mean like You know, whatever. Maybe whatever. Sorry about that. I'm in a hotel. What are you gonna do? Um uh the uh and because I've encountered people who said this at the Sprint 's DjangoCon Europe, like they started writing their own fetch modes to be make very specific decisions about for these models I want this behavior. For these models I want this behavior. Um I guess so that's that's one thing. Like find out if you're missing anything. But also I would be interested in the costs that you've you've gone to to To maintain those list of relation names. Was that a high cost? If it was, you can make different decisions going forward.

21:57

Speaker 1: Okay.

21:57

Speaker 3: Thank you.

21:58

Speaker 1: Yeah.

22:12

Speaker 4: Thank you for your talk. I'm trying to formulate my question, but I guess I'm curious how do you how can you evaluate the impact on the data based on using one or the other at any given line of code. And what's the worst like so for the book. authors you have the n plus one problem. What's the worst problem you could have with fetch related or Using this other approach. Two questions here.

22:39

Speaker 1: Okay, great. So the second question was what's the worst case scenario if I mess it up? And the first question was how do I measure the benefit?

22:45

Speaker 4: Compare um

22:50

Speaker 1: How do I measure the increased efficiency if I move to fetch peers? Yeah, so I would I would use you know some instrumentation, so maybe Um you know I've heard some people say, well, I want to start using this feature just because I have too much noise in Sentry from these N plus one uh error reports. But if you're not using something like Sentry, you can use Django debug toolbar, you can turn on a query logger just in your settings file and you can observe the number of queries before and after. Django also ships in a cert num queries test helper. So you can look at tests that exercise your basic workflows and use that test helper to quickly evaluate. How many queries happened during this basic workflow versus how many queries happened afterward when using fetch peers? Um the second part of your question was like what's the worst case scenario? I tried to think of everything that could potentially put you off from using it and putting it on the slide.

23:38

Speaker 1: So Those are the only negatives that I can think of, and in some cases they're pre-existing problems like overfetching. So there's something kind of nice about being forced to write more idiomatic Django by using this new feature. Thanks.

23:51

Speaker 5: Thank you for your questions. And yeah, it's a good question.

Presenters

Conference

DjangoCon US

August 24 - 28, 2026

Chicago, Illinois, USA

Note: We understand that names change, people change, and bodies change. We respect each individual's journey and privacy. If you have any concerns about a video or need us to remove content, please don't hesitate to contact us. We will handle your request with care and promptly address any issues.

More videos by Jacob Walls

More videos from DjangoCon US