README

Elasticsearch for Eloquent Laravel Models

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

Elasticquent 使用官方 Elasticsearch PHP API。要开始使用，您应该具备基本的 Elasticsearch 工作原理知识（索引、类型、映射等）。

Elasticsearch 要求

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

报告问题

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

或者，您可以分叉项目并提交一个 pull request :)

概述

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

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

在搜索时，您将获得一个具有一些特殊 Elasticsearch 功能的 Eloquent 集合，而不是一个普通的搜索结果数组。

    $books = Book::search('Moby Dick')->get();
    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 后，将 Elasticquent 特性添加到任何您希望能够在 Elasticsearch 中索引的 Eloquent 模型中

use Elasticquent\ElasticquentTrait;

class Book extends Eloquent {

    use ElasticquentTrait;

}

现在，您的 Eloquent 模型具有一些额外的功能，这些功能可以简化使用 Elasticsearch 索引模型数据。

Elasticsearch 配置

如果您需要传递一个特殊的配置数组到 Elasticsearch，您可以在 /app/config/elasticquent.php（Laravel 4）或 /config/elasticquent.php（Laravel 5）中的 elasticquent.php 配置文件中添加它

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

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

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

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

    Book::putMapping($ignoreConflicts = true);

要删除映射

    Book::deleteMapping();

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

    Book::rebuildMapping();

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

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

设置自定义索引名称

Elastiquent 将使用 default 作为您的索引名称，但您可以在 /app/config/ 中创建一个 elasticquent.php 配置文件来自定义索引名称。

<?php

return array(

    /*
    |--------------------------------------------------------------------------
    | Default Index Name
    |--------------------------------------------------------------------------
    |
    | This is the index name that Elastiquent will use for all
    | Elastiquent models.
    */

    'default_index' => 'my_custom_index_name',

);

设置自定义类型名称

默认情况下，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();

搜索

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

简单术语搜索

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

    $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 = new \Elasticquent\ElasticquentResultCollection($client->search($params), new Book);

在A类型中删除文档

如果您使用的是弹性版本 >= 2，您必须安装 delete-by-query 插件

删除所有文档

    Book::deleteAllDocuments();

通过查询删除文档

    $query = array('match' => array('is_published' => 0));
    Book::deleteDocuments($query);

路线图

Elasticquent 目前需要

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

amrsoliman / elasticquent

维护者

详细信息