> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# Query Builder

> Basi e uso avanzato del Query Builder di Laravel con DB::table(). Come costruire SQL direttamente e quando usarlo al posto di Eloquent.

## Cos'è il Query Builder

Il Query Builder di Laravel offre un'interfaccia fluida per costruire ed eseguire query sul database. Parte da `DB::table()` e concatena i metodi.

```php theme={null}
use Illuminate\Support\Facades\DB;

$users = DB::table('users')->get();
```

Internamente usa il parameter binding di PDO, quindi la protezione da SQL injection è automatica.

> [!NOTE]
>
> Il Query Builder funziona su tutti i database supportati (MySQL, MariaDB, PostgreSQL, SQLite, SQL Server). Il codice non cambia cambiando database.

## Quando usare il Query Builder o Eloquent

| Situazione | Consigliato |
| - | - |
| Servono modelli e relazioni | Eloquent |
| Aggregazioni e report complessi | Query Builder |
| Prestazioni su grandi volumi | Query Builder |
| Operazioni semplici su tabelle esistenti | Query Builder |
| Migration e seeder | Query Builder |

## Recupero dei dati

### Tutti i record

```php theme={null}
$users = DB::table('users')->get();

foreach ($users as $user) {
    echo $user->name;
}
```

`get()` restituisce `Illuminate\Support\Collection`. Ogni record è uno `stdClass`.

### Un solo record

```php theme={null}
$user = DB::table('users')->where('name', 'Mario Rossi')->first();
$user = DB::table('users')->where('name', 'Mario Rossi')->firstOrFail();
$email = DB::table('users')->where('name', 'Mario Rossi')->value('email');
$user = DB::table('users')->find(3);
```

### Elenchi di colonne

```php theme={null}
$emails = DB::table('users')->pluck('email');
$emailByName = DB::table('users')->pluck('email', 'name');
```

### Elaborazione a blocchi

```php theme={null}
use Illuminate\Support\Collection;

DB::table('users')->orderBy('id')->chunk(100, function (Collection $users) {
    foreach ($users as $user) {
        // ...
    }
});

DB::table('users')->where('active', false)
    ->chunkById(100, function (Collection $users) {
        foreach ($users as $user) {
            DB::table('users')
                ->where('id', $user->id)
                ->update(['active' => true]);
        }
    });
```

> [!WARNING]
>
> Se aggiorni/elimini record mentre esegui `chunk`, usa `chunkById()` per evitare disallineamenti.

### Streaming (LazyCollection)

```php theme={null}
DB::table('users')->orderBy('id')->lazy()->each(function (object $user) {
    // Un utente alla volta
});
```

## Aggregazioni

```php theme={null}
$count   = DB::table('users')->count();
$maxAge  = DB::table('users')->max('age');
$minAge  = DB::table('users')->min('age');
$avgAge  = DB::table('users')->avg('age');
$total   = DB::table('orders')->sum('amount');

$avgPremium = DB::table('orders')
    ->where('plan', 'premium')
    ->avg('amount');
```

### Verifica esistenza

```php theme={null}
if (DB::table('orders')->where('finalized', 1)->exists()) {
    // Esiste
}

if (DB::table('orders')->where('finalized', 1)->doesntExist()) {
    // Non esiste
}
```

## SELECT

```php theme={null}
$users = DB::table('users')
    ->select('name', 'email as user_email')
    ->get();

$users = DB::table('users')->distinct()->get();

$query = DB::table('users')->select('name');
$users = $query->addSelect('age')->get();
```

## WHERE

### Condizioni base

```php theme={null}
$users = DB::table('users')->where('votes', 100)->get();
$users = DB::table('users')->where('votes', '>=', 100)->get();
$users = DB::table('users')->where('name', 'like', 'Mario%')->get();

$users = DB::table('users')
    ->where('status', 'active')
    ->where('age', '>', 20)
    ->get();

$users = DB::table('users')
    ->where('votes', '>', 100)
    ->orWhere('name', 'Mario Rossi')
    ->get();
```

### Raggruppamento

```php theme={null}
use Illuminate\Database\Query\Builder;

$users = DB::table('users')
    ->where('active', true)
    ->where(function (Builder $query) {
        $query->where('role', 'admin')
              ->orWhere('role', 'moderator');
    })
    ->get();
// WHERE active = 1 AND (role = 'admin' OR role = 'moderator')
```

### whereIn / whereBetween / whereNull

```php theme={null}
$users = DB::table('users')->whereIn('id', [1, 2, 3])->get();
$users = DB::table('users')->whereNotIn('id', [1, 2, 3])->get();

$users = DB::table('users')->whereBetween('age', [20, 40])->get();

$users = DB::table('users')->whereNull('deleted_at')->get();
$users = DB::table('users')->whereNotNull('email_verified_at')->get();
```

### whereLike

