Laravel 中文文档

主题

全部文档

Laravel Scout ​

介绍 ​

Laravel Scout 提供基于驱动的简洁方案，为 Eloquent 模型 添加全文搜索。借助模型观察者，Scout 会自动保持搜索索引与 Eloquent 记录同步。

Scout 内置 database 引擎，使用 MySQL / PostgreSQL 全文索引与 LIKE 子句搜索现有数据库，无需外部服务。对大多数应用已足够。Laravel 全部搜索选项概览请参阅搜索文档。

当需要拼写容错、分面过滤、向量搜索或大规模地理搜索时，Scout 还提供 Algolia、Meilisearch、Typesense 与 Turbopuffer 驱动。另有「collection」驱动用于本地开发，也可编写自定义引擎。

安装 ​

首先，通过 Composer 安装 Scout：

shell
composer require laravel/scout

安装 Scout 后，应使用 vendor:publish Artisan 命令发布 Scout 配置文件。该命令会将 scout.php 发布到应用的 config 目录：

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

最后，为要设为可搜索的模型添加 Laravel\Scout\Searchable trait。该 trait 会注册模型观察者，自动保持模型与搜索驱动同步：

php
<?php

namespace App\Models;

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

class Post extends Model
{
    use Searchable;
}

队列 ​

使用非 database 或 collection 引擎时，强烈建议在使用库之前配置队列驱动。运行队列 worker 后，Scout 可将同步模型信息到搜索索引的操作入队，显著提升 Web 界面响应时间。

配置队列驱动后，将 config/scout.php 中的 queue 选项设为 true：

php
'queue' => true,

即使 queue 为 false，也要记住 Algolia、Meilisearch 等驱动始终异步索引。也就是说，Laravel 应用内索引操作虽已完成，搜索引擎本身可能不会立即反映新增与更新记录。

要指定 Scout 任务使用的连接与队列，可将 queue 配置项定义为数组：

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

当然，若自定义了 Scout 任务使用的连接与队列，应运行队列 worker 处理该连接与队列上的任务：

shell
php artisan queue:work redis --queue=scout

唯一任务 ​

在写入密集的应用中，你可能希望避免 Scout 为同一模型记录入队重复任务。可注册 MakeSearchableUniquely 与 RemoveFromSearchUniquely 任务类以启用唯一索引任务，通常在服务提供者的 boot 方法中完成：

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

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

这些任务使用 Laravel 的唯一任务锁，在已有匹配任务排队时，避免为同一可搜索模型记录重复派发索引任务。

驱动前置条件 ​

Algolia ​

使用 Algolia 驱动时，应在 config/scout.php 中配置 Algolia 的 id 与 secret 凭据。配置完成后，还需通过 Composer 安装 Algolia PHP SDK：

shell
composer require algolia/algoliasearch-client-php

Meilisearch ​

Meilisearch 是快速的开源搜索引擎。若不确定如何在本地安装，可使用 Laravel Sail——Laravel 官方支持的 Docker 开发环境。

使用 Meilisearch 驱动时，需通过 Composer 安装 Meilisearch PHP SDK：

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

然后在应用 .env 中设置 SCOUT_DRIVER 环境变量以及 Meilisearch 的 host 与 key 凭据：

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

有关 Meilisearch 的更多信息，请参阅 Meilisearch 文档。

此外，应查阅 Meilisearch 关于二进制兼容性的文档，确保安装的 meilisearch/meilisearch-php 版本与 Meilisearch 二进制版本兼容。

WARNING

在使用 Meilisearch 的应用上升级 Scout 时，应始终查阅 Meilisearch 服务本身的额外破坏性变更。

Typesense ​

Typesense 是极速开源搜索引擎，支持关键词搜索、语义搜索、地理搜索与向量搜索。

可自托管 Typesense，或使用 Typesense Cloud。

要在 Scout 中使用 Typesense，请通过 Composer 安装 Typesense PHP SDK：

shell
composer require typesense/typesense-php

