ORMs e o problema N+1

O que um ORM faz

O código trabalha com objetos: um Pedido tem um Cliente e uma lista de Itens. O banco relacional trabalha com tabelas e chaves. Um ORM (Object-Relational Mapper) faz a ponte entre os dois mundos.

Em vez de escrever SQL e montar os objetos à mão, você declara as classes e os relacionamentos, e o ORM gera as consultas:

const pedido = await orm.pedido.buscarPorId(981);
console.log(pedido.cliente.nome);

Por baixo, ele escreve algo como SELECT ... FROM pedidos WHERE id = 981, transforma a linha num objeto e, quando o código pede pedido.cliente, busca o cliente também.

Os ORMs mais usados: Prisma e TypeORM em TypeScript, SQLAlchemy e o ORM do Django em Python, GORM em Go, Hibernate e JPA em Java, Entity Framework Core em C#.

A coluna da direita é a origem do problema deste tópico.

Carregar agora ou carregar depois

Quando o código busca um pedido, o ORM precisa decidir o que fazer com os relacionamentos dele. Há duas estratégias:

• Carregamento antecipado (eager loading): busca o pedido e o cliente juntos, de uma vez.
• Carregamento tardio (lazy loading): busca só o pedido. O cliente é buscado no momento em que o código acessa pedido.cliente, com uma nova consulta.

O carregamento tardio parece econômico: só busca o que for usado. O problema aparece quando o acesso acontece dentro de um laço.

O problema N+1

A tela de pedidos mostra os 100 pedidos mais recentes, com o nome do cliente de cada um:

const pedidos = await orm.pedido.listar({ limite: 100 });

for (const pedido of pedidos) {
  console.log(pedido.id, pedido.cliente.nome);
}

O código tem uma consulta visível. O banco recebe 101:

SELECT * FROM pedidos ORDER BY id DESC LIMIT 100;   -- 1 consulta
SELECT * FROM clientes WHERE id = 4242;             -- e mais uma
SELECT * FROM clientes WHERE id = 117;              -- para cada
SELECT * FROM clientes WHERE id = 8810;             -- pedido...
-- ... 97 consultas iguais

É daí que vem o nome: 1 consulta para a lista e N consultas para os itens dela. O mesmo resultado sai de uma única consulta com junção:

SELECT p.id, c.nome
FROM pedidos p
JOIN clientes c ON c.id = p.cliente_id
ORDER BY p.id DESC
LIMIT 100;

Por que ninguém percebe

O N+1 passa pelos testes e pela revisão por três motivos:

• Em desenvolvimento, a lista é pequena. Com cinco pedidos, são seis consultas, e a tela abre na hora.
• O banco local responde rápido. Na mesma máquina, cada ida e volta leva uma fração de milissegundo.
• O código parece correto. Não há SQL à vista, e o acesso a pedido.cliente parece só ler um campo.

Medimos a diferença no PostgreSQL, com 100 pedidos:

Na mesma máquina, a diferença já é de quase 20 vezes, mas 16 milissegundos ainda parecem aceitáveis. Em produção, o banco fica em outra máquina, e cada consulta paga a ida e a volta pela rede. A coluna da direita acrescenta um pequeno atraso a cada consulta para simular isso: a tela passa de 2 para 227 milissegundos. Com várias listas na mesma página, ou com uma lista dentro de outra, o tempo chega a segundos.

O N+1 não é exclusivo de ORMs

O ORM facilita o problema, porque esconde as consultas, mas ele aparece em qualquer lugar onde um laço faz uma chamada por item:

• código sem ORM que chama buscarCliente(id) dentro de um for;
• resolvedores GraphQL, em que cada campo é resolvido separadamente (o tópico de estilos de API mostra esse caso);
• chamadas a outro serviço por HTTP, uma por item da lista;
• leituras de cache, uma chave por vez em vez de várias de uma vez.

A forma de resolver é a mesma em todos: juntar as buscas numa só, ou em poucas.

Por que isso importa quando a IA escreve o código

Assistentes escrevem código com ORM fluente e idiomático, e é exatamente esse estilo que esconde o N+1:

• O relacionamento é acessado dentro do laço de montagem da resposta, com carregamento tardio.
• Um laço chama uma função auxiliar que, sem estar à vista, faz uma consulta.
• Para "corrigir" um erro de relacionamento não carregado, o carregamento tardio é ligado globalmente.
• A correção traz todas as colunas de todas as tabelas relacionadas, quando a tela usa duas.

O próximo nível compara as formas de carregar relacionamentos e as ferramentas para detectar o problema.