README

使用流畅的PHP API构建和执行ElasticSearch查询

本包是Elasticsearch的轻量级查询构建器。它专门为我们构建的elasticsearch-search-string-parser，因此覆盖了大多数用例，但可能缺少某些功能。如果您需要任何特定功能，我们始终欢迎PRs！

use Spatie\ElasticsearchQueryBuilder\Aggregations\MaxAggregation;
use Spatie\ElasticsearchQueryBuilder\Builder;
use Spatie\ElasticsearchQueryBuilder\Queries\MatchQuery;

$client = Elastic\Elasticsearch\ClientBuilder::create()->build();

$companies = (new Builder($client))
    ->index('companies')
    ->addQuery(MatchQuery::create('name', 'spatie', fuzziness: 3))
    ->addAggregation(MaxAggregation::create('score'))
    ->search();

支持我们

我们投入了大量资源来创建最佳的开源包。您可以通过购买我们的付费产品之一来支持我们。

我们非常感谢您从家乡寄给我们明信片，注明您正在使用我们的哪个包。您可以在我们的联系页面上找到我们的地址。我们将发布收到的所有明信片在我们的虚拟明信片墙上。

安装

您可以通过composer安装此包

composer require spatie/elasticsearch-query-builder

注意如果您使用的是elasticsearch/elasticsearch v7，则需要使用此包的v1。

基本用法

您真正需要与之交互的类是Spatie\ElasticsearchQueryBuilder\Builder类。它需要通过构造函数传入一个\Elastic\Elasticsearch\Client。请查阅ElasticSearch SDK文档以了解更多关于连接到您的ElasticSearch集群的信息。

Builder类包含一些用于添加查询、聚合、排序、字段和一些用于分页的额外方法。您可以在下面阅读有关这些方法的更多信息。构建完查询后，您可以使用$builder->search()来执行查询，或使用$builder->getPayload()来获取ElasticSearch的原始有效载荷。

use Spatie\ElasticsearchQueryBuilder\Queries\RangeQuery;
use Spatie\ElasticsearchQueryBuilder\Builder;

$client = Elastic\Elasticsearch\ClientBuilder::create()->build();

$builder = new Builder($client);

$builder->addQuery(RangeQuery::create('age')->gte(18));

$results = $builder->search(); // raw response from ElasticSearch

添加查询

可以使用$builder->addQuery()方法将任何可用的Query类型添加到构建器中。可用的查询类型可以在下面或在本仓库的src/Queries目录中找到。每个Query都有一个静态的create()方法来传递其最重要的参数。

以下查询类型可用

`ExistsQuery`

https://elastic.ac.cn/guide/en/elasticsearch/reference/current/query-dsl-exists-query.html

\Spatie\ElasticsearchQueryBuilder\Queries\ExistsQuery::create('terms_and_conditions');

`MatchQuery`

https://elastic.ac.cn/guide/en/elasticsearch/reference/current/query-dsl-match-query.html

\Spatie\ElasticsearchQueryBuilder\Queries\MatchQuery::create('name', 'john doe', fuzziness: 2);

`MultiMatchQuery`

https://elastic.ac.cn/guide/en/elasticsearch/reference/current/query-dsl-multi-match-query.html

\Spatie\ElasticsearchQueryBuilder\Queries\MultiMatchQuery::create('john', ['email', 'email'], fuzziness: 'auto');

`NestedQuery`

https://elastic.ac.cn/guide/en/elasticsearch/reference/current/query-dsl-nested-query.html

\Spatie\ElasticsearchQueryBuilder\Queries\NestedQuery::create(
    'user', 
    new \Spatie\ElasticsearchQueryBuilder\Queries\MatchQuery('name', 'john')
);

`RangeQuery`

https://elastic.ac.cn/guide/en/elasticsearch/reference/current/query-dsl-range-query.html

\Spatie\ElasticsearchQueryBuilder\Queries\RangeQuery::create('age')
    ->gte(18)
    ->lte(1337);

`TermQuery`

https://elastic.ac.cn/guide/en/elasticsearch/reference/current/query-dsl-term-query.html

\Spatie\ElasticsearchQueryBuilder\Queries\TermQuery::create('user.id', 'flx');

`WildcardQuery`

