- Elasticsearch 指南其他版本
- 8.17 中的新功能
- Elasticsearch 基础
- 快速入门
- 设置 Elasticsearch
- 升级 Elasticsearch
- 索引模块
- 映射
- 文本分析
- 索引模板
- 数据流
- 摄取管道
- 别名
- 搜索您的数据
- 重新排名
- 查询 DSL
- 聚合
- 地理空间分析
- 连接器
- EQL
- ES|QL
- SQL
- 脚本
- 数据管理
- 自动缩放
- 监视集群
- 汇总或转换数据
- 设置高可用性集群
- 快照和还原
- 保护 Elastic Stack 的安全
- Watcher
- 命令行工具
- elasticsearch-certgen
- elasticsearch-certutil
- elasticsearch-create-enrollment-token
- elasticsearch-croneval
- elasticsearch-keystore
- elasticsearch-node
- elasticsearch-reconfigure-node
- elasticsearch-reset-password
- elasticsearch-saml-metadata
- elasticsearch-service-tokens
- elasticsearch-setup-passwords
- elasticsearch-shard
- elasticsearch-syskeygen
- elasticsearch-users
- 优化
- 故障排除
- 修复常见的集群问题
- 诊断未分配的分片
- 向系统中添加丢失的层
- 允许 Elasticsearch 在系统中分配数据
- 允许 Elasticsearch 分配索引
- 索引将索引分配过滤器与数据层节点角色混合,以在数据层之间移动
- 没有足够的节点来分配所有分片副本
- 单个节点上索引的分片总数已超过
- 每个节点的分片总数已达到
- 故障排除损坏
- 修复磁盘空间不足的数据节点
- 修复磁盘空间不足的主节点
- 修复磁盘空间不足的其他角色节点
- 启动索引生命周期管理
- 启动快照生命周期管理
- 从快照恢复
- 故障排除损坏的存储库
- 解决重复的快照策略失败问题
- 故障排除不稳定的集群
- 故障排除发现
- 故障排除监控
- 故障排除转换
- 故障排除 Watcher
- 故障排除搜索
- 故障排除分片容量健康问题
- 故障排除不平衡的集群
- 捕获诊断信息
- REST API
- API 约定
- 通用选项
- REST API 兼容性
- 自动缩放 API
- 行为分析 API
- 紧凑和对齐文本 (CAT) API
- 集群 API
- 跨集群复制 API
- 连接器 API
- 数据流 API
- 文档 API
- 丰富 API
- EQL API
- ES|QL API
- 功能 API
- Fleet API
- 图表探索 API
- 索引 API
- 别名是否存在
- 别名
- 分析
- 分析索引磁盘使用量
- 清除缓存
- 克隆索引
- 关闭索引
- 创建索引
- 创建或更新别名
- 创建或更新组件模板
- 创建或更新索引模板
- 创建或更新索引模板(旧版)
- 删除组件模板
- 删除悬挂索引
- 删除别名
- 删除索引
- 删除索引模板
- 删除索引模板(旧版)
- 存在
- 字段使用情况统计信息
- 刷新
- 强制合并
- 获取别名
- 获取组件模板
- 获取字段映射
- 获取索引
- 获取索引设置
- 获取索引模板
- 获取索引模板(旧版)
- 获取映射
- 导入悬挂索引
- 索引恢复
- 索引段
- 索引分片存储
- 索引统计信息
- 索引模板是否存在(旧版)
- 列出悬挂索引
- 打开索引
- 刷新
- 解析索引
- 解析集群
- 翻转
- 收缩索引
- 模拟索引
- 模拟模板
- 拆分索引
- 解冻索引
- 更新索引设置
- 更新映射
- 索引生命周期管理 API
- 推理 API
- 信息 API
- 摄取 API
- 许可 API
- Logstash API
- 机器学习 API
- 机器学习异常检测 API
- 机器学习数据帧分析 API
- 机器学习训练模型 API
- 迁移 API
- 节点生命周期 API
- 查询规则 API
- 重新加载搜索分析器 API
- 存储库计量 API
- 汇总 API
- 根 API
- 脚本 API
- 搜索 API
- 搜索应用程序 API
- 可搜索快照 API
- 安全 API
- 身份验证
- 更改密码
- 清除缓存
- 清除角色缓存
- 清除权限缓存
- 清除 API 密钥缓存
- 清除服务帐户令牌缓存
- 创建 API 密钥
- 创建或更新应用程序权限
- 创建或更新角色映射
- 创建或更新角色
- 批量创建或更新角色 API
- 批量删除角色 API
- 创建或更新用户
- 创建服务帐户令牌
- 委托 PKI 身份验证
- 删除应用程序权限
- 删除角色映射
- 删除角色
- 删除服务帐户令牌
- 删除用户
- 禁用用户
- 启用用户
- 注册 Kibana
- 注册节点
- 获取 API 密钥信息
- 获取应用程序权限
- 获取内置权限
- 获取角色映射
- 获取角色
- 查询角色
- 获取服务帐户
- 获取服务帐户凭据
- 获取安全设置
- 获取令牌
- 获取用户权限
- 获取用户
- 授予 API 密钥
- 具有权限
- 使 API 密钥失效
- 使令牌失效
- OpenID Connect 准备身份验证
- OpenID Connect 身份验证
- OpenID Connect 注销
- 查询 API 密钥信息
- 查询用户
- 更新 API 密钥
- 更新安全设置
- 批量更新 API 密钥
- SAML 准备身份验证
- SAML 身份验证
- SAML 注销
- SAML 失效
- SAML 完成注销
- SAML 服务提供商元数据
- SSL 证书
- 激活用户配置文件
- 禁用用户配置文件
- 启用用户配置文件
- 获取用户配置文件
- 建议用户配置文件
- 更新用户配置文件数据
- 具有用户配置文件权限
- 创建跨集群 API 密钥
- 更新跨集群 API 密钥
- 快照和还原 API
- 快照生命周期管理 API
- SQL API
- 同义词 API
- 文本结构 API
- 转换 API
- 使用情况 API
- Watcher API
- 定义
- 迁移指南
- 发行说明
- Elasticsearch 版本 8.17.0
- Elasticsearch 版本 8.16.1
- Elasticsearch 版本 8.16.0
- Elasticsearch 版本 8.15.5
- Elasticsearch 版本 8.15.4
- Elasticsearch 版本 8.15.3
- Elasticsearch 版本 8.15.2
- Elasticsearch 版本 8.15.1
- Elasticsearch 版本 8.15.0
- Elasticsearch 版本 8.14.3
- Elasticsearch 版本 8.14.2
- Elasticsearch 版本 8.14.1
- Elasticsearch 版本 8.14.0
- Elasticsearch 版本 8.13.4
- Elasticsearch 版本 8.13.3
- Elasticsearch 版本 8.13.2
- Elasticsearch 版本 8.13.1
- Elasticsearch 版本 8.13.0
- Elasticsearch 版本 8.12.2
- Elasticsearch 版本 8.12.1
- Elasticsearch 版本 8.12.0
- Elasticsearch 版本 8.11.4
- Elasticsearch 版本 8.11.3
- Elasticsearch 版本 8.11.2
- Elasticsearch 版本 8.11.1
- Elasticsearch 版本 8.11.0
- Elasticsearch 版本 8.10.4
- Elasticsearch 版本 8.10.3
- Elasticsearch 版本 8.10.2
- Elasticsearch 版本 8.10.1
- Elasticsearch 版本 8.10.0
- Elasticsearch 版本 8.9.2
- Elasticsearch 版本 8.9.1
- Elasticsearch 版本 8.9.0
- Elasticsearch 版本 8.8.2
- Elasticsearch 版本 8.8.1
- Elasticsearch 版本 8.8.0
- Elasticsearch 版本 8.7.1
- Elasticsearch 版本 8.7.0
- Elasticsearch 版本 8.6.2
- Elasticsearch 版本 8.6.1
- Elasticsearch 版本 8.6.0
- Elasticsearch 版本 8.5.3
- Elasticsearch 版本 8.5.2
- Elasticsearch 版本 8.5.1
- Elasticsearch 版本 8.5.0
- Elasticsearch 版本 8.4.3
- Elasticsearch 版本 8.4.2
- Elasticsearch 版本 8.4.1
- Elasticsearch 版本 8.4.0
- Elasticsearch 版本 8.3.3
- Elasticsearch 版本 8.3.2
- Elasticsearch 版本 8.3.1
- Elasticsearch 版本 8.3.0
- Elasticsearch 版本 8.2.3
- Elasticsearch 版本 8.2.2
- Elasticsearch 版本 8.2.1
- Elasticsearch 版本 8.2.0
- Elasticsearch 版本 8.1.3
- Elasticsearch 版本 8.1.2
- Elasticsearch 版本 8.1.1
- Elasticsearch 版本 8.1.0
- Elasticsearch 版本 8.0.1
- Elasticsearch 版本 8.0.0
- Elasticsearch 版本 8.0.0-rc2
- Elasticsearch 版本 8.0.0-rc1
- Elasticsearch 版本 8.0.0-beta1
- Elasticsearch 版本 8.0.0-alpha2
- Elasticsearch 版本 8.0.0-alpha1
- 依赖项和版本
ES|QL REST API
编辑ES|QL REST API
编辑概述
编辑ES|QL 查询 API 接受 query
参数中的 ES|QL 查询字符串,运行它并返回结果。例如
resp = client.esql.query( format="txt", query="FROM library | KEEP author, name, page_count, release_date | SORT page_count DESC | LIMIT 5", ) print(resp)
const response = await client.esql.query({ format: "txt", query: "FROM library | KEEP author, name, page_count, release_date | SORT page_count DESC | LIMIT 5", }); console.log(response);
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 控制台(强烈推荐),请在创建查询时利用三引号 """
。这不仅会自动转义查询字符串中的双引号("
),还支持多行请求
resp = client.esql.query( format="txt", query="\n FROM library\n | KEEP author, name, page_count, release_date\n | SORT page_count DESC\n | LIMIT 5\n ", ) print(resp)
const response = await client.esql.query({ format: "txt", query: "\n FROM library\n | KEEP author, name, page_count, release_date\n | SORT page_count DESC\n | LIMIT 5\n ", }); console.log(response);
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 不是标记语言) 人类可读格式 |
二进制 |
||
|
|
|
|
|
Smile 类似于 CBOR 的二进制数据格式 |
|
|
实验性。 Apache Arrow 数据框,IPC 流式格式 |
csv
格式接受格式化 URL 查询属性 delimiter
,该属性指示用于分隔 CSV 值的字符。它默认为逗号 ( ,
),并且不能采用以下任何值:双引号 ( "
)、回车符 ( \r
) 和换行符 ( \n
)。制表符(\t
)也不能使用。请改用 tsv
格式。
使用 Elasticsearch Query DSL 进行过滤
编辑在 filter
参数中指定 Query DSL 查询,以过滤 ES|QL 查询运行的文档集。
resp = client.esql.query( format="txt", query="\n FROM library\n | KEEP author, name, page_count, release_date\n | SORT page_count DESC\n | LIMIT 5\n ", filter={ "range": { "page_count": { "gte": 100, "lte": 200 } } }, ) print(resp)
const response = await client.esql.query({ format: "txt", query: "\n FROM library\n | KEEP author, name, page_count, release_date\n | SORT page_count DESC\n | LIMIT 5\n ", filter: { range: { page_count: { gte: 100, lte: 200, }, }, }, }); console.log(response);
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 可以以列式方式返回结果,其中一行表示结果中某一列的所有值。
resp = client.esql.query( format="json", query="\n FROM library\n | KEEP author, name, page_count, release_date\n | SORT page_count DESC\n | LIMIT 5\n ", columnar=True, ) print(resp)
const response = await client.esql.query({ format: "json", query: "\n FROM library\n | KEEP author, name, page_count, release_date\n | SORT page_count DESC\n | LIMIT 5\n ", columnar: true, }); console.log(response);
POST /_query?format=json { "query": """ FROM library | KEEP author, name, page_count, release_date | SORT page_count DESC | LIMIT 5 """, "columnar": true }
返回结果为
{ "took": 28, "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
格式(不区分大小写)的语言标记。
例如,要以法语返回月份名称
resp = client.esql.query( locale="fr-FR", query="\n ROW birth_date_string = \"2023-01-15T00:00:00.000Z\"\n | EVAL birth_date = date_parse(birth_date_string)\n | EVAL month_of_birth = DATE_FORMAT(\"MMMM\",birth_date)\n | LIMIT 5\n ", ) print(resp)
const response = await client.esql.query({ locale: "fr-FR", query: '\n ROW birth_date_string = "2023-01-15T00:00:00.000Z"\n | EVAL birth_date = date_parse(birth_date_string)\n | EVAL month_of_birth = DATE_FORMAT("MMMM",birth_date)\n | LIMIT 5\n ', }); console.log(response);
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 """ }
将参数传递给查询
编辑值(例如用于条件的值)可以通过将值集成到查询字符串本身来“内联”传递给查询
resp = client.esql.query( query="\n FROM library\n | EVAL year = DATE_EXTRACT(\"year\", release_date)\n | WHERE page_count > 300 AND author == \"Frank Herbert\"\n | STATS count = COUNT(*) by year\n | WHERE count > 0\n | LIMIT 5\n ", ) print(resp)
const response = await client.esql.query({ query: '\n FROM library\n | EVAL year = DATE_EXTRACT("year", release_date)\n | WHERE page_count > 300 AND author == "Frank Herbert"\n | STATS count = COUNT(*) by year\n | WHERE count > 0\n | LIMIT 5\n ', }); console.log(response);
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 """ }
为了避免任何黑客攻击或代码注入尝试,请在单独的参数列表中提取值。在查询字符串中使用问号占位符 ( ?
) 表示每个参数
resp = client.esql.query( query="\n FROM library\n | EVAL year = DATE_EXTRACT(\"year\", release_date)\n | WHERE page_count > ? AND author == ?\n | STATS count = COUNT(*) by year\n | WHERE count > ?\n | LIMIT 5\n ", params=[ 300, "Frank Herbert", 0 ], ) print(resp)
const response = await client.esql.query({ query: '\n FROM library\n | EVAL year = DATE_EXTRACT("year", release_date)\n | WHERE page_count > ? AND author == ?\n | STATS count = COUNT(*) by year\n | WHERE count > ?\n | LIMIT 5\n ', params: [300, "Frank Herbert", 0], }); console.log(response);
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] }
参数可以是命名参数或位置参数。
命名参数使用问号占位符 ( ?
) 后跟字符串。
resp = client.esql.query( query="\n FROM library\n | EVAL year = DATE_EXTRACT(\"year\", release_date)\n | WHERE page_count > ?page_count AND author == ?author\n | STATS count = COUNT(*) by year\n | WHERE count > ?count\n | LIMIT 5\n ", params=[ { "page_count": 300 }, { "author": "Frank Herbert" }, { "count": 0 } ], ) print(resp)
const response = await client.esql.query({ query: '\n FROM library\n | EVAL year = DATE_EXTRACT("year", release_date)\n | WHERE page_count > ?page_count AND author == ?author\n | STATS count = COUNT(*) by year\n | WHERE count > ?count\n | LIMIT 5\n ', params: [ { page_count: 300, }, { author: "Frank Herbert", }, { count: 0, }, ], }); console.log(response);
POST /_query { "query": """ FROM library | EVAL year = DATE_EXTRACT("year", release_date) | WHERE page_count > ?page_count AND author == ?author | STATS count = COUNT(*) by year | WHERE count > ?count | LIMIT 5 """, "params": [{"page_count" : 300}, {"author" : "Frank Herbert"}, {"count" : 0}] }
位置参数使用问号占位符 ( ?
) 后跟整数。
resp = client.esql.query( query="\n FROM library\n | EVAL year = DATE_EXTRACT(\"year\", release_date)\n | WHERE page_count > ?1 AND author == ?2\n | STATS count = COUNT(*) by year\n | WHERE count > ?3\n | LIMIT 5\n ", params=[ 300, "Frank Herbert", 0 ], ) print(resp)
const response = await client.esql.query({ query: '\n FROM library\n | EVAL year = DATE_EXTRACT("year", release_date)\n | WHERE page_count > ?1 AND author == ?2\n | STATS count = COUNT(*) by year\n | WHERE count > ?3\n | LIMIT 5\n ', params: [300, "Frank Herbert", 0], }); console.log(response);
POST /_query { "query": """ FROM library | EVAL year = DATE_EXTRACT("year", release_date) | WHERE page_count > ?1 AND author == ?2 | STATS count = COUNT(*) by year | WHERE count > ?3 | LIMIT 5 """, "params": [300, "Frank Herbert", 0] }
运行异步 ES|QL 查询
编辑ES|QL 异步查询 API 允许您异步执行查询请求、监视其进度并在结果可用时检索结果。
执行 ES|QL 查询通常非常快,但是跨大型数据集或冻结数据的查询可能需要一些时间。为了避免长时间等待,请运行异步 ES|QL 查询。
由异步查询 API 发起的查询可能会返回结果,也可能不返回结果。wait_for_completion_timeout
属性确定等待结果的时间。如果此时结果不可用,则会返回一个 查询 ID,该 ID 稍后可用于检索结果。例如
resp = client.esql.async_query( body={ "query": "\n FROM library\n | EVAL year = DATE_TRUNC(1 YEARS, release_date)\n | STATS MAX(page_count) BY year\n | SORT year\n | LIMIT 5\n ", "wait_for_completion_timeout": "2s" }, ) print(resp)
const response = await client.esql.asyncQuery({ body: { query: "\n FROM library\n | EVAL year = DATE_TRUNC(1 YEARS, release_date)\n | STATS MAX(page_count) BY year\n | SORT year\n | LIMIT 5\n ", wait_for_completion_timeout: "2s", }, }); console.log(response);
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
- 值为 true 的
is_running
值,表示查询正在进行中
查询继续在后台运行,而不会阻塞其他请求。
{ "id": "FmNJRUZ1YWZCU3dHY1BIOUhaenVSRkEaaXFlZ3h4c1RTWFNocDdnY2FSaERnUTozNDE=", "is_running": true }
要检查异步查询的进度,请使用 ES|QL 异步查询获取 API 以及查询 ID。在 wait_for_completion_timeout
参数中指定您希望等待完整结果的时间。
resp = client.esql.async_query_get( id="FmNJRUZ1YWZCU3dHY1BIOUhaenVSRkEaaXFlZ3h4c1RTWFNocDdnY2FSaERnUTozNDE=", wait_for_completion_timeout="30s", body=None, ) print(resp)
response = client.esql.async_query_get( id: 'FmNJRUZ1YWZCU3dHY1BIOUhaenVSRkEaaXFlZ3h4c1RTWFNocDdnY2FSaERnUTozNDE=', wait_for_completion_timeout: '30s' ) puts response
const response = await client.esql.asyncQueryGet({ id: "FmNJRUZ1YWZCU3dHY1BIOUhaenVSRkEaaXFlZ3h4c1RTWFNocDdnY2FSaERnUTozNDE=", wait_for_completion_timeout: "30s", body: null, }); console.log(response);
GET /_query/async/FmNJRUZ1YWZCU3dHY1BIOUhaenVSRkEaaXFlZ3h4c1RTWFNocDdnY2FSaERnUTozNDE=?wait_for_completion_timeout=30s
如果响应的 is_running
值为 false
,则表示查询已完成,并且返回结果以及查询的 took
时间。
{ "is_running": false, "took": 48, "columns": ... }
在 keep_alive
期间结束之前,使用 ES|QL 异步查询删除 API 删除异步查询。如果查询仍在运行,Elasticsearch 将取消它。
DELETE /_query/async/FmdMX2pIang3UWhLRU5QS0lqdlppYncaMUpYQ05oSkpTc3kwZ21EdC1tbFJXQToxOTI=