#Elasticquent

为 Eloquent Laravel 模型提供 Elasticsearch 支持

Elasticquent 通过将 Eloquent 模型映射到 Elasticsearch 类型，简化了使用 Elasticsearch 和 Eloquent 模型的操作。您可以使用默认设置，也可以在模型中定义 Elasticsearch 如何索引和搜索您的 Eloquent 模型。

Elasticquent 使用 官方 Elasticsearch PHP API。入门之前，您应该了解 Elasticsearch 的基本工作原理（索引、类型、映射等）。

#Elasticsearch 需求

您必须运行 至少 Elasticsearch 1.0。 Elasticsearch 0.9 及以下版本 将无法工作 且不受支持。

#内容

• 概述
  • Elasticquent 的工作原理
• 设置
  • Elasticsearch 配置
  • 索引和映射
  • 设置自定义索引名称
  • 设置自定义类型名称
• 索引文档
• 搜索
  • 搜索集合
  • 搜索集合文档
  • 从 Elastiquent 中分块结果
  • 在 Elasticquent 之外使用搜索集合
• 更多选项
  • 文档 ID
  • 文档数据
  • 将 Elasticquent 与自定义集合一起使用
• 路线图

#报告问题

如果您发现任何问题，请随时通过 GitHub 的此项目的错误跟踪器 报告。

或者，可以 fork 项目并发起 pull request :)

#概述

Elasticquent 允许您将 Eloquent 模型轻松地索引并在 Elasticsearch 中搜索其内容。

$books = Book::where('id', '<', 200)->get();
$books->addToIndex();

搜索时，您不会得到一个简单的搜索结果数组，而是得到一个带有 Elasticsearch 特殊功能的 Eloquent 集合。

$books = Book::search('Moby Dick');
echo $books->totalHits();

此外，您仍然可以使用所有 Eloquent 集合功能

$books = $books->filter(function ($book) {
    return $book->hasISBN();
});

查看其余文档，了解如何开始使用 Elasticsearch 和 Elasticquent！

#Elasticquent 的工作原理

在使用数据库时，Eloquent 模型从数据库表中读取的数据进行填充。使用 Elasticquent 时，模型从 Elasticsearch 中索引的数据进行填充。使用 Elasticsearch 进行搜索的整个想法是它的速度快且轻量级，因此您的模型功能将由为您的文档索引的数据决定。

#设置

在开始使用 Elasticquent 之前，请确保您已安装 Elasticsearch。

要开始使用，请将 Elasticquent 添加到您的 composer.json 文件中

"elasticquent/elasticquent": "dev-master"

运行 composer update 后，您需要在 config/app.php 中注册 Laravel 服务提供者

'providers' => [
    ...
    Elasticquent\ElasticquentServiceProvider::class,
],

我们还为 elasticsearch-php 客户端提供了一个门面（使用我们的设置进行连接），如果需要，请将以下内容添加到您的 config/app.php 中。

'aliases' => [
    ...
    'Es' => Elasticquent\ElasticquentElasticsearchFacade::class,
],

然后将 Elasticquent 特性添加到您想要在 Elasticsearch 中索引的任何 Eloquent 模型中

use Elasticquent\ElasticquentTrait;
 
class Book extends Eloquent
{
    use ElasticquentTrait;
}

现在，您的 Eloquent 模型具有一些额外的方法，可以更轻松地使用 Elasticsearch 索引模型的数据。

#Elasticsearch 配置

默认情况下，Elasticquent 将连接到 localhost:9200 并使用 default 作为索引名称，您可以在配置文件中更改此设置和其他设置。您可以将 elasticquent.php 配置文件添加到 Laravel 4 的 /app/config/elasticquent.php 中，或者使用以下 Artisan 命令将配置文件发布到 Laravel 5 的配置文件目录中

$ php artisan vendor:publish --provider="Elasticquent\ElasticquentServiceProvider"

<?php
 
