› › ›

EQL 搜索 API

EQL 搜索 API编辑

EQL 假设数据流或索引中的每个文档都对应一个事件。

response = client.eql.search(
  index: 'my-data-stream',
  body: {
    query: "\n    process where process.name == \"regsvr32.exe\"\n  "
  }
)
puts response

GET /my-data-stream/_eql/search
{
  "query": """
    process where process.name == "regsvr32.exe"
  """
}

请求编辑

GET /<target>/_eql/search

POST /<target>/_eql/search

先决条件编辑

如果启用了 Elasticsearch 安全功能，则您必须对目标数据流、索引或别名具有 read 索引权限。
请参阅必需字段。
[预览] 此功能处于技术预览阶段，可能会在将来的版本中更改或删除。Elastic 将努力解决任何问题，但技术预览中的功能不受官方 GA 功能支持 SLA 的约束。对于跨集群搜索，本地集群和远程集群必须使用相同的 Elasticsearch 版本，如果它们的版本早于 7.17.7（含）或早于 8.5.1（含）。有关安全性，请参阅 远程集群。

限制编辑

请参阅 EQL 限制。

路径参数编辑

<target>

(必需，字符串) 用于限制请求的数据流、索引或别名的逗号分隔列表。支持通配符 (*)。要搜索所有数据流和索引，请使用 * 或 _all。

[预览] 此功能处于技术预览阶段，可能会在将来的版本中更改或删除。Elastic 将努力解决任何问题，但技术预览中的功能不受官方 GA 功能支持 SLA 的约束。要搜索远程集群，请使用 <cluster>:<target> 语法。请参阅跨集群运行 EQL 搜索。

查询参数编辑

allow_no_indices

(可选，布尔值)

此参数的行为与其他多目标 API 中使用的 allow_no_indices 参数不同。

如果为 false，则如果任何通配符模式、别名或 _all 值仅针对缺失或关闭的索引，则请求将返回错误。即使请求针对其他打开的索引，此行为也适用。例如，如果索引以 foo 开头，但没有索引以 bar 开头，则针对 foo*,bar* 的请求将返回错误。

如果为 true，则只有专门针对缺失或关闭的索引的请求才会返回错误。例如，如果索引以 foo 开头，但没有索引以 bar 开头，则针对 foo*,bar* 的请求不会返回错误。但是，仅针对 bar* 的请求仍然会返回错误。

默认为 true。

ccs_minimize_roundtrips

(可选，布尔值) 如果为 true，则在运行跨集群搜索 (CCS) 请求时，本地集群和远程集群之间的网络往返次数将降至最低。

此选项对于针对完全包含在一个远程集群中的数据的请求有效；当数据分布在多个集群中时，该设置将被忽略。

默认为 true。

expand_wildcards

(可选，字符串) 通配符模式可以匹配的索引类型。如果请求可以针对数据流，则此参数决定通配符表达式是否匹配隐藏的数据流。支持逗号分隔的值，例如 open,hidden。有效值为

all: 匹配任何数据流或索引，包括隐藏的数据流或索引。
open: 匹配打开的、非隐藏的索引。还匹配任何非隐藏的数据流。
closed: 匹配关闭的、非隐藏的索引。还匹配任何非隐藏的数据流。数据流无法关闭。
hidden: 匹配隐藏的数据流和隐藏的索引。必须与 open、closed 或两者结合使用。
none: 不接受通配符模式。

默认为 open。

filter_path

(可选，字符串) API 响应的过滤器列表，以逗号分隔。请参阅响应过滤。

ignore_unavailable

(可选，布尔值) 如果为 false，则如果请求针对缺失或关闭的索引，则请求将返回错误。默认为 true。

keep_alive

(可选，时间值) 搜索及其结果在集群上存储的期限。默认为 5d（五天）。

当此期限到期时，即使搜索仍在进行，搜索及其结果也会被删除。

如果 keep_on_completion 参数为 false，则 Elasticsearch 仅存储在由 wait_for_completion_timeout 参数设置的期限内未完成的异步搜索，而不管此值如何。

您也可以使用 keep_alive 请求体参数指定此值。如果同时指定了这两个参数，则仅使用查询参数。

keep_on_completion

(可选，布尔值) 如果为 true，则搜索及其结果将存储在集群上。

如果为 false，则仅当请求在由 wait_for_completion_timeout 参数设置的期限内未完成时，搜索及其结果才会存储在集群上。默认为 false。

您也可以使用 keep_on_completion 请求体参数指定此值。如果同时指定了这两个参数，则仅使用查询参数。

wait_for_completion_timeout

