Scout-Laravel 文档-果果开发

简介

Laravel Scout 提供了一个简单且基于驱动的解决方案，用于为你的 Eloquent 模型添加全文搜索功能。借助模型观察者，Scout 会自动保持搜索索引与你 Eloquent 记录的同步。

Scout 内置了 database 引擎，它使用 MySQL / PostgreSQL 的全文索引和 LIKE 子句来搜索你现有的数据库——无需外部服务。对于大多数应用而言，这已经足够了。若想了解 Laravel 中所有可用搜索选项的概览，请查阅搜索文档。

当你需要容错（容忍拼写错误）、分面过滤、向量搜索或大规模地理搜索等功能时，Scout 还包含了对 Algolia、Meilisearch、Typesense 以及 Turbopuffer 的驱动支持。Scout 还提供了一个用于本地开发的“集合（collection）”驱动，你也可以自行编写自定义引擎。

安装

首先，通过 Composer 包管理器安装 Scout：

composer require laravel/scout

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

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

最后，将 Laravel\Scout\Searchable 特性（trait）添加到你希望可被搜索的模型中。该特性会注册一个模型观察者，从而自动保持该模型与搜索驱动的同步：

<?php

namespace App\Models;

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

class Post extends Model
{
    use Searchable;
}

队列处理

当使用的引擎不是 database 或 collection 引擎时，强烈建议你在使用该库之前先配置好队列驱动。运行队列工作进程可以让 Scout 将所有将模型信息同步到搜索索引的操作加入队列，从而为应用的 Web 界面提供更好的响应速度。

一旦配置好队列驱动，请将 config/scout.php 配置文件中的 queue 选项的值设置为 true：

'queue' => true,

即使 queue 选项被设置为 false，也请务必记住，部分 Scout 驱动（如 Algolia 和 Meilisearch）始终会异步对记录进行索引。换句话说，尽管索引操作已在 Laravel 应用内完成，但搜索引擎本身可能并不会立即反映出新增和更新的记录。

为了指定 Scout 任务所使用的连接和队列，你可以将 queue 配置选项定义为数组：

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

当然，如果你自定义了 Scout 任务所使用的连接和队列，就应该运行队列工作进程，以在该连接和队列上处理任务：

php artisan queue:work redis --queue=scout

唯一任务

在写操作密集型的应用中，你可能希望阻止 Scout 针对同一模型记录排队重复任务。你可以通过注册 MakeSearchableUniquely 和 RemoveFromSearchUniquely 任务类来选择启用唯一索引任务，通常在服务提供者的 boot 方法中进行注册：

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：

composer require algolia/algoliasearch-client-php

Meilisearch

Meilisearch 是一款快速、开源的搜索引擎，支持全文搜索、语义搜索和混合搜索。如果你不确定如何在本地计算机上安装 Meilisearch，可以使用 Laravel Sail，这是 Laravel 官方支持的 Docker 开发环境。对于生产环境，你可以自托管 Meilisearch，或者使用 Meilisearch Cloud。

使用 Meilisearch 驱动时，你需要通过 Composer 包管理器安装 Meilisearch PHP SDK：

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

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

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

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

Typesense

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

你可以自托管 Typesense，或者使用 Typesense Cloud。

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

composer require typesense/typesense-php

然后，在应用的 .env 文件中设置 SCOUT_DRIVER 环境变量，以及你的 Typesense 主机和 API 密钥凭据：

SCOUT_DRIVER=typesense
TYPESENSE_API_KEY=masterKey
TYPESENSE_HOST=localhost

如果你使用的是 Laravel Sail，可能需要调整 TYPESENSE_HOST 环境变量，使其与 Docker 容器名称匹配。你还可以选择指定安装实例的端口、路径和协议：

TYPESENSE_PORT=8108
TYPESENSE_PATH=
TYPESENSE_PROTOCOL=http

Typesense 集合的其他设置和模式定义，可以在应用的 config/scout.php 配置文件中找到。关于 Typesense 的更多信息，请参阅 Typesense 文档。

Turbopuffer

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

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

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

配置

配置可搜索数据

