ES|QL

class elasticsearch.client.EsqlClient

To use this client, access client.esql from an Elasticsearch client. For example:

from elasticsearch import Elasticsearch

# Create the client instance
client = Elasticsearch(...)
# Use the esql client
client.esql.<method>(...)
async_query(*, query=None, allow_partial_results=None, columnar=None, delimiter=None, drop_null_columns=None, error_trace=None, filter=None, filter_path=None, format=None, human=None, include_ccs_metadata=None, keep_alive=None, keep_on_completion=None, locale=None, params=None, pretty=None, profile=None, tables=None, wait_for_completion_timeout=None, body=None)

运行异步 ES|QL 查询。 异步执行 ES|QL (Elasticsearch 查询语言) 查询，监控其进度，并在结果可用时获取数据。

该 API 接受与同步查询 API 相同的参数和请求体，以及额外的异步相关属性。

https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-esql-async-query

Parameters:

  • query (str | None) – ES|QL 查询 API 接受查询参数中的 ES|QL 查询字符串， 执行并返回结果。

  • allow_partial_results (bool | None) – 如果为 true，当存在分片失败时仍会返回部分结果， 查询可以继续在其他集群和分片上执行。如果为 false，任何失败都会导致查询终止。 可通过设置 esql.query.allow_partial_results 集群参数为 false 来覆盖默认行为。

  • columnar (bool | None) – 默认情况下，ES|QL 以行形式返回结果。例如 FROM 操作 将每个文档作为一行返回。对于 JSON、YAML、CBOR 和 smile 格式， ES|QL 可以按列形式返回结果，其中一行代表结果中某列的所有值。

  • delimiter (str | None) – 在 CSV 行内分隔值的字符。仅对 CSV 格式有效。

  • drop_null_columns (bool | None) – 指示是否从结果的 columns 和 values 部分 移除完全为 null 的列。如果为 true，响应将包含名为 all_columns 的额外部分， 其中列出所有列名。

  • filter (Mapping[str, Any] | None) – 在 filter 参数中指定 Query DSL 查询，用于过滤 ES|QL 查询运行的文档集。

  • format (str | Literal['arrow', 'cbor', 'csv', 'json', 'smile', 'tsv', 'txt', 'yaml'] | None) – Accept 头的简写版本，例如 json 或 yaml。

  • include_ccs_metadata (bool | None) – 当设置为 true 且执行跨集群查询时， 响应将包含额外的 _clusters 对象，其中包含参与搜索的集群信息 以及分片计数等数据。

  • keep_alive (str | Literal[-1] | ~typing.Literal[0] | None) – 查询及其结果在集群中的存储期限。默认期限为五天。 当此期限到期时，即使查询仍在进行，查询及其结果也会被删除。 如果 keep_on_completion 参数为 false，无论此值如何，Elasticsearch 仅存储 未在 wait_for_completion_timeout 参数设置期限内完成的异步查询。

  • keep_on_completion (bool | None) – 指示是否将查询及其结果存储在集群中。 如果为 false，仅当请求未在 wait_for_completion_timeout 参数设置的期限内完成时， 查询及其结果才会存储在集群中。

  • locale (str | None)

  • params (Sequence[None | bool | float | int | str] | None) – 为避免黑客攻击或代码注入，将值提取到单独的参数列表中。 在查询字符串中对每个参数使用问号占位符 (?)。

  • profile (bool | None) – 如果提供且为 true，响应将包含额外的 profile 对象， 其中包含查询执行信息。此信息用于人工调试，其格式可能随时变更， 但可以提供查询各部分性能的洞察。

  • tables (Mapping[str, Mapping[str, Mapping[str, Any]]] | None) – 用于 LOOKUP 操作的表。顶级键是表名，下一级键是列名。

  • wait_for_completion_timeout (str | Literal[-1] | ~typing.Literal[0] | None) – 等待请求完成的期限。 默认情况下，请求等待查询结果 1 秒。如果查询在此期限内完成，则返回结果。 否则返回一个查询 ID，后续可用于获取结果。

  • error_trace (bool | None)

  • filter_path (str | Sequence[str] | None)

  • human (bool | None)

  • pretty (bool | None)

  • body (Dict[str, Any] | None)

Return type:

ObjectApiResponse[Any]

async_query_delete(*, id, error_trace=None, filter_path=None, human=None, pretty=None)

删除异步 ES|QL 查询。 如果查询仍在运行，则会被取消。 否则将删除存储的结果。

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

  • 提交原始查询请求的认证用户
  • 具有 cancel_task 集群权限的用户

https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-esql-async-query-delete

Parameters:

  • id (str) – 查询的唯一标识符。对于未在指定时间内完成的查询， ES|QL 异步查询 API 响应中会提供查询 ID。当请求提交时 将 keep_on_completion 参数设置为 true 时也会提供查询 ID。

  • error_trace (bool | None)

  • filter_path (str | Sequence[str] | None)

  • human (bool | None)

  • pretty (bool | None)

Return type:

ObjectApiResponse[Any]

async_query_get(*, id, drop_null_columns=None, error_trace=None, filter_path=None, format=None, human=None, keep_alive=None, pretty=None, wait_for_completion_timeout=None)

获取异步 ES|QL 查询结果。 获取 ES|QL 异步查询的当前状态和可用结果或存储的结果。 如果启用了 Elasticsearch 安全功能，只有首次提交 ES|QL 查询的用户可以使用此 API 检索结果。

https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-esql-async-query-get

