搜索 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)
GET /my-index-000001/_search
先决条件编辑
-
如果启用了 Elasticsearch 安全功能，则您必须对目标数据流、索引或别名具有
read索引权限。有关跨集群搜索，请参阅配置跨集群搜索的权限。要搜索别名的时间点 (PIT)，您必须对别名的数据流或索引具有
read索引权限。
路径参数编辑
-
<target> - （可选，字符串）要搜索的数据流、索引和别名的逗号分隔列表。支持通配符 (
*)。要搜索所有数据流和索引，请省略此参数或使用*或_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 - （可选，字符串）要作为每个结果的字段的文档值表示形式返回的字段的逗号分隔列表。请参阅文档值字段。
-
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个分片。 - 请求指向一个或多个只读索引。
- 查询的主排序指向索引字段。
- 请求指向超过
tag::search-preference[] preference:: （可选，字符串）用于搜索的节点和分片。默认情况下，Elasticsearch 使用自适应副本选择从符合条件的节点和分片中进行选择，并考虑分配感知。
+ .preference 的有效值
详情
-
_only_local - 仅在本地节点上的分片上运行搜索。
-
_local - 如果可能，在本地节点上的分片上运行搜索。否则，使用默认方法选择分片。
-
_only_nodes:<node-id>,<node-id> - 仅在指定的节点 ID 上运行搜索。如果在多个选定节点上存在合适的碎片，则使用默认方法使用这些节点上的碎片。如果没有一个指定的节点可用，则使用默认方法从任何可用节点中选择碎片。
-
_prefer_nodes:<node-id>,<node-id> - 如果可能，在指定的节点 ID 上运行搜索。否则，使用默认方法选择分片。
-
_shards:<shard>,<shard> - 仅在指定的分片上运行搜索。您可以将此值与其他
preference值组合使用。但是，_shards值必须放在首位。例如：_shards:2,3|_local。 -
<custom-string> - 任何不以
_开头的字符串。如果集群状态和选定的分片没有改变，则使用相同<custom-string>值的搜索将以相同的顺序路由到相同的分片。
end::search-preference[]
-
q -
（可选，字符串）使用 Lucene 查询字符串语法的查询。
您可以使用
q参数运行查询参数搜索。查询参数搜索不支持完整的 Elasticsearch 查询 DSL，但便于测试。q参数会覆盖请求正文中的query参数。如果同时指定了这两个参数，则不会返回与query请求正文参数匹配的文档。 -
request_cache - （可选，布尔值）如果为
true，则对size为0的请求启用搜索结果缓存。请参阅分片请求缓存设置。默认为索引级别设置。 -
rest_total_hits_as_int - （可选，布尔值）指示在 REST 搜索响应中是将 hits.total 呈现为整数还是对象。默认为
false。 -
routing - （可选，字符串）用于将操作路由到特定分片的自定义值。
-
size -
（可选，整数）定义要返回的匹配项数量。默认为
10。默认情况下，您不能使用
from和size参数对超过 10,000 个结果进行分页。要对更多结果进行分页，请使用search_after参数。
-
_source -
（可选）指示针对匹配文档返回哪些 源字段。这些字段在搜索响应的
hits._source属性中返回。默认为true。请参阅 源过滤。_source的有效值-
true - （布尔值）返回整个文档源。
-
false - （布尔值）不返回文档源。
-
<string> - （字符串）要返回的源字段的逗号分隔列表。支持通配符 (
*) 模式。
-
-
_source_excludes -
（可选，字符串）要从响应中排除的 源字段 的逗号分隔列表。
您还可以使用此参数从
_source_includes查询参数中指定的子集中排除字段。如果
_source参数为false，则忽略此参数。 -
_source_includes -
（可选，字符串）要包含在响应中的 源字段 的逗号分隔列表。
如果指定了此参数，则仅返回这些源字段。您可以使用
_source_excludes查询参数从此子集中排除字段。如果
_source参数为false，则忽略此参数。 -
stats - （可选，字符串）用于日志记录和统计目的的请求的特定
标记。 -
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属性中返回与这些模式匹配的字段名称的值。您可以将数组中的项指定为字符串或对象。请参阅 文档值字段。
docvalue_fields对象的属性-
field - （必需，字符串）通配符模式。请求返回与其名称与此模式匹配的字段的文档值。
-
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对象的属性-
<index>: <boost-value> -
（必需，浮点数）
<index>是索引或索引别名的名称。支持通配符 (*) 表达式。<boost-value>是分数相乘的因子。大于
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 -
（可选，浮点数）文档被视为匹配所需的最小相似度。计算出的相似度值与使用的原始
similarity相关。不是文档得分。然后根据similarity对匹配的文档进行评分，并应用提供的boost。similarity参数是直接向量相似度计算。-
l2_norm：也称为欧几里得距离，将包括向量在以query_vector为原点、半径为similarity的dims维超球面内的文档。 -
cosine、dot_product和max_inner_product：仅返回余弦相似度或点积至少为提供的similarity的向量。
在此处阅读更多信息：knn 相似度搜索
-
-
-
min_score - （可选，浮点数）匹配文档的最小
_score。_score较低的文档不包含在搜索结果中。
-
retriever - [预览] 此功能处于技术预览阶段，可能会在未来版本中更改或删除。Elastic 将努力解决任何问题，但技术预览版中的功能不受官方 GA 功能的支持 SLA 的约束。 （可选，检索器对象）定义顶级检索器以指定一组所需的顶级文档，而不是标准查询或 knn 搜索。
-
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())"
-
-
-
seq_no_primary_term - （可选，布尔值）如果为
true，则返回每个匹配项最后一次修改的序列号和主项。请参阅 乐观并发控制。 -
size -
（可选，整数）要返回的匹配数。需要是非负数，默认为
10。默认情况下，您不能使用
from和size参数对超过 10,000 个结果进行分页。要对更多结果进行分页，请使用search_after参数。
-
_source -
（可选）指示针对匹配文档返回哪些 源字段。这些字段在搜索响应的
hits._source属性中返回。默认为true。请参阅 源过滤。_source的有效值-
true - （布尔值）返回整个文档源。
-
false - （布尔值）不返回文档源。
-
<通配符模式> - （字符串或字符串数组）包含要返回的源字段的通配符 (
*) 模式或模式数组。 -
<对象> -
（对象）包含要包含或排除的源字段列表的对象。
<对象>的属性-
excludes -
（字符串或字符串数组）包含要从响应中排除的源字段的通配符 (
*) 模式或模式数组。您还可以使用此属性从
includes属性中指定的子集中排除字段。 -
includes -
（字符串或字符串数组）包含要返回的源字段的通配符 (
*) 模式或模式数组。如果指定了此属性，则仅返回这些源字段。您可以使用
excludes属性从此子集中排除字段。
-
-
-
stats - （可选，字符串数组）要与搜索关联的统计信息组。每个组都为其关联的搜索维护一个统计信息聚合。您可以使用索引统计信息 API 检索这些统计信息。
-
terminate_after -
（可选，整数）为每个分片收集的最大文档数。如果查询达到此限制，Elasticsearch 将提前终止查询。Elasticsearch 在排序之前收集文档。
谨慎使用。Elasticsearch 将此参数应用于处理请求的每个分片。如果可能，请让 Elasticsearch 自动执行提前终止。避免为针对跨多个数据层级的后备索引的数据流的请求指定此参数。
默认为
0，这不会提前终止查询执行。 -
timeout - （可选，时间单位）指定等待每个分片响应的时间段。如果在超时到期之前未收到响应，则请求失败并返回错误。默认为无超时。
响应正文编辑
-
_scroll_id -
（字符串）搜索及其搜索上下文的标识符。
您可以将此滚动 ID 与滚动 API 一起使用，以检索该请求的下一批搜索结果。请参阅滚动搜索结果。
仅当在请求中指定了
scroll查询参数时，才会返回此参数。
-
took -
（整数）Elasticsearch 执行请求所花费的毫秒数。
此值的计算方法是：测量协调节点收到请求到协调节点准备好发送响应之间经过的时间。
花费的时间包括
- 协调节点和数据节点之间的通信时间
- 请求在
search线程池中排队等待执行所花费的时间 - 实际执行时间
花费的时间不包括
- 将请求发送到 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",
body={"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
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"
}
}
},
...
]
}
}