¿Qué es el Query Builder y cómo se relaciona con Eloquent?

Question

Accepted Answer

El **Query Builder** de Laravel es una interfaz fluida y encadenable para construir y ejecutar consultas a la base de datos sin escribir SQL sin procesar. **Eloquent está construido sobre el Query Builder** — los modelos de Eloquent lo usan internamente, y las consultas de Eloquent pueden usar todos los métodos del Query Builder.

## The Query Builder (database-level, via DB facade)

```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']);
```

El Query Builder funciona directamente con tablas (devolviendo objetos simples, no modelos de Eloquent). Es encadenable e **utiliza automáticamente vinculación de parámetros** — evitando inyección SQL.

## Eloquent utiliza los mismos métodos fluidos

```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.)
```

Cuando encadenas métodos en un modelo de Eloquent, estás usando el Query Builder subyacente — pero obtienes **modelos** (con relaciones, accessores y métodos) en lugar de objetos simples.

## Consultas avanzadas (ambos las soportan)

```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 soportan joins, agregados, subconsultas y condiciones complejas.

## Cuándo usar cada uno

```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 qué es importante

Comprender el Query Builder y su relación con Eloquent es importante para trabajar efectivamente con bases de datos en Laravel y elegir la herramienta correcta para cada situación.

La idea clave es que **Eloquent está construido sobre el Query Builder** — por lo que los métodos fluidos y encadenables que usas en modelos de Eloquent (`where`, `orderBy`, `join`, etc.) son los del Query Builder, lo que significa que aprender uno te enseña ambos.

El Query Builder proporciona una forma limpia y segura contra inyección SQL (mediante vinculación automática de parámetros) para construir consultas sin escribir SQL sin procesar, y Eloquent añade funcionalidad de modelo (relaciones, accessores, métodos) encima.

Saber **cuándo usar cada uno** es la habilidad práctica: **Eloquent** para la mayoría de la lógica de aplicación (obtienes objetos modelo ricos con relaciones y comportamiento), y el **Query Builder directamente** (`DB::table`) para consultas ligeras sin sobrecarga de modelo, reportes/agregaciones complejas, o cuando no necesitas modelos completos — lo que puede ser más eficiente en ciertos casos.

Ambos manejan de forma segura consultas complejas (joins, agregados, subconsultas) con la misma API fluida.

Comprender el Query Builder, cómo Eloquent lo construye, la vinculación segura de parámetros compartida (evitando inyección SQL), y la elección entre ellos es conocimiento importante para escribir código de base de datos eficiente y seguro en Laravel, ya que el acceso a bases de datos es central en la mayoría de aplicaciones y elegir el nivel apropiado (Eloquent rico en modelos vs Query Builder ligero) afecta tanto la claridad como el rendimiento.