Laravel Scout - Knowledge of Laravel

Introduction

Laravel Scout est une solution simple, à base de drivers, qui ajoute la recherche plein texte aux modèles Eloquent. Un observer synchronise automatiquement les enregistrements avec l’index. Scout inclut un moteur database intégré qui utilise l’index full text et LIKE de MySQL / PostgreSQL — sans service externe. Pour de grosses productions avec tolérance aux fautes, facettes ou géo-recherche, un moteur externe est utile.

Moteurs supportés

Moteur	Caractéristiques	Usage
`database`	Index full text MySQL / PostgreSQL	La plupart des apps
`collection`	Filtrage en PHP (compatible SQLite)	Dev local, tests
Meilisearch	Open source, tolérant aux fautes, rapide	Production
Algolia	SaaS cloud, fonctions avancées	Production
Typesense	Open source, vector search	Production
Turbopuffer	Recherche full text, sémantique et hybride	Production

Installation

composer require laravel/scout

Publiez la configuration :

php artisan vendor:publish --provider="Laravel\Scout\ScoutServiceProvider"

Ajoutez le trait Laravel\Scout\Searchable aux modèles à indexer.

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Laravel\Scout\Searchable;

class Post extends Model
{
    use Searchable;
}

Configuration de la queue

Avec un moteur autre que database / collection, il est vivement recommandé de configurer une queue pour que la synchronisation d’index se fasse en arrière-plan et n’impacte pas les temps de réponse. Dans config/scout.php, mettez queue à true.

'queue' => true,

Vous pouvez préciser connexion et nom de queue :

'queue' => [
    'connection' => 'redis',
    'queue' => 'scout'
],

Démarrez un worker dédié :

php artisan queue:work redis --queue=scout

Jobs uniques

Pour éviter des jobs dupliqués sur le même enregistrement, enregistrez MakeSearchableUniquely / RemoveFromSearchUniquely (souvent dans boot).

use Laravel\Scout\Jobs\MakeSearchableUniquely;
use Laravel\Scout\Jobs\RemoveFromSearchUniquely;
use Laravel\Scout\Scout;

Scout::makeSearchableUsing(MakeSearchableUniquely::class);
Scout::removeFromSearchUsing(RemoveFromSearchUniquely::class);

Ils utilisent les jobs uniques pour prévenir les doublons.

Prérequis par driver

Algolia

Configurez id et secret dans config/scout.php et installez le SDK.

composer require algolia/algoliasearch-client-php

.env :

ALGOLIA_APP_ID=your-app-id
ALGOLIA_SECRET=your-secret-key

Paramètres d’index

Gérez les paramètres d’index dans config/scout.php.

use App\Models\User;

'algolia' => [
    'id' => env('ALGOLIA_APP_ID', ''),
    'secret' => env('ALGOLIA_SECRET', ''),
    'index-settings' => [
        User::class => [
            'searchableAttributes' => ['id', 'name', 'email'],
            'attributesForFaceting' => ['filterOnly(email)'],
        ],
    ],
],

Puis synchronisez :

php artisan scout:sync-index-settings

Meilisearch

Meilisearch est un moteur open source performant. En local, via Docker Sail :

./vendor/bin/sail up -d meilisearch

Ou directement avec Docker :

docker run -it --rm \
    -p 7700:7700 \
    getmeili/meilisearch:latest \
    meilisearch --master-key="masterKey"

Installez le SDK :

composer require meilisearch/meilisearch-php http-interop/http-factory-guzzle

.env :

SCOUT_DRIVER=meilisearch
MEILISEARCH_HOST=http://127.0.0.1:7700
MEILISEARCH_KEY=masterKey

À chaque upgrade Scout, consultez aussi les breaking changes de Meilisearch.

Paramètres d’index (Meilisearch)

Avant d’utiliser where(), déclarez filterableAttributes ; pour orderBy(), sortableAttributes.

use App\Models\User;

