🔍Laravel: Eloquent vs Query Builder — Qual usar para cada situação?

Por Paulo RB em 04/07/2025

No ecossistema Laravel, há duas formas principais de interagir com o banco de dados: o Eloquent ORM e o Query Builder. Ambos têm seu espaço, mas entender quando usar cada um é essencial para escrever código limpo, performático e fácil de manter.

Neste artigo, vamos comparar essas duas abordagens, mostrar exemplos reais de uso e apontar os cenários ideais para cada uma delas. Vamos nessa?

O que é o Eloquent?

O Eloquent é o ORM (Object-Relational Mapper) oficial do Laravel. Ele transforma tabelas em classes PHP, permitindo que você trabalhe com os dados como objetos.

Cada model representa uma tabela, e cada instância do model representa uma linha. Por trás das cortinas, o Eloquent é construído sobre o Query Builder, mas com uma interface orientada a objetos.

Exemplo real:

Copy Code


$candidato = Candidato::where('cpf', '123.456.789-00')->first();

Recursos do Eloquent:

Relacionamentos (hasMany, belongsTo, etc.)
Eventos (creating, updated, etc.)
Casts de atributos
Accessors e mutators
Soft deletes
Timestamps automáticos

O que é o Query Builder?

O Query Builder oferece uma forma fluente e segura de construir queries SQL diretamente, sem precisar criar models.

Ele é ótimo para consultas complexas, operações em massa ou quando você precisa de performance e controle granular da query.

Exemplo real:

Copy Code


$relatorio = DB::table('inscricoes')
    ->select('cargo_id', DB::raw('count(*) as total'))
    ->where('status', 'deferido')
    ->groupBy('cargo_id')
    ->get();

Comparativo: Eloquent vs Query Builder

Critério	Eloquent	Query Builder
Retorno	Modelos (objetos com métodos)	Objetos `stdClass`
Relacionamentos	Sim	Não
Lógica encapsulada	Sim	Não
Eventos (`creating`, etc.)	Sim	Não
Performance	Mais pesado	Mais leve e rápido
Facilidade para joins	Limitada	Muito flexível
Ideal para	CRUDs com lógica de negócio	Relatórios, queries otimizadas

Operações CRUD: Exemplos práticos

Criar um registro

Eloquent:

Copy Code


Pedido::create([
    'candidato_id' => 1,
    'tipo' => 'isenção',
    'status' => 'em análise',
]);

Query Builder

Copy Code


DB::table('pedidos')->insert([
    'candidato_id' => 1,
    'tipo' => 'isenção',
    'status' => 'em análise',
]);

Atualizar registros

Atualizar um único registro

Eloquent:

Copy Code


$pedido = Pedido::find(10);
$pedido->status = 'deferido';
$pedido->save();

Query Builder:

Copy Code


DB::table('pedidos')
    ->where('id', 10)
    ->update(['status' => 'deferido']);

Atualização em massa

Copy Code


// Query Builder é mais eficiente nesse caso
DB::table('pedidos')
    ->where('status', 'em análise')
    ->update(['status' => 'indeferido']);

Excluir registros

Eloquent com soft delete:

Copy Code


Candidato::find($id)->delete();

Query Builder direto:

Copy Code


DB::table('candidatos')->where('id', $id)->delete();

Quando usar cada um?

Use Eloquent quando:

Trabalhar com entidades de domínio (ex: Usuario, Pedido, Candidato)
Precisar de relacionamentos
Houver lógica de negócio acoplada ao dado (validações, métodos, regras)
Quiser manter o código mais expressivo e OO

Use Query Builder quando:

Estiver fazendo consultas com join, groupBy, having, etc.
Precisar de performance em consultas de grandes volumes
Estiver lidando com scripts administrativos
Não houver necessidade de criar um model (ex: relatórios ou dashboard)

Dicas práticas

Evite carregar muitos registros com Eloquent se você não for usá-los como objetos. Prefira o Query Builder nesse caso.
Use select() no Eloquent para reduzir colunas carregadas:

Copy Code


Candidato::select('id', 'nome')->get();

Para casos híbridos (ex: usar Eloquent mas com joins manuais), você também pode usar:

Copy Code


Pedido::join('candidatos', 'candidatos.id', '=', 'pedidos.candidato_id')
    ->select('pedidos.*', 'candidatos.nome')
    ->get();

O Laravel te dá a liberdade de escolher entre Eloquent e Query Builder dependendo da necessidade. Em geral:

Eloquent é ideal para domínio rico, com regras e relacionamentos.
Query Builder é melhor para performance, relatórios e manipulação em massa.

A chave está em entender a intenção da operação. Se for sobre um “objeto do seu negócio”, Eloquent. Se for só “dados”, talvez o Query Builder seja mais adequado.

Fontes e leitura complementar

Tags:

PauloRB.dev