« 获取异步 SQL 搜索状态 API SQL 转换 API »
Elastic 文档 ›Elasticsearch 指南 [8.17] ›REST API ›SQL API

SQL 搜索 API

编辑

SQL 搜索 API

编辑

返回 SQL 搜索的结果。

resp = client.sql.query(
    format="txt",
    query="SELECT * FROM library ORDER BY page_count DESC LIMIT 5",
)
print(resp)
const response = await client.sql.query({
  format: "txt",
  query: "SELECT * FROM library ORDER BY page_count DESC LIMIT 5",
});
console.log(response);
POST _sql?format=txt
{
  "query": "SELECT * FROM library ORDER BY page_count DESC LIMIT 5"
}

请求

编辑

GET _sql

POST _sql

前提条件

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

限制

编辑

请参阅 SQL 限制。

查询参数

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

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

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

请求体

编辑
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
(可选，对象) 用于筛选 SQL 搜索文档的 查询 DSL。请参阅使用 Elasticsearch 查询 DSL 进行筛选。
index_include_frozen
(可选，布尔值) 如果为 true，则搜索可以在冻结索引上运行。默认为 false。
keep_alive
(可选，时间值) 异步或保存的同步搜索的保留期。默认为 5d (五天)。
keep_on_completion
(可选，布尔值) 如果为 true，如果您还指定了 wait_for_completion_timeout 参数，则 Elasticsearch 会存储同步搜索。如果为 false，则 Elasticsearch 仅存储在 wait_for_completion_timeout 之前未完成的异步搜索。默认为 false。
page_timeout
(可选，时间值) 滚动游标的最短保留期。在此时间段之后，分页请求可能会失败，因为滚动游标不再可用。后续滚动请求会根据滚动请求中的 page_timeout 持续时间延长滚动游标的生存期。默认为 45s（45 秒）。
params
(可选，数组) query 中参数的值。有关语法，请参阅将参数传递给查询。
query
(必需，对象) 要运行的 SQL 查询。有关语法，请参阅SQL 语言。
request_timeout
(可选，时间值) 请求失败前的超时时间。默认为 90s（90 秒）。
runtime_mappings

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

runtime_mappings 对象的属性
<字段名称>

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

<字段名称> 的属性
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 参数。

响应体

编辑

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

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

columns 对象的属性
name
(字符串) 列的名称。
type
(字符串) 列的数据类型。
cursor
(字符串) 下一组分页结果的游标。对于 CSV、TSV 和 TXT 响应，此值在 Cursor HTTP 标头中返回。
« 获取异步 SQL 搜索状态 API SQL 转换 API »