数据增强

编辑

ES|QL 的 ENRICH 处理命令会在查询时,将来自一个或多个源索引的数据与 Elasticsearch 增强索引中找到的字段-值组合进行合并。

例如,您可以使用 ENRICH 来:

  • 根据已知的 IP 地址识别 Web 服务或供应商
  • 根据产品 ID 将产品信息添加到零售订单
  • 根据电子邮件地址补充联系信息

ENRICH 命令的工作原理

编辑

ENRICH 命令会向表中添加新列,这些列的数据来自 Elasticsearch 索引。它需要一些特殊的组件:

esql enrich
增强策略

一组用于将正确的增强数据添加到输入表的配置选项。

增强策略包含:

  • 一个或多个源索引的列表,这些索引将增强数据存储为文档
  • 策略类型,它决定了处理器如何将增强数据与传入文档进行匹配
  • 用于匹配传入文档的源索引中的匹配字段
  • 包含您要添加到传入文档的源索引中的增强数据的增强字段

创建策略后,必须先执行策略,才能使用它。执行增强策略会使用策略的源索引中的数据创建一个名为增强索引的精简系统索引。ENRICH 命令使用此索引来匹配和增强输入表。

源索引
一个索引,用于存储 ENRICH 命令可以添加到输入表中的增强数据。您可以像管理常规 Elasticsearch 索引一样创建和管理这些索引。您可以在一个增强策略中使用多个源索引。您也可以在多个增强策略中使用同一个源索引。
增强索引

与特定增强策略关联的特殊系统索引。

直接将输入表中的行与源索引中的文档进行匹配可能很慢并且会占用大量资源。为了加快速度,ENRICH 命令使用增强索引。

增强索引包含来自源索引的增强数据,但具有一些特殊属性以帮助简化它们:

  • 它们是系统索引,这意味着它们由 Elasticsearch 内部管理,仅供增强处理器和 ES|QL ENRICH 命令使用。
  • 它们始终以 .enrich-* 开头。
  • 它们是只读的,这意味着您无法直接更改它们。
  • 它们被强制合并以实现快速检索。

设置增强策略

编辑

要开始使用 ENRICH,请按照以下步骤操作:

设置增强策略后,您可以更新您的增强数据,并更新您的增强策略

ENRICH 命令会执行多个操作,并且可能会影响查询速度。

先决条件

编辑

要使用增强策略,您必须具有:

  • 任何使用的索引的 read 索引权限
  • enrich_user 内置角色

添加增强数据

编辑

首先,将文档添加到一个或多个源索引。这些文档应包含您最终想要添加到传入数据的增强数据。

您可以使用 文档索引 API 像管理常规 Elasticsearch 索引一样管理源索引。

您还可以设置 Beats,例如 Filebeat,以自动将文档发送并索引到您的源索引。请参阅 Beats 入门

创建增强策略

编辑

将增强数据添加到源索引后,使用 创建增强策略 APIKibana 中的索引管理来创建增强策略。

创建后,您无法更新或更改增强策略。请参阅更新增强策略

执行增强策略

编辑

创建增强策略后,您需要使用 执行增强策略 APIKibana 中的索引管理来执行它,以创建增强索引

esql enrich policy

增强索引包含来自策略的源索引的文档。增强索引始终以 .enrich-* 开头,是只读的,并且是强制合并的。

增强索引应仅由增强处理器ES|QL ENRICH 命令使用。避免将增强索引用于其他目的。

使用增强策略

编辑

执行策略后,您可以使用 ENRICH 命令来增强您的数据。

esql enrich command

以下示例使用 languages_policy 增强策略,为策略中定义的每个增强字段添加一个新列。匹配是使用 增强策略中定义的 match_field 执行的,并且要求输入表具有一个同名列(在本例中为 language_code)。ENRICH 将根据匹配字段值在增强索引中查找记录。

ROW language_code = "1"
| ENRICH languages_policy
language_code:keyword language_name:keyword

1

英语

要使用与策略中定义的 match_field 名称不同的列作为匹配字段,请使用 ON <column-name>

ROW a = "1"
| ENRICH languages_policy ON a
a:keyword language_name:keyword

1

英语

默认情况下,策略中定义的每个增强字段都会作为列添加。要显式选择要添加的增强字段,请使用 WITH <field1>, <field2>, ...

ROW a = "1"
| ENRICH languages_policy ON a WITH language_name
a:keyword language_name:keyword

1

英语

您可以使用 WITH new_name=<field1> 重命名添加的列

ROW a = "1"
| ENRICH languages_policy ON a WITH name = language_name
a:keyword name:keyword

1

英语

如果发生名称冲突,新创建的列将覆盖现有列。

更新增强索引

编辑

创建后,您无法更新增强索引或向其索引文档。相反,请更新您的源索引,并再次执行增强策略。这将从您更新的源索引创建一个新的增强索引。之前的增强索引将通过延迟维护作业删除。默认情况下,此操作每 15 分钟执行一次。

更新增强策略

编辑

创建后,您无法更新或更改增强策略。相反,您可以:

  1. 创建并执行新的增强策略。
  2. 在任何正在使用的增强处理器或 ES|QL 查询中,使用新的增强策略替换之前的增强策略。
  3. 使用 删除增强策略 API 或 Kibana 中的索引管理来删除之前的增强策略。

增强策略类型和限制

编辑

ES|QL ENRICH 命令支持所有三种增强策略类型:

geo_match
根据 geo_shape 查询,将增强数据与传入文档进行匹配。有关示例,请参阅示例:根据地理位置增强您的数据
match
根据 term 查询,将增强数据与传入文档进行匹配。有关示例,请参阅示例:根据精确值增强您的数据
range
根据 term 查询,将传入文档中的数字、日期或 IP 地址与增强索引中的范围进行匹配。有关示例,请参阅示例:通过将值与范围匹配来增强您的数据

虽然支持所有三种增强策略类型,但需要注意一些限制:

  • geo_match 增强策略类型仅支持 intersects 空间关系。
  • ENRICH 命令中的 match_field 必须具有正确的类型。例如,如果增强策略的类型为 geo_match,则 ENRICH 命令中的 match_field 必须具有 geo_pointgeo_shape 类型。同样,range 增强策略要求 match_field 的类型为 integerlongdateip,具体取决于原始增强索引中范围字段的类型。
  • 但是,当 match_field 的类型为 KEYWORD 时,对于 range 策略,此约束会放宽。在这种情况下,将在查询执行期间逐行解析字段值。如果任何值无法解析,则该行的输出值将设置为 null,将生成适当的警告,并且查询将继续执行。