默认情况下，给定模型的整个 toArray 形式会被持久化到其搜索索引中。如果你想自定义同步到搜索索引中的数据，可以在模型中重写 toSearchableArray 方法：

<?php

namespace App\Models;

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

class Post extends Model
{
    use Searchable;

    /**
     * 获取模型的可索引数据数组。
     *
     * @return array<string, mixed>
     */
    public function toSearchableArray(): array
    {
        $array = $this->toArray();

        // 自定义数据数组...

        return $array;
    }
}

配置模型引擎

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

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

    /**
     * 获取用于为模型建立索引的搜索引擎。
     */
    public function searchableUsing(): Engine
    {
        return Scout::engine('meilisearch');
    }
}

数据库 / 集合引擎

数据库引擎

数据库引擎目前支持 MySQL 和 PostgreSQL，这两者都提供了对快速全文列索引的支持。

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

要使用数据库引擎，请将 SCOUT_DRIVER 环境变量设置为 database：

SCOUT_DRIVER=database

配置完成后，您可以定义可搜索的数据，并开始对模型执行搜索查询。与第三方引擎不同，数据库引擎不需要单独的索引步骤 —— 它会直接搜索您的数据库表。

语义搜索与混合搜索

当使用 PostgreSQL 并配合 pgvector 扩展时，数据库引擎支持语义搜索和混合搜索。要开始使用，请在模型表中添加一个可为空的向量列以及一个全文索引。该向量列必须可为空，因为 Scout 会在模型持久化之后存储嵌入向量：

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 方法。

自定义数据库搜索策略

默认情况下，数据库引擎会对您配置为可搜索的每个模型属性执行 LIKE 查询。不过，您可以为特定列指定更高效的搜索策略。SearchUsingFullText 属性会使用数据库针对该列的全文索引，而 SearchUsingPrefix 则只会匹配字符串的开头（example%），而不是在整个字符串中进行搜索（%example%）。

要定义这种行为，请将 PHP 属性分配给您模型的 toSearchableArray 方法。任何未设置属性的列将继续使用默认的 LIKE 策略：

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

/**
 * 获取模型的可索引数据数组。
 *
 * @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,
    ];
}

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

集合引擎

“collection”引擎适用于快速原型开发、极小数据集（几百条记录）或运行测试。它会从您的数据库中检索所有可能的记录，并使用 Laravel 的 Str::is 辅助函数在 PHP 中进行过滤，因此不需要任何索引或特定于数据库的功能。对于任何超出简单用例的场景，您应该使用数据库引擎。

要使用集合引擎，您可以简单地将 SCOUT_DRIVER 环境变量的值设置为 collection，或者直接在应用程序的 scout 配置文件中指定 collection 驱动：

SCOUT_DRIVER=collection

一旦将集合驱动指定为您的首选驱动，就可以开始对模型执行搜索查询了。使用集合引擎时，不需要进行搜索引擎索引操作，例如为 Algolia、Meilisearch 或 Typesense 索引建立索引等操作。

与数据库引擎的差异

数据库引擎使用全文索引和 LIKE 子句来高效地查找匹配记录，而集合引擎会拉取所有记录并在 PHP 中进行过滤。集合引擎是最可移植的选项，因为它适用于 Laravel 支持的所有关系型数据库（包括 SQLite 和 SQL Server）；不过，它的效率远低于数据库引擎，不应用于处理大型数据集。

第三方引擎配置

以下配置选项仅在使用第三方搜索引擎（如 Algolia、Meilisearch 或 Typesense）时才相关。如果您使用的是数据库引擎，可以跳过本节。

配置模型索引

使用第三方引擎时，每个 Eloquent 模型都会与给定的搜索“索引”同步，该索引包含该模型所有可搜索的记录。默认情况下，每个模型都会被持久化到一个与模型典型“表”名称相匹配的索引中。通常，这是模型名称的复数形式；不过，您也可以通过在模型上重写 searchableAs 方法来自由自定义模型的索引：

<?php

namespace App\Models;

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

class Post extends Model
{
    use Searchable;

    /**
     * 获取与模型关联的索引名称。
     */
    public function searchableAs(): string
    {
        return 'posts_index';
    }
}