(可选，时间值) 等待请求完成的超时持续时间。默认为无超时，这意味着请求将等待完整的搜索结果。

如果指定了此参数，并且请求在此期限内完成，则将返回完整的搜索结果。

如果请求在此期限内未完成，则搜索将变为异步搜索。

您也可以使用 wait_for_completion_timeout 请求体参数指定此值。如果同时指定了这两个参数，则仅使用查询参数。

请求体编辑

event_category_field

(必需*，字符串) 包含事件分类的字段，例如 process、file 或 network。

默认为 event.category，如 Elastic 通用模式 (ECS) 中所定义。如果数据流或索引不包含 event.category 字段，则此值是必需的。

事件类别字段必须在 keyword 族中映射为字段类型。

fetch_size

(可选，整数) 针对序列查询一次搜索的最大事件数。默认为 1000。

此值必须大于 2，但不能超过 index.max_result_window 设置的值，该设置默认为 10000。

在内部，序列查询会获取和分页事件集以搜索匹配项。此参数控制这些集合的大小。此参数不会限制搜索的总事件数或返回的匹配事件数。

较大的 fetch_size 值通常会提高搜索速度，但会使用更多内存。

fields

(可选，字符串和对象的数组) 字段模式数组。请求将返回响应的 hits.fields 属性中与这些模式匹配的字段名称的值。

您可以将数组中的项目指定为字符串或对象。请参阅 the fields 选项。

fields 对象的属性

field

(必需，字符串) 要返回的字段。支持通配符 (*)。

format

(可选，字符串) 日期和地理空间字段的格式。其他字段数据类型不支持此参数。

date 和 date_nanos 字段接受日期格式。 geo_point 和 geo_shape 字段接受

geojson (默认)

GeoJSON

wkt

Well Known Text

mvt(<spec>)

二进制 Mapbox 矢量瓦片。API 以 Base64 编码字符串的形式返回瓦片。 <spec> 的格式为 <zoom>/<x>/<y>，并带有两个可选后缀： @<extent> 和/或 :<buffer>。例如， 2/0/1 或 2/0/1@4096:5。

mvt 参数

<zoom>: (必需，整数) 瓦片的缩放级别。接受 0-29。
<x>: (必需，整数) 瓦片的 X 坐标。
<y>: (必需，整数) 瓦片的 Y 坐标。
<extent>: (可选，整数) 瓦片边长的像素大小。矢量瓦片是正方形，边长相等。默认值为 4096。
<buffer>: (可选，整数) 瓦片外部剪切缓冲区的像素大小。这使渲染器能够避免几何体延伸到瓦片范围之外而产生的轮廓伪影。默认值为 5。

filter

(可选，Query DSL 对象) 使用 Query DSL 编写的查询，用于过滤 EQL 查询运行的事件。

keep_alive

(可选，时间值) 搜索及其结果在集群上存储的期限。默认为 5d（五天）。

当此期限到期时，即使搜索仍在进行，搜索及其结果也会被删除。

如果 keep_on_completion 参数为 false，则 Elasticsearch 仅存储在由 wait_for_completion_timeout 参数设置的期限内未完成的异步搜索，而不管此值如何。

您也可以使用 keep_alive 查询参数指定此值。如果同时指定了这两个参数，则只使用查询参数。

keep_on_completion

(可选，布尔值) 如果为 true，则搜索及其结果将存储在集群上。

如果为 false，则仅当请求在由 wait_for_completion_timeout 参数设置的期限内未完成时，搜索及其结果才会存储在集群上。默认为 false。

您也可以使用 keep_on_completion 查询参数指定此值。如果同时指定了这两个参数，则只使用查询参数。

query

(必需，字符串) 您要运行的 EQL 查询。

result_position

(可选，枚举) 要返回的一组匹配事件或序列。

result_position 的有效值

tail: (默认) 返回最新的匹配项，类似于 Unix tail 命令。
head: 返回最早的匹配项，类似于 Unix head 命令。

此参数可能会更改返回的命中集。但是，它不会更改响应中命中的排序顺序。

runtime_mappings

(可选，对象的对象) 在搜索请求中定义一个或多个运行时字段。这些字段优先于具有相同名称的映射字段。

runtime_mappings 对象的属性

<field-name>

(必需，对象) 运行时字段的配置。键是字段名称。

<field-name> 的属性

type

(必需，字符串) 字段类型，可以是以下任何一种

boolean
composite
date
double
geo_point
ip
keyword
long
lookup

script

(可选，字符串) 在查询时执行的 Painless 脚本。该脚本可以访问文档的整个上下文，包括原始 _source 和任何映射字段及其值。

