README

💥 介绍一个新的 Laravel Elasticsearch 生态系统。 💥

此软件包提供了在 Elasticsearch 中搜索和过滤数据的先进功能。查看其功能！

内容

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

功能

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

要求

该软件包在以下配置下进行了测试

PHP版本 >=7.4, <=8.0
Laravel 框架版本 >=7.0, <=8.0
Elasticsearch 版本 >=7

安装

使用 composer 安装此软件包

composer require buckhamduffy/scout-elasticsearch-driver

如果您正在使用 Laravel 版本 <= 5.4 或禁用了包发现，请在 config/app.php 中添加以下提供者

'providers' => [
    Laravel\Scout\ScoutServiceProvider::class,
    ScoutElastic\ScoutElasticServiceProvider::class,
]

配置

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

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

然后，在 config/scout.php 文件中将驱动设置设置为 elastic（或是在 .env 中设置 SCOUT_DRIVER=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 6.0.0及更高版本创建的索引只能包含一个映射类型。在5.x版本中创建的具有多个映射类型的索引将在Elasticsearch 6.x中继续按以前的方式运行。映射类型将在Elasticsearch 7.0.0中完全移除。

更多信息请查看这里。

可搜索模型

要创建一个具有在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 model fields
    protected $mapping = [
        'properties' => [
            'title' => [
                'type' => 'text',
                // Also you can configure multi-fields, more details you can find here https://elastic.ac.cn/guide/en/elasticsearch/reference/current/multi-fields.html
                'fields' => [
                    'raw' => [
                        'type' => 'keyword',
                    ]
                ]
            ],
        ]
    ];
}

每个可搜索模型代表一个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();

您还可以过滤出得分低于min_score的结果。

App\MyModel::search('sales')
    ->minScore(1.0)
    ->get();

您还可以添加更复杂的排序（例如geo_distance）。

$model = App\MyModel::search('sales')
    ->orderRaw([
       '_geo_distance' =>  [
           'coordinates' => [
               'lat'   =>  51.507351,
               'lon'   =>  -0.127758
           ],
           'order'     =>  'asc',
           'unit'      =>  'm'
       ]
    ])
    ->get();

// To retrieve sort result, use model `sortPayload` attribute:
$model->sortPayload;

您还可以与模型一起返回ElasticSearch分配的得分。

$model = App\MyModel::search('sales')
    ->withScores()
    ->get();
// To retrieve the score, use model \`_score\` attribute:
$model->_score;

最后，如果您想发送自定义请求，可以使用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;

聚合规则

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

php artisan make:aggregate-rule MyAggregateRule

在文件app/MyAggregateRule.php中，您将找到类定义。

<?php
namespace App;
use ScoutElastic\AggregateRule;
class MyAggregateRule extends AggregateRule
{
    // This method returns an array that represents a content of bool query.
    public function buildAggregatePayload()
    {
        return [
            'icon_count' => [
                'terms' => [
                    'field' => 'icon_id',
                    'size' => 15
                ]
            ],
            'style_count' => [
                'terms' => [
                    'field' => 'style_id',
                    'size' => 7
                ]
            ],
            'category_count' => [
                'terms' => [
                    'field' => 'category_id',
                    'size' => 39
                ]
            ]
        ];
    }
}

您可以在这里了解更多有关聚合查询的内容。

要确定模型默认的聚合规则，只需添加一个属性即可。

<?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 $aggregateRules = [
        MyAggregateRule::class
    ];
}

可用过滤器

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

在大多数情况下，使用原始字段进行记录过滤会更好，即不分析的字段。

零停机迁移

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

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

php artisan elastic:update-index "App\MyIndexConfigurator"

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

php artisan elastic:migrate-model "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();

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

替代方案

最近，我发布了一个新的Elasticsearch生态系统，用于Laravel，它包括

Elastic Scout Driver - Laravel Scout的通用Elasticsearch驱动程序。如果您需要在Laravel应用程序中构建简单的搜索，它非常合适。
Elastic Scout Driver Plus - Elastic Scout Driver的扩展。如果您想利用布尔查询、高亮显示等Elasticsearch功能，这是一个不错的选择。
Elastic Migrations - 创建、删除或更新Elasticsearch索引架构的简单方法，并与您的同事共享。它具有与Laravel数据库迁移非常相似的界面。

如果您对其中任何一项感兴趣并想了解更多详情，请阅读Laravel应用程序中Elasticsearch的终极指南。该文章对所提到的包进行了很好的概述，并提供了使用示例。

常见问题解答

为什么您创建了新的包而不是新的scout-elasticsearch-driver版本？ - 由于明显的原因，我不想再创建一个全新的包：没有关注点的分离、与其他Scout驱动程序不兼容、难以测试和开发等。由于Elastic Scout Driver是一个通用驱动程序，并没有实现所有的scout-elasticsearch-driver功能，所以将其称为新的scout-elasticsearch-driver版本是不正确的。
这对scout-elasticsearch-driver意味着什么？ - 目前，它由社区维护（感谢@iget-esoares和@lucamichot让项目保持活力🎉）。我希望他们将继续为项目做出贡献，并在未来带来新的scout-elasticsearch-driver版本。

buckhamduffy / scout-elasticsearch-driver

维护者

详细信息