当使用数据库引擎时，searchableAs 方法没有效果，因为数据库引擎始终直接搜索模型的数据库表。

配置模型 ID

默认情况下，Scout 会使用模型的主键作为存储在搜索索引中的模型唯一 ID / 键。如果在使用第三方引擎时需要自定义此行为，您可以在模型上重写 getScoutKey 和 getScoutKeyName 方法：

<?php

namespace App\Models;

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

class User extends Model
{
    use Searchable;

    /**
     * 获取用于为模型建立索引的值。
     */
    public function getScoutKey(): mixed
    {
        return $this->email;
    }

    /**
     * 获取用于为模型建立索引的键名。
     */
    public function getScoutKeyName(): mixed
    {
        return 'email';
    }
}

当使用数据库引擎时，getScoutKey 和 getScoutKeyName 方法没有效果，因为数据库引擎始终使用模型的主键。

Algolia

索引设置

有时您可能想要在 Algolia 索引上配置其他设置。虽然您可以通过 Algolia UI 来管理这些设置，但有时直接从应用程序的 config/scout.php 配置文件中管理索引配置的期望状态会更高效。

这种方式允许您通过应用程序的自动化部署流水线来部署这些设置，避免了手动配置，并确保了多个环境之间的一致性。您可以配置可过滤属性、排序、分面，或者任何其他支持的设置。

要开始使用，请在应用程序的 config/scout.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)'],
            // 其他设置字段...
        ],
        Flight::class => [
            'searchableAttributes'=> ['id', 'destination'],
        ],
    ],
],

如果给定索引背后的模型支持软删除，并且该模型包含在 index-settings 数组中，Scout 将自动在该索引上包含对软删除模型进行分面搜索的支持。如果您没有其他要为支持软删除的模型索引定义的分面属性，您可以简单地为该模型在 index-settings 数组中添加一个空条目：

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

配置完应用程序的索引设置后，您必须调用 scout:sync-index-settings Artisan 命令。此命令会将您当前配置的索引设置通知 Algolia。为了方便起见，您可能希望将此命令纳入您的部署流程：

php artisan scout:sync-index-settings

识别用户

Scout 可让您在使用 Algolia 时自动识别用户。将已认证用户与搜索操作关联起来，在 Algolia 的仪表板中查看搜索分析时会很有帮助。您可以通过在应用程序的 .env 文件中将 SCOUT_IDENTIFY 环境变量定义为 true 来启用用户识别功能：

SCOUT_IDENTIFY=true

启用此功能还会将请求的 IP 地址和已认证用户的主要标识符传递给 Algolia，以便将此数据与用户发起的任何搜索请求关联起来。

Meilisearch

索引设置

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

可过滤属性是指您计划在调用 Scout 的 where 方法时进行过滤的任何属性，而可排序属性是指您计划在调用 Scout 的 orderBy 方法时进行排序的任何属性。要定义索引设置，请调整应用程序 scout 配置文件中 meilisearch 配置项的 index-settings 部分：

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 数组中为该模型添加一个空条目即可：

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

配置好应用程序的索引设置后，必须执行 scout:sync-index-settings Artisan 命令。该命令会将您当前配置的索引设置告知 Meilisearch。为方便起见，您可能需要将此命令纳入部署流程：

php artisan scout:sync-index-settings

语义搜索和混合搜索

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

'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 命令。

或者，您可以将嵌入 driver 设置为 meilisearch，从而使用 Meilisearch 的原生嵌入功能。在此模式下，Meilisearch 会使用配置的嵌入器生成文档和查询嵌入，因此不需要 dimensions 选项和 toSearchableEmbedding 方法：

'meilisearch' => [
    'index-settings' => [
        Article::class => [
            'embedders' => [
                'default' => [
                    'source' => 'openAi',
                    'apiKey' => env('OPENAI_API_KEY'),
                    'model' => 'text-embedding-3-small',
                    'documentTemplate' => 'An article titled {{ doc.title }}: {{ doc.body }}',
                ],
            ],
        ],
    ],
    'model-settings' => [
        Article::class => [
            'embedding' => [
                'embedder' => 'default',
                'driver' => 'meilisearch',
            ],
        ],
    ],
],

