Elasticsearch 指南 [8.17] | Search APIs

Search API

返回与请求中定义的查询匹配的搜索结果。

 http

GET /my-index-000001/_search

Request

GET /<target>/_search

GET /_search

POST /<target>/_search

POST /_search

Prerequisites

        如果启用了 Elasticsearch 安全功能，针对目标数据流（data stream）、索引（index）或别名（alias）则必须具有 read 索引权限。对于跨集群搜索，请参阅配置跨集群搜索的权限。

       若要针对别名搜索特定时间点（PIT），则必须对该别名的数据流或索引具有 read 索引权限。

Description

允许您执行搜索查询，并返回与查询匹配的搜索结果。您可以使用 q 查询字符串参数或请求正文来提供搜索查询。

Path parameters

<target>

        （可选，字符串）要搜索的数据流、索引和别名的逗号分隔列表。支持通配符（*）。若要搜索所有数据流和索引，可以省略此参数，或者使用 * 或 _all。

Query parameters

        此 API 的许多选项可以通过查询参数（query parameter）或请求正文参数（request body parameter）指定。如果同时指定了这两个参数，则仅使用查询参数。

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:<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> 值的搜索将按相同的顺序路由到相同的分片。

q

（可选，字符串）Lucene 查询字符串语法中的查询。

可以使用q 参数运行查询参数搜索。查询参数搜索不支持完整的 Elasticsearch 查询 DSL，但便于测试。

q 参数会覆盖请求正文中指定的 query 参数。如果同时指定了这两个参数，则不会返回匹配请求正文中的 query 参数的文档。

request_cache

（可选，布尔值）如果为 true，则对于 size 为 0 的请求，启用搜索结果的缓存。请参阅分片请求缓存设置。默认值为索引级设置。

rest_total_hits_as_int

（可选，布尔值）指示是否应在 REST 搜索响应中将 hits.total 渲染为整数或对象。默认值为 false。

routing

（可选，字符串）用于将操作路由到特定分片的自定义值。

scroll

（可选，时间值）保留滚动搜索上下文的时长。请参阅滚动搜索结果。

默认情况下，此值不能超过 1d（24 小时）。可以使用 search.max_keep_alive 集群级设置来更改此限制。

search_type

（可选，字符串）用于计算相关性评分的分布式词频计算方式。

search_type 的有效值：

query_then_fetch

（默认）分布式词频在运行搜索的每个分片上本地计算。建议使用此选项，因为它可以更快地完成搜索，尽管评分可能不够准确。

dfs_query_then_fetch

分布式词频是全局计算的，使用运行搜索的所有分片收集的信息。虽然此选项可以提高评分的准确性，但它会为每个分片增加一次往返，从而可能导致搜索速度变慢。

seq_no_primary_term

（可选，布尔值）如果为 true，则返回每个命中的最后修改的序列号和主项。请参阅乐观并发控制。

size

（可选，整数）要返回的命中数量。默认值为 10。

默认情况下，您不能使用 from 和 size 参数翻阅超过 10,000 个命中的结果。要翻阅更多命中结果，请使用 search_after 参数。

sort

（可选，字符串）按 <字段>:<方向> 对的逗号分隔列表排序。

_source

（可选）指示要为匹配的文档返回哪些源字段。这些字段将返回在搜索响应的 hits._source 属性中。默认值为 true。请参阅源字段过滤。

_source 的有效值：

true

（布尔值）返回整个文档源。

false

（布尔值）不返回文档源。

<string>

（字符串）要返回的源字段的逗号分隔列表。支持通配符（*）。

_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。

Request body

docvalue_fields

（可选，字符串和对象的数组）字段模式的数组。请求将在响应的 hits.fields 属性中返回与这些模式匹配的字段名称的值。

可以将数组中的项目指定为字符串或对象。请参阅 Doc value 字段。

docvalue_fields 对象的属性：

field

