« Snapshot lifecycle management APIs Synonyms APIs »
Elastic Docs ›Elasticsearch Guide ›REST APIs

SQL API

edit

SQL API

edit

Elasticsearch 的 SQL API 允许您在 Elasticsearch 索引和数据流上运行 SQL 查询。 有关 Elasticsearch 的 SQL 功能和相关教程的概述，请参阅 SQL。

清除 SQL 游标 API

edit

清除一个SQL搜索游标。

POST _sql/close
{
  "cursor": "sDXF1ZXJ5QW5kRmV0Y2gBAAAAAAAAAAEWYUpOYklQMHhRUEtld3RsNnFtYU1hQQ==:BAFmBGRhdGUBZgVsaWtlcwFzB21lc3NhZ2UBZgR1c2Vy9f///w8="
}

请求

edit

POST _sql/close

限制

edit

请参阅SQL限制。

请求体

edit
cursor
(必需，字符串) 要清除的游标。

删除异步 SQL 搜索 API

edit

删除一个异步SQL搜索或一个存储的同步SQL搜索。如果搜索仍在运行，API将取消它。

DELETE _sql/async/delete/FkpMRkJGS1gzVDRlM3g4ZzMyRGlLbkEaTXlJZHdNT09TU2VTZVBoNDM3cFZMUToxMDM=

请求

edit

DELETE _sql/async/delete/

先决条件

edit

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

    • 具有cancel_task 集群权限的用户
    • 最初提交搜索的用户

限制

edit

请参阅SQL限制。

路径参数

edit
<search_id>
（必需，字符串）搜索的标识符。

获取异步SQL搜索API

edit

返回 异步 SQL 搜索 或 存储的同步 SQL 搜索 的结果。

GET _sql/async/FmdMX2pIang3UWhLRU5QS0lqdlppYncaMUpYQ05oSkpTc3kwZ21EdC1tbFJXQToxOTI=?format=json

请求

edit

GET _sql/async/

先决条件

edit
  • 如果启用了Elasticsearch的安全功能，只有最初提交SQL搜索的用户才能使用此API检索搜索结果。

限制

edit

请参阅SQL限制。

路径参数

edit
<search_id>
（必需，字符串）搜索的标识符。

查询参数

edit
delimiter
(可选，字符串) CSV结果的分隔符。默认为 ,。该API仅支持CSV响应的此参数。
format
(必需，字符串) 响应的格式。您必须使用此参数或 Accept HTTP 头指定格式。如果两者都指定，API 将使用此参数。有关有效值，请参阅 响应数据格式。
keep_alive
(可选，时间值) 搜索及其结果的保留期限。默认为原始SQL搜索的keep_alive周期。
wait_for_completion_timeout
(可选, 时间值) 等待完整结果的时间段。 默认为无超时，意味着请求会等待完整的搜索结果。

响应体

edit

get async SQL search API 返回的响应体与 SQL search API相同。

获取异步SQL搜索状态API

edit

返回异步SQL搜索或存储的同步SQL搜索的当前状态。

GET _sql/async/status/FmdMX2pIang3UWhLRU5QS0lqdlppYncaMUpYQ05oSkpTc3kwZ21EdC1tbFJXQToxOTI=?format=json

请求

edit

GET _sql/async/status/

先决条件

edit
  • 如果启用了Elasticsearch安全功能，您必须拥有monitor 集群权限才能使用此API。

限制

edit

请参阅SQL限制。

路径参数

edit
<search_id>
（必需，字符串）搜索的标识符。

响应体

edit
id
(字符串) 搜索的标识符。
is_running
(布尔值) 如果 true，搜索仍在进行中。如果 false，搜索已完成。
is_partial
(布尔值) 如果 true，响应中不包含完整的搜索结果。如果 is_partial 为 true 且 is_running 为 true，则搜索仍在进行中。 如果 is_partial 为 true 但 is_running 为 false，则结果由于失败或超时而部分返回。
start_time_in_millis
(整数) 时间戳，自Unix纪元以来的毫秒数，表示搜索开始的时间。API仅对正在运行的搜索返回此属性。
expiration_time_in_millis
(整数) 时间戳，自Unix纪元以来的毫秒数，Elasticsearch将删除搜索及其结果，即使搜索仍在进行中。
completion_status
(整数) 搜索的HTTP状态码。API仅在搜索完成时返回此属性。

SQL 搜索 API

edit

返回SQL搜索的结果。

POST _sql?format=txt
{
  "query": "SELECT * FROM library ORDER BY page_count DESC LIMIT 5"
}

请求

edit

GET _sql

POST _sql

先决条件

edit
  • 如果启用了Elasticsearch安全功能，您必须对您搜索的数据流、索引或别名具有read 索引权限。

限制

edit

请参阅SQL限制。

查询参数

edit
delimiter
(可选，字符串) CSV结果的分隔符。默认为,。该API仅支持CSV响应的此参数。
format