使用原生嵌入时，Scout 不会为已索引的文档生成向量或添加向量。您仍然可以使用 vector 搜索选项提供预计算的查询向量。与处理其他索引设置一样，更新嵌入器配置后需运行 scout:sync-index-settings 命令。

如需了解可用嵌入器来源及其选项的更多信息，请参阅Meilisearch 混合搜索文档。

可搜索数据类型

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

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

Typesense

准备可搜索数据

使用 Typesense 时，您的可搜索模型必须定义一个 toSearchableArray 方法，该方法需将模型的主键转换为字符串，并将创建日期转换为 UNIX 时间戳：

/**
 * 获取模型的可索引数据数组。
 *
 * @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 集合架构。集合架构描述了可通过 Typesense 搜索的每个字段的数据类型。如需了解所有可用架构选项的更多信息，请参阅Typesense 文档。

如果在定义 Typesense 集合的架构后需要对其进行更改，您可以运行 scout:flush 和 scout:import，这将删除所有已索引的数据并重新创建架构；或者，您可以使用 Typesense 的 API 来修改集合的架构，且无需删除任何已索引的数据。

如果您的可搜索模型支持软删除，应在应用程序 config/scout.php 配置文件中该模型对应的 Typesense 架构内定义一个 __soft_deleted 字段：

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

嵌入

要启用语义搜索和混合搜索，需在模型的 Typesense 配置中定义 embedding 设置和向量字段。默认情况下，Scout 使用Laravel AI SDK来生成嵌入：

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

模型的 toSearchableEmbedding 方法应返回 Scout 应进行嵌入处理的源文本，或者返回预计算的嵌入数组：

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

动态搜索参数

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

use App\Models\Todo;

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

Turbopuffer

Turbopuffer 要求为每个模型定义架构和可搜索属性。请在 scout 配置文件中 turbopuffer 配置的 model-settings 数组中定义这些内容：

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：

'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 需要嵌入的源文本，或预先计算好的 embedding 数组。Scout 使用 Laravel AI SDK 生成源文本的 embedding。

或者，您也可以使用 Turbopuffer 的原生 embedding，无需安装 Laravel AI SDK，也无需定义 toSearchableEmbedding 方法。将 embedding 驱动设置为 turbopuffer，并在可搜索的源属性上配置 embed schema：

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

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

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

第三方引擎索引

本节所述的索引功能主要在使用第三方引擎（Algolia、Meilisearch、Typesense 或 Turbopuffer）时才有意义。数据库引擎会直接搜索您的数据库表，因此无需手动管理索引。

批量导入

如果您要将 Scout 安装到现有项目中，可能已有需要导入到索引的数据库记录。Scout 提供了 scout:import Artisan 命令，您可以使用它将所有现有记录导入到搜索索引中：

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

可以使用 scout:queue-import 命令，通过队列作业来导入所有现有记录：

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

可以使用 flush 命令，从搜索索引中删除模型的所有记录：

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

修改导入查询

如果您想修改用于检索所有模型以进行批量导入的查询，可以在模型上定义 makeAllSearchableUsing 方法。这是在导入模型之前添加必要的预加载关联的理想位置：

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

使用队列批量导入模型时，makeAllSearchableUsing 方法可能不适用。当模型集合由作业处理时，关联不会被还原。

添加记录

一旦在模型中添加了 Laravel\Scout\Searchable trait，您只需对模型实例执行 save 或 create 操作，它就会自动添加到搜索索引中。如果您已将 Scout 配置为使用队列，此操作将由队列工作进程在后台执行：

use App\Models\Order;

$order = new Order;

// ...

$order->save();

通过查询添加记录

如果您想通过 Eloquent 查询将一组模型添加到搜索索引中，可以在 Eloquent 查询上链式调用 searchable 方法。searchable 方法会对查询结果分块，并将记录添加到搜索索引中。同样，如果您已将 Scout 配置为使用队列，所有分块都将由队列工作进程在后台导入：

use App\Models\Order;

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

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

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

或者，如果您内存中已有 Eloquent 模型集合，可以在集合实例上调用 searchable 方法，将模型实例添加到对应的索引中：

$orders->searchable();

searchable 方法可视为一种“upsert”操作。也就是说，如果模型记录已在索引中，它会执行更新；如果搜索索引中不存在，则会将其添加到索引中。

更新记录

要更新可搜索的模型，您只需更新模型实例的属性，并将模型 save 到数据库中。Scout 会自动将更改同步到搜索索引：

use App\Models\Order;

$order = Order::find(1);

// Update the order...

$order->save();

您也可以在 Eloquent 查询实例上调用 searchable 方法来更新一组模型。如果模型在搜索索引中不存在，则会创建这些模型：

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

如果您想更新关联中所有模型的搜索索引记录，可以在关联实例上调用 searchable：

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

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

$orders->searchable();

导入前修改记录

有时，您可能需要在模型变为可搜索之前对其进行预处理。例如，您可能需要预加载关联，以便将关联数据高效添加到搜索索引中。要实现这一点，请在相应模型上定义 makeSearchableUsing 方法：

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 方法：

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

删除记录

要从索引中删除记录，您只需从数据库中 delete 该模型。即使您使用的是软删除模型，也可以执行此操作：

use App\Models\Order;

$order = Order::find(1);

$order->delete();

如果您不想在删除记录前检索模型，可以在 Eloquent 查询实例上使用 unsearchable 方法：

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

如果您想删除关联中所有模型的搜索索引记录，可以在关联实例上调用 unsearchable：

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

或者，如果你已经在内存中拥有一组 Eloquent 模型，你可以在集合实例上调用 unsearchable 方法，将这些模型实例从其对应的索引中移除：

$orders->unsearchable();

若要将所有模型记录从其对应的索引中移除，你可以调用 removeAllFromSearch 方法：

Order::removeAllFromSearch();

暂停索引

有时，你可能需要在不对模型数据同步到搜索索引的情况下，对模型执行一批 Eloquent 操作。你可以使用 withoutSyncingToSearch 方法来实现这一点。该方法接受一个闭包，该闭包会被立即执行。在闭包内发生的任何模型操作都不会同步到模型的索引中：

use App\Models\Order;

Order::withoutSyncingToSearch(function () {
    // 执行模型操作...
});

有条件地使模型实例可搜索

有时，你可能希望仅在特定条件下将模型设为可搜索。例如，假设你有一个 App\Models\Post 模型，它可能处于两种状态之一：“草稿”和“已发布”。你可能只想允许“已发布”的文章可被搜索。要实现这一点，你可以在模型中定义一个 shouldBeSearchable 方法：

/**
 * 确定该模型是否应被设为可搜索。
 */
