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

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:

$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:

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

Comparativo: Eloquent vs Query Builder

Operações CRUD: Exemplos práticos

Criar um registro

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

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

Atualizar registros

Atualizar um único registro

Eloquent:

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

Query Builder:

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

Atualização em massa

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

Excluir registros

Eloquent com soft delete:

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

Query Builder direto:

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:

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

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

• Documentação do Eloquent ORM (Laravel)

• Documentação do Query Builder (Laravel)

• Eloquent Performance Tips - Laracasts