Download the PHP package joba/scout without Composer

Hyperf 模型全文搜索组件

简介

hyperf-ext/scout 组件为 Hyperf 模型的全文搜索提供了基于 Elasticsearch 的简单的解决方案。通过使用模型观察者，组件会自动同步模型记录的搜索索引。

该组件移植自 Laravel Scout，与 Laravel Scout 不同的是，为了提升使用体验并更好的与 Elasticsearch 结合，该组件移除了自定义驱动的特性，仅支持 Elasticsearch，同时针对 Elasticsearch 的特性在原来的基础上进行了诸多的优化，通过队列更新索引的方式也改为通过协程实现。

另外，组件在搜索查询构造器中通过 ongr/elasticsearch-dsl 包来使用 Elasticsearch DSL 构建复杂的查询条件。

注意，组件依赖的 elasticsearch/elasticsearch 包版本为 ^7.9，映射类型已被废弃并将在 8.0 中彻底移除，因此组件同样也不提供映射类型的支持，即一个模型对应一个索引。

使用独立的索引取代使用映射类型可以让数据更倾向于密集而非稀疏，并且由于同一个索引中的所有的文档表示为同一种实体，在通过全文搜索时打分的条件统计会更为精确。

安装

该组件自动依赖了 hyperf-ext/elasticsearch 组件来使用 Elasticsearch 客户端，请在本组件安装完成后发布此组件的配置。

Scout 安装完成后，使用 vendor:publish 命令来生成 Scout 配置文件。这个命令将在你的 config/autoload 目录下生成一个 scout.php 配置文件。

最后，在你要做搜索的模型中添加 HyperfExt\Scout\Searchable Trait。这个 Trait 会自动注册一个模型观察者来保持模型和 Elasticsearch 的同步：

默认配置

配置模型

配置 Elasticsearch 索引设置

索引设置可以通过在模型中添加 scoutSettings 属性或重写 getScoutSettings 方法来配置：

配置 Elasticsearch 映射

映射可以通过在模型中添加 scoutMapping 属性或重写 getScoutMapping 方法来配置：

配置 Elasticsearch 索引名称

每个模型都是通过给定的索引名称创建「索引」来与 Elasticsearch 进行同步，该「索引」下包含所有可搜索的模型记录。换句话说，你可以把每一个「索引」设想为一张 MySQL 数据表。

默认情况下，每个模型都会被持久化到与模型的「表」名（通常是模型名称的复数形式）相匹配的索引，如果在配置文件中设置了索引前缀，则会在表名前拼接该前缀。你可以通过重写模型上的 searchableAs 方法来自定义索引名称：

配置可搜索数据

默认情况下，通过模型的 toArray 方法将返回的数据持久化到搜索索引。如果要自定义同步到搜索索引的数据，可以覆盖模型上的 toSearchableArray 方法：

配置模型 ID

默认情况下，Scout 将使用模型的主键作为搜索索引中存储的唯一 ID。可以通过模型上的 getScoutKey 和 getScoutKeyName 方法自定义：

索引

创建索引并更新映射

更新索引设置

删除索引

更新映射

批量导入

如果你想安装 Scout 到已存在的项目中，你可能已经有了想要导入搜索驱动的数据库记录。Scout 提供了 scout:import 命令来导入所有已存在的记录到搜索索引：

sscout:flush 命令可用于从搜索索引中删除所有模型的记录：

添加记录

当你将 HyperfExt\Scout\Searchable trait 添加到模型中，你需要做的就是 save 一个模型实例。更新索引操作将会在协程结束时进行，不会堵塞请求。

通过查询添加

如果你想通过查询构造器将模型集合添加到搜索索引中，你可以在模型查询构造器上链式调用 searchable 方法。searchable 会把构造器的查询结果分块并且将记录添加到你的搜索索引里。同样的，所有的数据块将在协程中添加。

searchable 方法可以被看做是「更新插入」的操作。换句话说，如果模型记录已经在你的索引里了，它就会被更新。如果搜索索引中不存在，则将其添加到索引中。

更新记录

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

你也可以在模型查询语句上使用 searchable 方法来更新一个模型的集合。如果这个模型不存在你检索的索引里，就会被创建：

删除记录

使用 delete 从数据库中删除该模型就可以移除索引里的记录。这种删除形式甚至与软删除的模型兼容:

如果你不希望记录在删除之前被检索到，可以在模型查询实例或集合上使用 unsearchable 方法：

暂停索引

你可能需要在批量执行模型操作的时候，不同步模型数据到搜索索引。此时你可以使用 withoutSyncingToSearch 方法来执行此操作。这个方法接受一个立即执行的回调。该回调中所有的操作都不会同步到模型的索引：

有条件的搜索模型实例

有时候你可能需要在某些条件下模型是可搜索的。例如，假设你有 App\Models\Post 模型可能两种状态之一：「草稿」和「发布」。你可能只允许搜索 「发布」过的帖子。为了实现这一点，你需要在模型中定义一个 shouldBeSearchable 方法：

只有在通过 save 方法、查询或关联模型操作时，才应使用 shouldBeSearchable 方法。直接使用 searchable 方法将使模型或集合的可搜索结果覆盖 shouldBeSearchable 方法的结果:

搜索

你可以使用 search 方法来搜索模型。search 方法接受一个用于搜索模型的字符串。你还需要在搜索查询上链式调用 get 方法，才能用给定的搜索语句查询与之匹配的模型。

传递给 search 方法的字符串参数即 query_string 的 query 参数。

如果你想在它们返回模型前得到原结果，你应该使用 getRaw 方法：

搜索查询通常会在模型的 searchableAs 方法指定的索引上执行。当然，你也可以使用 within 方法指定应该搜索的自定义索引：

查询构造器

通过 search 方法返回的查询构造器，你可以使用其提供的一系列方法构造复杂的查询条件。

可用的 Where 方法

以下列出的以 where 开头的方法同时提供以 mustWhere、shouldWhere、notWhere 开头的版本。

where 开头的方法使用 filter Occurrence 进行查询，mustWhere 方法使用 must，shouldWhere 方法使用 should，notWhere 方法使用 must_not。

使用 DSL 查询

组件的 Elasticsearch DSL 支持由 ongr/elasticsearch-dsl 包提供，使用方法请访问项目主页查阅。

使用原始数组查询

分页

除了检索模型的集合，您也可以使用 paginate 方法对搜索结果进行分页。这个方法会返回一个就像传统的模型查询分页一样的 Paginator 实例：

您可以通过将数量作为第一个参数传递给 paginate 方法来指定每页检索多少个模型：

软删除

如果您索引的模型配置了软删除，并且您需要搜索已删除的模型，请设置 config/autoload/scout.php 中的 soft_delete 选项为 true（默认值）：

当此配置选项为 true 时，Scout 将不会从搜索索引中删除软删除的模型。并且在查询时，其逻辑与传统的模型是一致的，因此请确保索引的数据中包含软删除的标识字段，通常是 deleted_at。然后，您可以在搜索时使用 withTrashed 或 onlyTrashed 方法来检索软删除的记录：

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