Laravel Scout - Knowledge of Laravel

Introduction

Laravel Scout provides a simple, driver-based solution for adding full-text search to your Eloquent models. Using model observers, Scout will automatically keep your search indexes in sync with your Eloquent records. Scout ships with a built-in database engine that uses MySQL / PostgreSQL full-text indexes and LIKE clauses to search your existing database — no external service required. For large-scale production workloads requiring typo tolerance, faceted filtering, vector search, or geo-search, external engines are available.

Supported engines

Engine	Characteristics	Use case
`database`	MySQL / PostgreSQL full-text indexes	Most applications
`collection`	PHP-based filtering (SQLite compatible)	Local dev and testing
Meilisearch	Open source, typo tolerant, fast	Production
Algolia	Cloud SaaS, advanced features	Production
Typesense	Open source, vector search support	Production
Turbopuffer	Full-text, semantic, and hybrid search	Production

Installation

Install Scout via Composer:

composer require laravel/scout

After installing, publish the Scout configuration file. This command publishes scout.php to your application’s config directory:

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

Finally, add the Laravel\Scout\Searchable trait to the model you want to make searchable. This trait registers a model observer that keeps the model in sync with your search driver:

<?php

namespace App\Models;

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

class Post extends Model
{
    use Searchable;
}

Queueing

When using an engine other than database or collection, you should strongly consider configuring a queue driver before using Scout. Running a queue worker allows Scout to queue all index sync operations in the background, providing much better response times for your web interface. Set the queue option in config/scout.php to true:

'queue' => true,

You can also specify the connection and queue name:

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

Then run a queue worker for the dedicated queue:

php artisan queue:work redis --queue=scout

Unique indexing jobs

In write-heavy applications, you may wish to prevent Scout from queueing duplicate jobs for the same model records. You may opt into unique indexing jobs by registering the MakeSearchableUniquely and RemoveFromSearchUniquely job classes, typically within the boot method of a service provider:

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

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

These jobs use Laravel’s unique job locks to avoid dispatching duplicate queued indexing operations for the same searchable model records while a matching job is already queued.

Driver prerequisites

Algolia

When using the Algolia driver, configure your id and secret credentials in config/scout.php and install the Algolia PHP SDK:

composer require algolia/algoliasearch-client-php

Add your credentials to the .env file:

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

Index settings

You can manage Algolia index settings directly in 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)'],
        ],
    ],
],

After configuring, sync the settings to Algolia:

php artisan scout:sync-index-settings

Meilisearch

Meilisearch is a fast, open source search engine. For local development, the easiest way is to use Laravel Sail’s Docker environment.

# With Laravel Sail
./vendor/bin/sail up -d meilisearch

Without Sail, you can start Meilisearch directly with Docker:

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

Install the Meilisearch PHP SDK:

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

Set the driver and host in your .env file:

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

When upgrading Scout on an application that uses Meilisearch, always review any breaking changes to the Meilisearch service itself.

Index settings (Meilisearch)

Meilisearch requires you to pre-define filterableAttributes for columns you plan to use with Scout’s where method, and sortableAttributes for columns you plan to sort by:

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'],
        ],
    ],
],

Pay attention to data types — Meilisearch only performs filter operations (>, <, etc.) on data of the correct type:

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

After configuring, sync the settings:

php artisan scout:sync-index-settings

Semantic and hybrid search (Meilisearch)

To use semantic or hybrid search with Meilisearch, configure an embedder in the index settings and embedding settings for each searchable model:

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

The model’s toSearchableEmbedding method may return source text, which Scout embeds using the Laravel AI SDK, or a precomputed embedding array. After updating the configuration, run scout:sync-index-settings.

Typesense

Typesense is a lightning-fast, open source search engine with support for keyword, semantic, geo, and vector search.

composer require typesense/typesense-php

Set the connection details in your .env file:

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

When using Typesense, your toSearchableArray method must cast the model’s primary key to a string and creation date to a UNIX timestamp:

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

Embeddings

To enable semantic and hybrid search, define an embedding setting and vector field in the model’s Typesense configuration. By default, Scout uses the Laravel AI SDK to generate 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,
        ],
    ],
],

Your model’s toSearchableEmbedding method should return the source text that Scout should embed or a precomputed embedding array:

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

Typesense’s native embeddings can also be used without the Laravel AI SDK. See the Typesense documentation for details.

Turbopuffer

Turbopuffer is a search engine that supports full-text, semantic, and hybrid search. To use the Turbopuffer driver, set the SCOUT_DRIVER environment variable and provide your API key:

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

The TURBOPUFFER_REGION environment variable is optional and defaults to gcp-us-central1.

Turbopuffer configuration

Turbopuffer requires searchable attributes and a schema for each model. Define them in the model-settings array of your scout configuration:

use App\Models\Article;

'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'],
            ],
        ],
    ],
],

The numeric values assigned to searchable-attributes are relative BM25 weights. To enable semantic search, add an embedding setting and vector schema:

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

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