'meilisearch' => [
    'host' => env('MEILISEARCH_HOST', 'http://localhost:7700'),
    'key' => env('MEILISEARCH_KEY', null),
    'index-settings' => [
        User::class => [
            'filterableAttributes' => ['id', 'name', 'email'],
            'sortableAttributes' => ['created_at'],
        ],
    ],
],

Attention aux types numériques : Meilisearch ne filtre correctement que si les types sont bons.

public function toSearchableArray(): array
{
    return [
        'id' => (int) $this->id,
        'name' => $this->name,
        'price' => (float) $this->price,
    ];
}

Synchronisez :

php artisan scout:sync-index-settings

Recherche sémantique et hybride (Meilisearch)

Pour utiliser la recherche sémantique ou hybride avec Meilisearch, définissez un embedder dans les paramètres d’index et les informations d’embedding dans les paramètres de modèle.

'meilisearch' => [
    'index-settings' => [
        Article::class => [
            'embedders' => [
                'default' => [
                    'source' => 'userProvided',
                    'dimensions' => 1536,
                ],
            ],
        ],
    ],
    'model-settings' => [
        Article::class => [
            'embedding' => [
                'embedder' => 'default',
                'dimensions' => 1536,
            ],
        ],
    ],
],

La méthode toSearchableEmbedding du modèle renvoie le texte source à embarquer via le Laravel AI SDK, ou un tableau d’embedding précalculé. Après modification de la configuration, exécutez scout:sync-index-settings.

Typesense

Typesense prend en charge keyword, sémantique, géo et vector search.

composer require typesense/typesense-php

.env :

SCOUT_DRIVER=typesense
TYPESENSE_API_KEY=masterKey
TYPESENSE_HOST=localhost
TYPESENSE_PORT=8108
TYPESENSE_PATH=
TYPESENSE_PROTOCOL=http

Convertissez la clé primaire en string et created_at en timestamp UNIX.

public function toSearchableArray(): array
{
    return array_merge($this->toArray(), [
        'id' => (string) $this->id,
        'created_at' => $this->created_at->timestamp,
    ]);
}

Recherche sémantique et hybride (Typesense)

Pour activer la recherche sémantique et hybride avec Typesense, définissez un réglage embedding et un champ vectoriel dans les paramètres Typesense du modèle. Par défaut, Scout utilise le Laravel AI SDK pour générer les embeddings.

use App\Models\Article;

'model-settings' => [
    Article::class => [
        'collection-schema' => [
            'fields' => [
                ['name' => 'title', 'type' => 'string'],
                ['name' => 'embedding', 'type' => 'float[]', 'num_dim' => 1536],
            ],
        ],
        'search-parameters' => ['query_by' => 'title'],
        'embedding' => [
            'attribute' => 'embedding',
            'dimensions' => 1536,
        ],
    ],
],

La méthode toSearchableEmbedding du modèle renvoie le texte source à embarquer par Scout, ou un tableau d’embedding précalculé.

public function toSearchableEmbedding(): string|array
{
    return $this->title.' '.$this->body;
}

Si vous utilisez la fonctionnalité d’embedding native de Typesense, vous pouvez générer les embeddings sans passer par le Laravel AI SDK. Pour plus de détails, consultez la documentation officielle de Typesense.

Turbopuffer

Turbopuffer est un moteur de recherche qui prend en charge la recherche full text, sémantique et hybride. Pour utiliser le driver Turbopuffer, définissez SCOUT_DRIVER et votre clé API.

SCOUT_DRIVER=turbopuffer
TURBOPUFFER_API_KEY=tpuf_...
TURBOPUFFER_REGION=gcp-us-central1

TURBOPUFFER_REGION est facultatif et vaut gcp-us-central1 par défaut.

Moteurs `database` / `collection`

Idéal sans service externe. database : full text + LIKE sur MySQL / PostgreSQL. Suffit dans la plupart des cas.

SCOUT_DRIVER=database

Recherche sémantique et hybride

