Elasticsearch：ES|QL lookup JOIN 介绍 - 8.18/9.0

警告：此功能在 8.18/9.0 中刚推出。此功能处于技术预览阶段，未来版本可能会更改或删除。Elastic 会努力修复任何问题，但技术预览中的功能不受正式 正式发布功能支持 SLA 的约束。

ES|QL LOOKUP JOIN 处理命令将你的 ES|QL 查询结果表中的数据与指定的查找索引中的匹配记录合并。它根据联接字段中的匹配值，将查找索引中的字段作为新列添加到结果表中。

团队常常将数据分散在多个索引中，例如日志、IP、用户 ID、主机、员工等。如果没有直接的方式来丰富或关联每个事件与参考数据，那么根本原因分析、安全检查和操作洞察将变得耗时。

例如，你可以使用 LOOKUP JOIN 来：

• 获取每个主机的环境或所有权详细信息，以关联你的指标数据。

• 快速查看任何源 IP 是否与已知的恶意地址匹配。

• 为日志标记拥有团队或升级信息，以便更快地进行分类和事件响应。

与 ENRICH 对比

LOOKUP JOIN 和 ENRICH 的相似之处在于，它们都帮助你将数据结合在一起。你应该在以下情况下使用 LOOKUP JOIN：

• 你的富集数据经常变化

• 你想避免索引时处理

• 你想要 SQL 类似的行为，即多个匹配结果生成多行

• 你需要在查找索引中的任何字段上进行匹配

• 你使用文档或字段级安全

• 你希望限制用户只能使用特定的查找索引

• 你不需要使用范围或空间关系进行匹配

命令如何工作

LOOKUP JOIN 命令根据联接字段中的匹配值，将查找索引中的字段作为新列添加到结果表中。

LOOKUP JOIN <lookup_index> ON <field_name>

该命令需要两个参数：

• lookup_index
  查找索引的名称。必须是一个特定的索引名称——不支持通配符、别名和远程集群引用。用于查找的索引必须配置为查找模式（lookup mode）。

• field_name
  用于联接的字段。该字段必须在当前查询结果和查找索引中都存在。如果字段包含多值条目，这些条目将不会匹配任何内容（对于这些行，添加的字段将包含 null）。

如果你熟悉 SQL，LOOKUP JOIN 具有左连接行为。这意味着，如果在查找索引中没有匹配的行，传入的行将被保留，并且会添加 null。如果在查找索引中有多行匹配，LOOKUP JOIN 将为每个匹配添加一行。

一个例子：

如上所示，在左边的 events 例子中，它含有一个叫做 userid 的列，在右边的例子中它也含有一个叫做 userid 的列。我们实际上可以使用如下的命令来针对两个索引进行 JOIN：

FROM events |
LOOKUP JOIN userinfo ON userid

注意：针对右边的索引，它必须配置正确的 lookup mode：

PUT userinfo
{"settings": {"index.mode": "lookup"}
}

实际操作

下面，我们将由一个例子来详细说明如何实现上面所述的 JOIN。你可以通过设置索引并添加示例数据来亲自运行此示例，看看它是如何工作的。否则，你只需检查查询和响应。

设置索引

首先，让我们创建两个带有映射的索引：threat_list 和 firewall_logs。

PUT threat_list
{"settings": {"index.mode": "lookup"  /* 1 */},"mappings": {"properties": {"source.ip": { "type": "ip" },"threat_level": { "type": "keyword" },"threat_type": { "type": "keyword" },"last_updated": { "type": "date" }}}
}

1. 查找索引必须使用此模式进行设置。它创建 LOOKUP 所需的右索引

PUT firewall_logs
{"mappings": {"properties": {"timestamp": { "type": "date" },"source.ip": { "type": "ip" },"destination.ip": { "type": "ip" },"action": { "type": "keyword" },"bytes_transferred": { "type": "long" }}}
}

上面的命令将创建一个叫做 firewall_logs 的索引，也就是我们所指的左索引。

添加示例数据

接下来，让我们向两个索引添加一些示例数据。threat_list 索引包含已知的恶意 IP，而 firewall_logs 索引包含网络流量日志。

