README

已弃用，请使用 https://github.com/ensi-platform/laravel-elastic-query-specification 代替

greensight/laravel-elastic-query 的扩展，用于以声明方式描述查询。

安装

1. 安装greensight/laravel-elastic-query https://github.com/greensight/laravel-elastic-query#installation
2. composer require greensight/laravel-elastic-query-specification

用法 // TODO 翻译为英文

所有声明性查询都基于该规范。其中包含可用的过滤器、排序和聚合的定义。

use Greensight\LaravelElasticQuery\Declarative\Agregating\AllowedAggregate;
use Greensight\LaravelElasticQuery\Declarative\Filtering\AllowedFilter;
use Greensight\LaravelElasticQuery\Declarative\Sorting\AllowedSort;
use Greensight\LaravelElasticQuery\Declarative\Specification\CompositeSpecification;
use Greensight\LaravelElasticQuery\Declarative\Specification\Specification;

class ProductSpecification extends CompositeSpecification
{
    public function __construct()
    {
        parent::__construct();
        
        $this->allowedFilters([
            'package',
            'active',
            AllowedFilter::exact('cashback', 'cashback.active')->default(true)
        ]);
        
        $this->allowedSorts(['name', 'rating']);
        
        $this->allowedAggregates([
            'package',
            AllowedAggregate::minmax('rating')
        ]);
        
        $this->whereNotNull('package');
        
        $this->nested('offers', function (Specification $spec) {
            $spec->allowedFilters(['seller_id', 'active']);
            
            $spec->allowedAggregates([
                'seller_id',
                AllowedAggregate::minmax('price')
            ]);
            
            $spec->allowedSorts([
                AllowedSort::field('price')->byMin()
            ]);
        });
    }
}

该规范查询示例。

{
 "sort": ["+price", "-rating"],
 "filter": {
    "active": true,
    "seller_id": 10
 }
}

{
 "aggregate": ["price", "rating"],
 "filter": {
    "package": "bottle",
    "seller_id": 10
 }
}

nested方法添加嵌套文档的规范。过滤器、聚合和排序的名称从其中导出到全局作用域，不添加任何前缀。如果对于过滤器可以有不同的名称，则对于其他组件则不行。

$this->nested('nested_field', function (Specification $spec) { ... })
$this->nested('nested_field', new SomeSpecificationImpl());

嵌套文档的规范中只能使用这些文档的字段。

可以为同一字段类型 nested 添加多个规范。

where*限制允许设置客户端无法更改的额外选择条件。根规范中设置的限制始终生效。嵌套规范中的限制仅作为对请求中添加的过滤器、聚合或排序的补充。例如，如果嵌套规范中没有活动过滤器，则该规范中的限制不会出现在Elasticsearch查询的过滤器部分。

allowedFilters方法定义客户端可用的过滤器。每个过滤器都必须包含在规范范围内唯一的名称。同时，在根和嵌套规范或不同的嵌套规范中，名称可以重复。具有相同名称的所有过滤器都将使用请求参数中的值填充。

除了过滤器的名称外，还可以单独指定应用于索引中字段的名称和默认值。

$this->allowedFilters([AllowedFilter::exact('name', 'field')->default(500)]);

// the following statements are equivalent
$this->allowedFilters(['name']);
$this->allowedFilters([AllowedFilter::exact('name', 'name')]);

过滤器类型

AllowedFilter::exact('name', 'field');  // Значение поля проверяется на равенство одному из заданных
AllowedFilter::exists('name', 'field'); // Проверяется, что поле присутствует в документе и имеет ненулевое значение

通过allowedSorts方法添加客户端可用的排序。排序方向由其名称指定。加号+或无符号号表示升序，减号-表示降序。默认情况下，使用升序排序，选择字段中的最小值。

$this->allowedSorts([AllowedSort::field('name', 'field')]);

// the following statements are equivalent
$this->allowedSorts(['name']);
$this->allowedSorts([AllowedSort::field('+name', 'name')]);
$this->allowedSorts([AllowedSort::field('+name', 'name')->byMin()]);

// set the sorting mode
$this->allowedSorts([AllowedSort::field('name', 'field')->byMin()]);
$this->allowedSorts([AllowedSort::field('name', 'field')->byMax()]);
$this->allowedSorts([AllowedSort::field('name', 'field')->byAvg()]);
$this->allowedSorts([AllowedSort::field('name', 'field')->bySum()]);
$this->allowedSorts([AllowedSort::field('name', 'field')->byMedian()]);

在嵌套规范中对排序考虑所有限制和活动过滤器。

使用allowedAggregates方法声明聚合。客户端在请求参数中指定期望在响应中获取的聚合名称列表。

$this->allowedAggregates([AllowedAggregate::terms('name', 'field')]);

// the following statements are equivalent
$this->allowedAggregates(['name']);
$this->allowedAggregates([AllowedAggregate::terms('name', 'name')]);

聚合类型

AllowedAggregate::terms('name', 'field');   // Get all variants of attribute values
AllowedAggregate::minmax('name', 'field');  // Get min and max attribute values

从嵌套规范添加的聚合将带有所有限制和活动过滤器一起添加到Elasticsearch查询中。

搜索文档

use Greensight\LaravelElasticQuery\Declarative\SearchQueryBuilder;
use Greensight\LaravelElasticQuery\Declarative\QueryBuilderRequest;

class ProductsSearchQuery extends SearchQueryBuilder
{
    public function __construct(QueryBuilderRequest $request)
    {
        parent::__construct(ProductsIndex::query(), new ProductSpecification(), $request);
    }
}

class ProductsController
{
    // ...
    public function index(ProductsSearchQuery $query)
    {
        return ProductResource::collection($query->get());
    }
}

计算汇总指标

use Greensight\LaravelElasticQuery\Declarative\AggregateQueryBuilder;
use Greensight\LaravelElasticQuery\Declarative\QueryBuilderRequest;

class ProductsAggregateQuery extends AggregateQueryBuilder
{
    public function __construct(QueryBuilderRequest $request)
    {
        parent::__construct(ProductsIndex::aggregate(), new ProductSpecification(), $request);
    }
}

class ProductsController
{
    // ...
    public function totals(ProductsAggregateQuery $query)
    {
        return new ProductAggregateResource($query->get());
    }
}

贡献

请参阅贡献指南获取详细信息。

测试

1. 执行composer install
2. 执行npm i
3. 使用您首选的方式启动Elasticsearch。
4. 将phpunit.xml.dist复制到phpunit.xml，并在此处设置正确的环境变量
5. 执行composer test

安全漏洞

请查看如何报告安全漏洞的安全策略。

许可

MIT许可（MIT）。请参阅许可文件获取更多信息。