[%3Chttps://elastic.ac.cn/guide/cn/elasticsearch/reference/current/query-dsl-wildcard-query.html](https://www. elastic.co/guide/cn/elasticsearch/reference/current/query-dsl-wildcard-query.html)

\Spatie\ElasticsearchQueryBuilder\Queries\WildcardQuery::create('user.id', '*doe');

`BoolQuery`

https://elastic.ac.cn/guide/cn/elasticsearch/reference/current/query-dsl-bool-query.html

\Spatie\ElasticsearchQueryBuilder\Queries\BoolQuery::create()
    ->add($matchQuery, 'must_not')
    ->add($existsQuery, 'must_not');

链式多个查询

可以在一个 Builder 上链式调用多个 addQuery() 调用。底层会将它们添加到具有 must 发生类型的 BoolQuery 中。通过传递 addQuery() 方法的第二个参数，您可以选择不同的发生类型

$builder
    ->addQuery(
        MatchQuery::create('name', 'billie'), 
        'must_not' // available types: must, must_not, should, filter
    )
    ->addQuery(
        MatchQuery::create('team', 'eillish')
    );

有关布尔查询及其发生类型的更多信息，请参阅 ElasticSearch 文档。

添加聚合

可以使用 $builder->addAggregation() 方法将任何可用的 Aggregation 添加到构建器中。可用的聚合类型可以在以下位置找到或在此存储库的 src/Aggregations 目录中。每个 Aggregation 都有一个静态的 create() 方法，用于传递其最重要的参数，有时还有一些额外的方法。

use Spatie\ElasticsearchQueryBuilder\Aggregations\TermsAggregation;
use Spatie\ElasticsearchQueryBuilder\Builder;

$results = (new Builder(Elastic\Elasticsearch\ClientBuilder::create()->build()))
    ->addAggregation(TermsAggregation::create('genres', 'genre'))
    ->search();

$genres = $results['aggregations']['genres']['buckets'];

以下查询类型可用

`CardinalityAggregation`

\Spatie\ElasticsearchQueryBuilder\Aggregations\CardinalityAggregation::create('team_agg', 'team_name');

`FilterAggregation`

https://elastic.ac.cn/guide/cn/elasticsearch/reference/current/search-aggregations-bucket-filter-aggregation.html

\Spatie\ElasticsearchQueryBuilder\Aggregations\FilterAggregation::create(
    'tshirts',
    \Spatie\ElasticsearchQueryBuilder\Queries\TermQuery::create('type', 'tshirt'),
    \Spatie\ElasticsearchQueryBuilder\Aggregations\MaxAggregation::create('max_price', 'price')
);

`MaxAggregation`

https://elastic.ac.cn/guide/cn/elasticsearch/reference/current/search-aggregations-metrics-max-aggregation.html

\Spatie\ElasticsearchQueryBuilder\Aggregations\MaxAggregation::create('max_price', 'price');

`MinAggregation`

https://elastic.ac.cn/guide/cn/elasticsearch/reference/current/search-aggregations-metrics-min-aggregation.html

\Spatie\ElasticsearchQueryBuilder\Aggregations\MinAggregation::create('min_price', 'price');

`NestedAggregation`

https://elastic.ac.cn/guide/cn/elasticsearch/reference/current/search-aggregations-bucket-nested-aggregation.html

\Spatie\ElasticsearchQueryBuilder\Aggregations\NestedAggregation::create(
    'resellers',
    'resellers',
    \Spatie\ElasticsearchQueryBuilder\Aggregations\MinAggregation::create('min_price', 'resellers.price'),
    \Spatie\ElasticsearchQueryBuilder\Aggregations\MaxAggregation::create('max_price', 'resellers.price'),
);

`ReverseNestedAggregation`

https://elastic.ac.cn/guide/cn/elasticsearch/reference/current/search-aggregations-bucket-reverse-nested-aggregation.html

\Spatie\ElasticsearchQueryBuilder\Aggregations\ReverseNestedAggregation::create(
    'name',
    ...$aggregations
);

`TermsAggregation`

https://elastic.ac.cn/guide/cn/elasticsearch/reference/current/search-aggregations-bucket-terms-aggregation.html

\Spatie\ElasticsearchQueryBuilder\Aggregations\TermsAggregation::create(
    'genres',
    'genre'
)
    ->size(10)
    ->order(['_count' => 'asc'])
    ->missing('N/A')
    ->aggregation(/* $subAggregation */);

`TopHitsAggregation`

https://elastic.ac.cn/guide/cn/elasticsearch/reference/current/search-aggregations-metrics-top-hits-aggregation.html

\Spatie\ElasticsearchQueryBuilder\Aggregations\TopHitsAggregation::create(
    'top_sales_hits',
    size: 10,
);

添加排序

Builder（和一些聚合）有一个 addSort() 方法，该方法接受一个 Sort 实例以对结果进行排序。有关排序工作原理的更多信息，请参阅 ElasticSearch 文档。

use Spatie\ElasticsearchQueryBuilder\Sorts\Sort;

$builder
    ->addSort(Sort::create('age', Sort::DESC))
    ->addSort(
        Sort::create('score', Sort::ASC)
            ->unmappedType('long')
            ->missing(0)
    );

检索特定字段

可以使用 fields() 方法请求从结果文档中获取特定字段，而不返回整个 _source 条目。有关字段参数的详细信息，请参阅 ElasticSearch 文档。

$builder->fields('user.id', 'http.*.status');

分页

最后，Builder 还具有相应的 ElasticSearch 搜索参数的 size() 和 from() 方法。这些可以用于构建分页搜索。查看以下示例以获取大致概念

use Spatie\ElasticsearchQueryBuilder\Builder;

$pageSize = 100;
$pageNumber = $_GET['page'] ?? 1;

$pageResults = (new Builder(Elastic\Elasticsearch\ClientBuilder::create()))
    ->size($pageSize)
    ->from(($pageNumber - 1) * $pageSize)
    ->search();

测试

composer test

变更日志

有关最近更改的更多信息，请参阅变更日志。

贡献

有关详细信息，请参阅贡献指南。

安全漏洞

有关如何报告安全漏洞的详细信息，请参阅我们的安全策略。

鸣谢

许可证

MIT 许可证（MIT）。有关更多信息，请参阅许可证文件。

maxzhang666 / elasticsearch-query-builder

维护者

详细信息