```php theme={null}
$users = DB::table('users')
    ->whereLike('name', '%Rossi%')
    ->get();

$users = DB::table('users')
    ->whereLike('name', '%Rossi%', caseSensitive: true)
    ->get();
```

### whereAny / whereAll

```php theme={null}
$users = DB::table('users')
    ->where('active', true)
    ->whereAny(['name', 'email', 'bio'], 'like', '%Laravel%')
    ->get();

$posts = DB::table('posts')
    ->whereAll(['title', 'content'], 'like', '%Laravel%')
    ->get();
```

### whereNullSafeEquals

`whereNullSafeEquals` (e `orWhereNullSafeEquals`) confronta considerando **due NULL come uguali**.

L'operatore `=` normale rende `NULL = NULL` come `false`; con `whereNullSafeEquals` invece i `NULL` sono uguali. Corrisponde a `<=>` di MySQL e `IS NOT DISTINCT FROM` di PostgreSQL.

```php theme={null}
$lastLoginIp = $request->input('last_login_ip');

$users = DB::table('users')
    ->whereNullSafeEquals('last_login_ip', $lastLoginIp)
    ->get();
```

> [!NOTE]
>
> Il classico `where('column', null)` diventa `WHERE column IS NULL`; `whereNullSafeEquals('column', $value)` funziona in modo coerente anche quando il valore associato è o non è `null`. Molto utile con input utente potenzialmente nullo.

## JOIN

```php theme={null}
$users = DB::table('users')
    ->join('orders', 'users.id', '=', 'orders.user_id')
    ->select('users.name', 'orders.amount')
    ->get();

$users = DB::table('users')
    ->leftJoin('orders', 'users.id', '=', 'orders.user_id')
    ->get();

$users = DB::table('users')
    ->join('contacts', 'users.id', '=', 'contacts.user_id')
    ->join('orders', 'users.id', '=', 'orders.user_id')
    ->select('users.*', 'contacts.phone', 'orders.amount')
    ->get();
```

### JOIN con sottoquery

```php theme={null}
$latestOrders = DB::table('orders')
    ->select('user_id', DB::raw('MAX(created_at) as last_order_at'))
    ->groupBy('user_id');

$users = DB::table('users')
    ->joinSub($latestOrders, 'latest_orders', function ($join) {
        $join->on('users.id', '=', 'latest_orders.user_id');
    })
    ->get();
```

## Ordinamento, raggruppamento, limit

```php theme={null}
$users = DB::table('users')->orderBy('name', 'asc')->get();

$users = DB::table('users')
    ->orderBy('last_name')
    ->orderBy('first_name', 'desc')
    ->get();

$users = DB::table('users')->inRandomOrder()->get();

$orders = DB::table('orders')
    ->select('status', DB::raw('COUNT(*) as count'))
    ->groupBy('status')
    ->get();

$orders = DB::table('orders')
    ->select('user_id', DB::raw('SUM(amount) as total'))
    ->groupBy('user_id')
    ->having('total', '>', 10000)
    ->get();

$users = DB::table('users')
    ->skip(10)
    ->take(5)
    ->get();
```

## Sottoquery

```php theme={null}
$activeUsers = DB::table('users')->select('id')->where('is_active', 1);

$comments = DB::table('comments')
    ->whereIn('user_id', $activeUsers)
    ->get();

$users = DB::table('users')
    ->select('name')
    ->selectSub(function ($query) {
        $query->from('orders')
              ->selectRaw('COUNT(*)')
              ->whereColumn('orders.user_id', 'users.id');
    }, 'order_count')
    ->get();
```

## Ricerca per similarità vettoriale

