Ricerca

Panoramica delle funzioni di ricerca di Laravel. Come scegliere tra full-text, vector search, reranking e Laravel Scout in base al caso d’uso.

​

Introduzione

Ci sono più modi per aggiungere la ricerca a un’applicazione. Laravel fornisce strumenti integrati che vanno dal match per keyword alla ricerca semantica con AI, senza servizi esterni obbligatori.

​

Confronto

Funzione	Servizio esterno	Caratteristiche
whereFullText	Nessuno	Indici full-text integrati di MariaDB/MySQL/PostgreSQL
whereVectorSimilarTo	Nessuno (PostgreSQL + pgvector)	Similarità semantica. Richiede AI SDK
Reranking	Provider AI	Riordina qualsiasi set per rilevanza tramite AI
Laravel Scout	Nessuno (database engine) / opzionale	Sincronizzazione automatica dell’indice

---

​

Ricerca full-text

Le query LIKE non capiscono la lingua. La ricerca full-text usa indici dedicati e tiene conto di parole, forme, punteggio di rilevanza.

MariaDB, MySQL e PostgreSQL la supportano nativamente.

Supportata su MariaDB, MySQL, PostgreSQL.

​

Indici full-text

Schema::create('articles', function (Blueprint $table) {
    $table->id();
    $table->string('title');
    $table->text('body');
    $table->timestamps();

    $table->fullText(['title', 'body']);
});

PostgreSQL può indicare la lingua:

$table->fullText('body')->language('english');

Nota sulla ricerca full-text in giapponese / italiano non-standard
In MySQL la ricerca full-text non anglofona ha limiti (es. AWS RDS supporta solo N-gram parser). Anche PostgreSQL è limitato per lingue con morfologia complessa. Considera motori dedicati come Meilisearch o Typesense.

​

Esecuzione

$articles = Article::whereFullText('body', 'web developer')->get();

Con indice composito:

$articles = Article::whereFullText(
    ['title', 'body'], 'web developer'
)->get();

MariaDB/MySQL ordinano per rilevanza. In PostgreSQL whereFullText filtra soltanto: per l’ordinamento automatico usa il database engine di Scout.

Anche orWhereFullText per OR. Vedi il query builder.

---

​

Ricerca semantica / vettoriale

Il full-text si basa su match di keyword. La vector search usa embedding generati da AI per rappresentare il significato come array numerici e trovare risultati semanticamente vicini.

Esempio: “best wineries in Napa Valley” corrisponde a “Top Vineyards to Visit” pur senza keyword condivise.

Richiede Laravel AI SDK. Supporta PostgreSQL (con l’estensione pgvector) e MongoDB (con laravel-mongodb). Laravel Cloud ha pgvector preinstallato su tutti i database Postgres.

​

Generare gli embedding

Con Stringable::toEmbeddings:

use Illuminate\Support\Str;

$embedding = Str::of('Napa Valley has great wine.')->toEmbeddings();

Batch con Embeddings:

use Laravel\Ai\Embeddings;

$response = Embeddings::for([
    'Napa Valley has great wine.',
    'Laravel is a PHP framework.',
])->generate();

$response->embeddings;

Vedi la documentazione dell’AI SDK per configurazione e dimensioni.

​

Salvataggio e indicizzazione

Colonna vector in migration:

Schema::ensureVectorExtensionExists();

Schema::create('documents', function (Blueprint $table) {
    $table->id();
    $table->string('title');
    $table->text('content');
    $table->vector('embedding', dimensions: 1536)->index();
    $table->timestamps();
});

Cast in array:

protected function casts(): array
{
    return [
        'embedding' => 'array',
    ];
}

Vedi Migration.

​

Ricerca per similarità

$documents = Document::query()
    ->whereVectorSimilarTo('embedding', $queryEmbedding, minSimilarity: 0.4)
    ->limit(10)
    ->get();

Passando una stringa, Laravel calcola l’embedding.

$documents = Document::query()
    ->whereVectorSimilarTo('embedding', 'best wineries in Napa Valley')
    ->limit(10)
    ->get();

Anche whereVectorDistanceLessThan, selectVectorDistance, orderByVectorDistance.

---

​

Reranking

L’AI riordina un set di risultati per rilevanza rispetto alla query. Diversa dalla vector search: non richiede embedding preesistenti e si applica a qualsiasi collezione di testo.

Pattern efficace: filtra veloce + rerank.

use Laravel\Ai\Reranking;

$response = Reranking::of([
    'Django is a Python web framework.',
    'Laravel is a PHP web application framework.',
    'React is a JavaScript library for building user interfaces.',
])->rerank('PHP frameworks');

$response->first()->document;

Le Collection Laravel hanno la macro rerank.

$articles = Article::all()
    ->rerank('body', 'Laravel tutorials');

Vedi la documentazione dell’AI SDK.

---

​

Laravel Scout

Fin qui abbiamo usato metodi del query builder. Laravel Scout è diverso: aggiungi il trait Searchable e Scout sincronizza automaticamente gli indici.

​

Database engine

Full-text + LIKE sul DB esistente. Senza servizi esterni.

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Laravel\Scout\Attributes\SearchUsingFullText;
use Laravel\Scout\Attributes\SearchUsingPrefix;
use Laravel\Scout\Searchable;

class Article extends Model
{
    use Searchable;

    #[SearchUsingPrefix(['id'])]
    #[SearchUsingFullText(['title', 'body'])]
    public function toSearchableArray(): array
    {
        return [
            'id' => $this->id,
            'title' => $this->title,
            'body' => $this->body,
        ];
    }
}

Attributo	Strategia
SearchUsingFullText	Full-text (MATCH...AGAINST / to_tsvector)
SearchUsingPrefix	Prefisso (example%)
Nessuno	Wildcard davanti/dietro (%example%)

Serve un indice full-text.

$articles = Article::search('Laravel')->get();

Il database engine di Scout ordina per rilevanza anche in PostgreSQL.

​

Motori di terze parti

Scout supporta Algolia, Meilisearch, Typesense. API unificata: puoi migrare cambiando poco.

Non serve a tutti. I metodi integrati coprono la maggior parte dei casi.

Vedi la guida a Laravel Scout.

---

​

Combinazioni

​

Full-text + Reranking

Filtra veloce con full-text, poi rerank con AI.

$articles = Article::query()
    ->whereFullText('body', $request->input('query'))
    ->limit(50)
    ->get()
    ->rerank('body', $request->input('query'), limit: 10);

​

Vector + filtri classici

Restringi a un tenant e cerca per similarità.

$documents = Document::query()
    ->where('team_id', $user->team_id)
    ->whereVectorSimilarTo('embedding', $request->input('query'))
    ->limit(10)
    ->get();

---

​

Pagine correlate

Laravel Scout

Guida completa alla sincronizzazione automatica degli indici.

Laravel AI SDK

Configurazione dell’AI SDK per embedding e reranking.

Query Builder

Dettagli su whereFullText, whereVectorSimilarTo, ecc.

Migration

Creazione di indici full-text e colonne vector.