README

内容

功能
要求
安装
配置
索引配置器
可搜索模型
用法
控制台命令
搜索规则
可用过滤器
零停机迁移
调试

功能

一种简单的方式来配置和创建 Elasticsearch 索引。
为每个模型提供完全可配置的映射。
可以通过自动或使用 artisan 命令将新字段添加到现有映射中。
有很多不同的方式来实现您的搜索算法：使用搜索规则或原始搜索。
提供各种过滤器类型以使搜索查询更具体。
从旧索引到新索引的零停机迁移。
批量索引，请参阅配置部分。

要求

该包已在以下配置下进行测试

PHP 版本 >= 7.1.3
Laravel 框架版本 >= 5.6
Elasticsearch 版本 >= 6

安装

使用 composer 安装包

composer require babenkoivan/scout-elasticsearch-driver

配置

要配置该包，您需要首先发布设置

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

然后，在 config/scout.php 文件中将驱动设置设置为 elastic 并在 config/scout_elastic.php 文件中配置驱动程序本身。可用选项包括

注意，如果您使用批量文档索引，可能需要更改块大小，您可以在 config/scout.php 文件中这样做。

索引配置器

使用索引配置器类来设置 Elasticsearch 索引的设置。要创建新的索引配置器，请使用以下 artisan 命令

php artisan make:index-configurator MyIndexConfigurator

它将在您的项目 app 文件夹中创建 MyIndexConfigurator.php 文件。您可以在以下示例中指定索引名称和设置

<?php

namespace App;

use ScoutElastic\IndexConfigurator;

class MyIndexConfigurator extends IndexConfigurator
{
    // It's not obligatory to determine name. By default it'll be a snaked class name without `IndexConfigurator` part.
    protected $name = 'my_index';  
    
    // You can specify any settings you want, for example, analyzers. 
    protected $settings = [
        'analysis' => [
            'analyzer' => [
                'es_std' => [
                    'type' => 'standard',
                    'stopwords' => '_spanish_'
                ]
            ]    
        ]
    ];
}

有关索引设置的更多信息，您可以在 Elasticsearch 文档的索引管理部分中找到。

要创建索引，只需运行 artisan 命令

php artisan elastic:create-index App\\MyIndexConfigurator

可搜索模型

要创建一个可以在 Elasticsearch 索引中执行搜索请求的模型，请使用以下命令

php artisan make:searchable-model MyModel --index-configurator=MyIndexConfigurator

执行命令后，您将在您的 app 文件夹中找到 MyModel.php 文件

<?php

namespace App;

use ScoutElastic\Searchable;
use Illuminate\Database\Eloquent\Model;

class MyModel extends Model
{
    use Searchable;

    protected $indexConfigurator = MyIndexConfigurator::class;

    protected $searchRules = [
        //
    ];

    // Here you can specify a mapping for a model fields.
    protected $mapping = [
        'properties' => [
            'text' => [
                'type' => 'text',
                'fields' => [
                    'raw' => [
                        'type' => 'text',
                        'index' => 'not_analyzed',
                    ]
                ]
            ],
        ]
    ];
}

每个可搜索模型代表一个 Elasticsearch 类型。默认情况下，类型名称与表名称相同，但您可以通过 searchableAs 方法设置任何类型名称。您还可以通过 toSearchableArray 方法指定将由驱动程序索引的字段。有关这些选项的更多信息，您可以在 scout 官方文档中找到。

在 MyModel 类中您可以设置的最后一个重要选项是 $searchRules 属性。它允许您为模型设置不同的搜索算法。我们将在搜索规则部分中更详细地介绍它。

在您的模型中设置映射后，您可以更新Elasticsearch类型映射

php artisan elastic:update-mapping App\\MyModel

用法

一旦您创建了索引配置器、Elasticsearch索引本身和可搜索的模型，您就可以开始了。现在，您可以根据文档进行索引和搜索数据。

基本搜索使用示例

// set query string
App\MyModel::search('phone')
    // specify columns to select
    ->select(['title', 'price'])
    // filter 
    ->where('color', 'red')
    // sort
    ->orderBy('price', 'asc')
    // collapse by field
    ->collapse('brand')
    // set offset
    ->from(0)
    // set limit
    ->take(10)
    // get results
    ->get();

如果您只需要查询的匹配数量，请使用count方法

App\MyModel::search('phone') 
    ->count();

如果您需要加载关系，请使用with方法

App\MyModel::search('phone') 
    ->with('makers')
    ->get();

除了标准功能外，该包还为您提供了一种在不指定查询字符串的情况下在Elasticsearch中过滤数据的方法

App\MyModel::search('*')
    ->where('id', 1)
    ->get();