Your model’s toSearchableEmbedding method should return source text for the Laravel AI SDK to embed or a precomputed embedding array. Alternatively, Turbopuffer’s native embeddings can be used without the AI SDK by setting the embedding driver to turbopuffer and including the source attribute in toSearchableArray.

Database / collection engines

These built-in engines require no external service. The database engine uses MySQL / PostgreSQL full-text indexes and LIKE clauses. It is the recommended starting point for most applications:

SCOUT_DRIVER=database

Semantic and hybrid search

The database engine supports semantic and hybrid search when using PostgreSQL with the pgvector extension. Add a nullable vector column and a full-text index to the model’s table:

Schema::ensureVectorExtensionExists();

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

Define a toSearchableEmbedding method on the model to return source text or a precomputed embedding array. Scout stores embeddings in the embedding column by default; define searchableEmbeddingColumn to use another column. The collection engine retrieves all records from your database and filters them in PHP, so it works with any database Laravel supports, including SQLite. It is intended for local development, small datasets, and tests:

SCOUT_DRIVER=collection

The database engine searches your database tables directly — no separate indexing step is required.

The Searchable trait

Customizing toSearchableArray()

By default, the entire toArray form of a model is persisted to its search index. Override toSearchableArray to control which data is synchronized:

<?php

namespace App\Models;

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

class Post extends Model
{
    use Searchable;

    /**
     * Get the indexable data array for the model.
     *
     * @return array<string, mixed>
     */
    public function toSearchableArray(): array
    {
        $array = $this->toArray();

        // Customize the data array...

        return $array;
    }
}

Customizing the index name

By default, the model’s table name (plural) is used as the index name. Override searchableAs to customize it:

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

Database engine search strategies

For the database engine, you can assign PHP attributes to specify more efficient per-column search strategies:

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,
    ];
}

Before using SearchUsingFullText, ensure the column has a full-text index.

PostgreSQL full-text search

When using PostgreSQL, Scout can search a stored tsvector column to perform indexed, weighted full-text search. First, use the searchable method in a migration to add the generated search_vector column and its GIN index.

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

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

Column weights range from A (highest) to D (lowest). You can also pass a list of column names without weights, such as ['title', 'body'], in which case each column is assigned the default weight D. PostgreSQL automatically updates the generated column when the source columns change. Next, apply the SearchUsingFullText attribute to the model’s toSearchableArray method and set the vector option to true.

use Laravel\Scout\Attributes\SearchUsingFullText;

/**
 * Get the indexable data array for the model.
 *
 * @return array<string, mixed>
 */
#[SearchUsingFullText(['search_vector'], ['vector' => true])]
public function toSearchableArray(): array
{
    return ['search_vector' => null];
}

Only the column name is required. Scout searches the stored value directly. Return only the vector column, because adding LIKE clauses for other attributes may prevent PostgreSQL from using the GIN index. The searchable method also accepts a text search configuration, columns for a trigram index, and a custom vector column name.

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

To drop the generated column and its indexes when rolling back the migration, use the dropSearchable method with the same trigram columns and vector column name.

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

PostgreSQL search options

You can customize PostgreSQL full-text search with the second argument of the SearchUsingFullText attribute.

Option	Description	Default
`vector`	Whether the full-text column is a stored `tsvector` column	`false`
`language`	The text search configuration, such as `english` or `public.english_unaccent`	`english`
`mode`	The query syntax: `plain`, `phrase`, `websearch`, or `raw`	`plain`
`rank`	The ranking function: `ts_rank` or `ts_rank_cd`	`ts_rank`
`trigram`	A column name or array of columns used for typo-tolerant matching	None
`trigram_mode`	Whether trigram matching is used as a `fallback` for full-text matches or combined with them as a `blend`	`fallback`

plain mode searches for all query terms, and phrase mode matches when the terms appear in order. websearch mode supports web search syntax such as quoted phrases and excluded terms, and raw mode accepts PostgreSQL tsquery syntax. When searching a stored vector column, language must match the text search configuration used to generate the column. To enable typo tolerance, specify trigram columns in both the migration and the attribute options.

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

By default, Scout retries the search with trigram matching only when the initial search returns no results. Setting trigram_mode to blend includes trigram matches alongside full-text matches and factors trigram similarity into relevance ranking.

Trigram matching requires the pg_trgm extension to be available on the connection’s search path. When you specify trigram columns, the searchable migration method creates the extension, so the database user running the migration needs permission to create extensions.

For individual searches, you can override the mode, language, rank, trigram, and trigram_mode options with the options method.

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

Conditionally searchable models

To make a model searchable only under certain conditions, define a shouldBeSearchable method:

/**
 * Determine if the model should be searchable.
 */
public function shouldBeSearchable(): bool
{
    return $this->isPublished();
}

shouldBeSearchable is not applicable when using the database engine. Use where clauses instead.

Index management

The commands in this section are primarily relevant when using a third-party engine (Algolia, Meilisearch, Typesense, or Turbopuffer). The database engine does not require manual index management.

Batch import

If you are adding Scout to an existing project, import existing database records into your indexes:

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

To import using queued jobs in the background:

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

Flushing the index

Remove all records for a model from its search index:

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

Pausing indexing

