O que é o query builder e como se relaciona com Eloquent?

Question

Accepted Answer

O **Query Builder** do Laravel é uma interface fluente e encadeável para construir e executar consultas de banco de dados sem escrever SQL puro. **Eloquent é construído sobre o Query Builder** — modelos Eloquent o usam internamente, e consultas Eloquent podem usar todos os métodos do Query Builder.

## O Query Builder (nível de banco de dados, via facade DB)

```php
use Illuminate\Support\Facades\DB;

DB::table('users')
    ->where('active', true)
    ->where('age', '>', 18)
    ->orderBy('name')
    ->limit(10)
    ->get();                          // returns generic objects (not models)

DB::table('users')->where('id', 1)->update(['name' => 'X']);
DB::table('users')->insert(['name' => 'Ann']);
```

O Query Builder trabalha diretamente com tabelas (retornando objetos simples, não modelos Eloquent). É encadeável e **usa automaticamente vinculação de parâmetros** — prevenindo injeção de SQL.

## Eloquent usa os mesmos métodos fluentes

```php
// Eloquent queries support ALL Query Builder methods (it's built on top)
User::where('active', true)
    ->where('age', '>', 18)
    ->orderBy('name')
    ->get();                          // returns User MODELS (with relationships, etc.)
```

Quando você encadeia métodos em um modelo Eloquent, está usando o Query Builder por baixo — mas você obtém **modelos** (com relacionamentos, acessadores e métodos) em vez de objetos simples.

## Consultas avançadas (ambos suportam isso)

```php
DB::table('orders')
    ->join('users', 'orders.user_id', '=', 'users.id')   // joins
    ->select('orders.*', 'users.name')
    ->where('orders.total', '>', 100)
    ->groupBy('users.id')
    ->havingRaw('SUM(orders.total) > 1000')
    ->get();

User::where('role', 'admin')
    ->orWhere('role', 'editor')
    ->whereIn('status', ['active', 'pending'])
    ->get();
```

Ambos suportam joins, agregações, subconsultas e condições complexas.

## Quando usar qual

```text
Eloquent (Model::...) → the default — get models with relationships/accessors/methods.
                        Best for most application logic.
Query Builder (DB::table) → when you want lightweight queries without model overhead,
                            complex reporting/aggregations, or to avoid loading models.
```

## Por que isso importa

Entender o Query Builder e sua relação com Eloquent é importante para trabalhar efetivamente com bancos de dados em Laravel e escolher a ferramenta certa para cada situação.

A ideia principal é que **Eloquent é construído sobre o Query Builder** — então os métodos fluentes e encadeáveis que você usa em modelos Eloquent (`where`, `orderBy`, `join`, etc.) são do Query Builder, o que significa que aprender um ensina você ambos.

O Query Builder fornece uma forma limpa e segura contra injeção de SQL (via vinculação automática de parâmetros) de construir consultas sem escrever SQL puro, e Eloquent adiciona funcionalidade de modelo (relacionamentos, acessadores, métodos) por cima.

Saber **quando usar qual** é a habilidade prática: **Eloquent** para a maioria da lógica da aplicação (você obtém objetos modelo ricos com relacionamentos e comportamento), e o **Query Builder diretamente** (`DB::table`) para consultas leves sem sobrecarga de modelo, relatórios/agregações complexas, ou quando você não precisa de modelos completos — o que pode ser mais eficiente em certos casos.

Ambos lidam com segurança consultas complexas (joins, agregações, subconsultas) com a mesma API fluente.

Entender o Query Builder, como Eloquent se baseia nele, a vinculação segura de parâmetros compartilhados (prevenindo injeção de SQL), e a escolha entre eles é conhecimento importante para escrever código de banco de dados eficiente e seguro em Laravel, já que o acesso ao banco de dados é central para a maioria das aplicações e escolher o nível apropriado (Eloquent rico em modelo vs Query Builder leve) afeta tanto a clareza quanto o desempenho.