Все заметки
Программирование

N+1 в Django: одна страница, 500 запросов — select_related, prefetch_related и подсчёт запросов

Локально страница открывается мгновенно, а в production тормозит — потому что шаблон ходит в базу на каждой строке. Разбираем, как найти N+1, закрепить исправление тестом и когда нужен select_related, а когда prefetch_related.

Представьте страницу со списком заказов. В каждом заказе — имя клиента и список товаров. Локально в базе 5 тестовых заказов, страница открывается мгновенно. В production на странице 100 заказов, в каждом в среднем по 3 товара, — и страница заметно тормозит. В коде нет ни тяжёлых вычислений, ни вложенных циклов по базе. Но в базу уходит не один запрос, а около 500.

Это проблема N+1. Одна из самых частых проблем производительности в Django, потому что в коде её не видно: запросы выполняются «молча» внутри шаблона или сериализатора при обращении к обычному атрибуту.

Откуда берётся проблема

Модели простые:

# shop/models.py
from django.db import models


class Customer(models.Model):
    name = models.CharField(max_length=200)


class Product(models.Model):
    title = models.CharField(max_length=200)
    price = models.DecimalField(max_digits=12, decimal_places=2)


class Order(models.Model):
    customer = models.ForeignKey(
        Customer, on_delete=models.PROTECT, related_name="orders"
    )
    status = models.CharField(max_length=20, default="new")
    created_at = models.DateTimeField(auto_now_add=True)


class OrderItem(models.Model):
    order = models.ForeignKey(Order, on_delete=models.CASCADE, related_name="items")
    product = models.ForeignKey(Product, on_delete=models.PROTECT)
    quantity = models.PositiveIntegerField(default=1)

View выглядит совершенно безобидно:

# shop/views.py
from django.shortcuts import render

from .models import Order


def order_list(request):
    orders = Order.objects.order_by("-created_at")[:100]
    return render(request, "shop/order_list.html", {"orders": orders})

А шаблон такой:

{% for order in orders %}
  <h3>#{{ order.id }} — {{ order.customer.name }}</h3>
  <ul>
    {% for item in order.items.all %}
      <li>{{ item.product.title }} × {{ item.quantity }}</li>
    {% endfor %}
  </ul>
{% endfor %}

Посчитаем запросы:

  1. orders — 1 запрос за списком заказов.
  2. order.customer.name — клиент для каждого заказа: 100 запросов.
  3. order.items.all — позиции каждого заказа: ещё 100.
  4. item.product.title — товар для каждой позиции: 100 × 3 = 300.

Итого 1 + 100 + 100 + 300 = 501. Отсюда и название: «1 + N» (а у нас даже «1 + N + N + N×M»).

В DRF происходит то же самое, только ещё незаметнее:

# shop/serializers.py
from rest_framework import serializers

from .models import Order, OrderItem


class OrderItemSerializer(serializers.ModelSerializer):
    product_title = serializers.CharField(source="product.title")

    class Meta:
        model = OrderItem
        fields = ["id", "product_title", "quantity"]


class OrderSerializer(serializers.ModelSerializer):
    customer_name = serializers.CharField(source="customer.name")
    items = OrderItemSerializer(many=True)

    class Meta:
        model = Order
        fields = ["id", "status", "customer_name", "items"]

source="customer.name" и вложенный OrderItemSerializer — это тоже отдельные запросы на каждый объект. Читая сериализатор, догадаться об обращениях к базе сложно.

Почему «обычный» код не работает

Всё дело в ленивости Django ORM. Order.objects.order_by(...) ещё не выполняет никакого SQL — он лишь создаёт объект QuerySet. Запрос уходит, когда {% for %} в шаблоне начинает итерироваться.

order.customer — это дескриптор ForeignKey. При обращении к нему Django смотрит в кэш объекта; если клиента там нет, выполняется SELECT ... FROM shop_customer WHERE id = %s. Обратная связь order.items.all() каждый раз возвращает новый QuerySet, который вычисляется отдельным запросом WHERE order_id = %s.

