« Enrich APIs ES|QL APIs »
Elastic Docs ›Elasticsearch Guide ›REST APIs

EQL API

edit

EQL API

edit

事件查询语言 (EQL) 是一种用于基于事件的时间序列数据的查询语言， 例如日志、指标和跟踪。有关 EQL 的概述和相关教程， 请参阅 EQL。

删除异步 EQL 搜索 API

edit

删除一个异步EQL搜索或一个 存储的同步EQL搜索。该API还会删除该搜索的结果。

DELETE /_eql/search/FkpMRkJGS1gzVDRlM3g4ZzMyRGlLbkEaTXlJZHdNT09TU2VTZVBoNDM3cFZMUToxMDM=

请求

edit

DELETE /_eql/search/

先决条件

edit

  • 如果启用了Elasticsearch安全功能，只有以下用户可以使用此API删除搜索：

    • 具有cancel_task 集群权限的用户
    • 最初提交搜索的用户
  • 参见所需字段。

限制

edit

请参阅EQL 限制。

路径参数

edit
<search_id>

(必需, 字符串) 用于删除搜索的标识符。

在 EQL 搜索 API 的响应中提供了一个搜索 ID，用于 异步搜索。如果请求的 keep_on_completion 参数为 true，也会提供一个搜索 ID。

EQL 搜索 API

edit

返回针对事件查询语言 (EQL) 查询的搜索结果。

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

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

请求

edit

GET //_eql/search

POST //_eql/search

先决条件

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

限制

edit

请参阅 EQL 限制。

路径参数

edit
<target>

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

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

查询参数

edit
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 来指定此值。如果同时指定了这两个参数，则仅使用查询参数。

请求体

edit
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 选项。

Properties of fields objects
field
(必需, 字符串) 要返回的字段。支持通配符 (*)。
format

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

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

geojson (默认)
GeoJSON
wkt
Well Known Text
mvt()

二进制 Mapbox 矢量瓦片。API 返回瓦片作为base64编码的字符串。 的格式为 //，带有两个可选的后缀：@ 和/或 :。例如，2/0/1 或 2/0/1@4096:5。

mvt parameters
(必需, 整数) 瓦片的缩放级别。接受 0-29。
(必需, 整数) 瓦片的X坐标。
(必需, 整数) 瓦片的Y坐标。
(可选, 整数) 瓦片一边的大小，以像素为单位。矢量瓦片是正方形，边长相等。默认为 4096。
(可选, 整数) 瓦片外部裁剪缓冲区的大小，以像素为单位。这允许渲染器避免几何图形延伸到瓦片范围之外时产生的轮廓伪影。默认为 5。
filter
(可选，查询DSL对象) 查询，使用查询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

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

Properties of runtime_mappings objects

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

Properties of
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查询参数指定此值。如果同时指定了这两个参数，则仅使用查询参数。

响应体

edit
id

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

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

您可以使用此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

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

Properties of hits
total

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

Properties of total
value

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

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

relation

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

返回的值为：

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

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

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

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

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

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

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

示例

edit

基本查询示例

edit

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

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

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

如果两个或更多事件共享相同的timestamp，则使用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"
          }
        }
      }
    ]
  }
}

序列查询示例

edit

以下EQL搜索请求匹配一个序列事件，该事件：

  1. 从以下事件开始：

    • 一个 event.category 为 file
    • 一个 file.name 为 cmd.exe
    • 一个 process.pid 不是 2013

  2. 随后是一个事件，内容为：

    • 一个 event.category 为 process
    • 一个 process.executable 包含子字符串 regsvr32

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

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

edit

返回异步EQL搜索或存储的同步EQL搜索的当前状态和可用结果。

GET /_eql/search/FkpMRkJGS1gzVDRlM3g4ZzMyRGlLbkEaTXlJZHdNT09TU2VTZVBoNDM3cFZMUToxMDM=

请求

edit

GET /_eql/search/

先决条件

edit
  • 如果启用了Elasticsearch安全功能，只有最初提交EQL搜索的用户才能使用此API检索搜索。
  • 请参阅必需字段。