public function shouldBeSearchable(): bool
{
    return $this->isPublished();
}

shouldBeSearchable 方法仅在通过 save 和 create 方法、查询或关系来操作模型时才会生效。如果直接使用 searchable 方法将模型或集合设为可搜索，则会覆盖 shouldBeSearchable 方法的判定结果。

在使用 Scout 的“数据库”引擎时，shouldBeSearchable 方法并不适用，因为所有可搜索的数据始终存储在数据库中。若要在使用数据库引擎时实现类似行为，应改用 where 子句。

搜索

你可以使用 search 方法开始对模型进行搜索。search 方法接受一个字符串参数，该字符串将用于搜索你的模型。然后，你可以将 get 方法链式调用到搜索查询上，以检索匹配给定搜索查询的 Eloquent 模型：

use App\Models\Order;

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

由于 Scout 的搜索结果会返回一个 Eloquent 模型集合，因此你甚至可以将结果直接从路由或控制器中返回，它们会被自动转换为 JSON：

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

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

如果你想在将搜索结果转换为 Eloquent 模型之前获取原始搜索结果，可以使用 raw 方法：

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

语义搜索

数据库、Meilisearch、Typesense 和 Turbopuffer 引擎支持语义搜索，它会根据查询的含义匹配记录。当 Scout 生成嵌入向量时，语义搜索和混合搜索需要使用 Laravel AI SDK。Typesense 的原生嵌入向量、Turbopuffer 的原生嵌入向量以及预先计算的查询向量则不需要使用 Laravel AI SDK。

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

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