Le moteur database prend en charge la recherche sémantique et hybride avec PostgreSQL et l’extension pgvector. Ajoutez à la table du modèle une colonne vectorielle nullable et un index full text. Scout enregistre l’embedding après la sauvegarde du modèle : la colonne vectorielle doit donc être nullable.

Schema::ensureVectorExtensionExists();

Schema::table('articles', function (Blueprint $table) {
    $table->vector('embedding', dimensions: 1536)->nullable();
    $table->vectorIndex('embedding');
    $table->fullText(['title', 'body']);
});

Définissez une méthode toSearchableEmbedding sur le modèle : elle renvoie le texte source que Scout embarque, ou un tableau d’embedding précalculé. Les embeddings sont stockés par défaut dans la colonne embedding ; définissez searchableEmbeddingColumn pour utiliser une autre colonne. collection : filtre en PHP, fonctionne avec toutes les DB de Laravel dont SQLite. Adapté dev / tests / petits datasets.

SCOUT_DRIVER=collection

Avec le moteur database, pas de gestion d’index manuelle : la recherche est directement sur la table.

Configuration de Turbopuffer

Turbopuffer nécessite des attributs cherchables et un schéma pour chaque modèle. Définissez-les dans le tableau model-settings de config/scout.php.

'turbopuffer' => [
    'model-settings' => [
        Article::class => [
            'searchable-attributes' => [
                'title' => 3,
                'body' => 1,
            ],
            'schema' => [
                'title' => ['type' => 'string', 'full_text_search' => true],
                'body' => ['type' => 'string', 'full_text_search' => true],
                'status' => ['type' => 'string'],
            ],
        ],
    ],
],

Les valeurs numériques de searchable-attributes sont des poids BM25 relatifs. Dans l’exemple, une correspondance dans le titre pèse trois fois plus qu’une correspondance dans le corps. Pour activer la recherche sémantique, ajoutez un réglage embedding et un schéma vectoriel, et renvoyez le texte source ou un tableau d’embedding précalculé depuis la méthode toSearchableEmbedding du modèle.

'embedding' => [
    'attribute' => 'embedding',
    'dimensions' => 1536,
],

'schema' => [
    'embedding' => ['type' => '[1536]f32', 'ann' => true],
],

Pour utiliser les embeddings natifs de Turbopuffer, le Laravel AI SDK et toSearchableEmbedding sont inutiles : incluez l’attribut source dans le retour de toSearchableArray et configurez le driver d’embedding ainsi.

'embedding' => [
    'driver' => 'turbopuffer',
    'attribute' => 'embedding_text',
],

Trait Searchable

Personnaliser `toSearchableArray()`

Par défaut, toArray() alimente l’index. Surchargez si nécessaire.

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Laravel\Scout\Searchable;

class Post extends Model
{
    use Searchable;

    /**
     * Retourne les données à indexer.
     *
     * @return array<string, mixed>
     */
    public function toSearchableArray(): array
    {
        $array = $this->toArray();

        // Personnalisation...

        return $array;
    }
}

Personnaliser le nom d’index

Par défaut, le nom de table (pluriel). Surchargez searchableAs.

public function searchableAs(): string
{
    return 'posts_index';
}

Stratégies pour le moteur database

Précisez la stratégie par colonne avec des attributs PHP.

use Laravel\Scout\Attributes\SearchUsingFullText;
use Laravel\Scout\Attributes\SearchUsingPrefix;

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

Pour SearchUsingFullText, ajoutez un index full text sur les colonnes.

Recherche plein texte PostgreSQL

Avec PostgreSQL, Scout peut interroger une colonne tsvector stockée pour effectuer une recherche plein texte pondérée et indexée. Commencez par utiliser la méthode searchable dans une migration pour ajouter la colonne générée search_vector et son index GIN.

use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

Schema::table('posts', function (Blueprint $table) {
    $table->searchable(['title' => 'A', 'body' => 'D']);
});