然后在应用 .env 中设置 SCOUT_DRIVER 环境变量以及 Typesense 主机与 API 密钥凭据：

ini
SCOUT_DRIVER=typesense
TYPESENSE_API_KEY=masterKey
TYPESENSE_HOST=localhost

若使用 Laravel Sail，可能需要调整 TYPESENSE_HOST 以匹配 Docker 容器名。也可选填安装实例的端口、路径与协议：

ini
TYPESENSE_PORT=8108
TYPESENSE_PATH=
TYPESENSE_PROTOCOL=http

Typesense 集合的更多设置与 schema 定义见 config/scout.php。有关 Typesense 的更多信息，请参阅 Typesense 文档。

Turbopuffer ​

Turbopuffer 是支持全文、语义与混合搜索的搜索引擎。使用 Turbopuffer 驱动时，设置 SCOUT_DRIVER 环境变量并提供 Turbopuffer API 密钥：

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

TURBOPUFFER_REGION 环境变量为可选，默认为 gcp-us-central1。

配置 ​

配置可搜索数据 ​

默认情况下，模型的完整 toArray 形式会持久化到搜索索引。若要自定义同步到索引的数据，可在模型上重写 toSearchableArray 方法：

php
<?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;
    }
}

配置模型引擎 ​

搜索时，Scout 通常使用 scout 配置文件中指定的默认搜索引擎。但可通过重写模型的 searchableUsing 方法更改特定模型的搜索引擎：

php
<?php

namespace App\Models;

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

class User extends Model
{
    use Searchable;

    /**
     * Get the engine used to index the model.
     */
    public function searchableUsing(): Engine
    {
        return Scout::engine('meilisearch');
    }
}

Database / Collection 引擎 ​

Database 引擎 ​

WARNING

database 引擎目前支持 MySQL 与 PostgreSQL，二者均支持高速全文列索引。

database 引擎使用 MySQL / PostgreSQL 全文索引与 LIKE 子句直接搜索现有数据库。对许多应用而言，这是添加搜索最简单实用的方式，无需外部服务或额外基础设施。

使用 database 引擎时，将 SCOUT_DRIVER 环境变量设为 database：

ini
SCOUT_DRIVER=database

配置完成后，可定义可搜索数据并对模型执行搜索查询。与第三方引擎不同，database 引擎无需单独索引步骤，直接搜索数据库表。

在 PostgreSQL 配合 pgvector 扩展时，database 引擎支持语义与混合搜索。首先为模型表添加可空向量列与全文索引。向量列必须可空，因为 Scout 在模型持久化后才存储嵌入：

php
Schema::ensureVectorExtensionExists();