return array(
 
    /*
    |--------------------------------------------------------------------------
    | Custom Elasticsearch Client Configuration
    |--------------------------------------------------------------------------
    |
    | This array will be passed to the Elasticsearch client.
    | See configuration options here:
    |
    | http://www.elasticsearch.org/guide/en/elasticsearch/client/php-api/current/_configuration.html
    */
 
    'config' => [
        'hosts'     => ['localhost:9200'],
        'retries'   => 1,
    ],
 
    /*
    |--------------------------------------------------------------------------
    | Default Index Name
    |--------------------------------------------------------------------------
    |
    | This is the index name that Elastiquent will use for all
    | Elastiquent models.
    */
 
    'default_index' => 'my_custom_index_name',
 
);

#索引和映射

虽然您绝对可以通过 Elasticsearch API 创建索引和映射，但您也可以使用一些辅助方法直接从模型中创建索引和类型。

如果您希望以简单的方式创建索引，Elasticquent 模型提供了一个函数

Book::createIndex($shards = null, $replicas = null);

对于自定义分析器，您可以在模型中设置 indexSettings 属性并从那里定义分析器

/**
 * The elasticsearch settings.
 *
 * @var array
 */
protected $indexSettings = [
    'analysis' => [
        'char_filter' => [
            'replace' => [
                'type' => 'mapping',
                'mappings' => [
                    '&=> and '
                ],
            ],
        ],
        'filter' => [
            'word_delimiter' => [
                'type' => 'word_delimiter',
                'split_on_numerics' => false,
                'split_on_case_change' => true,
                'generate_word_parts' => true,
                'generate_number_parts' => true,
                'catenate_all' => true,
                'preserve_original' => true,
                'catenate_numbers' => true,
            ]
        ],
        'analyzer' => [
            'default' => [
                'type' => 'custom',
                'char_filter' => [
                    'html_strip',
                    'replace',
                ],
                'tokenizer' => 'whitespace',
                'filter' => [
                    'lowercase',
                    'word_delimiter',
                ],
            ],
        ],
    ],
];

对于映射，您可以在模型中设置 mappingProperties 属性，并从那里使用一些映射函数

protected $mappingProperties = array(
   'title' => array(
        'type' => 'string',
        'analyzer' => 'standard'
    )
);

如果您希望根据映射属性设置模型的类型映射，可以使用

Book::putMapping($ignoreConflicts = true);

要删除映射

Book::deleteMapping();

要重建（删除并重新添加，在您对映射进行重要更改时很有用）映射

Book::rebuildMapping();

您还可以获取类型映射并检查它是否存在。

Book::mappingExists();
Book::getMapping();

#设置自定义索引名称

默认情况下，Elasticquent 将在您的配置文件 (config/elasticquent.php) 中查找 default_index 键。要设置正在使用的索引的默认值，您可以编辑此文件并设置 default_index 键

return array(
 
   // Other configuration keys ...
 
   /*
    |--------------------------------------------------------------------------
    | Default Index Name
    |--------------------------------------------------------------------------
    |
    | This is the index name that Elastiquent will use for all
    | Elastiquent models.
    */
 
   'default_index' => 'my_custom_index_name',
);

如果您希望拥有更动态的索引，您还可以在 Eloquent 模型中使用 getIndexName 方法覆盖默认配置

function getIndexName()
{
    return 'custom_index_name';
}

注意：如果没有指定索引，Elasticquent 将使用一个硬编码字符串，其值为 default。

#设置自定义类型名称

默认情况下，Elasticquent 将使用模型的表名称作为索引的类型名称。如果您希望覆盖它，可以使用 getTypeName 函数。

function getTypeName()
{
    return 'custom_type_name';
}

要检查 Elasticquent 模型的类型是否已存在，请使用 typeExists

$typeExists = Book::typeExists();

#索引文档

要索引 Eloquent 模型中的所有条目，请使用 addAllToIndex

Book::addAllToIndex();

您也可以索引模型的集合

$books = Book::where('id', '<', 200)->get();
$books->addToIndex();

您也可以索引单个条目

$book = Book::find($id);
$book->addToIndex();

您也可以重新索引整个模型