Les poids des colonnes vont de A (le plus élevé) à D (le plus faible). Vous pouvez aussi passer une liste de noms de colonnes sans poids, comme ['title', 'body']. Dans ce cas, chaque colonne reçoit le poids par défaut D. PostgreSQL met automatiquement à jour la colonne générée lorsque les colonnes sources changent. Ensuite, appliquez l’attribut SearchUsingFullText à la méthode toSearchableArray du modèle et définissez l’option vector sur true.

use Laravel\Scout\Attributes\SearchUsingFullText;

/**
 * Retourne les données à indexer.
 *
 * @return array<string, mixed>
 */
#[SearchUsingFullText(['search_vector'], ['vector' => true])]
public function toSearchableArray(): array
{
    return ['search_vector' => null];
}

Seul le nom de la colonne est nécessaire. Scout interroge directement la valeur stockée. Ne renvoyez que la colonne vectorielle, car l’ajout de clauses LIKE sur d’autres attributs peut empêcher PostgreSQL d’utiliser l’index GIN. La méthode searchable accepte aussi une configuration de recherche textuelle, des colonnes pour un index trigram et un nom personnalisé pour la colonne vectorielle.

$table->searchable(
    columns: ['title' => 'A', 'body' => 'D'],
    language: 'english',
    trigram: ['title'],
    tsvector: 'search_vector',
);

Pour supprimer la colonne générée et ses index lors du rollback de la migration, utilisez la méthode dropSearchable avec les mêmes colonnes trigram et le même nom de colonne vectorielle.

Schema::table('posts', function (Blueprint $table) {
    $table->dropSearchable(trigram: ['title'], tsvector: 'search_vector');
});

Options de recherche PostgreSQL

Vous pouvez personnaliser la recherche plein texte PostgreSQL avec le second argument de l’attribut SearchUsingFullText.

Option	Description	Défaut
`vector`	Indique si la colonne plein texte est une colonne `tsvector` stockée	`false`
`language`	La configuration de recherche textuelle, comme `english` ou `public.english_unaccent`	`english`
`mode`	La syntaxe de requête : `plain`, `phrase`, `websearch` ou `raw`	`plain`
`rank`	La fonction de classement : `ts_rank` ou `ts_rank_cd`	`ts_rank`
`trigram`	Nom de colonne ou tableau de colonnes utilisé pour la correspondance tolérante aux fautes de frappe	Aucun
`trigram_mode`	Indique si la correspondance trigram sert de `fallback` aux correspondances plein texte ou se combine avec elles en `blend`	`fallback`

Le mode plain recherche tous les termes de la requête, et le mode phrase correspond lorsque les termes apparaissent dans l’ordre. Le mode websearch prend en charge la syntaxe de recherche web, comme les phrases entre guillemets et les termes exclus, et le mode raw accepte la syntaxe tsquery de PostgreSQL. Lorsque vous interrogez une colonne vectorielle stockée, language doit correspondre à la configuration de recherche textuelle utilisée pour générer la colonne. Pour activer la tolérance aux fautes de frappe, indiquez les colonnes trigram à la fois dans la migration et dans les options de l’attribut.

#[SearchUsingFullText(['search_vector'], ['vector' => true, 'trigram' => ['title']])]
public function toSearchableArray(): array
{
    return ['search_vector' => null];
}

Par défaut, Scout ne relance la recherche avec la correspondance trigram que lorsque la recherche initiale ne renvoie aucun résultat. En définissant trigram_mode sur blend, les correspondances trigram sont incluses aux côtés des correspondances plein texte et la similarité trigram est prise en compte dans le classement par pertinence.

La correspondance trigram nécessite que l’extension pg_trgm soit disponible dans le chemin de recherche de la connexion. Lorsque vous indiquez des colonnes trigram, la méthode de migration searchable crée l’extension. L’utilisateur de base de données qui exécute la migration doit donc avoir le droit de créer des extensions.

Pour une recherche donnée, vous pouvez remplacer les options mode, language, rank, trigram et trigram_mode avec la méthode options.

$posts = Post::search('"laravel scout"')->options(['mode' => 'websearch'])->get();

Indexation conditionnelle

Définissez shouldBeSearchable.