限制

edit

请参阅 EQL 限制。

路径参数

edit
<search_id>

(必需，字符串) 搜索的标识符。

在 EQL 搜索 API 的响应中提供了一个搜索 ID，用于 异步搜索。如果请求的 keep_on_completion 参数为 true，也会提供一个搜索 ID。

查询参数

edit
keep_alive

(可选，时间值) 搜索及其结果在集群上存储的周期。默认为搜索的EQL搜索API请求中设置的keep_alive值。

如果指定，此参数为搜索设置一个新的 keep_alive 周期，从执行异步 EQL 搜索 API 请求开始。这个新的周期会覆盖 EQL 搜索 API 请求中指定的周期。

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

wait_for_completion_timeout

(可选, 时间值) 等待请求完成的时间限制。默认为无超时，意味着请求会等待完整的搜索结果。

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

如果请求在此期间未完成，响应将返回一个is_partial值为true且没有搜索结果。

响应体

edit

异步EQL搜索API返回与EQL搜索API相同的响应体。 请参阅EQL搜索API的响应体参数。

获取异步EQL状态API

edit

返回异步EQL搜索或 存储的同步EQL搜索的当前状态， 而不返回结果。这是一个比 获取异步EQL搜索API更轻量级的API， 因为它不返回搜索结果，只报告状态。

如果启用了Elasticsearch安全功能，则对获取异步EQL状态API的访问权限仅限于monitoring_user角色。

GET /_eql/search/status/FkpMRkJGS1gzVDRlM3g4ZzMyRGlLbkEaTXlJZHdNT09TU2VTZVBoNDM3cFZMUToxMDM=

请求

edit

GET /_eql/search/status/

路径参数

edit
<search_id>

(必需, 字符串) 搜索的标识符。

在 EQL 搜索 API 的响应中提供了一个搜索 ID，用于 异步搜索。如果请求的 keep_on_completion 参数为 true，也会提供一个搜索 ID。

响应体

edit
id
(字符串) 搜索的标识符。
is_running
(布尔值) 如果true，搜索请求仍在执行中。 如果false，搜索已完成。
is_partial
(布尔值) 如果true，则响应不包含完整的搜索结果。 这可能是因为搜索仍在运行 (is_running 状态为 false)，或者因为它已经完成 (is_running 状态为 true) 并且由于失败或超时导致结果不完整。
start_time_in_millis
(长整型) 对于正在运行的搜索，显示eql搜索开始的时间戳，自Unix纪元以来的毫秒数。
expiration_time_in_millis
(长整型) 显示eql搜索将过期的时间戳，自Unix纪元以来的毫秒数。当达到这个时间时，搜索及其结果将被删除，即使搜索仍在进行中。
completion_status
(整数) 对于已完成的搜索，显示已完成搜索的HTTP状态码。

示例

edit
GET /_eql/search/status/FmNJRUZ1YWZCU3dHY1BIOUhaenVSRkEaaXFlZ3h4c1RTWFNocDdnY2FSaERnUTozNDE=?keep_alive=5d

如果搜索仍在进行中，状态响应具有以下形式：

{
  "id" : "FmNJRUZ1YWZCU3dHY1BIOUhaenVSRkEaaXFlZ3h4c1RTWFNocDdnY2FSaERnUTozNDE=",
  "is_running" : true,
  "is_partial" : true,
  "start_time_in_millis" : 1611690235000,
  "expiration_time_in_millis" : 1611690295000

}

如果搜索已完成，状态响应中将不包含start_time_in_millis，但会包含一个额外的completion_status字段，该字段显示已完成EQL搜索的状态码：

{
  "id" : "FmNJRUZ1YWZCU3dHY1BIOUhaenVSRkEaaXFlZ3h4c1RTWFNocDdnY2FSaERnUTozNDE=",
  "is_running" : false,
  "is_partial" : false,
  "expiration_time_in_millis" : 1611690295000,
  "completion_status" : 200 
}

表示 eql 搜索已成功完成
« Enrich APIs ES|QL APIs »