此脚本必须包含 emit 以返回计算出的值。例如

"script": "emit(doc['@timestamp'].value.dayOfWeekEnum.toString())"

size

(可选，整数或浮点数) 对于基本查询，要返回的最大匹配事件数。

对于序列查询，要返回的最大匹配序列数。

默认值为 10。此值必须大于 0。

您不能使用管道（如 head 或 tail）来超过此值。

tiebreaker_field: (可选，字符串) 用于按升序对具有相同时间戳的命中进行排序的字段。请参阅指定排序断路器。

timestamp_field

(必需*，字符串) 包含事件时间戳的字段。

默认值为 @timestamp，如 Elastic Common Schema (ECS) 中所定义。如果数据流或索引不包含 @timestamp 字段，则需要此值。

API 响应中的事件按此字段的值排序，转换为自 Unix 纪元以来以毫秒为单位的时间，按升序排列。

时间戳字段应映射为 date。不支持 date_nanos 字段类型。

wait_for_completion_timeout

(可选，时间值) 等待请求完成的超时持续时间。默认为无超时，这意味着请求将等待完整的搜索结果。

如果指定了此参数，并且请求在此期限内完成，则将返回完整的搜索结果。

如果请求在此期限内未完成，则搜索将变为异步搜索。

您也可以使用 wait_for_completion_timeout 查询参数指定此值。如果同时指定了这两个参数，则只使用查询参数。

响应主体编辑

id

(字符串) 搜索的标识符。

仅当满足以下条件之一时，才会提供此搜索 ID

搜索请求在 wait_for_completion_timeout 参数的超时时间段内没有返回完整结果，成为异步搜索。
搜索请求的 keep_on_completion 参数为 true。

您可以使用此 ID 与获取异步 EQL 搜索 API 获取搜索的当前状态和可用结果，或使用获取异步 EQL 状态 API 仅获取当前状态。

is_partial

(布尔值) 如果为 true，则响应不包含完整的搜索结果。

is_running

(布尔值) 如果为 true，则搜索请求仍在执行。

如果此参数和 is_partial 参数为 true，则搜索为正在进行的异步搜索。如果 keep_alive 时间段没有过去，则搜索完成后将提供完整的搜索结果。

如果 is_partial 为 true 但 is_running 为 false，则搜索由于故障而返回了部分结果。只有一部分分片返回了结果，或者协调搜索的节点发生了故障。

took

(整数) Elasticsearch 执行请求所花费的毫秒数。

此值通过测量协调节点接收请求的时间与协调节点准备好发送响应的时间之间的经过时间来计算。

执行时间包括

协调节点与数据节点之间的通信时间
请求在 search 线程池中排队等待执行的时间
实际执行时间

执行时间不包括

将请求发送到 Elasticsearch 所需的时间
序列化 JSON 响应所需的时间
将响应发送到客户端所需的时间

timed_out

(布尔值) 如果为 true，则请求在完成之前超时。

hits

(对象) 包含匹配的事件和序列。还包含相关元数据。

hits 的属性

total

(对象) 有关匹配事件或序列数量的元数据。

total 的属性

value

(整数) 对于基本查询，匹配事件的总数。

对于序列查询，匹配序列的总数。

relation

(字符串) 指示返回的事件或序列数量是准确的还是下限。

返回的值为

eq: 准确的
gte: 下限，包括返回的事件或序列

sequences

(对象数组) 包含与查询匹配的事件序列。每个对象代表一个匹配的序列。此参数仅针对包含序列的 EQL 查询返回。

sequences 对象的属性

join_keys

(值数组) 用于约束序列中匹配项的共享字段值。这些是在 EQL 查询语法中使用 by 关键字定义的。

events

(对象数组) 包含与查询匹配的事件。每个对象代表一个匹配的事件。

events 对象的属性

_index: (字符串) 包含事件的索引的名称。
_id: (字符串) 事件的唯一标识符。此 ID 仅在索引内唯一。
_source: (对象) 在索引时为事件传递的原始 JSON 主体。

events

(对象数组) 包含与查询匹配的事件。每个对象代表一个匹配的事件。

events 对象的属性

_index: (字符串) 包含事件的索引的名称。
_id: (字符串) (字符串) 事件的唯一标识符。此 ID 仅在索引内唯一。
_source: (对象) 在索引时为事件传递的原始 JSON 主体。

示例编辑

基本查询示例编辑

以下 EQL 搜索请求搜索具有 event.category 为 process 的事件，这些事件满足以下条件

process.name 为 cmd.exe
process.pid 不为 2013