/**
 * Détermine si ce modèle doit être indexé.
 */
public function shouldBeSearchable(): bool
{
    return $this->isPublished();
}

shouldBeSearchable ne fonctionne pas avec le moteur database. Utilisez une clause where à la place.

Gestion des index

Cette section concerne principalement Algolia, Meilisearch, Typesense, Turbopuffer. Le moteur database n’a pas besoin de gestion d’index.

Importer des enregistrements existants

scout:import importe les enregistrements existants.

php artisan scout:import "App\Models\Post"

Import en queue :

php artisan scout:queue-import "App\Models\Post" --chunk=500

Vider l’index

php artisan scout:flush "App\Models\Post"

Pause de la synchronisation

Utilisez withoutSyncingToSearch pour désactiver temporairement la sync.

use App\Models\Order;

Order::withoutSyncingToSearch(function () {
    // Les opérations à l'intérieur ne synchronisent pas
});

Ajout / suppression manuels

// Ajouter le résultat d'une requête
Order::where('price', '>', 100)->searchable();

// Via une relation
$user->orders()->searchable();

unsearchable retire :

Order::where('price', '>', 100)->unsearchable();

delete sur un modèle retire automatiquement de l’index.

Recherche

search puis get :

use App\Models\Order;

$orders = Order::search('Star Trek')->get();

Renvoyer directement depuis une route donne du JSON.

use Illuminate\Http\Request;

Route::get('/search', function (Request $request) {
    return Order::search($request->search)->get();
});

raw() pour la réponse brute :

$orders = Order::search('Star Trek')->raw();

Recherche sémantique

Les moteurs database, Meilisearch, Typesense et Turbopuffer prennent en charge la recherche sémantique, qui recherche les enregistrements d’après le sens de la requête. Après avoir configuré les embeddings du moteur choisi, ajoutez la méthode semantic à la requête de recherche. Lorsque Scout génère les embeddings, la recherche sémantique et hybride nécessite le Laravel AI SDK. Si vous utilisez les embeddings natifs de Typesense, ceux de Turbopuffer ou un vecteur de requête précalculé, le Laravel AI SDK n’est pas requis.

$articles = Article::search('how to keep a house comfortable without electricity')
    ->semantic()
    ->get();

Selon le moteur choisi, vous pouvez indiquer un seuil de similarité minimal.

$articles = Article::search('renewable energy storage')
    ->semantic(minSimilarity: 0.6)
    ->get();

Pour combiner recherche full text et recherche sémantique, utilisez la méthode hybrid. Ses arguments contrôlent les poids relatifs des résultats textuels et sémantiques.

$articles = Article::search('renewable energy storage')
    ->hybrid(textWeight: 1, semanticWeight: 2)
    ->get();

Pagination

$orders = Order::search('Star Trek')->paginate();

// Par page
$orders = Order::search('Star Trek')->paginate(15);

Sur le moteur database, simplePaginate est efficace pour de gros volumes.

$orders = Order::search('Star Trek')->simplePaginate(15);

Blade :

<div class="container">
    @foreach ($orders as $order)
        {{ $order->price }}
    @endforeach
</div>

{{ $orders->links() }}

Filtres et tri

where ajoute des filtres.

use App\Models\Order;

// Égalité
$orders = Order::search('Star Trek')->where('user_id', 1)->get();

// Dans un tableau
$orders = Order::search('Star Trek')->whereIn('status', ['open', 'paid'])->get();

// Pas dans un tableau
$orders = Order::search('Star Trek')->whereNotIn('status', ['closed'])->get();

Sous Meilisearch, déclarez filterableAttributes au préalable.

query personnalise la requête Eloquent finale.

use Illuminate\Database\Eloquent\Builder;

$orders = Order::search('Star Trek')
    ->query(fn (Builder $query) => $query->with('invoices'))
    ->get();

Eager Loading

Scout récupère les IDs puis les modèles via Eloquent. Évitez N+1 avec with() dans query.

use App\Models\Order;
use Illuminate\Database\Eloquent\Builder;