（必需，字符串）通配符模式。请求将返回与该模式匹配的字段名称的 doc 值。

format

（可选，字符串）返回 doc 值的格式。

对于日期字段，可以指定日期格式。对于数字字段，可以指定 DecimalFormat 模式。

对于其他字段数据类型，不支持此参数。

fields

（可选，字符串和对象的数组）字段模式的数组。请求将在响应的 hits.fields 属性中返回与这些模式匹配的字段名称的值。

可以将数组中的项目指定为字符串或对象。请参阅 fields 选项。

fields 对象的属性：

field

（必需，字符串）要返回的字段。支持通配符（*）。

format

（可选，字符串）日期和地理空间字段的格式。其他字段数据类型不支持此参数。

date 和 date_nanos 字段接受日期格式。geo_point 和 geo_shape 字段接受：

geojson（默认）GeoJSONwktWell Known Textmvt(<spec>)

二进制 Mapbox 矢量瓦片。API 将瓦片作为 base64 编码的字符串返回。

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（如果未提供 k），且不能超过 10,000。Elasticsearch 从每个分片中收集 num_candidates 个结果，然后合并它们以找到前 k 个结果。增加 num_candidates 通常可以提高最终 k 个结果的准确性。默认值为 Math.min(1.5 * k, 10_000)。

query_vector

（可选，浮点数数组）查询向量。必须与您正在搜索的向量字段具有相同数量的维度。必须是浮点数数组或十六进制编码的字节向量。

query_vector_builder

（可选，对象）一个配置对象，指示如何在执行请求之前构建查询向量。必须提供 query_vector_builder 或 query_vector，但不能同时提供两者。请参阅执行语义搜索以了解更多信息。

similarity

（可选，浮点数）文档被视为匹配所需的最小相似度。计算出的相似度值与原始相似度相关，而不是文档分数。然后根据相似度和提供的 boost 对匹配的文档进行评分。

similarity 参数是直接的向量相似度计算：

• l2_norm：也称为欧几里得距离，将包括向量在以 query_vector 为原点、半径为 similarity 的 dims 维超球体内的文档。

• cosine、dot_product 和 max_inner_product：仅返回向量，其余弦相似度或点积至少为提供的 similarity。

内容：kNN 相似度搜索

min_score

（可选，浮点数）匹配文档的最小 _score。分数低于此值的文档不会包含在搜索结果中。

pit

（可选，对象）将搜索限制在特定时间点（PIT）。如果提供了 pit，则不能在请求路径中指定 <target>。

pit 的属性：

id

（必需，字符串）要搜索的 PIT 的 ID。如果提供了 pit 对象，则必须提供此参数。

keep_alive

（可选，时间值）用于延长 PIT 生存期的时间段。

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

（可选，时间单位）指定等待每个分片响应的时长。如果在超时时间到期之前未收到响应，则请求失败并返回错误。默认值为无超时。

version

（可选，布尔值）如果为 true，则作为命中的一部分返回文档版本。默认值为 false。

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。

hits

（对象数组）返回的文档对象数组。

hits 对象的属性：

_index

（字符串）包含返回文档的索引名称。

_id

（字符串）返回文档的唯一标识符。此 ID 仅在返回的索引内唯一。

_score

（浮点数）用于确定返回文档相关性的正 32 位浮点数。

_source

（对象）索引时为文档传递的原始 JSON 正文。

可以使用 _source 参数从响应中排除此属性，或指定要返回的源字段。

fields

（对象）包含文档的字段值。这些字段必须使用以下请求参数中的一个或多个在请求中指定：

• fields

• docvalue_fields

• script_fields

• stored_fields

只有在设置了这些参数中的一个或多个时，才会返回此属性。

fields 的属性：

<field>

（数组）键是字段名称，值是该字段的值。

http

GET /my-index-000001/_search?from=40&size=20
{"query": {"term": {"user.id": "kimchy"}}
}

API 返回以下响应：

JSON复制

{"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"}}},...]}
}