sopheos/pebble_es

请求/响应库

维护者

详细信息

github.com/sopheos/pebble_es

源代码

问题

安装: 111

依赖项: 0

建议者: 0

安全: 0

星标: 1

关注者: 1

分支: 0

开放问题: 0

1.0.8 2023-11-21 09:36 UTC

Requires

Requires (Dev)

MIT d00ae963817f3556e09b8cac2c25e393b378df79

This package is auto-updated.

Last update: 2024-09-21 11:18:20 UTC

README

本文档是Pebble的Elasticsearch查询构建器使用指南。

简单示例

准备搜索

要进行搜索，需要准备一个请求，并添加一个组件。

$bool = \Pebble\ES\BoolQuery::make()->minimumSouldMatch(1);
$query =  \Pebble\ES\Query::make()->query($bool);

布尔查询允许在指令（must、must_not、filter、should）中分组搜索过滤器。

\Pebble\ES\Term::make('pays', 'FR')->filter($bool);
\Pebble\ES\Match::make('recherche', $search)->boost(16)->should($bool);
\Pebble\ES\Match::make('nom', $search)->boost(8)->should($bool);

查看Elasticsearch文档：https://elastic.ac.cn/guide/en/elasticsearch/reference/current/query-dsl-bool-query.html

发送请求

查询构建器使用发送HTTP请求到服务器。

$options = ['base_uri' => 'http://127.0.0.1:9200'];
$guzzle  = new \GuzzleHttp\Client($options);
$request = \Pebble\ES\Request::make($guzzle);
$res = $request->search('loc_villes');

查看Guzzle文档：https://github.com/guzzle/guzzle

获取结果

search方法返回一个对象。

echo json_encode($res, JSON_PRETTY_PRINT);

ES\Request组件

构造函数

构造函数或静态方法make需要一个对象作为参数。

方法

  • request(string $method, string $url, $data = []) : \stdClass : 发送请求。
  • get($url) : \stdClass : 发送GET请求的快捷方式。
  • post($url, $data = []) : \stdClass : 发送POST请求的快捷方式。
  • put($url, $data = []) : \stdClass : 发送PUT请求的快捷方式。
  • delete($url) : \stdClass : 发送DELETE请求的快捷方式。
  • search(string $url = '', $data = []) : \Pebble\ES\Result : 进行搜索的快捷方式。
  • search(string $url = '', $data = []) : \Pebble\ES\Result : 进行搜索的快捷方式。
  • scroll(string $url = '', $data = [], string $time = '1m') : \Pebble\ES\Result : 进行长时间搜索的快捷方式。
  • clearScroll(string $id) : \Pebble\ES\Result : 删除长时间搜索。
  • bulk(string $url, array $data) : \stdClass : 批量发送数据。
  • lastRequest() : array : 获取最后一个请求。

长时间搜索

标准搜索限制为10,000个元素。要获取所有结果，需要使用预准备请求进行长时间搜索。

第一次搜索：使用与search方法相同的scroll方法。一个附加参数用于确定此请求将被保留多长时间。

结果将返回一个附加参数：scroll_id。要获取后续结果，需要将此值直接传递给$data参数。

搜索完成后，最好使用clearScroll方法删除预准备请求。

示例

// Première recherche
$query =  \Pebble\ES\Query::make();
// ...
$res = $request->scroll('loc_villes', $query);
$scroll_id = $res1->scrollID();

// Seconde recherche
$res2 = $request->scroll('loc_villes', $scroll_id);

// Fin
$request->clearScroll($scroll_id);

ES\Result组件

took()

返回查询执行的毫秒时间。

total()

返回与查询匹配的总结果数。

maxScore()

返回与查询匹配的最高分数。

hits()

返回查询的结果集。

aggs($name0, $name1, ... , $nameN)

返回聚合的结果集。参数列表对应于聚合的路径。

raw()

返回搜索的原始结果。

jsonSerialize()

与raw()方法相同的方法。此方法对于将对象转换为JSON对象是必需的。

查询构建器

Elasticsearch请求非常冗长。查询构建器有助于构建最常用的查询。

查询构建器中的所有元素都必须扩展 \Pebble\ES\AbstractRaw

  • abstract raw() : array : 以数组形式返回查询组件的数据。

可以使用辅助器 \Pebble\ES\Raw 创建自定义组件。

Raw::make(["prefix" => ["user" => "ki"]]);

Pebble\ES\Query 组件

查询构建器的主要容器。

  • static make() : Query : 构造函数的替代方案。
  • set(string $key, $value) : 将键值对添加到查询中。
  • size(int $value = 10) : 限制结果数量。
  • from(int $value = 0) : 结果集的偏移（偏移量）。
  • searchAfter(array $value) : 仅返回超出传递的值的排序值的结果（通常基于上一个查询的最后一个排序值）。
  • query(AbstractRaw $query) : 添加搜索字段。
  • conflictsProceed() : 在通过查询修改/删除时处理冲突。
  • aggs(AbstractRaw $agg) : 添加聚合。
  • sort(AbstractRaw $sort) : 添加排序。
  • highlight(AbstractRaw $highlight) : 添加高亮。

布尔查询 ES\BoolQuery

在指令中排序查询。

  • static make() : Query : 构造函数的替代方案。
  • must(AbstractFilter $filter) : 将过滤器添加到 must 指令。
  • should(AbstractFilter $filter) : 将过滤器添加到 should 指令。
  • filter(AbstractFilter $filter) : 将过滤器添加到 filter 指令。
  • must_not(AbstractFilter $filter) : 将过滤器添加到 must_not 指令。
  • minimumSouldMatch(int $value) : should 指令的最小结果数量。
  • boost(float $value) : 加强搜索分数。