$orders = Order::search('Star Trek')
    ->query(fn (Builder $query) => $query->with(['invoices', 'user']))
    ->get();

Pour les imports en batch, définissez makeAllSearchableUsing.

use Illuminate\Database\Eloquent\Builder;

protected function makeAllSearchableUsing(Builder $query): Builder
{
    return $query->with('author');
}

makeAllSearchableUsing peut être inopérant avec des imports en queue : les relations ne survivent pas nécessairement à la sérialisation.

Soft delete

Si le modèle utilise soft delete, activez soft_delete: true dans config/scout.php.

'soft_delete' => true,

Vous pouvez alors utiliser withTrashed / onlyTrashed.

// Inclut supprimés
$orders = Order::search('Star Trek')->withTrashed()->get();

// Uniquement supprimés
$orders = Order::search('Star Trek')->onlyTrashed()->get();

Moteur personnalisé

Créez votre propre moteur en étendant Laravel\Scout\Engines\Engine et en implémentant 8 méthodes.

use Laravel\Scout\Builder;

abstract public function update($models);
abstract public function delete($models);
abstract public function search(Builder $builder);
abstract public function paginate(Builder $builder, $perPage, $page);
abstract public function mapIds($results);
abstract public function map(Builder $builder, $results, $model);
abstract public function getTotalCount($results);
abstract public function flush($model);

Inspirez-vous de Laravel\Scout\Engines\AlgoliaEngine. Enregistrez-le dans boot :

use App\ScoutExtensions\MySqlSearchEngine;
use Laravel\Scout\EngineManager;

public function boot(): void
{
    resolve(EngineManager::class)->extend('mysql', function () {
        return new MySqlSearchEngine;
    });
}

Puis dans config/scout.php :

'driver' => 'mysql',

Pages associées

Eloquent ORM

Rappels sur les modèles Eloquent.

Relations Eloquent

Relations et eager loading.

Queues

Scout peut mettre à jour l’index en arrière-plan via les queues.

​Introduction

​Moteurs supportés

​Installation

​Configuration de la queue

​Jobs uniques

​Prérequis par driver

​Algolia

​Paramètres d’index

​Meilisearch

​Paramètres d’index (Meilisearch)

​Recherche sémantique et hybride (Meilisearch)

​Typesense

​Recherche sémantique et hybride (Typesense)

​Turbopuffer

​Moteurs database / collection

​Recherche sémantique et hybride

​Configuration de Turbopuffer

​Trait Searchable

​Personnaliser toSearchableArray()

​Personnaliser le nom d’index

​Stratégies pour le moteur database

​Recherche plein texte PostgreSQL

​Options de recherche PostgreSQL

​Indexation conditionnelle

​Gestion des index

​Importer des enregistrements existants

​Vider l’index

​Pause de la synchronisation

​Ajout / suppression manuels

​Recherche

​Recherche sémantique

​Pagination

​Filtres et tri

​Eager Loading

​Soft delete

​Moteur personnalisé

​Pages associées

Eloquent ORM

Relations Eloquent

Queues

Introduction

Moteurs supportés

Installation

Configuration de la queue

Jobs uniques

Prérequis par driver

Algolia

Paramètres d’index

Meilisearch

Paramètres d’index (Meilisearch)

Recherche sémantique et hybride (Meilisearch)

Typesense

Recherche sémantique et hybride (Typesense)

Turbopuffer

Moteurs `database` / `collection`

Recherche sémantique et hybride

Configuration de Turbopuffer

Trait Searchable

Personnaliser `toSearchableArray()`

Personnaliser le nom d’index

Stratégies pour le moteur database

Recherche plein texte PostgreSQL

Options de recherche PostgreSQL

Indexation conditionnelle

Gestion des index

Importer des enregistrements existants

Vider l’index

Pause de la synchronisation

Ajout / suppression manuels

Recherche

Recherche sémantique

Pagination

Filtres et tri

Eager Loading

Soft delete

Moteur personnalisé

Pages associées