Каждый запрос по отдельности быстрый — выборка одной строки по индексу может занимать долю миллисекунды. Но у каждого есть сетевой round-trip, разбор SQL, работа с соединением и создание Python-объектов из результата. Повторите это 500 раз — и именно это станет основной частью времени ответа. Хуже всего то, что число запросов растёт вместе с данными: на тестовой базе ничего не заметно, а в production становится всё хуже.

N+1 — это не медленный запрос, а много быстрых. Поэтому его находят не через EXPLAIN, а подсчётом запросов.

Считаем запросы: connection.queries, CaptureQueriesContext, assertNumQueries

Самый простой способ — django.db.connection.queries, но он заполняется только при DEBUG=True. Удобнее CaptureQueriesContext: он не зависит от DEBUG и работает где угодно:

# python manage.py shell
from django.db import connection
from django.template.loader import render_to_string
from django.test.utils import CaptureQueriesContext

from shop.models import Order

orders = Order.objects.order_by("-created_at")[:100]

with CaptureQueriesContext(connection) as ctx:
    render_to_string("shop/order_list.html", {"orders": orders})

print(len(ctx.captured_queries))
for q in ctx.captured_queries[:5]:
    print(q["sql"])

Обратите внимание: шаблон рендерится внутри контекста. Поскольку QuerySet ленивый, если обернуть только строку orders = ..., вы увидите 0 запросов — реальная работа происходит при рендеринге.

В разработке очень помогает django-debug-toolbar: он показывает список запросов для каждой страницы и отдельно помечает повторяющийся SQL.

Но главное — тест. Исправленный N+1 легко вернуть: кто-то добавит в шаблон {{ order.customer.phone }}, и всё сломается снова. Закрепляем количество запросов через assertNumQueries:

# shop/tests.py
from django.test import TestCase
from django.urls import reverse

from .models import Customer, Order, OrderItem, Product


class OrderListQueryCountTest(TestCase):
    @classmethod
    def setUpTestData(cls):
        for i in range(10):
            customer = Customer.objects.create(name=f"Customer {i}")
            order = Order.objects.create(customer=customer)
            for j in range(3):
                product = Product.objects.create(title=f"P{i}-{j}", price=10)
                OrderItem.objects.create(order=order, product=product, quantity=1)

    def test_query_count_does_not_grow_with_rows(self):
        with self.assertNumQueries(2):
            response = self.client.get(reverse("order-list"))
        self.assertEqual(response.status_code, 200)

Важный момент: в тестовых данных должно быть несколько заказов и по несколько позиций в каждом. С одним заказом N+1 может выглядеть как те же «2 запроса». Кроме того, middleware (сессии, аутентификация) может добавлять свои запросы — один раз проверьте ожидаемое число вручную.

select_related предназначен для связей «к одному»: ForeignKey и OneToOneField (включая обратный one-to-one). Django добавляет JOIN в основной запрос и собирает связанный объект из той же строки. В итоге order.customer уже лежит в кэше, и отдельный запрос не нужен.

Если ForeignKey объявлен с null=True, Django использует LEFT OUTER JOIN вместо INNER JOIN, чтобы заказы без клиента не выпали из результата.

Для связей «ко многим» (обратный ForeignKey, ManyToMany) JOIN — плохой вариант: каждая строка заказа размножится на число его позиций. Поэтому prefetch_related работает иначе:

  1. Сначала выполняется основной запрос, и получается список заказов.
  2. Django собирает их id.
  3. Отправляет один дополнительный запрос: WHERE order_id IN (...).
  4. Группирует результат по order_id на стороне Python и раскладывает по prefetch-кэшу каждого заказа.

Исправленный view:

# shop/views.py
from django.db.models import Prefetch
from django.shortcuts import render

from .models import Order, OrderItem


def order_list(request):
    items = OrderItem.objects.select_related("product").order_by("id")
    orders = (
        Order.objects.select_related("customer")
        .prefetch_related(Prefetch("items", queryset=items))
        .order_by("-created_at")[:100]
    )
    return render(request, "shop/order_list.html", {"orders": orders})

SQL, который уходит в базу, выглядит примерно так:

-- 1) select_related("customer"): one JOIN
SELECT "shop_order"."id", "shop_order"."customer_id", "shop_order"."status",
       "shop_order"."created_at", "shop_customer"."id", "shop_customer"."name"
