警告：此功能在 8.18/9.0 中刚推出。此功能处于技术预览阶段，未来版本可能会更改或删除。Elastic 会努力修复任何问题，但技术预览中的功能不受正式 正式发布功能支持 SLA 的约束。
ES|QL LOOKUP JOIN 处理命令将你的 ES|QL 查询结果表中的数据与指定的查找索引中的匹配记录合并。它根据联接字段中的匹配值，将查找索引中的字段作为新列添加到结果表中。
团队常常将数据分散在多个索引中，例如日志、IP、用户 ID、主机、员工等。如果没有直接的方式来丰富或关联每个事件与参考数据，那么根本原因分析、安全检查和操作洞察将变得耗时。
例如，你可以使用 LOOKUP JOIN 来：
与 ENRICH 对比
LOOKUP JOIN 和 ENRICH 的相似之处在于，它们都帮助你将数据结合在一起。你应该在以下情况下使用 LOOKUP JOIN：
命令如何工作
LOOKUP JOIN 命令根据联接字段中的匹配值，将查找索引中的字段作为新列添加到结果表中。
LOOKUP JOIN <lookup_index> ON <field_name>
该命令需要两个参数：
![]()
如果你熟悉 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" }
}
}
}
- 查找索引必须使用此模式进行设置。它创建 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 */
"""
}
- 源索引
- 查找索引和连接字段
- 筛选具有非空威胁级别的行
- LOOKUP JOIN 不保证输出顺序，因此必须显式排序
- 仅保留相关字段
- 将输出限制为 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 字段被添加到输出中。
附加示例
请参阅 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 的情况大致相同。