Schema::table('articles', function (Blueprint $table) {
    // ...

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

接下来在模型上定义 toSearchableEmbedding 方法。该方法可返回 Scout 应嵌入的源文本，或预计算的嵌入数组。Scout 默认将嵌入存入 embedding 列；若使用其他列，可在模型上定义 searchableEmbeddingColumn 方法。

自定义数据库搜索策略 ​

默认情况下，database 引擎会对配置为可搜索的每个模型属性执行 LIKE 查询。但可为特定列指定更高效的搜索策略：SearchUsingFullText 对该列使用数据库全文索引，SearchUsingPrefix 仅匹配字符串开头（example%），而非整串搜索（%example%）。

要定义该行为，在模型的 toSearchableArray 方法上分配 PHP 属性。未分配属性的列仍使用默认 LIKE 策略：

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

/**
 * Get the indexable data array for the model.
 *
 * @return array<string, mixed>
 */
#[SearchUsingPrefix(['id', 'email'])]
#[SearchUsingFullText(['bio'])]
public function toSearchableArray(): array
{
    return [
        'id' => $this->id,
        'name' => $this->name,
        'email' => $this->email,
        'bio' => $this->bio,
    ];
}

WARNING

在指定列使用全文查询约束之前，请确保该列已分配全文索引。

Collection 引擎 ​

「collection」引擎适用于快速原型、极小数据集（数百条记录）或运行测试。它从数据库取出所有可能记录，在 PHP 中用 Laravel 的 Str::is 辅助函数过滤，因此无需索引或数据库特定功能。超出简单场景时，应改用 database 引擎。

使用 collection 引擎时，可将 SCOUT_DRIVER 设为 collection，或在 scout 配置文件中直接指定 collection 驱动：

ini
SCOUT_DRIVER=collection

将 collection 驱动设为首选后，即可对模型执行搜索查询。使用 collection 引擎时无需搜索引擎索引（例如为 Algolia、Meilisearch 或 Typesense 建索引）。

与 Database 引擎的差异 ​

database 引擎借助全文索引与 LIKE 子句高效查找匹配记录，而 collection 引擎会取出全部记录在 PHP 中过滤。collection 引擎可移植性最强，适用于 Laravel 支持的所有关系型数据库（含 SQLite 与 SQL Server）；但效率远低于 database 引擎，不应用于大数据集。

第三方引擎配置 ​

以下配置选项仅在使用 Algolia、Meilisearch、Typesense 等第三方搜索引擎时相关。若使用 database 引擎，可跳过本节。

配置模型索引 ​

使用第三方引擎时，每个 Eloquent 模型会同步到给定搜索「索引」，其中包含该模型的全部可搜索记录。默认情况下，模型会持久化到与其典型「表」名匹配的索引，通常是模型名的复数形式；也可通过重写模型的 searchableAs 方法自定义索引：

php
<?php

namespace App\Models;

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

class Post extends Model
{
    use Searchable;

    /**
     * Get the name of the index associated with the model.
     */
    public function searchableAs(): string
    {
        return 'posts_index';
    }
}

INFO

使用 database 引擎时，searchableAs 方法无效，该引擎始终直接搜索模型的数据库表。

配置模型 ID ​

默认情况下，Scout 使用模型主键作为存入搜索索引的唯一 ID / 键。使用第三方引擎时若需自定义，可重写模型的 getScoutKey 与 getScoutKeyName 方法：

php
<?php

namespace App\Models;

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

class User extends Model
{
    use Searchable;

    /**
     * Get the value used to index the model.
     */
    public function getScoutKey(): mixed
    {
        return $this->email;
    }

    /**
     * Get the key name used to index the model.
     */
    public function getScoutKeyName(): mixed
    {
        return 'email';
    }
}

INFO

使用 database 引擎时，getScoutKey 与 getScoutKeyName 方法无效，该引擎始终使用模型主键。

Algolia ​

索引设置 ​

有时你可能想在 Algolia 索引上配置额外设置。虽可通过 Algolia UI 管理，但从 config/scout.php 直接管理索引配置的期望状态有时更高效。

这样可通过自动化部署流水线发布这些设置，避免手动配置并确保多环境一致。可配置可过滤属性、排序、分面或其他支持的设置。

首先，在 config/scout.php 中为每个索引添加设置：

php
use App\Models\User;
use App\Models\Flight;

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

若给定索引的底层模型可软删除且包含在 index-settings 数组中，Scout 会自动在该索引上支持对软删除模型的分面。若软删除模型索引没有其他分面属性可定义，可为该模型在 index-settings 中添加空条目：

php
'index-settings' => [
    Flight::class => []
],

配置索引设置后，必须执行 scout:sync-index-settings Artisan 命令，将当前索引设置同步到 Algolia。为方便起见，可将其纳入部署流程：

shell
php artisan scout:sync-index-settings

识别用户 ​

Scout 在使用 Algolia 时支持自动识别用户。将已认证用户与搜索操作关联，有助于在 Algolia 仪表板中查看搜索分析。可在 .env 中将 SCOUT_IDENTIFY 设为 true 以启用：

ini
SCOUT_IDENTIFY=true

启用后，还会将请求 IP 地址与已认证用户的主标识符传给 Algolia，使这些数据与用户发起的搜索请求关联。

Meilisearch ​

索引设置 ​

Meilisearch 要求预先定义索引搜索设置，例如可过滤属性、可排序属性及其他支持的设置字段。

可过滤属性是调用 Scout 的 where 方法时计划用于过滤的属性；可排序属性是调用 orderBy 时计划用于排序的属性。在 scout 配置文件的 meilisearch 配置项中调整 index-settings 部分即可定义索引设置：

php
use App\Models\User;
use App\Models\Flight;

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

若给定索引的底层模型可软删除且包含在 index-settings 中，Scout 会自动在该索引上支持过滤软删除模型。若无其他可过滤或可排序属性，可为该模型在 index-settings 中添加空条目：

php
'index-settings' => [
    Flight::class => []
],

配置索引设置后，必须执行 scout:sync-index-settings Artisan 命令，将当前索引设置同步到 Meilisearch。为方便起见，可将其纳入部署流程：

shell
php artisan scout:sync-index-settings

要在 Meilisearch 中使用语义或混合搜索，需在索引设置中为每个可搜索模型配置嵌入器与嵌入设置：

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

模型的 toSearchableEmbedding 方法可返回源文本（Scout 使用 Laravel AI SDK 嵌入）或预计算的嵌入数组。更新配置后运行 scout:sync-index-settings 命令。

可搜索数据类型 ​

Meilisearch 仅对正确类型的数据执行过滤操作（>、< 等）。自定义可搜索数据时，应确保数值已转换为正确类型：

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

Typesense ​

准备可搜索数据 ​

使用 Typesense 时，可搜索模型必须定义 toSearchableArray 方法，将主键转为字符串、创建时间转为 UNIX 时间戳：

php
/**
 * Get the indexable data array for the model.
 *
 * @return array<string, mixed>
 */
public function toSearchableArray(): array
{
    return array_merge($this->toArray(),[
        'id' => (string) $this->id,
        'created_at' => $this->created_at->timestamp,
    ]);
}

还应在 config/scout.php 中定义 Typesense 集合 schema。集合 schema 描述通过 Typesense 可搜索的各字段数据类型。所有可用 schema 选项请参阅 Typesense 文档。

定义后若需更改 Typesense 集合 schema，可运行 scout:flush 与 scout:import（会删除所有已索引数据并重建 schema），或使用 Typesense API 在不删除已索引数据的情况下修改 schema。

若可搜索模型可软删除，应在 config/scout.php 中该模型对应的 Typesense schema 中定义 __soft_deleted 字段：

php
User::class => [
    'collection-schema' => [
        'fields' => [
            // ...
            [
                'name' => '__soft_deleted',
                'type' => 'int32',
                'optional' => true,
            ],
        ],
    ],
],

动态搜索参数 ​

Typesense 允许通过 options 方法在执行搜索时动态修改搜索参数：

php
use App\Models\Todo;

Todo::search('Groceries')->options([
    'query_by' => 'title, description'
])->get();

Turbopuffer ​

Turbopuffer 要求每个模型都有 schema 与可搜索属性。在 scout 配置文件的 turbopuffer 配置的 model-settings 数组中定义：

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

searchable-attributes 的数值为相对 BM25 权重。上例中，标题匹配得分为正文匹配的三倍。

要启用语义与混合搜索，在模型配置中添加 embedding 设置与向量 schema：

php
'turbopuffer' => [
    // ...
    'model-settings' => [
        Article::class => [
            'searchable-attributes' => [
                'title' => 3,
                'body' => 1,
            ],
            'embedding' => [
                'attribute' => 'embedding',
                'dimensions' => 1536,
            ],
            'schema' => [
                'title' => ['type' => 'string', 'full_text_search' => true],
                'body' => ['type' => 'string', 'full_text_search' => true],
                'embedding' => ['type' => '[1536]f32', 'ann' => true],
            ],
        ],
    ],
],

模型的 toSearchableEmbedding 方法应返回 Scout 应嵌入的源文本或预计算的嵌入数组。Scout 使用 Laravel AI SDK 生成源文本嵌入。

或者，可不安装 Laravel AI SDK、不定义 toSearchableEmbedding 方法，而使用 Turbopuffer 原生嵌入。将嵌入驱动设为 turbopuffer，并在可搜索源属性上配置 embed schema：

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

'schema' => [
    // ...
    'embedding_text' => [
        'type' => 'string',
        'embed' => [
            'model' => 'voyage/voyage-4',
            'dimensions' => 1024,
            'attribute' => 'embedding',
        ],
    ],
],

源属性必须包含在模型的 toSearchableArray 输出中。

第三方引擎索引 ​

INFO

本节索引功能主要适用于第三方引擎（Algolia、Meilisearch、Typesense 或 Turbopuffer）。database 引擎直接搜索数据库表，无需手动管理索引。

批量导入 ​

在现有项目中安装 Scout 时，可能已有需要导入索引的数据库记录。Scout 提供 scout:import Artisan 命令，可将所有现有记录导入搜索索引：

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

可使用 scout:queue-import 命令通过队列任务导入所有现有记录：

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

可使用 flush 命令从搜索索引中移除某模型的全部记录：

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

修改导入查询 ​

若要修改批量导入时获取全部模型的查询，可在模型上定义 makeAllSearchableUsing 方法。这是导入前添加必要关联预加载的好地方：

php
use Illuminate\Database\Eloquent\Builder;

/**
 * Modify the query used to retrieve models when making all of the models searchable.
 */
protected function makeAllSearchableUsing(Builder $query): Builder
{
    return $query->with('author');
}

WARNING

使用队列批量导入模型时，makeAllSearchableUsing 方法可能不适用。任务处理模型集合时关联不会恢复。

添加记录 ​

为模型添加 Laravel\Scout\Searchable trait 后，只需 save 或 create 模型实例，就会自动加入搜索索引。若已配置 Scout 使用队列，该操作由队列 worker 在后台执行：

php
use App\Models\Order;

$order = new Order;

// ...

$order->save();

通过查询添加记录 ​

若要通过 Eloquent 查询将一批模型加入搜索索引，可在查询上链式调用 searchable 方法。该方法会分块查询结果并加入索引。若配置了队列，各分块由队列 worker 在后台导入：

php
use App\Models\Order;

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

也可在 Eloquent 关联实例上调用 searchable 方法：

php
$user->orders()->searchable();

或者，若内存中已有 Eloquent 模型集合，可在集合实例上调用 searchable，将模型实例加入对应索引：

php
$orders->searchable();

INFO

searchable 方法可视为「upsert」操作：若模型记录已在索引中则更新，否则加入索引。

更新记录 ​

更新可搜索模型时，只需修改属性并 save 到数据库，Scout 会自动将变更持久化到搜索索引：

php
use App\Models\Order;

$order = Order::find(1);

// Update the order...

$order->save();

也可在 Eloquent 查询实例上调用 searchable 更新一批模型。若模型不在搜索索引中，将被创建：

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

若要更新关联中所有模型的搜索索引记录，可在关联实例上调用 searchable：

php
$user->orders()->searchable();

或者，若内存中已有 Eloquent 模型集合，可在集合实例上调用 searchable 更新对应索引中的模型实例：

php
$orders->searchable();

导入前修改记录 ​

有时需要在设为可搜索前准备模型集合。例如预加载关联，以便高效将关联数据加入搜索索引。可在对应模型上定义 makeSearchableUsing 方法：

php
use Illuminate\Database\Eloquent\Collection;

/**
 * Modify the collection of models being made searchable.
 */
public function makeSearchableUsing(Collection $models): Collection
{
    return $models->load('author');
}

条件更新搜索索引 ​

默认情况下，无论修改了哪些属性，Scout 都会重新索引已更新的模型。若要自定义该行为，可在模型上定义 searchIndexShouldBeUpdated 方法：

php
/**
 * Determine if the search index should be updated.
 */
public function searchIndexShouldBeUpdated(): bool
{
    return $this->wasRecentlyCreated || $this->wasChanged(['title', 'body']);
}

移除记录 ​

要从索引移除记录，只需从数据库 delete 模型。即使使用软删除模型也可如此操作：

php
use App\Models\Order;

$order = Order::find(1);

$order->delete();

若不想先获取模型再删除，可在 Eloquent 查询实例上使用 unsearchable 方法：

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

若要移除关联中所有模型的搜索索引记录，可在关联实例上调用 unsearchable：

php
$user->orders()->unsearchable();

或者，若内存中已有 Eloquent 模型集合，可在集合实例上调用 unsearchable 从对应索引移除模型实例：

php
$orders->unsearchable();

要从对应索引移除某模型的全部记录，可调用 removeAllFromSearch 方法：

php
Order::removeAllFromSearch();

暂停索引 ​

有时需要批量执行 Eloquent 操作而不同步到搜索索引。可使用 withoutSyncingToSearch 方法，它接受一个立即执行的闭包；闭包内的模型操作不会同步到索引：

php
use App\Models\Order;

Order::withoutSyncingToSearch(function () {
    // Perform model actions...
});

条件可搜索模型实例 ​

有时只需在特定条件下使模型可搜索。例如 App\Models\Post 可能有「draft」与「published」两种状态，你可能只希望「published」帖子可搜索。可在模型上定义 shouldBeSearchable 方法：

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

shouldBeSearchable 仅在通过 save、create、查询或关联操作模型时生效。直接使用 searchable 方法会使模型或集合可搜索，将覆盖 shouldBeSearchable 的结果。

WARNING

使用 Scout 的「database」引擎时，shouldBeSearchable 不适用，因为所有可搜索数据始终存储在数据库中。使用 database 引擎时若要类似行为，应改用 where 子句。

搜索 ​

可使用 search 方法开始搜索模型。该方法接受一个用于搜索的字符串，然后在搜索查询上链式调用 get 获取匹配的 Eloquent 模型：

php
use App\Models\Order;

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

由于 Scout 搜索返回 Eloquent 模型集合，可直接从路由或控制器返回结果，它们会自动转为 JSON：

php
use App\Models\Order;
use Illuminate\Http\Request;

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

若要在转换为 Eloquent 模型之前获取原始搜索结果，可使用 raw 方法：

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

database、Meilisearch 与 Turbopuffer 引擎支持语义搜索，按查询含义匹配记录。Scout 生成嵌入时，语义与混合搜索需要 Laravel AI SDK。Turbopuffer 的原生嵌入与预计算查询向量不需要 Laravel AI SDK。

为所选引擎配置嵌入后，在搜索查询上调用 semantic 方法：

php
$articles = Article::search('staying cool in the summer')
    ->semantic()
    ->get();

所选引擎支持时，可指定最小相似度阈值：

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

要组合全文与语义搜索，使用 hybrid 方法。前两个参数控制文本与语义结果的相对权重：

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

自定义索引 ​

使用第三方引擎搜索时，查询通常在模型 searchableAs 方法指定的索引上执行。也可使用 within 方法指定要搜索的自定义索引：

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

Where 子句 ​

Scout 允许为搜索查询添加「where」子句。例如，基本相等检查可用于按所有者 ID 限定搜索范围：

php
use App\Models\Order;

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

也可使用 =、!=、<、>、>=、<= 比较运算符构建更复杂的查询：

php
Order::search('Star Trek')
  ->where('status', '=', 'completed')
  ->where('is_refunded', '!=', true)
  ->where('total_price', '>', 100)
  ->where('shipping_cost', '<', 20)
  ->where('discount_percent', '>=', 10)
  ->where('item_count', '<=', 5)
  ->get();

此外，whereIn 方法可验证给定列的值是否包含在指定数组中：

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

whereNotIn 方法验证给定列的值不在指定数组中：

php
$orders = Order::search('Star Trek')->whereNotIn(
    'status', ['closed']
)->get();

WARNING

若应用使用 Meilisearch，在使用 Scout 的「where」子句之前，必须配置应用的可过滤属性。

自定义 Eloquent 结果查询 ​

Scout 从搜索引擎获取匹配的 Eloquent 模型列表后，Eloquent 会按主键检索所有匹配模型。可调用 query 方法自定义该查询；query 接受一个闭包，参数为 Eloquent 查询构建器实例：

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

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

使用第三方引擎时，该回调在已从搜索引擎获取相关模型之后调用，因此不应用于「过滤」结果——应改用 Scout where 子句。使用 database 引擎时，query 方法的约束会直接应用于数据库查询，也可用于过滤。

分页 ​

除获取模型集合外，还可使用 paginate 方法对搜索结果分页。该方法返回 Illuminate\Pagination\LengthAwarePaginator 实例，与对传统 Eloquent 查询分页相同：

php
use App\Models\Order;

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

可将每页数量作为 paginate 方法的第一个参数传入：

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

使用 database 引擎时，也可使用 simplePaginate 方法。与 paginate 会获取匹配总数以显示页码不同，simplePaginate 仅判断当前页之后是否还有更多结果——对只需「上一页」「下一页」链接的大数据集更高效：

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

获取结果后，可使用 Blade 展示结果并渲染分页链接，与传统 Eloquent 查询分页相同：

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

{{ $orders->links() }}

当然，若要以 JSON 获取分页结果，可直接从路由或控制器返回分页器实例：

php
use App\Models\Order;
use Illuminate\Http\Request;

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

WARNING

搜索引擎不知道 Eloquent 模型的全局作用域定义，使用 Scout 分页的应用不应使用全局作用域；或在通过 Scout 搜索时重新应用全局作用域的约束。

软删除 ​

若索引模型支持软删除且需要搜索软删除模型，将 config/scout.php 中的 soft_delete 选项设为 true：

php
'soft_delete' => true,

当该配置为 true 时，Scout 不会从搜索索引移除软删除模型，而是在索引记录上设置隐藏的 __soft_deleted 属性。搜索时可使用 withTrashed 或 onlyTrashed 方法获取软删除记录：

php
use App\Models\Order;

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

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

INFO

使用 forceDelete 永久删除软删除模型时，Scout 会自动从搜索索引中移除它。

自定义引擎搜索 ​

若需对引擎搜索行为做高级自定义，可将闭包作为 search 方法的第二个参数。例如，在将查询传给 Algolia 之前，可用该回调向搜索选项添加地理位置数据：

php
use Algolia\AlgoliaSearch\SearchIndex;
use App\Models\Order;

Order::search(
    'Star Trek',
    function (SearchIndex $algolia, string $query, array $options) {
        $options['body']['query']['bool']['filter']['geo_distance'] = [
            'distance' => '1000km',
            'location' => ['lat' => 36, 'lon' => 111],
        ];

        return $algolia->search($query, $options);
    }
)->get();

自定义引擎 ​

编写引擎 ​

若内置 Scout 搜索引擎都不满足需求，可自行编写自定义引擎并向 Scout 注册。引擎应继承 Laravel\Scout\Engines\Engine 抽象类，该类包含自定义引擎必须实现的八个方法：

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

建议参考 Laravel\Scout\Engines\AlgoliaEngine 类中这些方法的实现，作为在自己引擎中实现各方法的良好起点。

注册引擎 ​

编写自定义引擎后，可使用 Scout 引擎管理器的 extend 方法向 Scout 注册。引擎管理器可从 Laravel 服务容器解析。应在 App\Providers\AppServiceProvider 或其他服务提供者的 boot 方法中调用 extend：

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

/**
 * Bootstrap any application services.
 */
public function boot(): void
{
    resolve(EngineManager::class)->extend('mysql', function () {
        return new MySqlSearchEngine;
    });
}

注册引擎后，可在 config/scout.php 中将其指定为默认 Scout driver：

php
'driver' => 'mysql',