Book::reindex();

#搜索

在 Elasticquent 中有三种搜索方式。所有三种方法都返回一个搜索集合。

#简单词语搜索

第一种方法是简单的词语搜索，它搜索所有字段。

$books = Book::search('Moby Dick');

#基于查询的搜索

第二种是基于查询的搜索，用于更复杂的搜索需求

public static function searchByQuery($query = null, $aggregations = null, $sourceFields = null, $limit = null, $offset = null, $sort = null)

示例

$books = Book::searchByQuery(array('match' => array('title' => 'Moby Dick')));

以下是可用参数的列表

• query - 您的 ElasticSearch 查询
• aggregations - 您希望返回的聚合。 有关详细信息，请参阅聚合。
• sourceFields - 将返回集限制为仅选定的字段
• limit - 要返回的记录数
• offset - 设置记录偏移量（用于分页结果）
• sort - 您的排序查询

#原始查询

最后一种方法是原始查询，它将发送到 Elasticsearch。这种方法在 Elasticsearch 中搜索记录时将提供最大的灵活性

$books = Book::complexSearch(array(
    'body' => array(
        'query' => array(
            'match' => array(
                'title' => 'Moby Dick'
            )
        )
    )
));

这等同于

$books = Book::searchByQuery(array('match' => array('title' => 'Moby Dick')));

#搜索集合

在 Elasticquent 模型上搜索时，您会得到一个包含一些特殊函数的搜索集合。

您可以获取总命中次数。

$books->totalHits();

访问分片数组。

$books->shards();

访问最大得分。

$books->maxScore();

访问超时布尔属性。

$books->timedOut();

并访问 took 属性。

$books->took();

并访问搜索聚合 - 查看聚合以了解详情

$books->getAggregations();

#搜索集合文档

搜索结果集合中的项目将包含来自 Elasticsearch 的一些额外数据。您可以始终使用 isDocument 函数检查并查看模型是否为文档。

$book->isDocument();

您可以检查 Elasticsearch 为此文档分配的文档得分，方法是使用

$book->documentScore();

#对来自 Elastiquent 的结果进行分块

与 Illuminate\Support\Collection 类似，chunk 方法将 Elasticquent 集合分解成多个较小的、给定大小的集合。

$all_books = Book::searchByQuery(array('match' => array('title' => 'Moby Dick')));
$books = $all_books->chunk(10);

#在 Elasticquent 之外使用搜索集合

如果您正在处理来自 Elasticquent 之外的原始搜索数据，您可以使用 Elasticquent 搜索结果集合将这些数据转换为集合。

$client = new \Elasticsearch\Client();
 
$params = array(
    'index' => 'default',
    'type'  => 'books'
);
 
$params['body']['query']['match']['title'] = 'Moby Dick';
 
$collection = Book::hydrateElasticsearchResult($client->search($params));

#更多选项

#文档 ID

Elasticquent 将使用为您的 Eloquent 模型设置的 primaryKey 作为您 Elasticsearch 文档的 ID。

#文档数据

默认情况下，Elasticquent 将使用您 Elasticsearch 文档的整个属性数组。但是，如果您想自定义搜索文档的结构，您可以设置一个 getIndexDocumentData 函数，该函数将返回您自己的自定义文档数组。

function getIndexDocumentData()
{
    return array(
        'id'      => $this->id,
        'title'   => $this->title,
        'custom'  => 'variable'
    );
}

小心使用此方法，因为 Elasticquent 在创建搜索结果集合时将文档源读入 Eloquent 模型属性，因此请确保您为要使用的模型功能索引了足够的数据。

#将 Elasticquent 与自定义集合一起使用

如果您在 Eloquent 模型中使用自定义集合，您只需要将 ElasticquentCollectionTrait 添加到您的集合中，这样您就可以使用 addToIndex。

class MyCollection extends \Illuminate\Database\Eloquent\Collection
{
    use ElasticquentCollectionTrait;
}

#路线图

Elasticquent 目前需要

• 模拟 ES API 调用的测试。
• 对路由的支持