过滤器

并非所有过滤器都已被添加到 Pebble。请根据需要添加它们。

同样，可以添加某些过滤器的可选选项（请参阅 ElasticSearch 文档）。它们可以使用以下方法添加：

$filter->set('key', $value);

可以根据需要添加到过滤器上的快捷方式。

注意：某些过滤器具有搜索上下文（全文）。这将影响分数。其他过滤器将具有过滤器上下文。不会影响分数。

匹配

全文搜索字段的值（全文）。

Match::make('titre', 'meuble')->fuzzy('auto')->boost(16);

匹配所有

全文搜索所有文档。

MatchAll::make();

范围

搜索由区间界定的值。

Range::make('prix')->gte(10)->lte(15);
Range::make('borne')->gte('01/01/2012')->lte('2013')->format('dd/MM/yyyy||yyyy');
  • gte($value) : 大于或等于。
  • gt($value) : 大于。
  • lte($value) : 小于或等于。
  • lt($value) : 小于。
  • format(string $value) : 日期格式。
  • time_zone(string $value) : 将日期转换为其他时区。

存在

搜索具有非空值的字段的文档。

Exists::make('petname');

术语

搜索字段的特定值。

Term::make('pays', 'FR');

术语

搜索与特定值对应的字段。

Terms::make('pays', 'FR', 'CH', 'BE');

前缀

允许搜索以特定值开头的未分析字段。扩展 Term。

Prefix('user', 'ki');

通配符

允许使用通配符搜索未分析字段的值。扩展 Term。

Wildcard::make('user', 'ki*y');

正则表达式

允许使用正则表达式搜索未分析字段的值。扩展 Term。

Regex::make('user', 'k.*m');

模糊

允许搜索非分析字段的近似值。扩展 Term。

Fuzzy::make('ville', 'milhouse')
    ->fuzziness(1)
    ->prefixLength(0)
    ->maxExpansions(20);

Ids

筛选具有列表中标识符的文档。

Ids::make(['jsgrvdoi', 'zldns']);

地理距离

筛选位于特定点周围一定范围内的文档。字段必须是 geo_point 类型。

GeoDistance::make('loc', 47.75, 7.31, '100m'); // field, lat, lon, distance

地理边界

筛选位于特定边界之间的文档。字段必须是 geo_point 类型。

GeoDistance::make(field, latMin, latMax, lonMin, lonMax)
GeoDistance::fromDistance(field, lat, lon, $distance)

三重态

排序

按值排序

Sort::make()->add('_score')->desc('type')->asc('pays_alias');

SortGeo

按距离排序。

SortGeo::make('loc', 47.75, 7.31); // // field, lat, lon

聚合

收集由搜索查询选择的所有数据。

让我们回到前面的例子，查找地区列表

$aggs = \Pebble\ES\Aggregation::make('admin_list', 'terms')->field('admin_nom')->size(1000)->addTo($request);

注意：如果我们只对聚合感兴趣，可以要求查询不返回搜索结果

$request->size(0);

要获取此列表，只需在聚合中搜索其名称

$list = $res->aggs('admin_list');

可以在聚合上进行布尔搜索

$boolQuery->addToAggs($aggs)

或

$aggs->filter($boolQuery);

高亮显示

可以使用高亮显示来突出显示与搜索匹配的项，并定义包围匹配项的标签。

$highlight = ES\Highlight::make('title')->preTags('<br>')->postTags('</br>');
$query->highlight($highlight);

标签是可选的，ES默认将匹配项放在标签<em>之间。

如果在一个或多个字段中进行搜索，可以传递一个字符串或字符串数组来高亮显示多个字段。

$highlight = ES\Highlight::make(['title', 'description']);
$query->highlight($highlight);

结果存储在hits->highlight中。

插入/替换文档

未提供标识符

$res = Request::make($guzzle)->post("tests/_doc", [
    "name" => "Mathieu",
    "age" => 2,
]);
$success = isset($res->result) && ($res->result === 'created' || $res->result === 'updated');

提供了标识符

$res = Request::make($guzzle)->put("tests/_doc/1/_update", [
    "name" => "Mathieu",
    "age" => 2,
]);
$success = isset($res->result) && ($res->result === 'created' || $res->result === 'updated');

更新文档

$res = Request::make($guzzle)->post("tests/_doc/1/_update", [
    "doc" => ["age" => 3],
]);

原子更新

$res = Request::make($guzzle)->post("tests/_doc/1/_update", [
    "script" => "ctx._source.age += 5"
]);
$success = isset($res->result) && $res->result === 'updated';

删除文档

$res = Request::make($guzzle)->delete("tests/_doc/1");
$success = isset($res->result) && $res->result === 'deleted';

批量插入

$data = [];
$data[] = ['index' => ["_id" : "1"]];
$data[] = ['name' => 'Pierre'];
$data[] = ['index' => ["_id" : "2"]];
$data[] = ['name' => 'Chloé'];

Request::make($guzzle)->bulk('tests/_doc', $data);

批量删除

// Delete
$bool = BoolQuery::make();
// ...
$query = Query::make()->query($bool)->conflictsProceed();
Request::make($guzzle)->post('tests/_delete_by_query', $query);