ES|QL REST API
编辑ES|QL REST API编辑
概述编辑
在 ES|QL 查询 API 中，您可以将 ES|QL 查询字符串放在 query 参数中，运行它并返回结果。例如
POST /_query?format=txt
{
"query": "FROM library | KEEP author, name, page_count, release_date | SORT page_count DESC | LIMIT 5"
}
返回
author | name | page_count | release_date -----------------+--------------------+---------------+------------------------ Peter F. Hamilton|Pandora's Star |768 |2004-03-02T00:00:00.000Z Vernor Vinge |A Fire Upon the Deep|613 |1992-06-01T00:00:00.000Z Frank Herbert |Dune |604 |1965-06-01T00:00:00.000Z Alastair Reynolds|Revelation Space |585 |2000-03-15T00:00:00.000Z James S.A. Corey |Leviathan Wakes |561 |2011-06-02T00:00:00.000Z
Kibana 控制台编辑
如果您使用的是 Kibana 控制台（强烈推荐），请在创建查询时使用三引号 """。这不仅会自动转义查询字符串中的双引号 (")，还会支持多行请求
POST /_query?format=txt
{
"query": """
FROM library
| KEEP author, name, page_count, release_date
| SORT page_count DESC
| LIMIT 5
"""
}
响应格式编辑
ES|QL 可以以以下人类可读和二进制格式返回数据。您可以通过在 URL 中指定 format 参数或设置 Accept 或 Content-Type HTTP 标头来设置格式。
URL 参数优先于 HTTP 标头。如果两者都没有指定，则响应将以与请求相同的格式返回。
|
HTTP 标头 |
描述 |
人类可读 |
||
|
|
|
|
|
JSON（JavaScript 对象表示法）人类可读格式 |
|
|
|
|
|
类似 CLI 的表示 |
|
|
YAML（YAML Ain’t Markup Language）人类可读格式 |
二进制 |
||
|
|
|
|
|
Smile 与 CBOR 类似的二进制数据格式 |
在 csv 格式中，接受一个格式化 URL 查询属性 delimiter，它指示应使用哪个字符来分隔 CSV 值。它默认为逗号 (,)，并且不能采用以下任何值：双引号 (")、回车 (\r) 和换行 (\n)。制表符 (\t) 也不能使用。请改用 tsv 格式。
使用 Elasticsearch 查询 DSL 进行过滤编辑
在 filter 参数中指定一个查询 DSL 查询，以过滤 ES|QL 查询运行的文档集。
POST /_query?format=txt
{
"query": """
FROM library
| KEEP author, name, page_count, release_date
| SORT page_count DESC
| LIMIT 5
""",
"filter": {
"range": {
"page_count": {
"gte": 100,
"lte": 200
}
}
}
}
返回
author | name | page_count | release_date ---------------+------------------------------------+---------------+------------------------ Douglas Adams |The Hitchhiker's Guide to the Galaxy|180 |1979-10-12T00:00:00.000Z
列式结果编辑
默认情况下，ES|QL 以行形式返回结果。例如，FROM 将每个单独的文档作为一行返回。对于 json、yaml、cbor 和 smile 格式，ES|QL 可以以列式方式返回结果，其中一行表示结果中某个特定列的所有值。
POST /_query?format=json
{
"query": """
FROM library
| KEEP author, name, page_count, release_date
| SORT page_count DESC
| LIMIT 5
""",
"columnar": true
}
返回
{
"columns": [
{"name": "author", "type": "text"},
{"name": "name", "type": "text"},
{"name": "page_count", "type": "integer"},
{"name": "release_date", "type": "date"}
],
"values": [
["Peter F. Hamilton", "Vernor Vinge", "Frank Herbert", "Alastair Reynolds", "James S.A. Corey"],
["Pandora's Star", "A Fire Upon the Deep", "Dune", "Revelation Space", "Leviathan Wakes"],
[768, 613, 604, 585, 561],
["2004-03-02T00:00:00.000Z", "1992-06-01T00:00:00.000Z", "1965-06-01T00:00:00.000Z", "2000-03-15T00:00:00.000Z", "2011-06-02T00:00:00.000Z"]
]
}
返回本地化结果编辑
在请求正文中使用 locale 参数以返回根据区域设置约定格式化的结果（尤其是日期）。如果未指定 locale，则默认为 en-US（英语）。请参阅 JDK 支持的区域设置。
语法：locale 参数接受以（不区分大小写）格式 xy 和 xy-XY 表示的语言标记。
例如，要以法语返回月份名称
POST /_query
{
"locale": "fr-FR",
"query": """
ROW birth_date_string = "2023-01-15T00:00:00.000Z"
| EVAL birth_date = date_parse(birth_date_string)
| EVAL month_of_birth = DATE_FORMAT("MMMM",birth_date)
| LIMIT 5
"""
}
将参数传递给查询编辑
值（例如，用于条件）可以通过“内联”方式传递给查询，方法是将值集成到查询字符串本身中
POST /_query
{
"query": """
FROM library
| EVAL year = DATE_EXTRACT("year", release_date)
| WHERE page_count > 300 AND author == "Frank Herbert"
| STATS count = COUNT(*) by year
| WHERE count > 0
| LIMIT 5
"""
}
为了避免任何黑客攻击或代码注入尝试，请将值提取到一个单独的参数列表中。在查询字符串中，对每个参数使用问号占位符 (?)
POST /_query
{
"query": """
FROM library
| EVAL year = DATE_EXTRACT("year", release_date)
| WHERE page_count > ? AND author == ?
| STATS count = COUNT(*) by year
| WHERE count > ?
| LIMIT 5
""",
"params": [300, "Frank Herbert", 0]
}
运行异步 ES|QL 查询编辑
ES|QL 异步查询 API 允许您异步执行查询请求，监控其进度，并在结果可用时检索结果。
执行 ES|QL 查询通常非常快，但是跨大型数据集或冻结数据的查询可能需要一些时间。为了避免长时间等待，请运行异步 ES|QL 查询。
由异步查询 API 启动的查询可能会返回结果，也可能不会返回结果。 wait_for_completion_timeout 属性决定等待结果的时间。如果在此时间内结果不可用，则会返回一个 查询 ID，该 ID 稍后可用于检索结果。例如
POST /_query/async
{
"query": """
FROM library
| EVAL year = DATE_TRUNC(1 YEARS, release_date)
| STATS MAX(page_count) BY year
| SORT year
| LIMIT 5
""",
"wait_for_completion_timeout": "2s"
}
如果在给定的超时时间段（在本例中为 2 秒）内结果不可用，则不会返回任何结果，而是返回一个包含以下内容的响应：
- 查询 ID
- 一个
is_running值为 *true*，表示查询正在进行
查询将在后台继续运行，不会阻塞其他请求。
{
"id": "FmNJRUZ1YWZCU3dHY1BIOUhaenVSRkEaaXFlZ3h4c1RTWFNocDdnY2FSaERnUTozNDE=",
"is_running": true
}
要检查异步查询的进度，请使用 ES|QL 异步查询获取 API 以及查询 ID。在 wait_for_completion_timeout 参数中指定您希望等待完整结果的时间。
GET /_query/async/FmNJRUZ1YWZCU3dHY1BIOUhaenVSRkEaaXFlZ3h4c1RTWFNocDdnY2FSaERnUTozNDE=?wait_for_completion_timeout=30s
如果响应的 is_running 值为 false，则表示查询已完成，并且会返回结果。
{
"is_running": false,
"columns": ...
}
使用 ES|QL 异步查询删除 API 在 keep_alive 时间段结束之前删除异步查询。如果查询仍在运行，Elasticsearch 会取消它。
DELETE /_query/async/FmdMX2pIang3UWhLRU5QS0lqdlppYncaMUpYQ05oSkpTc3kwZ21EdC1tbFJXQToxOTI=