搜索 API
编辑搜索 API
编辑返回与请求中定义的查询匹配的搜索命中结果。
resp = client.search(
index="my-index-000001",
)
print(resp)
response = client.search( index: 'my-index-000001' ) puts response
res, err := es.Search(
es.Search.WithIndex("my-index-000001"),
es.Search.WithPretty(),
)
fmt.Println(res, err)
const response = await client.search({
index: "my-index-000001",
});
console.log(response);
GET /my-index-000001/_search
先决条件
编辑-
如果启用了 Elasticsearch 安全功能，则您必须拥有目标数据流、索引或别名的
read索引权限。对于跨集群搜索，请参阅 配置跨集群搜索的权限。要搜索别名的 时间点 (PIT)，您必须拥有该别名的数据流或索引的
read索引权限。
路径参数
编辑-
<目标> - (可选，字符串) 要搜索的数据流、索引和别名的逗号分隔列表。支持通配符 (
*)。要搜索所有数据流和索引，请省略此参数或使用*或_all。
查询参数
编辑此 API 的几个选项可以使用查询参数或请求体参数指定。如果同时指定了这两个参数，则仅使用查询参数。
-
allow_no_indices -
(可选，布尔值) 如果为
false，则当任何通配符表达式、索引别名或_all值仅以缺失或关闭的索引为目标时，请求会返回错误。即使请求以其他打开的索引为目标，也会应用此行为。例如，如果一个索引以foo开头，但没有索引以bar开头，则以foo*,bar*为目标的请求会返回错误。默认为
true。
-
allow_partial_search_results -
(可选，布尔值) 如果为
true，则当存在分片请求超时或 分片失败时，会返回部分结果。如果为false，则会返回错误，且不返回部分结果。默认为true。要覆盖此字段的默认值，请将
search.default_allow_partial_results集群设置设置为false。 -
analyzer -
(可选，字符串) 用于查询字符串的分析器。
仅当指定了
q查询字符串参数时，才能使用此参数。 -
analyze_wildcard -
(可选，布尔值) 如果为
true，则会分析通配符和前缀查询。默认为false。仅当指定了
q查询字符串参数时，才能使用此参数。 -
batched_reduce_size - (可选，整数) 协调节点上应一次减少的分片结果数。如果请求中潜在的分片数可能很大，则应使用此值作为保护机制，以减少每个搜索请求的内存开销。默认为
512。
-
ccs_minimize_roundtrips - (可选，布尔值) 如果为
true，则在执行跨集群搜索 (CCS) 请求时，协调节点和远程集群之间的网络往返次数会最小化。请参阅 跨集群搜索如何处理网络延迟。默认为true。 -
default_operator -
(可选，字符串) 查询字符串查询的默认运算符：AND 或 OR。默认为
OR。仅当指定了
q查询字符串参数时，才能使用此参数。 -
df -
(可选，字符串) 在查询字符串中未给定字段前缀时用作默认值的字段。
仅当指定了
q查询字符串参数时，才能使用此参数。 -
docvalue_fields - (可选，字符串) 要作为每个命中的字段的 docvalue 表示形式返回的字段的逗号分隔列表。请参阅 Doc value 字段。
-
expand_wildcards -
(可选，字符串) 通配符模式可以匹配的索引类型。如果请求可以以数据流为目标，则此参数确定通配符表达式是否匹配隐藏的数据流。支持逗号分隔值，例如
open,hidden。有效值为-
all - 匹配任何数据流或索引，包括隐藏的数据流和索引。
-
open - 匹配打开的非隐藏索引。也匹配任何非隐藏的数据流。
-
closed - 匹配关闭的非隐藏索引。也匹配任何非隐藏的数据流。数据流无法关闭。
-
hidden - 匹配隐藏的数据流和隐藏的索引。必须与
open、closed或两者结合使用。 -
none - 不接受通配符模式。
默认为
open。 -
-
explain - (可选，布尔值) 如果为
true，则返回有关评分计算的详细信息作为命中的一部分。默认为false。
-
from -
(可选，整数) 起始文档偏移量。必须为非负数，默认为
0。默认情况下，您不能使用
from和size参数翻阅超过 10,000 个命中结果。要翻阅更多命中结果，请使用search_after参数。 -
ignore_throttled -
(可选，布尔值) 如果为
true，则在冻结时，会忽略具体、展开或别名的索引。默认为true。[7.16.0] 在 7.16.0 中已弃用。
-
include_named_queries_score - (可选，布尔值) 如果为
true，则包含任何已命名查询的评分贡献。此功能会在搜索响应中的每个命中结果上重新运行每个已命名查询。通常，这会为请求增加少量开销。但是，在大量命中结果上使用计算开销大的已命名查询可能会增加显著的开销。默认为false。 -
ignore_unavailable - (可选，布尔值) 如果为
false，则当请求以缺失或关闭的索引为目标时，会返回错误。默认为false。 -
lenient -
(可选，布尔值) 如果为
true，则会忽略查询字符串中基于格式的查询失败（例如，向数字字段提供文本）。默认为false。仅当指定了
q查询字符串参数时，才能使用此参数。 -
max_concurrent_shard_requests - (可选，整数) 定义此搜索并发执行时每个节点并发分片请求的数量。应使用此值来限制搜索对集群的影响，以便限制并发分片请求的数量。默认为
5。 -
pre_filter_shard_size -
(可选，整数) 定义一个阈值，如果搜索请求扩展到的分片数超过该阈值，则会强制执行预过滤往返以基于查询重写来预过滤搜索分片。如果例如，一个分片无法根据其重写方法匹配任何文档（即，如果日期过滤器是强制匹配的，但分片边界和查询是不相交的），则此过滤往返可以显著限制分片数。如果未指定，则在满足以下任何条件时执行预过滤阶段
- 请求以超过
128个分片为目标。 - 请求以一个或多个只读索引为目标。
- 查询的主排序以索引字段为目标。
- 请求以超过
-
preference -
(可选，字符串) 用于搜索的节点和分片。默认情况下，Elasticsearch 使用 自适应副本选择从符合条件的节点和分片中进行选择，并考虑 分配感知。
preference的有效值-
_only_local - 仅在本地节点上的分片上运行搜索。
-
_local - 如果可能，在本地节点上的分片上运行搜索。如果不可能，则使用默认方法选择分片。
-
_only_nodes:<节点 ID>,<节点 ID> - 仅在指定的节点 ID 上运行搜索。如果多个选定节点上存在合适的分片，则使用这些节点上的分片，并采用默认方法。如果指定的节点都不可用，则使用默认方法从任何可用节点选择分片。
-
_prefer_nodes:<节点 ID>,<节点 ID> - 如果可能，在指定的节点 ID 上运行搜索。如果不可能，则使用默认方法选择分片。
-
_shards:<分片>,<分片> - 仅在指定的分片上运行搜索。可以将此值与其他
preference值组合使用。但是，_shards值必须位于第一位。例如：_shards:2,3|_local。 -
<自定义字符串> - 任何不以
_开头的字符串。如果集群状态和选定分片没有更改，则使用相同的<自定义字符串>值的搜索会按相同的顺序路由到相同的分片。
-
-
q -
(可选，字符串) Lucene 查询字符串语法中的查询。
您可以使用
q参数来运行查询参数搜索。查询参数搜索不支持完整的 Elasticsearch 查询 DSL，但对于测试非常方便。q参数会覆盖请求体中的query参数。如果同时指定了这两个参数，则不会返回与query请求体参数匹配的文档。 -
request_cache - (可选，布尔值) 如果为
true，则为size为0的请求启用搜索结果的缓存。请参阅 分片请求缓存设置。默认为索引级设置。 -
rest_total_hits_as_int - (可选，布尔值) 指示 hits.total 应在 rest 搜索响应中呈现为整数还是对象。默认为
false。 -
routing - （可选，字符串）用于将操作路由到特定分片的自定义值。
-
size -
（可选，整数）定义要返回的命中数。默认为
10。默认情况下，您不能使用
from和size参数翻阅超过 10,000 个命中结果。要翻阅更多命中结果，请使用search_after参数。
-
_source -
（可选）指示为匹配文档返回哪些源字段。这些字段在搜索响应的
hits._source属性中返回。默认为true。请参阅源过滤。_source的有效值-
true - （布尔值）返回整个文档源。
-
false - （布尔值）不返回文档源。
-
<字符串> - （字符串）要返回的源字段的逗号分隔列表。支持通配符 (
*) 模式。
-
-
_source_excludes -
（可选，字符串）要从响应中排除的源字段的逗号分隔列表。
您还可以使用此参数从
_source_includes查询参数中指定的子集中排除字段。如果
_source参数为false，则忽略此参数。 -
_source_includes -
（可选，字符串）要包含在响应中的源字段的逗号分隔列表。
如果指定了此参数，则仅返回这些源字段。您可以使用
_source_excludes查询参数从此子集中排除字段。如果
_source参数为false，则忽略此参数。 -
stats - （可选，字符串）用于记录和统计目的的请求的特定
tag。 -
stored_fields -
（可选，字符串）要作为命中一部分返回的存储字段的逗号分隔列表。如果未指定任何字段，则响应中不包含任何存储字段。请参阅存储字段。
如果指定了此字段，则
_source参数默认为false。您可以传递_source: true以在搜索响应中同时返回源字段和存储字段。 -
suggest_field - （可选，字符串）指定用于建议的字段。
-
suggest_mode -
（可选，字符串）指定建议模式。默认为
missing。可用选项-
always -
missing -
popular
只有在指定了
suggest_field和suggest_text查询字符串参数时，才能使用此参数。 -
-
suggest_size -
（可选，整数）要返回的建议的数量。
只有在指定了
suggest_field和suggest_text查询字符串参数时，才能使用此参数。 -
suggest_text -
（可选，字符串）应返回建议的源文本。
只有在指定了
suggest_field查询字符串参数时，才能使用此参数。 -
terminate_after -
（可选，整数）每个分片要收集的最大文档数。如果查询达到此限制，则 Elasticsearch 会提前终止查询。Elasticsearch 在排序之前收集文档。
谨慎使用。Elasticsearch 将此参数应用于处理请求的每个分片。如果可能，让 Elasticsearch 自动执行提前终止。对于以跨多个数据层支持索引的数据流为目标的请求，请避免指定此参数。
默认为
0，这不会提前终止查询执行。 -
timeout - （可选，时间单位）指定等待每个分片响应的期限。如果在超时到期之前未收到任何响应，则请求失败并返回错误。默认为无超时。
-
track_scores - （可选，布尔值）如果为
true，则计算并返回文档得分，即使得分不用于排序。默认为false。 -
track_total_hits -
（可选，整数或布尔值）精确计算与查询匹配的命中数。默认为
10000。如果为
true，则会返回准确的命中数，但会牺牲一些性能。如果为false，则响应不包括与查询匹配的命中总数。 -
typed_keys - （可选，布尔值）如果为
true，则在响应中聚合和建议器名称会加上各自类型的前缀。默认为false。 -
version - （可选，布尔值）如果为
true，则返回文档版本作为命中的一部分。默认为false。
请求正文
编辑-
docvalue_fields -
（可选，字符串和对象的数组）字段模式的数组。请求返回与响应的
hits.fields属性中的这些模式匹配的字段名称的值。您可以在数组中将项指定为字符串或对象。请参阅Doc 值字段。
docvalue_fields对象的属性-
field - （必需，字符串）通配符模式。请求返回与此模式匹配的字段名称的 doc 值。
-
format -
（可选，字符串）返回 doc 值的格式。
对于日期字段，您可以指定日期
format。对于数字字段，您可以指定DecimalFormat 模式。对于其他字段数据类型，不支持此参数。
-
-
fields -
（可选，字符串和对象的数组）字段模式的数组。请求返回与响应的
hits.fields属性中的这些模式匹配的字段名称的值。您可以在数组中将项指定为字符串或对象。请参阅
fields选项。fields对象的属性-
field - （必需，字符串）要返回的字段。支持通配符 (
*)。 -
format -
（可选，字符串）日期和地理空间字段的格式。其他字段数据类型不支持此参数。
date和date_nanos字段接受日期格式。geo_point和geo_shape字段接受-
geojson(默认) - GeoJSON
-
wkt - 已知文本
-
mvt(<spec>) -
二进制Mapbox 矢量瓦片。API 将瓦片作为 base64 编码的字符串返回。
<spec>的格式为<zoom>/<x>/<y>，带有两个可选后缀：@<extent>和/或:<buffer>。例如，2/0/1或2/0/1@4096:5。mvt参数-
<zoom> - （必需，整数）瓦片的缩放级别。接受
0-29。 -
<x> - （必需，整数）瓦片的 X 坐标。
-
<y> - （必需，整数）瓦片的 Y 坐标。
-
<extent> - （可选，整数）瓦片一侧的像素大小。矢量瓦片是正方形，边长相等。默认为
4096。 -
<buffer> - （可选，整数）瓦片外部裁剪缓冲区的像素大小。这允许渲染器避免几何图形从超出瓦片范围延伸而产生的轮廓伪影。默认为
5。
-
-
-
-
stored_fields -
（可选，字符串）要作为命中一部分返回的存储字段的逗号分隔列表。如果未指定任何字段，则响应中不包含任何存储字段。请参阅存储字段。
如果指定了此选项，则
_source参数默认为false。您可以传递_source: true以在搜索响应中同时返回源字段和存储字段。
-
explain - (可选，布尔值) 如果为
true，则返回有关评分计算的详细信息作为命中的一部分。默认为false。 -
from -
(可选，整数) 起始文档偏移量。必须为非负数，默认为
0。默认情况下，您不能使用
from和size参数翻阅超过 10,000 个命中结果。要翻阅更多命中结果，请使用search_after参数。 -
indices_boost -
（可选，对象数组）提升来自指定索引的文档的
_score。indices_boost对象的属性-
<索引>: <提升值> -
（必需，浮点数）
<索引>是索引或索引别名的名称。支持通配符 (*) 表达式。<提升值>是分数乘以的因子。大于
1.0的提升值会增加分数。介于0和1.0之间的提升值会降低分数。
-
-
knn -
（可选，对象或对象数组）定义要运行的kNN 查询。
knn对象的属性-
field - （必需，字符串）要搜索的向量字段的名称。必须是启用了索引的
dense_vector字段。 -
filter - （可选，查询 DSL 对象）用于过滤可以匹配的文档的查询。kNN 搜索将返回也与此过滤器匹配的前
k个文档。该值可以是单个查询或查询列表。如果未提供filter，则允许所有文档匹配。 -
k - （可选，整数）作为顶部命中最邻近的邻居的数量。此值必须小于或等于
num_candidates。默认为size。 -
num_candidates - （可选，整数）每个分片要考虑的最近邻候选者的数量。需要大于
k，或者如果省略k，则大于size，并且不能超过 10,000。Elasticsearch 从每个分片收集num_candidates个结果，然后将它们合并以找到前k个结果。增加num_candidates往往会提高最终k个结果的准确性。默认为Math.min(1.5 * k, 10_000)。 -
query_vector - （可选，浮点数数组）查询向量。必须具有与您要搜索的向量字段相同的维度数。必须是浮点数数组或十六进制编码的字节向量。
-
query_vector_builder - （可选，对象）一个配置对象，指示如何在执行请求之前构建 query_vector。您必须提供
query_vector_builder或query_vector，但不能同时提供两者。有关详细信息，请参阅 执行语义搜索。 -
similarity -
（可选，浮点数）文档被视为匹配所需的最小相似度。计算的相似度值与使用的原始
相似度有关。不是文档得分。然后根据相似度对匹配的文档进行评分，并应用提供的boost。similarity参数是直接向量相似度计算。-
l2_norm：也称为欧几里得距离，将包括向量在dims维超球面内的文档，该超球面以similarity为半径，以query_vector为原点。 -
cosine、dot_product和max_inner_product：仅返回余弦相似度或点积至少为提供的similarity的向量。
在此处阅读更多内容：kNN 相似度搜索
-
-
-
min_score - （可选，浮点数）匹配文档的最小
_score。搜索结果中不包括_score较低的文档。
-
retriever - [预览] 此功能处于技术预览阶段，可能会在未来的版本中更改或删除。Elastic 将努力修复任何问题，但技术预览中的功能不受官方 GA 功能的支持 SLA 的约束。 （可选，检索器对象）定义一个顶级检索器，以指定所需的一组顶部文档，而不是标准查询或 knn 搜索。
-
runtime_mappings -
（可选，对象对象）在搜索请求中定义一个或多个运行时字段。这些字段优先于具有相同名称的已映射字段。
runtime_mappings对象的属性-
<field-name> -
（必需，对象）运行时字段的配置。键是字段名称。
<field-name>的属性-
type -
（必需，字符串）字段类型，可以是以下任何一种
-
boolean -
composite -
date -
double -
geo_point -
ip -
keyword -
long -
lookup
-
-
script -
（可选，字符串）在查询时执行的 Painless 脚本。该脚本可以访问文档的整个上下文，包括原始的
_source和任何已映射的字段及其值。此脚本必须包含
emit以返回计算值。例如"script": "emit(doc['@timestamp'].value.dayOfWeekEnum.toString())"
-
-
-
seq_no_primary_term - （可选，布尔值）如果为
true，则返回每个命中的最后修改的序列号和主项。请参阅乐观并发控制。 -
size -
（可选，整数）要返回的命中数。需要为非负数，默认为
10。默认情况下，您不能使用
from和size参数翻阅超过 10,000 个命中结果。要翻阅更多命中结果，请使用search_after参数。
-
_source -
（可选）指示为匹配文档返回哪些源字段。这些字段在搜索响应的
hits._source属性中返回。默认为true。请参阅源过滤。_source的有效值-
true - （布尔值）返回整个文档源。
-
false - （布尔值）不返回文档源。
-
<wildcard_pattern> - （字符串或字符串数组）通配符 (
*) 模式或包含要返回的源字段的模式数组。 -
<object> -
（对象）包含要包含或排除的源字段列表的对象。
<object>的属性-
excludes -
（字符串或字符串数组）通配符 (
*) 模式或包含要从响应中排除的源字段的模式数组。您还可以使用此属性从
includes属性中指定的子集中排除字段。 -
includes -
（字符串或字符串数组）通配符 (
*) 模式或包含要返回的源字段的模式数组。如果指定此属性，则仅返回这些源字段。您可以使用
excludes属性从此子集中排除字段。
-
-
-
stats - （可选，字符串数组）与搜索关联的统计信息组。每个组都为其关联的搜索维护一个统计信息聚合。您可以使用 索引统计信息 API 检索这些统计信息。
-
terminate_after -
（可选，整数）每个分片要收集的最大文档数。如果查询达到此限制，则 Elasticsearch 会提前终止查询。Elasticsearch 在排序之前收集文档。
谨慎使用。Elasticsearch 将此参数应用于处理请求的每个分片。如果可能，让 Elasticsearch 自动执行提前终止。对于以跨多个数据层支持索引的数据流为目标的请求，请避免指定此参数。
默认为
0，这不会提前终止查询执行。 -
timeout - （可选，时间单位）指定等待每个分片响应的期限。如果在超时到期之前未收到任何响应，则请求失败并返回错误。默认为无超时。
响应主体
编辑-
_scroll_id -
（字符串）搜索及其搜索上下文的标识符。
您可以将此滚动 ID 与 滚动 API 一起使用，以检索请求的下一批搜索结果。请参阅滚动搜索结果。
仅当在请求中指定了
scroll查询参数时，才会返回此参数。
-
took -
（整数）Elasticsearch 执行请求所花费的毫秒数。
此值是通过测量协调节点上接收请求的时间与协调节点准备好发送响应的时间之间的时间间隔来计算的。
Took 时间包括
- 协调节点和数据节点之间的通信时间
- 请求在
search线程池 中花费的时间，排队等待执行 - 实际执行时间
Took 时间 不 包括
- 将请求发送到 Elasticsearch 所需的时间
- 序列化 JSON 响应所需的时间
- 将响应发送给客户端所需的时间
-
timed_out - （布尔值）如果为
true，则请求在完成之前超时；返回的结果可能是部分或为空的。
-
_shards -
（对象）包含用于请求的分片计数。
_shards的属性-
total - （整数）需要查询的分片总数，包括未分配的分片。
-
successful - （整数）成功执行请求的分片数。
-
skipped - （整数）跳过请求的分片数，因为轻量级检查帮助意识到此分片上不可能匹配任何文档。当搜索请求包含范围过滤器且分片仅具有超出该范围的值时，通常会发生这种情况。
-
failed - （整数）未能执行请求的分片数。请注意，未分配的分片既不被认为是成功的，也不被认为是失败的。因此，
failed+successful小于total表明某些分片未分配。
-
-
hits -
（对象）包含返回的文档和元数据。
hits的属性-
total -
（对象）有关匹配文档数量的元数据。
total的属性-
value - （整数）匹配文档的总数。
-
relation -
（字符串）指示
value参数中的匹配文档数是准确的还是下限。relation的值-
eq - 准确
-
gte - 下限
-
-
-
max_score -
（浮点数）返回的最高 文档
_score。对于不按
_score排序的请求，此值为null。
-
示例
编辑resp = client.search(
index="my-index-000001",
from_="40",
size="20",
query={
"term": {
"user.id": "kimchy"
}
},
)
print(resp)
response = client.search(
index: 'my-index-000001',
from: 40,
size: 20,
body: {
query: {
term: {
'user.id' => 'kimchy'
}
}
}
)
puts response
const response = await client.search({
index: "my-index-000001",
from: 40,
size: 20,
query: {
term: {
"user.id": "kimchy",
},
},
});
console.log(response);
GET /my-index-000001/_search?from=40&size=20
{
"query": {
"term": {
"user.id": "kimchy"
}
}
}
API 返回以下响应
{
"took": 5,
"timed_out": false,
"_shards": {
"total": 1,
"successful": 1,
"skipped": 0,
"failed": 0
},
"hits": {
"total": {
"value": 20,
"relation": "eq"
},
"max_score": 1.3862942,
"hits": [
{
"_index": "my-index-000001",
"_id": "0",
"_score": 1.3862942,
"_source": {
"@timestamp": "2099-11-15T14:12:12",
"http": {
"request": {
"method": "get"
},
"response": {
"status_code": 200,
"bytes": 1070000
},
"version": "1.1"
},
"source": {
"ip": "127.0.0.1"
},
"message": "GET /search HTTP/1.1 200 1070000",
"user": {
"id": "kimchy"
}
}
},
...
]
}
}