FROM "shop_order"
INNER JOIN "shop_customer" ON ("shop_order"."customer_id" = "shop_customer"."id")
ORDER BY "shop_order"."created_at" DESC
LIMIT 100;

-- 2) prefetch_related("items") + select_related("product"): one IN query
SELECT "shop_orderitem"."id", "shop_orderitem"."order_id",
       "shop_orderitem"."product_id", "shop_orderitem"."quantity",
       "shop_product"."id", "shop_product"."title", "shop_product"."price"
FROM "shop_orderitem"
INNER JOIN "shop_product" ON ("shop_orderitem"."product_id" = "shop_product"."id")
WHERE "shop_orderitem"."order_id" IN (412, 411, 409, 408 /* ... */)
ORDER BY "shop_orderitem"."id" ASC;

100 заказов или 10 — всегда 2 запроса. Именно это и проверяет наш тест.

select_related prefetch_related
Тип связи ForeignKey, OneToOne обратный FK, ManyToMany, GenericRelation
SQL JOIN в основном запросе отдельный запрос, IN (...)
Число запросов 1 1 + по одному на связь
Где склеивается в базе в Python
Риск слишком много JOIN, широкие строки слишком длинный IN, много памяти

Объект Prefetch: какие строки и куда

prefetch_related("items") загружает все связанные строки. Часто этого мало: нужны только оплаченные заказы, в определённом порядке или с вложенным select_related. Для этого есть объект Prefetch — выше мы уже использовали его для items + product.

С to_attr результат сохраняется в отдельный атрибут в виде обычного list. Начиная с Django 4.2, queryset внутри Prefetch можно срезать — например, последние 3 оплаченных заказа каждого клиента:

from django.db.models import Prefetch

from shop.models import Customer, Order

last_paid = Prefetch(
    "orders",
    queryset=Order.objects.filter(status="paid").order_by("-created_at")[:3],
    to_attr="last_paid_orders",
)

customers = Customer.objects.prefetch_related(last_paid)

for customer in customers:
    for order in customer.last_paid_orders:  # plain list, no extra query
        print(customer.name, order.id)

У to_attr есть ещё одно преимущество: отфильтрованный результат не смешивается со стандартным customer.orders.all(), а по имени last_paid_orders сразу понятно, что внутри.

В DRF исправлять нужно в get_queryset view, сериализатор менять не обязательно:

# shop/api.py
from django.db.models import Prefetch
from rest_framework import generics

from .models import Order, OrderItem
from .serializers import OrderSerializer


class OrderListAPIView(generics.ListAPIView):
    serializer_class = OrderSerializer

    def get_queryset(self):
        return (
            Order.objects.select_related("customer")
            .prefetch_related(
                Prefetch("items", queryset=OrderItem.objects.select_related("product"))
            )
            .order_by("-created_at")
        )

Почему ленивая загрузка ломается в async-коде

Начиная с Django 4.1 у QuerySet есть async API: aget(), afirst(), acount(), async for. Поэтому такой код выглядит естественно:

# shop/views.py
from django.http import JsonResponse

from .models import Order


async def order_detail(request, pk):
    order = await Order.objects.aget(pk=pk)
    # SynchronousOnlyOperation: You cannot call this from an async context ...
    return JsonResponse({"id": order.id, "customer": order.customer.name})

aget() отработает, но order.customer.name выбросит SynchronousOnlyOperation. Причина: обращение к атрибуту — обычная синхронная операция, перед ней нельзя поставить await. А ленивой загрузке нужно как раз здесь сделать синхронный запрос в базу. Синхронная часть Django ORM, вызванная из event loop, намеренно падает с ошибкой, чтобы не заблокировать цикл.

То есть в async-контексте ленивой загрузки нет вообще — и это, по сути, защита от N+1. Всё нужное приходится загружать заранее и явно:

# shop/views.py
from django.db.models import Prefetch
from django.http import JsonResponse

from .models import Order, OrderItem


async def order_detail(request, pk):
    order = await (
        Order.objects.select_related("customer")
        .prefetch_related(
            Prefetch("items", queryset=OrderItem.objects.select_related("product"))
        )
        .aget(pk=pk)
    )
    items = [
        {"product": item.product.title, "quantity": item.quantity}
        for item in order.items.all()  # already in memory, no DB call
    ]
    return JsonResponse(
        {"id": order.id, "customer": order.customer.name, "items": items}
    )