当所选引擎支持时，你可以设置一个最低相似度阈值：

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

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

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

自定义索引

在使用第三方引擎进行搜索时，搜索查询通常会针对模型的 searchableAs 方法指定的索引执行。不过，你可以使用 within 方法来指定要搜索的自定义索引：

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

Where 子句

Scout 允许你在搜索查询中添加“where”子句。例如，使用基本相等性检查来按所有者 ID 限定搜索范围很有用：

use App\Models\Order;

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

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

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 方法来验证给定列的值是否包含在指定的数组中：

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

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

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

如果你的应用使用的是 Meilisearch，那么在使用 Scout 的“where”子句之前，必须先配置应用的可过滤属性。

自定义 Eloquent 结果查询

当 Scout 从应用的搜索引擎中检索到匹配的 Eloquent 模型列表后，Eloquent 会通过主键检索所有匹配的模型。你可以调用 query 方法来自定义此查询。query 方法接受一个闭包，该闭包会接收 Eloquent 查询构建器实例作为参数：

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

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

在使用第三方引擎时，该回调会在相关模型从搜索引擎中检索完成后才会被调用，因此不应将其用于“过滤”结果——此时应改用 Scout 的 where 子句。不过，在使用数据库引擎时，query 方法的限制条件会直接应用于数据库查询，因此也可以用它来进行过滤。

分页

除了检索模型集合外，你还可以使用 paginate 方法对搜索结果进行分页。该方法会返回一个 Illuminate\Pagination\LengthAwarePaginator 实例，就像你对传统的 Eloquent 查询进行了分页一样：

use App\Models\Order;

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

你可以将每页要检索的模型数量作为第一个参数传递给 paginate 方法，来指定每页的模型数量：

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

在使用数据库引擎时，你也可以使用 simplePaginate 方法。与会检索匹配记录的总数以显示页码的 paginate 不同，simplePaginate 只会判断当前页面之后是否还有更多结果——这使其在仅需要“上一页”和“下一页”链接的大型数据集场景下更为高效：

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

获取到结果后，你可以像对传统的 Eloquent 查询进行分页一样，使用 Blade 来展示结果并渲染页面链接：

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

{{ $orders->links() }}

当然，如果你想以 JSON 格式获取分页结果，可以直接将分页器实例从路由或控制器中返回：

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

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

由于搜索引擎并不了解你 Eloquent 模型的全局作用域定义，因此在使用 Scout 分页的应用中，不应使用全局作用域。或者，你应该在通过 Scout 搜索时重新构建全局作用域的限制条件。

软删除

如果你的已索引模型正在软删除，并且你需要搜索软删除的模型，请将 config/scout.php 配置文件中的 soft_delete 选项设置为 true：

'soft_delete' => true,

当此配置选项为 true 时，Scout 不会从搜索索引中移除软删除的模型。相反，它会在索引记录上设置一个隐藏的 __soft_deleted 属性。然后，你可以在搜索时使用 withTrashed 或 onlyTrashed 方法来检索软删除的记录：

use App\Models\Order;

// 在获取结果时包含已删除的记录……
$orders = Order::search('Star Trek')->withTrashed()->get();

// 仅在获取结果时包含已删除的记录……
$orders = Order::search('Star Trek')->onlyTrashed()->get();

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

自定义引擎搜索

如果你需要对引擎的搜索行为进行高级自定义，可以将一个闭包作为第二个参数传递给 search 方法。例如，你可以在搜索查询传递给 Algolia 之前，使用此回调将地理位置数据添加到搜索选项中：

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 抽象类。此抽象类包含你的自定义引擎必须实现的八个方法：

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 中。Scout 的引擎管理器可以从 Laravel 服务容器中解析出来。你应该从 App\Providers\AppServiceProvider 类或应用程序使用的任何其他服务提供者的 boot 方法中调用 extend 方法：

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

/**
 * 初始化任何应用服务。
 */
public function boot(): void
{
    resolve(EngineManager::class)->extend('mysql', function () {
        return new MySqlSearchEngine;
    });
}

一旦引擎注册成功，你就可以在应用程序的 config/scout.php 配置文件中将其指定为默认的 Scout driver：

'driver' => 'mysql',