response = client.eql.search(
  index: 'my-data-stream',
  body: {
    query: "\n    process where (process.name == \"cmd.exe\" and process.pid != 2013)\n  "
  }
)
puts response

GET /my-data-stream/_eql/search
{
  "query": """
    process where (process.name == "cmd.exe" and process.pid != 2013)
  """
}

API 返回以下响应。 hits.events 属性中的匹配事件按时间戳排序，转换为自 Unix 纪元以来以毫秒为单位的时间，按升序排列。

如果两个或多个事件共享相同的时间戳，则使用 tiebreaker_field 字段按升序对事件进行排序。

{
  "is_partial": false,
  "is_running": false,
  "took": 6,
  "timed_out": false,
  "hits": {
    "total": {
      "value": 2,
      "relation": "eq"
    },
    "events": [
      {
        "_index": ".ds-my-data-stream-2099.12.07-000001",
        "_id": "babI3XMBI9IjHuIqU0S_",
        "_source": {
          "@timestamp": "2099-12-06T11:04:05.000Z",
          "event": {
            "category": "process",
            "id": "edwCRnyD",
            "sequence": 1
          },
          "process": {
            "pid": 2012,
            "name": "cmd.exe",
            "executable": "C:\\Windows\\System32\\cmd.exe"
          }
        }
      },
      {
        "_index": ".ds-my-data-stream-2099.12.07-000001",
        "_id": "b6bI3XMBI9IjHuIqU0S_",
        "_source": {
          "@timestamp": "2099-12-07T11:06:07.000Z",
          "event": {
            "category": "process",
            "id": "cMyt5SZ2",
            "sequence": 3
          },
          "process": {
            "pid": 2012,
            "name": "cmd.exe",
            "executable": "C:\\Windows\\System32\\cmd.exe"
          }
        }
      }
    ]
  }
}

序列查询示例编辑

以下 EQL 搜索请求匹配序列的事件，这些事件

以具有以下特征的事件开始
- event.category 为 file
- file.name 为 cmd.exe
- process.pid 不为 2013
接着是具有以下特征的事件
- event.category 为 process
- process.executable 包含子字符串 regsvr32

这些事件还必须共享相同的 process.pid 值。

response = client.eql.search(
  index: 'my-data-stream',
  body: {
    query: "\n    sequence by process.pid\n      [ file where file.name == \"cmd.exe\" and process.pid != 2013 ]\n      [ process where stringContains(process.executable, \"regsvr32\") ]\n  "
  }
)
puts response

GET /my-data-stream/_eql/search
{
  "query": """
    sequence by process.pid
      [ file where file.name == "cmd.exe" and process.pid != 2013 ]
      [ process where stringContains(process.executable, "regsvr32") ]
  """
}

API 返回以下响应。匹配的序列包含在 hits.sequences 属性中。 hits.sequences.join_keys 属性包含每个匹配事件的共享 process.pid 值。

{
  "is_partial": false,
  "is_running": false,
  "took": 6,
  "timed_out": false,
  "hits": {
    "total": {
      "value": 1,
      "relation": "eq"
    },
    "sequences": [
      {
        "join_keys": [
          2012
        ],
        "events": [
          {
            "_index": ".ds-my-data-stream-2099.12.07-000001",
            "_id": "AtOJ4UjUBAAx3XR5kcCM",
            "_source": {
              "@timestamp": "2099-12-06T11:04:07.000Z",
              "event": {
                "category": "file",
                "id": "dGCHwoeS",
                "sequence": 2
              },
              "file": {
                "accessed": "2099-12-07T11:07:08.000Z",
                "name": "cmd.exe",
                "path": "C:\\Windows\\System32\\cmd.exe",
                "type": "file",
                "size": 16384
              },
              "process": {
                "pid": 2012,
                "name": "cmd.exe",
                "executable": "C:\\Windows\\System32\\cmd.exe"
              }
            }
          },
          {
            "_index": ".ds-my-data-stream-2099.12.07-000001",
            "_id": "OQmfCaduce8zoHT93o4H",
            "_source": {
              "@timestamp": "2099-12-07T11:07:09.000Z",
              "event": {
                "category": "process",
                "id": "aR3NWVOs",
                "sequence": 4
              },
              "process": {
                "pid": 2012,
                "name": "regsvr32.exe",
                "command_line": "regsvr32.exe  /s /u /i:https://...RegSvr32.sct scrobj.dll",
                "executable": "C:\\Windows\\System32\\regsvr32.exe"
              }
            }
          }
        ]
      }
    ]
  }
}

« 删除异步 EQL 搜索 API 获取异步 EQL 搜索 API »