POST threat_list/_bulk
{"index":{}}
{"source.ip":"203.0.113.5","threat_level":"high","threat_type":"C2_SERVER","last_updated":"2025-04-22"}
{"index":{}}
{"source.ip":"198.51.100.2","threat_level":"medium","threat_type":"SCANNER","last_updated":"2025-04-23"}

POST firewall_logs/_bulk
{"index":{}}
{"timestamp":"2025-04-23T10:00:01Z","source.ip":"192.0.2.1","destination.ip":"10.0.0.100","action":"allow","bytes_transferred":1024}
{"index":{}}
{"timestamp":"2025-04-23T10:00:05Z","source.ip":"203.0.113.5","destination.ip":"10.0.0.55","action":"allow","bytes_transferred":2048}
{"index":{}}
{"timestamp":"2025-04-23T10:00:08Z","source.ip":"198.51.100.2","destination.ip":"10.0.0.200","action":"block","bytes_transferred":0}
{"index":{}}
{"timestamp":"2025-04-23T10:00:15Z","source.ip":"203.0.113.5","destination.ip":"10.0.0.44","action":"allow","bytes_transferred":4096}
{"index":{}}
{"timestamp":"2025-04-23T10:00:30Z","source.ip":"192.0.2.1","destination.ip":"10.0.0.100","action":"allow","bytes_transferred":512}

查询数据

POST _query?format=txt
{"query": """FROM firewall_logs /* 1 */| LOOKUP JOIN threat_list ON source.ip /* 2 */ | WHERE threat_level IS NOT NULL /* 3 */| SORT timestamp /* 4 */| KEEP source.ip, action, threat_level, threat_type /* 5 */| LIMIT 10 /* 6 */"""
}

1. 源索引
2. 查找索引和连接字段
3. 筛选具有非空威胁级别的行
4. LOOKUP JOIN 不保证输出顺序，因此必须显式排序
5. 仅保留相关字段
6. 将输出限制为 10 行

响应

   source.ip   |    action     | threat_level  |  threat_type  
---------------+---------------+---------------+---------------
203.0.113.5    |allow          |high           |C2_SERVER      
198.51.100.2   |block          |medium         |SCANNER        
203.0.113.5    |allow          |high           |C2_SERVER  

在这个示例中，你可以看到 firewall_logs 索引中的 source.ip 字段与 threat_list 索引中的 source.ip 字段匹配，对应的 threat_level 和 threat_type 字段被添加到输出中。

更多有关 ES|QL 的操作，请参考文章 “Elasticsearch：ES|QL 查询展示”。

附加示例

请参阅 LOOKUP JOIN 命令参考中的示例部分，获取更多示例。

前提条件

要使用 LOOKUP JOIN，必须满足以下要求：

• 用于查找的索引必须配置为查找模式（lookup mode）
• 兼容的数据类型：查找索引中的连接键和连接字段必须具有兼容的数据类型。这意味着：
  • 数据类型必须完全相同或在 ES|QL 中以相同类型内部表示
  • 数字类型遵循以下兼容性规则：
    • short 和 byte 与 integer 兼容（都表示为 int）
    • float、half_float 和 scaled_float 与 double 兼容（都表示为 double）
  • 对于文本字段：你只能将文本字段作为左侧连接的连接键，并且只能在它们具有 .keyword 子字段时使用

如有需要，可以使用转换函数获取兼容类型的连接键。

有关支持的数据类型及其内部表示的完整列表，请参见支持的字段类型文档。

限制

以下是当前 LOOKUP JOIN 的限制：

• lookup 模式中的索引始终是单分片的。
• 初始时不支持跨集群搜索。源索引和查找索引必须是本地的。
• 目前，只支持基于相等性进行匹配。
• LOOKUP JOIN 只能使用一个匹配字段和一个索引。不支持通配符、别名、日期数学和数据流。
• LOOKUP JOIN 中的匹配字段名 lu++++idx ON match++++field 必须与查询中的现有字段匹配。这可能需要重命名或 evals 以实现。
• 如果查找索引中有太多匹配文档，或者文档太大，查询将触发断路器。更精确地说，LOOKUP JOIN 是按批次工作的，通常每批次大约 10,000 行；如果批次中来自查找索引的匹配文档有多个兆字节或更大，则需要大量堆空间。这与 ENRICH 的情况大致相同。