Внутри aget() select_related и prefetch_related выполняются как обычно, а затем order.customer и order.items.all() читаются из памяти. Если связь не была загружена заранее, используйте async-методы вроде async for item in order.items.all() или await order.items.acount() — но в цикле это снова будет N+1. Кроме того, начиная с Django 5.0 aiterator() тоже поддерживает prefetch_related.

Ещё одна ловушка: если async view вызывает render(), шаблон рендерится в том же контексте, и {{ order.customer.name }} в шаблоне вызовет ту же ошибку.

Ловушки в production

Сломать prefetch-кэш своими руками. Prefetch работает только для .all(). Если вызвать у связанного менеджера filter(), exclude() или order_by(), Django отправит новый запрос:

orders = Order.objects.prefetch_related("items")

for order in orders:
    order.items.all()                      # from prefetch cache
    order.items.count()                    # from cache: len() of cached results
    order.items.filter(quantity__gt=1)     # NEW query for every order
    order.items.order_by("-quantity")      # NEW query for every order

Нужен фильтр — перенесите его в Prefetch(queryset=...). Нужно только количество — не делайте prefetch вовсе, посчитайте в базе:

from django.db.models import Count, Q

orders = Order.objects.annotate(
    items_total=Count("items"),
    bulk_items=Count("items", filter=Q(items__quantity__gt=1)),
)

only() и defer(). Если сделать Order.objects.only("id"), а в шаблоне обратиться к order.status, Django догрузит отложенное поле отдельным запросом для каждого объекта. Это тот же N+1 в другой одежде.

order.customer_id против order.customer.id. Первое — колонка в самом объекте, запрос не нужен. Второе (без select_related) загрузит клиента из базы. Нужен только ID — используйте атрибут _id.

Слишком много JOIN. select_related() можно вызвать без аргументов — тогда он по цепочке JOIN-ит все ForeignKey с null=False. Это широкие строки и лишние данные. Всегда указывайте поля явно.

Слишком длинный IN. Если делать prefetch по всей таблице без пагинации, в IN (...) попадут десятки тысяч ID, и всё это окажется в памяти. На страницах списков используйте пагинацию, в фоновых задачах — iterator(chunk_size=...): начиная с Django 4.1 он поддерживает prefetch_related, если передан chunk_size.

Связи в __str__. Если Order.__str__ возвращает self.customer.name, N+1 появится в админке, логах и выпадающих списках. Для админки используйте list_select_related или переопределите get_queryset.

Property и вычисляемые поля. Обращение к связанному объекту внутри property модели — классический источник N+1, невидимого в шаблоне. Если property используется в списке, проверьте, какой запрос за ним стоит.

Чеклист

  • Для каждой страницы списка и list-эндпоинта — тест с assertNumQueries, в тестовых данных несколько объектов.
  • ForeignKey/OneToOne — select_related, обратный FK и ManyToMany — prefetch_related.
  • Нужно фильтровать, сортировать связанные строки или добавить вложенный select_related — Prefetch(queryset=..., to_attr=...).
  • Нужно только количество или сумма — annotate(Count(...)), а не prefetch.
  • В DRF оптимизируйте в get_queryset и проверяйте каждый source="a.b" в сериализаторе.
  • В async view загружайте всё заранее; SynchronousOnlyOperation — сигнал «здесь ленивая загрузка».
  • В разработке ищите повторяющийся SQL через django-debug-toolbar или CaptureQueriesContext.
  • Нужен только ID — obj.fk_id.

Итог

N+1 вызван не медленными запросами, а их числом, которое растёт вместе с данными, поэтому его находят подсчётом и закрепляют через assertNumQueries. select_related загружает связи «к одному» через JOIN, prefetch_related — связи «ко многим» одним IN-запросом, а Prefetch позволяет точно управлять тем, что и куда загружается. Async-код вообще не допускает ленивой загрузки — и приучает загружать данные заранее и явно.

// комментарии

Загружаем комментарии...

    // следующий шаг

    Давайте построим что-нибудь вместе.

    Написать в Telegram
    aslbek@asldev: ~
    ❯