To perform a batch of Eloquent operations without syncing to the search index, use withoutSyncingToSearch:

use App\Models\Order;

Order::withoutSyncingToSearch(function () {
    // Model operations here are not synced to the index
});

Manually adding and removing records

Add a collection of models to the index via an Eloquent query:

// Add via query
Order::where('price', '>', 100)->searchable();

// Add via relationship
$user->orders()->searchable();

Remove records from the index using unsearchable:

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

Deleting a model removes it from the search index automatically.

Searching

Use the search method to search a model. Chain get to retrieve the matching Eloquent models:

use App\Models\Order;

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

You can return search results directly from a route or controller — they will be converted to JSON automatically:

use Illuminate\Http\Request;

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

To get the raw search results before they are converted to Eloquent models, use raw:

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

Semantic search

The database, Meilisearch, Typesense, and Turbopuffer engines support semantic search, which matches records based on the meaning of a query. When Scout generates embeddings, semantic and hybrid searches require the Laravel AI SDK. Typesense’s native embeddings, Turbopuffer’s native embeddings, and precomputed query vectors do not require the Laravel AI SDK. After configuring embeddings for the selected engine, invoke the semantic method:

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

You may provide a minimum similarity threshold when supported by the selected engine:

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

To combine full-text and semantic search, use the hybrid method. Its arguments control the relative weights of text and semantic results:

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

Pagination

Paginate search results with the paginate method, which returns an Illuminate\Pagination\LengthAwarePaginator:

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

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

The database engine also supports simplePaginate, which skips the total count query for better performance on large datasets:

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

Render results and pagination links in a Blade template:

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

{{ $orders->links() }}

Filtering and sorting

Add filter conditions to your search query with where:

use App\Models\Order;

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

// Match any value in array
$orders = Order::search('Star Trek')->whereIn('status', ['open', 'paid'])->get();

// Exclude values in array
$orders = Order::search('Star Trek')->whereNotIn('status', ['closed'])->get();

When using Meilisearch, you must configure filterable attributes before using Scout’s where clauses.

Customize the Eloquent query for the results using query:

use Illuminate\Database\Eloquent\Builder;

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

Eager loading

Scout retrieves IDs from the search engine and then fetches the models via Eloquent. To avoid N+1 queries, use the query method to eager load relationships:

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

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

To eager load relationships during batch import, define makeAllSearchableUsing on the model:

use Illuminate\Database\Eloquent\Builder;

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

makeAllSearchableUsing may not be applicable when using a queue to batch import models, because relationships are not restored when model collections are processed by jobs.

Soft deleting

If your indexed models use soft deletes and you need to search soft deleted records, set soft_delete to true in config/scout.php:

'soft_delete' => true,

You can then use withTrashed or onlyTrashed when searching:

// Include trashed records
$orders = Order::search('Star Trek')->withTrashed()->get();

// Only trashed records
$orders = Order::search('Star Trek')->onlyTrashed()->get();

Custom engines

If the built-in engines don’t meet your needs, you can write your own. Extend the Laravel\Scout\Engines\Engine abstract class and implement its eight required methods:

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);

Review Laravel\Scout\Engines\AlgoliaEngine for a reference implementation. Register your custom engine in the boot method of App\Providers\AppServiceProvider:

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

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

Then specify it as the driver in config/scout.php:

'driver' => 'mysql',

Eloquent ORM

Learn the fundamentals of working with Eloquent models.

Eloquent relationships

Learn how to define relationships and use eager loading.

Queues

Scout can use queues to update indexes in the background.

​Introduction

​Supported engines

​Installation

​Queueing

​Unique indexing jobs

​Driver prerequisites

​Algolia

​Index settings

​Meilisearch

​Index settings (Meilisearch)

​Semantic and hybrid search (Meilisearch)

​Typesense

​Embeddings

​Turbopuffer

​Turbopuffer configuration

​Database / collection engines

​Semantic and hybrid search

​The Searchable trait

​Customizing toSearchableArray()

​Customizing the index name

​Database engine search strategies

​PostgreSQL full-text search

​PostgreSQL search options

​Conditionally searchable models

​Index management

​Batch import

​Flushing the index

​Pausing indexing

​Manually adding and removing records

​Searching

​Semantic search

​Pagination

​Filtering and sorting

​Eager loading

​Soft deleting

​Custom engines

​Related pages

Eloquent ORM

Eloquent relationships

Queues

Introduction

Supported engines

Installation

Queueing

Unique indexing jobs

Driver prerequisites

Algolia

Index settings

Meilisearch

Index settings (Meilisearch)

Semantic and hybrid search (Meilisearch)

Typesense

Embeddings

Turbopuffer

Turbopuffer configuration

Database / collection engines

Semantic and hybrid search

The Searchable trait

Customizing toSearchableArray()

Customizing the index name

Database engine search strategies

PostgreSQL full-text search

PostgreSQL search options

Conditionally searchable models

Index management

Batch import

Flushing the index

Pausing indexing

Manually adding and removing records

Searching

Semantic search

Pagination

Filtering and sorting

Eager loading

Soft deleting

Custom engines

Related pages