Consultas N+1: como detectá-las contando e corrigi-las com batching

O que é

O código carrega uma lista de N linhas pai com uma consulta e depois lê, em cada linha, uma relação carregada de forma lazy; o ORM emite uma consulta adicional por linha. A documentação do SQLAlchemy descreve o problema: para quaisquer N objetos carregados, acessar seus atributos lazy-loaded significa que serão emitidas N+1 instruções SELECT. O mesmo padrão aparece sem ORM: um loop que chama uma API HTTP para cada item, um resolver GraphQL que busca dados por nó, uma consulta ao cache por chave.

Por que importa

Cada consulta custa um round trip, por menos que retorne. Uma página de 200 linhas vira 201 round trips; o custo escala com os dados, não com o código, de modo que o problema é invisível numa fixture de teste com três linhas e só aparece em produção. Os logs de consultas lentas também não o revelam, porque cada uma das N consultas é rápida.

Como aplicar

• Detecte contando. Verifique nos testes o número de consultas por requisição (o assertNumQueries do Django, que verifica se uma chamada executa um determinado número de consultas; um event listener do engine no SQLAlchemy; um contador por requisição no logger de consultas) e faça o teste falhar quando a contagem depender do tamanho do resultado: execute a mesma requisição com 1 linha e com 50 linhas e compare.
• Faça os lazy loads indesejados falharem de forma explícita. O raiseload() do SQLAlchemy substitui o lazy loading por uma exceção, de modo que um novo acesso a atributo num template ou serializer aparece nos testes, e não como N+1 em produção.
• Corrija relações to-one com um join: select_related() no Django, joinedload() no SQLAlchemy. Uma só consulta, com linhas mais largas.
• Corrija coleções com uma segunda consulta baseada em IN (ids): prefetch_related() no Django, selectinload() no SQLAlchemy, que sua documentação prefere ao antigo subquery loading. Duas consultas em vez de N+1, sem multiplicação de linhas.
• Fora dos ORMs, aplique a mesma ideia: reúna primeiro as chaves, busque tudo numa única chamada e depois associe os resultados aos itens (o padrão DataLoader); para APIs remotas, use endpoints em lote ou concorrência limitada.
• O guia de otimização do Django recomenda entender quando os querysets são avaliados e quais atributos ficam em cache, e aplicar select_related() e prefetch_related() onde necessário, possivelmente em managers, com a ressalva de que o acesso a objetos relacionados usa o base manager, e não o default manager.

Armadilhas

Fazer join de uma coleção repete a linha pai para cada filho e pode ser mais lento do que duas consultas. Pré-carregar tudo desperdiça memória com campos que ninguém lê. Uma lista IN com dezenas de milhares de ids precisa ser dividida em blocos. A contagem de consultas é uma propriedade do caminho de código, não do modelo: um atributo a mais num serializer reintroduz o N+1, e é por isso que a verificação da contagem deve fazer parte da suíte de testes de forma permanente.