Per le colonne che memorizzano vettori di embedding, `whereVectorSimilarTo` consente di filtrare i record vicini a un vettore specifico. Le colonne vettoriali si definiscono nelle migrazioni con il tipo `vector` (vedi [colonne vettoriali nelle migrazioni](https://kawax.biz/it/migrations.md#colonne-e-indici-vettoriali)).

```php theme={null}
use Illuminate\Support\Facades\DB;

$embedding = [0.12, -0.34, 0.56];

$documents = DB::table('documents')
    ->whereVectorSimilarTo('embedding', $embedding, minSimilarity: 0.4)
    ->limit(10)
    ->get();
```

`whereVectorSimilarTo` ordina i risultati dal più simile al meno simile. Se non serve indicare una similarità minima ma si vuole solo esplicitare l'ordinamento per distanza, si può usare `orderByVectorDistance`. Per includere la distanza tra le colonne restituite, `selectVectorDistance` permette di assegnarle un alias.

```php theme={null}
$documents = DB::table('documents')
    ->select('id', 'title')
    ->selectVectorDistance('embedding', $embedding, as: 'distance')
    ->orderByVectorDistance('embedding', $embedding)
    ->limit(10)
    ->get();
```

Questi metodi vengono tradotti negli operatori vettoriali forniti dal database. Verifica che il database in uso supporti il tipo vector e le relative operazioni e, con PostgreSQL, assicurati di aver abilitato l'estensione `pgvector`.

## Espressioni Raw

> [!WARNING]
>
> Le espressioni Raw vengono inserite come SQL. Passare input utente direttamente causa SQL injection. Usa sempre binding.

```php theme={null}
$users = DB::table('users')
    ->select(DB::raw('count(*) as user_count, status'))
    ->groupBy('status')
    ->get();

$orders = DB::table('orders')
    ->selectRaw('price * ? as price_with_tax', [1.10])
    ->get();

$orders = DB::table('orders')
    ->whereRaw('price > IF(state = "IT", ?, 100)', [500])
    ->get();

$orders = DB::table('orders')
    ->select('department', DB::raw('SUM(amount) as total'))
    ->groupBy('department')
    ->havingRaw('SUM(amount) > ?', [100000])
    ->get();

$orders = DB::table('orders')
    ->orderByRaw('updated_at - created_at DESC')
    ->get();
```

## INSERT / UPDATE / DELETE

### INSERT

```php theme={null}
DB::table('users')->insert([
    'email' => 'mario@example.com',
    'name'  => 'Mario Rossi',
]);

DB::table('users')->insert([
    ['email' => 'mario@example.com', 'name' => 'Mario Rossi'],
    ['email' => 'giulia@example.com', 'name' => 'Giulia Bianchi'],
]);

$id = DB::table('users')->insertGetId([
    'email' => 'luca@example.com',
    'name'  => 'Luca Verdi',
]);
```

### UPSERT

```php theme={null}
DB::table('users')->upsert(
    [
        ['email' => 'mario@example.com', 'name' => 'Mario Rossi', 'votes' => 5],
        ['email' => 'giulia@example.com', 'name' => 'Giulia Bianchi', 'votes' => 10],
    ],
    uniqueBy: ['email'],
    update: ['name', 'votes']
);
```

### UPDATE

```php theme={null}
$affected = DB::table('users')
    ->where('id', 1)
    ->update(['name' => 'Mario R.', 'updated_at' => now()]);

DB::table('users')->where('id', 1)->increment('votes');
DB::table('users')->where('id', 1)->increment('votes', 5);
DB::table('users')->where('id', 1)->decrement('votes');
DB::table('users')->where('id', 1)->decrement('balance', 100);
```

### DELETE

```php theme={null}
$deleted = DB::table('users')->where('status', 'inactive')->delete();

DB::table('users')->truncate();
```

## Query condizionali (when)

```php theme={null}
$status = request('status');
$sortBy = request('sort', 'name');

$users = DB::table('users')
    ->when($status, function ($query, $status) {
        $query->where('status', $status);
    })
    ->when($sortBy === 'email', function ($query) {
        $query->orderBy('email');
    }, function ($query) {
        $query->orderBy('name');
    })
    ->get();
```

## Debug

```php theme={null}
$sql = DB::table('users')->where('active', true)->toSql();
$bindings = DB::table('users')->where('active', true)->getBindings();

DB::table('users')->where('active', true)->dump();
DB::table('users')->where('active', true)->dd();
```

> [!TIP]
>
> `dd()` è comodo in debug ma non usarlo in produzione. `toSql()` e `getBindings()` sono più sicuri.

## Riepilogo

> [accordion] Metodi più usati
>
> | Metodo | Descrizione |
> | - | - |
> | `get()` | Tutti i record (Collection) |
> | `first()` | Primo record |
> | `find($id)` | Per ID |
> | `value($column)` | Valore di una colonna |
> | `pluck($column)` | Elenco valori di una colonna |
> | `count()` | Conteggio |
> | `sum($col)` | Somma |
> | `avg($col)` | Media |
> | `max($col)` / `min($col)` | Massimo/minimo |
> | `exists()` | Verifica esistenza |
> | `insert([...])` | Insert |
> | `update([...])` | Update |
> | `delete()` | Delete |
> | `chunk($n, fn)` | A blocchi |
> | `when($cond, fn)` | Condizionale |
> | `toSql()` | Verifica SQL |

> [accordion] Query Builder vs Eloquent
>
> Il Query Builder è più a basso livello e restituisce `stdClass`.
> Se non ti servono relazioni ed eventi dei modelli è più semplice e veloce.
>
> ```php theme={null}
> // Eloquent
> $users = User::where('active', true)->get();
> echo $users[0]->name; // Istanza User
>
> // Query Builder
> $users = DB::table('users')->where('active', true)->get();
> echo $users[0]->name; // stdClass
> ```


## Related topics

- [MongoDB](https://kawax.biz/it/mongodb.md)
- [afterQuery di Eloquent e il contratto dei risultati](https://kawax.biz/it/advanced/eloquent-after-query.md)
- [Configurazione del database](https://kawax.biz/it/database.md)
- [Trait Conditionable](https://kawax.biz/it/advanced/conditionable.md)
- [Riepilogo delle novità di Laravel 13](https://kawax.biz/it/blog/laravel-13-new-features.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.