您还可以覆盖模型搜索规则

App\MyModel::search('Brazil')
    ->rule(App\MySearchRule::class)
    ->get();

并且使用各种where条件变异

App\MyModel::search('*')
    ->whereRegexp('name.raw', 'A.+')
    ->where('age', '>=', 30)
    ->whereExists('unemployed')
    ->get();

最后，如果您想发送自定义请求，可以使用searchRaw方法

App\MyModel::searchRaw([
    'query' => [
        'bool' => [
            'must' => [
                'match' => [
                    '_all' => 'Brazil'
                ]
            ]
        ]
    ]
]);

此查询将返回原始响应。

控制台命令

以下列出了可用的Artisan命令

要在命令行中获取详细描述和所有可用选项，请运行php artisan help [command]。

搜索规则

搜索规则是一个描述搜索查询如何执行的类。要创建搜索规则，请使用以下命令

php artisan make:search-rule MySearchRule

在文件app/MySearchRule.php中，您将找到一个类定义

<?php

namespace App;

use ScoutElastic\SearchRule;

class MySearch extends SearchRule
{
    // This method returns an array, describes how to highlight the results.
    // If null is returned, no highlighting will be used. 
    public function buildHighlightPayload()
    {
        return [
            'fields' => [
                'name' => [
                    'type' => 'plain'
                ]
            ]
        ];
    }
    
    // This method returns an array, that represents bool query.
    public function buildQueryPayload()
    {
        return [
            'must' => [
                'match' => [
                    'name' => $this->builder->query
                ]
            ]
        ];
    }
}

您可以在这里了解更多关于bool查询的信息，以及如何在这里了解更多关于高亮显示的信息。

默认搜索规则返回以下有效载荷

return [
   'must' => [
       'query_string' => [
           'query' => $this->builder->query
       ]
   ]
];

这意味着默认情况下，当您在模型上调用search方法时，它会尝试在任意字段中查找查询字符串。

要确定模型的默认搜索规则，只需添加一个属性

<?php

namespace App;

use ScoutElastic\Searchable;
use Illuminate\Database\Eloquent\Model;

class MyModel extends Model
{
    use Searchable;
    
    // You can set several rules for one model. In this case, the first not empty result will be returned.
    protected $searchRules = [
        MySearchRule::class
    ];
}

您还可以在查询构建器中设置搜索规则

// You can set either a SearchRule class
App\MyModel::search('Brazil')
    ->rule(App\MySearchRule::class)
    ->get();
    
// or a callable
App\MyModel::search('Brazil')
    ->rule(function($builder) {
        return [
            'must' => [
                'match' => [
                    'Country' => $builder->query
                ]
            ]
        ];
    })
    ->get();

要检索高亮，请使用模型的highlight属性

// Let's say we highlight field `name` of `MyModel`.
$model = App\MyModel::search('Brazil')
    ->rule(App\MySearchRule::class)
    ->first();

// Now you can get raw highlighted value:
$model->highlight->name;

// or string value:
 $model->highlight->nameAsString;

可用过滤器

您可以使用不同类型的过滤器

在大多数情况下，最好使用原始字段来过滤记录，即非分析字段。

零停机迁移

如您所知，您无法更改Elasticsearch中已创建字段的类型。在这种情况下，唯一的选择是创建一个新的索引，并带有必要的映射，然后将您的模型导入新索引。
迁移可能需要相当长的时间，因此为了在迁移过程中避免停机时间，驱动程序从旧索引中读取并写入新索引。一旦迁移完成，它开始从新索引中读取并删除旧索引。这是Artisan elastic:migrate命令的工作原理。

在运行命令之前，请确保您的索引配置器使用ScoutElastic\Migratable特质。如果不是，请添加特质，并使用索引配置器类名作为参数运行Artisan elastic:update-index命令。

php artisan elastic:update-index App\\MyIndexConfigurator

准备好后，在模型映射中进行更改，并使用模型类作为第一个参数，所需索引名称作为第二个参数运行elastic:migrate命令。

php artisan elastic:migrate App\\MyModel my_index_v2

注意，如果您只想在映射中添加新字段，请使用elastic:update-mapping命令。

调试

有两种方法可以帮助您分析搜索查询的结果

explain

App\MyModel::search('Brazil')
    ->explain();

profile

App\MyModel::search('Brazil')
    ->profile();

这两种方法都返回来自ES的原始数据。

此外，您可以通过调用buildPayload方法来获取将发送到ES的查询有效载荷。

App\MyModel::search('Brazil')
    ->buildPayload();

请注意，由于一个查询中可能使用多个搜索规则，此方法返回一个有效载荷集合。

captainnx / scout-elasticsearch-driver

维护者

详细信息