Parameters:

  • id (str) – 查询的唯一标识符。对于未在指定时间内完成的查询， ES|QL 异步查询 API 响应中会提供查询 ID。当请求提交时 将 keep_on_completion 参数设置为 true 时也会提供查询 ID。

  • drop_null_columns (bool | None) – 指示是否从结果的 columns 和 values 部分 移除完全为 null 的列。如果为 true，响应将包含名为 all_columns 的额外部分， 其中列出所有列名。

  • format (str | Literal['arrow', 'cbor', 'csv', 'json', 'smile', 'tsv', 'txt', 'yaml'] | None) – Accept 头的简写版本，例如 json 或 yaml。

  • keep_alive (str | Literal[-1] | ~typing.Literal[0] | None) – 查询及其结果在集群中的存储期限。 当此期限到期时，即使查询仍在进行，查询及其结果也会被删除。

  • wait_for_completion_timeout (str | Literal[-1] | ~typing.Literal[0] | None) – 等待请求完成的期限。 默认情况下，请求等待完整查询结果。如果请求在此参数指定的期限内完成， 则返回完整查询结果。否则响应返回 is_running 值为 true 且无结果。

  • error_trace (bool | None)

  • filter_path (str | Sequence[str] | None)

  • human (bool | None)

  • pretty (bool | None)

Return type:

ObjectApiResponse[Any]

async_query_stop(*, id, drop_null_columns=None, error_trace=None, filter_path=None, human=None, pretty=None)

停止异步 ES|QL 查询。

此 API 中断查询执行并返回当前已获取的结果。 如果启用了 Elasticsearch 安全功能，只有首次提交 ES|QL 查询的用户可以停止它。

https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-esql-async-query-stop

Parameters:

  • id (str) – 查询的唯一标识符。对于未在指定时间内完成的查询， ES|QL 异步查询 API 响应中会提供查询 ID。当请求提交时 将 keep_on_completion 参数设置为 true 时也会提供查询 ID。

  • drop_null_columns (bool | None) – 指示是否从结果的 columns 和 values 部分 移除完全为 null 的列。如果为 true，响应将包含名为 all_columns 的额外部分， 其中列出所有列名。

  • error_trace (bool | None)

  • filter_path (str | Sequence[str] | None)

  • human (bool | None)

  • pretty (bool | None)

Return type:

ObjectApiResponse[Any]

get_query(*, id, error_trace=None, filter_path=None, human=None, pretty=None)

获取特定运行中的 ES|QL 查询信息。 返回包含运行中 ES|QL 查询扩展信息的对象。

Parameters:
Return type:

ObjectApiResponse[Any]

list_queries(*, error_trace=None, filter_path=None, human=None, pretty=None)

获取正在运行的ES|QL查询信息。 返回一个包含运行中ES|QL查询ID及其他信息的对象。

Parameters:
Return type:

ObjectApiResponse[Any]

query(*, query=None, allow_partial_results=None, columnar=None, delimiter=None, drop_null_columns=None, error_trace=None, filter=None, filter_path=None, format=None, human=None, include_ccs_metadata=None, locale=None, params=None, pretty=None, profile=None, tables=None, body=None)

执行ES|QL查询。 获取ES|QL（Elasticsearch查询语言）查询的搜索结果。

https://www.elastic.co/docs/explore-analyze/query-filter/languages/esql-rest

Parameters:

  • query (str | None) – ES|QL查询API接受查询参数中的ES|QL查询字符串，执行并返回结果。

  • allow_partial_results (bool | None) – 若为`true`，当存在分片失败时仍会返回部分结果，查询可继续在其他集群和分片上执行。 若为`false`，任何失败都会导致查询终止。可通过设置`esql.query.allow_partial_results` 集群参数为`false`来覆盖默认行为。

  • columnar (bool | None) – 默认情况下ES|QL按行返回结果。对于JSON、YAML、CBOR和smile格式， ES|QL可以按列方式返回结果，其中一行代表结果中某列的所有值。

  • delimiter (str | None) – 在CSV行内值之间使用的分隔字符。仅对CSV格式有效。

  • drop_null_columns (bool | None) – 是否应从结果的`columns`和`values`部分移除完全为`null`的列？ 默认为`false`。若为`true`，响应将包含名为`all_columns`的额外部分列出所有列名。

  • filter (Mapping[str, Any] | None) – 在filter参数中指定Query DSL查询以过滤ES|QL查询运行的文档集。

  • format (str | Literal['arrow', 'cbor', 'csv', 'json', 'smile', 'tsv', 'txt', 'yaml'] | None) – Accept头的简写版本，如json、yaml。

  • include_ccs_metadata (bool | None) – 当设置为`true`且执行跨集群查询时，响应将包含额外的`_clusters`对象， 其中包含参与搜索的集群信息及分片计数等元数据。

  • locale (str | None)

  • params (Sequence[None | bool | float | int | str] | None) – 为防止黑客攻击或代码注入，将值提取到单独的参数列表中。在查询字符串中对每个参数使用问号占位符(?)。

  • profile (bool | None) – 若提供且为`true`，响应将包含额外的`profile`对象，其中包含查询执行信息。 该信息用于人工调试，其格式可能随时变更，但可帮助了解查询各部分的性能表现。

  • tables (Mapping[str, Mapping[str, Mapping[str, Any]]] | None) – 与LOOKUP操作配合使用的表。顶层键是表名，下一级键是列名。

  • error_trace (bool | None)

  • filter_path (str | Sequence[str] | None)

  • human (bool | None)

  • pretty (bool | None)

  • body (Dict[str, Any] | None)

Return type:

ObjectApiResponse[Any]