（可选，字符串）响应的格式。有关有效值，请参阅 响应数据格式。

您还可以使用Accept HTTP头指定格式。如果您同时指定此参数和Accept HTTP头，此参数优先。

请求体

edit
allow_partial_search_results
(可选，布尔值) 如果为true，则在存在分片请求超时或分片失败时返回部分结果。如果为false，则在无部分结果的情况下返回错误。默认为false。
catalog

(可选，字符串) 查询的默认目录（集群）。如果未指定，查询仅在本地集群中的数据上执行。

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

columnar
(可选，布尔值) 如果为true，则以列格式返回结果。默认为 false。该API仅支持CBOR、JSON、SMILE和YAML响应的此参数。请参阅列式结果。
cursor
(可选，字符串) 游标 用于检索一组分页结果。如果您指定一个 cursor，API 仅使用 columnar 和 time_zone 请求体参数。它会忽略其他请求体参数。
fetch_size
(可选，整数) 响应中返回的最大行数。默认为 1000。
field_multi_value_leniency
(可选，布尔值) 如果为false，API 会对包含 数组值的字段返回错误。如果为true，API 会从数组中返回第一个值，但不保证结果的一致性。默认为 false。
filter
(可选, 对象) 查询DSL 用于过滤SQL搜索的文档。请参阅 使用Elasticsearch查询DSL进行过滤。
index_include_frozen
(可选，布尔值) 如果 true，搜索可以在冻结索引上运行。默认为 false。
keep_alive
(可选, 时间值) 对于一个 异步 或 保存的同步搜索 的保留期。默认为 5d (五天)。
keep_on_completion
(可选，布尔值) 如果为true，Elasticsearch会在您同时指定wait_for_completion_timeout参数时存储同步搜索。如果为false，Elasticsearch只会存储在wait_for_completion_timeout之前未完成的异步搜索。默认为false。
page_timeout
(可选, 时间值) 滚动游标的最小保留期。在此时间之后，分页请求可能会失败，因为滚动游标不再可用。后续的滚动请求会通过滚动请求中的page_timeout时长延长滚动游标的生命周期。默认为45s（45秒）。
params
(可选, 数组) query 中参数的值。语法请参见 将参数传递给查询。
query
(必需, 对象) 要运行的SQL查询。有关语法，请参见SQL语言。
request_timeout
(可选，时间值) 请求失败前的超时时间。默认为90s（90秒）。
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())"
time_zone
(可选，字符串) 用于搜索的ISO-8601时区ID。多个 SQL日期/时间函数使用此时区。默认为 Z（UTC）。
wait_for_completion_timeout

(可选, 时间值) 等待完整结果的时间段。 默认为无超时，意味着请求会等待完整的搜索结果。 如果搜索在此时间段内未完成，搜索将变为 异步。

要保存同步搜索，您必须指定此参数和keep_on_completion参数。

响应体

edit

SQL 搜索 API 支持 多种响应格式。大多数响应格式使用表格布局。JSON 响应包含以下属性：

id
(字符串) 搜索的标识符。此值仅针对 异步 和 保存的同步搜索 返回。对于 CSV、TSV 和 TXT 响应，此值在 Async-ID HTTP 头中返回。
is_running
(布尔值) 如果 true，表示搜索仍在进行中。如果 false，表示搜索已完成。此值仅针对 异步 和 保存的同步搜索 返回。对于 CSV、TSV 和 TXT 响应，此值在 Async-partial HTTP 头中返回。
is_partial

(布尔值) 如果 true，响应不包含完整的搜索结果。如果 is_partial 是 true 且 is_running 是 true，搜索仍在进行中。 如果 is_partial 是 true 但 is_running 是 false，结果由于失败或超时而部分不完整。

此值仅针对 异步 和 保存的同步搜索 返回。对于 CSV、TSV 和 TXT 响应，此值在 Async-partial HTTP 头中返回。

rows
(数组数组) 搜索结果的值。
columns

(对象数组) 搜索结果的列标题。每个对象代表一列。

Properties of columns objects
name
(字符串) 列的名称。
type
(字符串) 列的数据类型。
cursor
(字符串) 用于下一组分页结果的游标。对于CSV、TSV和TXT响应，此值在Cursor HTTP头中返回。

SQL 翻译 API

edit

将一个SQL搜索转换为一个包含查询DSL的搜索API请求。请参阅SQL Translate API。

POST _sql/translate
{
  "query": "SELECT * FROM library ORDER BY page_count DESC",
  "fetch_size": 10
}

请求

edit

GET _sql/translate

POST _sql/translate

先决条件

edit
  • 如果启用了Elasticsearch安全功能，您必须对您搜索的数据流、索引或别名具有read 索引权限。

限制

edit

请参阅SQL限制。

请求体

edit

SQL translate API 接受与 SQL search API 相同的请求体参数，但不包括 cursor。

响应体

edit

SQL translate API 返回与 search API 相同的响应体。

« Snapshot lifecycle management APIs Synonyms APIs »