elasticsearch/_async/client/__init__.py [4433:4917]:
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
self,
*,
index: t.Optional[t.Union[str, t.Sequence[str]]] = None,
aggregations: t.Optional[t.Mapping[str, t.Mapping[str, t.Any]]] = None,
aggs: t.Optional[t.Mapping[str, t.Mapping[str, t.Any]]] = None,
allow_no_indices: t.Optional[bool] = None,
allow_partial_search_results: t.Optional[bool] = None,
analyze_wildcard: t.Optional[bool] = None,
analyzer: t.Optional[str] = None,
batched_reduce_size: t.Optional[int] = None,
ccs_minimize_roundtrips: t.Optional[bool] = None,
collapse: t.Optional[t.Mapping[str, t.Any]] = None,
default_operator: t.Optional[t.Union[str, t.Literal["and", "or"]]] = None,
df: t.Optional[str] = None,
docvalue_fields: t.Optional[t.Sequence[t.Mapping[str, t.Any]]] = None,
error_trace: t.Optional[bool] = None,
expand_wildcards: t.Optional[
t.Union[
t.Sequence[
t.Union[str, t.Literal["all", "closed", "hidden", "none", "open"]]
],
t.Union[str, t.Literal["all", "closed", "hidden", "none", "open"]],
]
] = None,
explain: t.Optional[bool] = None,
ext: t.Optional[t.Mapping[str, t.Any]] = None,
fields: t.Optional[t.Sequence[t.Mapping[str, t.Any]]] = None,
filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None,
force_synthetic_source: t.Optional[bool] = None,
from_: t.Optional[int] = None,
highlight: t.Optional[t.Mapping[str, t.Any]] = None,
human: t.Optional[bool] = None,
ignore_throttled: t.Optional[bool] = None,
ignore_unavailable: t.Optional[bool] = None,
include_named_queries_score: t.Optional[bool] = None,
indices_boost: t.Optional[t.Sequence[t.Mapping[str, float]]] = None,
knn: t.Optional[
t.Union[t.Mapping[str, t.Any], t.Sequence[t.Mapping[str, t.Any]]]
] = None,
lenient: t.Optional[bool] = None,
max_concurrent_shard_requests: t.Optional[int] = None,
min_score: t.Optional[float] = None,
pit: t.Optional[t.Mapping[str, t.Any]] = None,
post_filter: t.Optional[t.Mapping[str, t.Any]] = None,
pre_filter_shard_size: t.Optional[int] = None,
preference: t.Optional[str] = None,
pretty: t.Optional[bool] = None,
profile: t.Optional[bool] = None,
q: t.Optional[str] = None,
query: t.Optional[t.Mapping[str, t.Any]] = None,
rank: t.Optional[t.Mapping[str, t.Any]] = None,
request_cache: t.Optional[bool] = None,
rescore: t.Optional[
t.Union[t.Mapping[str, t.Any], t.Sequence[t.Mapping[str, t.Any]]]
] = None,
rest_total_hits_as_int: t.Optional[bool] = None,
retriever: t.Optional[t.Mapping[str, t.Any]] = None,
routing: t.Optional[str] = None,
runtime_mappings: t.Optional[t.Mapping[str, t.Mapping[str, t.Any]]] = None,
script_fields: t.Optional[t.Mapping[str, t.Mapping[str, t.Any]]] = None,
scroll: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None,
search_after: t.Optional[
t.Sequence[t.Union[None, bool, float, int, str]]
] = None,
search_type: t.Optional[
t.Union[str, t.Literal["dfs_query_then_fetch", "query_then_fetch"]]
] = None,
seq_no_primary_term: t.Optional[bool] = None,
size: t.Optional[int] = None,
slice: t.Optional[t.Mapping[str, t.Any]] = None,
sort: t.Optional[
t.Union[
t.Sequence[t.Union[str, t.Mapping[str, t.Any]]],
t.Union[str, t.Mapping[str, t.Any]],
]
] = None,
source: t.Optional[t.Union[bool, t.Mapping[str, t.Any]]] = None,
source_excludes: t.Optional[t.Union[str, t.Sequence[str]]] = None,
source_includes: t.Optional[t.Union[str, t.Sequence[str]]] = None,
stats: t.Optional[t.Sequence[str]] = None,
stored_fields: t.Optional[t.Union[str, t.Sequence[str]]] = None,
suggest: t.Optional[t.Mapping[str, t.Any]] = None,
suggest_field: t.Optional[str] = None,
suggest_mode: t.Optional[
t.Union[str, t.Literal["always", "missing", "popular"]]
] = None,
suggest_size: t.Optional[int] = None,
suggest_text: t.Optional[str] = None,
terminate_after: t.Optional[int] = None,
timeout: t.Optional[str] = None,
track_scores: t.Optional[bool] = None,
track_total_hits: t.Optional[t.Union[bool, int]] = None,
typed_keys: t.Optional[bool] = None,
version: t.Optional[bool] = None,
body: t.Optional[t.Dict[str, t.Any]] = None,
) -> ObjectApiResponse[t.Any]:
"""
.. raw:: html
Run a search.
Get search hits that match the query defined in the request.
You can provide search queries using the q query string parameter or the request body.
If both are specified, only the query parameter is used.
If the Elasticsearch security features are enabled, you must have the read index privilege for the target data stream, index, or alias. For cross-cluster search, refer to the documentation about configuring CCS privileges.
To search a point in time (PIT) for an alias, you must have the read index privilege for the alias's data streams or indices.
Search slicing
When paging through a large number of documents, it can be helpful to split the search into multiple slices to consume them independently with the slice and pit properties.
By default the splitting is done first on the shards, then locally on each shard.
The local splitting partitions the shard into contiguous ranges based on Lucene document IDs.
For instance if the number of shards is equal to 2 and you request 4 slices, the slices 0 and 2 are assigned to the first shard and the slices 1 and 3 are assigned to the second shard.
IMPORTANT: The same point-in-time ID should be used for all slices.
If different PIT IDs are used, slices can overlap and miss documents.
This situation can occur because the splitting criterion is based on Lucene document IDs, which are not stable across changes to the index.
``_
:param index: A comma-separated list of data streams, indices, and aliases to
search. It supports wildcards (`*`). To search all data streams and indices,
omit this parameter or use `*` or `_all`.
:param aggregations: Defines the aggregations that are run as part of the search
request.
:param aggs: Defines the aggregations that are run as part of the search request.
:param allow_no_indices: If `false`, the request returns an error if any wildcard
expression, index alias, or `_all` value targets only missing or closed indices.
This behavior applies even if the request targets other open indices. For
example, a request targeting `foo*,bar*` returns an error if an index starts
with `foo` but no index starts with `bar`.
:param allow_partial_search_results: If `true` and there are shard request timeouts
or shard failures, the request returns partial results. If `false`, it returns
an error with no partial results. To override the default behavior, you can
set the `search.default_allow_partial_results` cluster setting to `false`.
:param analyze_wildcard: If `true`, wildcard and prefix queries are analyzed.
This parameter can be used only when the `q` query string parameter is specified.
:param analyzer: The analyzer to use for the query string. This parameter can
be used only when the `q` query string parameter is specified.
:param batched_reduce_size: The number of shard results that should be reduced
at once on the coordinating node. If the potential number of shards in the
request can be large, this value should be used as a protection mechanism
to reduce the memory overhead per search request.
:param ccs_minimize_roundtrips: If `true`, network round-trips between the coordinating
node and the remote clusters are minimized when running cross-cluster search
(CCS) requests.
:param collapse: Collapses search results the values of the specified field.
:param default_operator: The default operator for the query string query: `AND`
or `OR`. This parameter can be used only when the `q` query string parameter
is specified.
:param df: The field to use as a default when no field prefix is given in the
query string. This parameter can be used only when the `q` query string parameter
is specified.
:param docvalue_fields: An array of wildcard (`*`) field patterns. The request
returns doc values for field names matching these patterns in the `hits.fields`
property of the response.
:param expand_wildcards: The type of index that wildcard patterns can match.
If the request can target data streams, this argument determines whether
wildcard expressions match hidden data streams. It supports comma-separated
values such as `open,hidden`.
:param explain: If `true`, the request returns detailed information about score
computation as part of a hit.
:param ext: Configuration of search extensions defined by Elasticsearch plugins.
:param fields: An array of wildcard (`*`) field patterns. The request returns
values for field names matching these patterns in the `hits.fields` property
of the response.
:param force_synthetic_source: Should this request force synthetic _source? Use
this to test if the mapping supports synthetic _source and to get a sense
of the worst case performance. Fetches with this enabled will be slower the
enabling synthetic source natively in the index.
:param from_: The starting document offset, which must be non-negative. By default,
you cannot page through more than 10,000 hits using the `from` and `size`
parameters. To page through more hits, use the `search_after` parameter.
:param highlight: Specifies the highlighter to use for retrieving highlighted
snippets from one or more fields in your search results.
:param ignore_throttled: If `true`, concrete, expanded or aliased indices will
be ignored when frozen.
:param ignore_unavailable: If `false`, the request returns an error if it targets
a missing or closed index.
:param include_named_queries_score: If `true`, the response includes the score
contribution from any named queries. This functionality reruns each named
query on every hit in a search response. Typically, this adds a small overhead
to a request. However, using computationally expensive named queries on a
large number of hits may add significant overhead.
:param indices_boost: Boost the `_score` of documents from specified indices.
The boost value is the factor by which scores are multiplied. A boost value
greater than `1.0` increases the score. A boost value between `0` and `1.0`
decreases the score.
:param knn: The approximate kNN search to run.
:param lenient: If `true`, format-based query failures (such as providing text
to a numeric field) in the query string will be ignored. This parameter can
be used only when the `q` query string parameter is specified.
:param max_concurrent_shard_requests: The number of concurrent shard requests
per node that the search runs concurrently. This value should be used to
limit the impact of the search on the cluster in order to limit the number
of concurrent shard requests.
:param min_score: The minimum `_score` for matching documents. Documents with
a lower `_score` are not included in search results and results collected
by aggregations.
:param pit: Limit the search to a point in time (PIT). If you provide a PIT,
you cannot specify an `` in the request path.
:param post_filter: Use the `post_filter` parameter to filter search results.
The search hits are filtered after the aggregations are calculated. A post
filter has no impact on the aggregation results.
:param pre_filter_shard_size: A threshold that enforces a pre-filter roundtrip
to prefilter search shards based on query rewriting if the number of shards
the search request expands to exceeds the threshold. This filter roundtrip
can limit the number of shards significantly if for instance a shard can
not match any documents based on its rewrite method (if date filters are
mandatory to match but the shard bounds and the query are disjoint). When
unspecified, the pre-filter phase is executed if any of these conditions
is met: * The request targets more than 128 shards. * The request targets
one or more read-only index. * The primary sort of the query targets an indexed
field.
:param preference: The nodes and shards used for the search. By default, Elasticsearch
selects from eligible nodes and shards using adaptive replica selection,
accounting for allocation awareness. Valid values are: * `_only_local` to
run the search only on shards on the local node. * `_local` to, if possible,
run the search on shards on the local node, or if not, select shards using
the default method. * `_only_nodes:,` to run the search
on only the specified nodes IDs. If suitable shards exist on more than one
selected node, use shards on those nodes using the default method. If none
of the specified nodes are available, select shards from any available node
using the default method. * `_prefer_nodes:,` to if possible,
run the search on the specified nodes IDs. If not, select shards using the
default method. `_shards:,` to run the search only on the specified
shards. You can combine this value with other `preference` values. However,
the `_shards` value must come first. For example: `_shards:2,3|_local`. ``
(any string that does not start with `_`) to route searches with the same
`` to the same shards in the same order.
:param profile: Set to `true` to return detailed timing information about the
execution of individual components in a search request. NOTE: This is a debugging
tool and adds significant overhead to search execution.
:param q: A query in the Lucene query string syntax. Query parameter searches
do not support the full Elasticsearch Query DSL but are handy for testing.
IMPORTANT: This parameter overrides the query parameter in the request body.
If both parameters are specified, documents matching the query request body
parameter are not returned.
:param query: The search definition using the Query DSL.
:param rank: The Reciprocal Rank Fusion (RRF) to use.
:param request_cache: If `true`, the caching of search results is enabled for
requests where `size` is `0`. It defaults to index level settings.
:param rescore: Can be used to improve precision by reordering just the top (for
example 100 - 500) documents returned by the `query` and `post_filter` phases.
:param rest_total_hits_as_int: Indicates whether `hits.total` should be rendered
as an integer or an object in the rest search response.
:param retriever: A retriever is a specification to describe top documents returned
from a search. A retriever replaces other elements of the search API that
also return top documents such as `query` and `knn`.
:param routing: A custom value that is used to route operations to a specific
shard.
:param runtime_mappings: One or more runtime fields in the search request. These
fields take precedence over mapped fields with the same name.
:param script_fields: Retrieve a script evaluation (based on different fields)
for each hit.
:param scroll: The period to retain the search context for scrolling. By default,
this value cannot exceed `1d` (24 hours). You can change this limit by using
the `search.max_keep_alive` cluster-level setting.
:param search_after: Used to retrieve the next page of hits using a set of sort
values from the previous page.
:param search_type: Indicates how distributed term frequencies are calculated
for relevance scoring.
:param seq_no_primary_term: If `true`, the request returns sequence number and
primary term of the last modification of each hit.
:param size: The number of hits to return, which must not be negative. By default,
you cannot page through more than 10,000 hits using the `from` and `size`
parameters. To page through more hits, use the `search_after` property.
:param slice: Split a scrolled search into multiple slices that can be consumed
independently.
:param sort: A comma-separated list of : pairs.
:param source: The source fields that are returned for matching documents. These
fields are returned in the `hits._source` property of the search response.
If the `stored_fields` property is specified, the `_source` property defaults
to `false`. Otherwise, it defaults to `true`.
:param source_excludes: A comma-separated list of source fields to exclude from
the response. You can also use this parameter to exclude fields from the
subset specified in `_source_includes` query parameter. If the `_source`
parameter is `false`, this parameter is ignored.
:param source_includes: A comma-separated list of source fields to include in
the response. If this parameter is specified, only these source fields are
returned. You can exclude fields from this subset using the `_source_excludes`
query parameter. If the `_source` parameter is `false`, this parameter is
ignored.
:param stats: The stats groups to associate with the search. Each group maintains
a statistics aggregation for its associated searches. You can retrieve these
stats using the indices stats API.
:param stored_fields: A comma-separated list of stored fields to return as part
of a hit. If no fields are specified, no stored fields are included in the
response. If this field is specified, the `_source` property defaults to
`false`. You can pass `_source: true` to return both source fields and stored
fields in the search response.
:param suggest: Defines a suggester that provides similar looking terms based
on a provided text.
:param suggest_field: The field to use for suggestions.
:param suggest_mode: The suggest mode. This parameter can be used only when the
`suggest_field` and `suggest_text` query string parameters are specified.
:param suggest_size: The number of suggestions to return. This parameter can
be used only when the `suggest_field` and `suggest_text` query string parameters
are specified.
:param suggest_text: The source text for which the suggestions should be returned.
This parameter can be used only when the `suggest_field` and `suggest_text`
query string parameters are specified.
:param terminate_after: The maximum number of documents to collect for each shard.
If a query reaches this limit, Elasticsearch terminates the query early.
Elasticsearch collects documents before sorting. IMPORTANT: Use with caution.
Elasticsearch applies this property to each shard handling the request. When
possible, let Elasticsearch perform early termination automatically. Avoid
specifying this property for requests that target data streams with backing
indices across multiple data tiers. If set to `0` (default), the query does
not terminate early.
:param timeout: The period of time to wait for a response from each shard. If
no response is received before the timeout expires, the request fails and
returns an error. Defaults to no timeout.
:param track_scores: If `true`, calculate and return document scores, even if
the scores are not used for sorting.
:param track_total_hits: Number of hits matching the query to count accurately.
If `true`, the exact number of hits is returned at the cost of some performance.
If `false`, the response does not include the total number of hits matching
the query.
:param typed_keys: If `true`, aggregation and suggester names are be prefixed
by their respective types in the response.
:param version: If `true`, the request returns the document version as part of
a hit.
"""
__path_parts: t.Dict[str, str]
if index not in SKIP_IN_PATH:
__path_parts = {"index": _quote(index)}
__path = f'/{__path_parts["index"]}/_search'
else:
__path_parts = {}
__path = "/_search"
__query: t.Dict[str, t.Any] = {}
__body: t.Dict[str, t.Any] = body if body is not None else {}
# The 'sort' parameter with a colon can't be encoded to the body.
if sort is not None and (
(isinstance(sort, str) and ":" in sort)
or (
isinstance(sort, (list, tuple))
and all(isinstance(_x, str) for _x in sort)
and any(":" in _x for _x in sort)
)
):
__query["sort"] = sort
sort = None
if allow_no_indices is not None:
__query["allow_no_indices"] = allow_no_indices
if allow_partial_search_results is not None:
__query["allow_partial_search_results"] = allow_partial_search_results
if analyze_wildcard is not None:
__query["analyze_wildcard"] = analyze_wildcard
if analyzer is not None:
__query["analyzer"] = analyzer
if batched_reduce_size is not None:
__query["batched_reduce_size"] = batched_reduce_size
if ccs_minimize_roundtrips is not None:
__query["ccs_minimize_roundtrips"] = ccs_minimize_roundtrips
if default_operator is not None:
__query["default_operator"] = default_operator
if df is not None:
__query["df"] = df
if error_trace is not None:
__query["error_trace"] = error_trace
if expand_wildcards is not None:
__query["expand_wildcards"] = expand_wildcards
if filter_path is not None:
__query["filter_path"] = filter_path
if force_synthetic_source is not None:
__query["force_synthetic_source"] = force_synthetic_source
if human is not None:
__query["human"] = human
if ignore_throttled is not None:
__query["ignore_throttled"] = ignore_throttled
if ignore_unavailable is not None:
__query["ignore_unavailable"] = ignore_unavailable
if include_named_queries_score is not None:
__query["include_named_queries_score"] = include_named_queries_score
if lenient is not None:
__query["lenient"] = lenient
if max_concurrent_shard_requests is not None:
__query["max_concurrent_shard_requests"] = max_concurrent_shard_requests
if pre_filter_shard_size is not None:
__query["pre_filter_shard_size"] = pre_filter_shard_size
if preference is not None:
__query["preference"] = preference
if pretty is not None:
__query["pretty"] = pretty
if q is not None:
__query["q"] = q
if request_cache is not None:
__query["request_cache"] = request_cache
if rest_total_hits_as_int is not None:
__query["rest_total_hits_as_int"] = rest_total_hits_as_int
if routing is not None:
__query["routing"] = routing
if scroll is not None:
__query["scroll"] = scroll
if search_type is not None:
__query["search_type"] = search_type
if source_excludes is not None:
__query["_source_excludes"] = source_excludes
if source_includes is not None:
__query["_source_includes"] = source_includes
if suggest_field is not None:
__query["suggest_field"] = suggest_field
if suggest_mode is not None:
__query["suggest_mode"] = suggest_mode
if suggest_size is not None:
__query["suggest_size"] = suggest_size
if suggest_text is not None:
__query["suggest_text"] = suggest_text
if typed_keys is not None:
__query["typed_keys"] = typed_keys
if not __body:
if aggregations is not None:
__body["aggregations"] = aggregations
if aggs is not None:
__body["aggs"] = aggs
if collapse is not None:
__body["collapse"] = collapse
if docvalue_fields is not None:
__body["docvalue_fields"] = docvalue_fields
if explain is not None:
__body["explain"] = explain
if ext is not None:
__body["ext"] = ext
if fields is not None:
__body["fields"] = fields
if from_ is not None:
__body["from"] = from_
if highlight is not None:
__body["highlight"] = highlight
if indices_boost is not None:
__body["indices_boost"] = indices_boost
if knn is not None:
__body["knn"] = knn
if min_score is not None:
__body["min_score"] = min_score
if pit is not None:
__body["pit"] = pit
if post_filter is not None:
__body["post_filter"] = post_filter
if profile is not None:
__body["profile"] = profile
if query is not None:
__body["query"] = query
if rank is not None:
__body["rank"] = rank
if rescore is not None:
__body["rescore"] = rescore
if retriever is not None:
__body["retriever"] = retriever
if runtime_mappings is not None:
__body["runtime_mappings"] = runtime_mappings
if script_fields is not None:
__body["script_fields"] = script_fields
if search_after is not None:
__body["search_after"] = search_after
if seq_no_primary_term is not None:
__body["seq_no_primary_term"] = seq_no_primary_term
if size is not None:
__body["size"] = size
if slice is not None:
__body["slice"] = slice
if sort is not None:
__body["sort"] = sort
if source is not None:
__body["_source"] = source
if stats is not None:
__body["stats"] = stats
if stored_fields is not None:
__body["stored_fields"] = stored_fields
if suggest is not None:
__body["suggest"] = suggest
if terminate_after is not None:
__body["terminate_after"] = terminate_after
if timeout is not None:
__body["timeout"] = timeout
if track_scores is not None:
__body["track_scores"] = track_scores
if track_total_hits is not None:
__body["track_total_hits"] = track_total_hits
if version is not None:
__body["version"] = version
if not __body:
__body = None # type: ignore[assignment]
__headers = {"accept": "application/json"}
if __body is not None:
__headers["content-type"] = "application/json"
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
elasticsearch/_sync/client/__init__.py [4431:4915]:
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
self,
*,
index: t.Optional[t.Union[str, t.Sequence[str]]] = None,
aggregations: t.Optional[t.Mapping[str, t.Mapping[str, t.Any]]] = None,
aggs: t.Optional[t.Mapping[str, t.Mapping[str, t.Any]]] = None,
allow_no_indices: t.Optional[bool] = None,
allow_partial_search_results: t.Optional[bool] = None,
analyze_wildcard: t.Optional[bool] = None,
analyzer: t.Optional[str] = None,
batched_reduce_size: t.Optional[int] = None,
ccs_minimize_roundtrips: t.Optional[bool] = None,
collapse: t.Optional[t.Mapping[str, t.Any]] = None,
default_operator: t.Optional[t.Union[str, t.Literal["and", "or"]]] = None,
df: t.Optional[str] = None,
docvalue_fields: t.Optional[t.Sequence[t.Mapping[str, t.Any]]] = None,
error_trace: t.Optional[bool] = None,
expand_wildcards: t.Optional[
t.Union[
t.Sequence[
t.Union[str, t.Literal["all", "closed", "hidden", "none", "open"]]
],
t.Union[str, t.Literal["all", "closed", "hidden", "none", "open"]],
]
] = None,
explain: t.Optional[bool] = None,
ext: t.Optional[t.Mapping[str, t.Any]] = None,
fields: t.Optional[t.Sequence[t.Mapping[str, t.Any]]] = None,
filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None,
force_synthetic_source: t.Optional[bool] = None,
from_: t.Optional[int] = None,
highlight: t.Optional[t.Mapping[str, t.Any]] = None,
human: t.Optional[bool] = None,
ignore_throttled: t.Optional[bool] = None,
ignore_unavailable: t.Optional[bool] = None,
include_named_queries_score: t.Optional[bool] = None,
indices_boost: t.Optional[t.Sequence[t.Mapping[str, float]]] = None,
knn: t.Optional[
t.Union[t.Mapping[str, t.Any], t.Sequence[t.Mapping[str, t.Any]]]
] = None,
lenient: t.Optional[bool] = None,
max_concurrent_shard_requests: t.Optional[int] = None,
min_score: t.Optional[float] = None,
pit: t.Optional[t.Mapping[str, t.Any]] = None,
post_filter: t.Optional[t.Mapping[str, t.Any]] = None,
pre_filter_shard_size: t.Optional[int] = None,
preference: t.Optional[str] = None,
pretty: t.Optional[bool] = None,
profile: t.Optional[bool] = None,
q: t.Optional[str] = None,
query: t.Optional[t.Mapping[str, t.Any]] = None,
rank: t.Optional[t.Mapping[str, t.Any]] = None,
request_cache: t.Optional[bool] = None,
rescore: t.Optional[
t.Union[t.Mapping[str, t.Any], t.Sequence[t.Mapping[str, t.Any]]]
] = None,
rest_total_hits_as_int: t.Optional[bool] = None,
retriever: t.Optional[t.Mapping[str, t.Any]] = None,
routing: t.Optional[str] = None,
runtime_mappings: t.Optional[t.Mapping[str, t.Mapping[str, t.Any]]] = None,
script_fields: t.Optional[t.Mapping[str, t.Mapping[str, t.Any]]] = None,
scroll: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None,
search_after: t.Optional[
t.Sequence[t.Union[None, bool, float, int, str]]
] = None,
search_type: t.Optional[
t.Union[str, t.Literal["dfs_query_then_fetch", "query_then_fetch"]]
] = None,
seq_no_primary_term: t.Optional[bool] = None,
size: t.Optional[int] = None,
slice: t.Optional[t.Mapping[str, t.Any]] = None,
sort: t.Optional[
t.Union[
t.Sequence[t.Union[str, t.Mapping[str, t.Any]]],
t.Union[str, t.Mapping[str, t.Any]],
]
] = None,
source: t.Optional[t.Union[bool, t.Mapping[str, t.Any]]] = None,
source_excludes: t.Optional[t.Union[str, t.Sequence[str]]] = None,
source_includes: t.Optional[t.Union[str, t.Sequence[str]]] = None,
stats: t.Optional[t.Sequence[str]] = None,
stored_fields: t.Optional[t.Union[str, t.Sequence[str]]] = None,
suggest: t.Optional[t.Mapping[str, t.Any]] = None,
suggest_field: t.Optional[str] = None,
suggest_mode: t.Optional[
t.Union[str, t.Literal["always", "missing", "popular"]]
] = None,
suggest_size: t.Optional[int] = None,
suggest_text: t.Optional[str] = None,
terminate_after: t.Optional[int] = None,
timeout: t.Optional[str] = None,
track_scores: t.Optional[bool] = None,
track_total_hits: t.Optional[t.Union[bool, int]] = None,
typed_keys: t.Optional[bool] = None,
version: t.Optional[bool] = None,
body: t.Optional[t.Dict[str, t.Any]] = None,
) -> ObjectApiResponse[t.Any]:
"""
.. raw:: html
Run a search.
Get search hits that match the query defined in the request.
You can provide search queries using the q query string parameter or the request body.
If both are specified, only the query parameter is used.
If the Elasticsearch security features are enabled, you must have the read index privilege for the target data stream, index, or alias. For cross-cluster search, refer to the documentation about configuring CCS privileges.
To search a point in time (PIT) for an alias, you must have the read index privilege for the alias's data streams or indices.
Search slicing
When paging through a large number of documents, it can be helpful to split the search into multiple slices to consume them independently with the slice and pit properties.
By default the splitting is done first on the shards, then locally on each shard.
The local splitting partitions the shard into contiguous ranges based on Lucene document IDs.
For instance if the number of shards is equal to 2 and you request 4 slices, the slices 0 and 2 are assigned to the first shard and the slices 1 and 3 are assigned to the second shard.
IMPORTANT: The same point-in-time ID should be used for all slices.
If different PIT IDs are used, slices can overlap and miss documents.
This situation can occur because the splitting criterion is based on Lucene document IDs, which are not stable across changes to the index.
``_
:param index: A comma-separated list of data streams, indices, and aliases to
search. It supports wildcards (`*`). To search all data streams and indices,
omit this parameter or use `*` or `_all`.
:param aggregations: Defines the aggregations that are run as part of the search
request.
:param aggs: Defines the aggregations that are run as part of the search request.
:param allow_no_indices: If `false`, the request returns an error if any wildcard
expression, index alias, or `_all` value targets only missing or closed indices.
This behavior applies even if the request targets other open indices. For
example, a request targeting `foo*,bar*` returns an error if an index starts
with `foo` but no index starts with `bar`.
:param allow_partial_search_results: If `true` and there are shard request timeouts
or shard failures, the request returns partial results. If `false`, it returns
an error with no partial results. To override the default behavior, you can
set the `search.default_allow_partial_results` cluster setting to `false`.
:param analyze_wildcard: If `true`, wildcard and prefix queries are analyzed.
This parameter can be used only when the `q` query string parameter is specified.
:param analyzer: The analyzer to use for the query string. This parameter can
be used only when the `q` query string parameter is specified.
:param batched_reduce_size: The number of shard results that should be reduced
at once on the coordinating node. If the potential number of shards in the
request can be large, this value should be used as a protection mechanism
to reduce the memory overhead per search request.
:param ccs_minimize_roundtrips: If `true`, network round-trips between the coordinating
node and the remote clusters are minimized when running cross-cluster search
(CCS) requests.
:param collapse: Collapses search results the values of the specified field.
:param default_operator: The default operator for the query string query: `AND`
or `OR`. This parameter can be used only when the `q` query string parameter
is specified.
:param df: The field to use as a default when no field prefix is given in the
query string. This parameter can be used only when the `q` query string parameter
is specified.
:param docvalue_fields: An array of wildcard (`*`) field patterns. The request
returns doc values for field names matching these patterns in the `hits.fields`
property of the response.
:param expand_wildcards: The type of index that wildcard patterns can match.
If the request can target data streams, this argument determines whether
wildcard expressions match hidden data streams. It supports comma-separated
values such as `open,hidden`.
:param explain: If `true`, the request returns detailed information about score
computation as part of a hit.
:param ext: Configuration of search extensions defined by Elasticsearch plugins.
:param fields: An array of wildcard (`*`) field patterns. The request returns
values for field names matching these patterns in the `hits.fields` property
of the response.
:param force_synthetic_source: Should this request force synthetic _source? Use
this to test if the mapping supports synthetic _source and to get a sense
of the worst case performance. Fetches with this enabled will be slower the
enabling synthetic source natively in the index.
:param from_: The starting document offset, which must be non-negative. By default,
you cannot page through more than 10,000 hits using the `from` and `size`
parameters. To page through more hits, use the `search_after` parameter.
:param highlight: Specifies the highlighter to use for retrieving highlighted
snippets from one or more fields in your search results.
:param ignore_throttled: If `true`, concrete, expanded or aliased indices will
be ignored when frozen.
:param ignore_unavailable: If `false`, the request returns an error if it targets
a missing or closed index.
:param include_named_queries_score: If `true`, the response includes the score
contribution from any named queries. This functionality reruns each named
query on every hit in a search response. Typically, this adds a small overhead
to a request. However, using computationally expensive named queries on a
large number of hits may add significant overhead.
:param indices_boost: Boost the `_score` of documents from specified indices.
The boost value is the factor by which scores are multiplied. A boost value
greater than `1.0` increases the score. A boost value between `0` and `1.0`
decreases the score.
:param knn: The approximate kNN search to run.
:param lenient: If `true`, format-based query failures (such as providing text
to a numeric field) in the query string will be ignored. This parameter can
be used only when the `q` query string parameter is specified.
:param max_concurrent_shard_requests: The number of concurrent shard requests
per node that the search runs concurrently. This value should be used to
limit the impact of the search on the cluster in order to limit the number
of concurrent shard requests.
:param min_score: The minimum `_score` for matching documents. Documents with
a lower `_score` are not included in search results and results collected
by aggregations.
:param pit: Limit the search to a point in time (PIT). If you provide a PIT,
you cannot specify an `` in the request path.
:param post_filter: Use the `post_filter` parameter to filter search results.
The search hits are filtered after the aggregations are calculated. A post
filter has no impact on the aggregation results.
:param pre_filter_shard_size: A threshold that enforces a pre-filter roundtrip
to prefilter search shards based on query rewriting if the number of shards
the search request expands to exceeds the threshold. This filter roundtrip
can limit the number of shards significantly if for instance a shard can
not match any documents based on its rewrite method (if date filters are
mandatory to match but the shard bounds and the query are disjoint). When
unspecified, the pre-filter phase is executed if any of these conditions
is met: * The request targets more than 128 shards. * The request targets
one or more read-only index. * The primary sort of the query targets an indexed
field.
:param preference: The nodes and shards used for the search. By default, Elasticsearch
selects from eligible nodes and shards using adaptive replica selection,
accounting for allocation awareness. Valid values are: * `_only_local` to
run the search only on shards on the local node. * `_local` to, if possible,
run the search on shards on the local node, or if not, select shards using
the default method. * `_only_nodes:,` to run the search
on only the specified nodes IDs. If suitable shards exist on more than one
selected node, use shards on those nodes using the default method. If none
of the specified nodes are available, select shards from any available node
using the default method. * `_prefer_nodes:,` to if possible,
run the search on the specified nodes IDs. If not, select shards using the
default method. `_shards:,` to run the search only on the specified
shards. You can combine this value with other `preference` values. However,
the `_shards` value must come first. For example: `_shards:2,3|_local`. ``
(any string that does not start with `_`) to route searches with the same
`` to the same shards in the same order.
:param profile: Set to `true` to return detailed timing information about the
execution of individual components in a search request. NOTE: This is a debugging
tool and adds significant overhead to search execution.
:param q: A query in the Lucene query string syntax. Query parameter searches
do not support the full Elasticsearch Query DSL but are handy for testing.
IMPORTANT: This parameter overrides the query parameter in the request body.
If both parameters are specified, documents matching the query request body
parameter are not returned.
:param query: The search definition using the Query DSL.
:param rank: The Reciprocal Rank Fusion (RRF) to use.
:param request_cache: If `true`, the caching of search results is enabled for
requests where `size` is `0`. It defaults to index level settings.
:param rescore: Can be used to improve precision by reordering just the top (for
example 100 - 500) documents returned by the `query` and `post_filter` phases.
:param rest_total_hits_as_int: Indicates whether `hits.total` should be rendered
as an integer or an object in the rest search response.
:param retriever: A retriever is a specification to describe top documents returned
from a search. A retriever replaces other elements of the search API that
also return top documents such as `query` and `knn`.
:param routing: A custom value that is used to route operations to a specific
shard.
:param runtime_mappings: One or more runtime fields in the search request. These
fields take precedence over mapped fields with the same name.
:param script_fields: Retrieve a script evaluation (based on different fields)
for each hit.
:param scroll: The period to retain the search context for scrolling. By default,
this value cannot exceed `1d` (24 hours). You can change this limit by using
the `search.max_keep_alive` cluster-level setting.
:param search_after: Used to retrieve the next page of hits using a set of sort
values from the previous page.
:param search_type: Indicates how distributed term frequencies are calculated
for relevance scoring.
:param seq_no_primary_term: If `true`, the request returns sequence number and
primary term of the last modification of each hit.
:param size: The number of hits to return, which must not be negative. By default,
you cannot page through more than 10,000 hits using the `from` and `size`
parameters. To page through more hits, use the `search_after` property.
:param slice: Split a scrolled search into multiple slices that can be consumed
independently.
:param sort: A comma-separated list of : pairs.
:param source: The source fields that are returned for matching documents. These
fields are returned in the `hits._source` property of the search response.
If the `stored_fields` property is specified, the `_source` property defaults
to `false`. Otherwise, it defaults to `true`.
:param source_excludes: A comma-separated list of source fields to exclude from
the response. You can also use this parameter to exclude fields from the
subset specified in `_source_includes` query parameter. If the `_source`
parameter is `false`, this parameter is ignored.
:param source_includes: A comma-separated list of source fields to include in
the response. If this parameter is specified, only these source fields are
returned. You can exclude fields from this subset using the `_source_excludes`
query parameter. If the `_source` parameter is `false`, this parameter is
ignored.
:param stats: The stats groups to associate with the search. Each group maintains
a statistics aggregation for its associated searches. You can retrieve these
stats using the indices stats API.
:param stored_fields: A comma-separated list of stored fields to return as part
of a hit. If no fields are specified, no stored fields are included in the
response. If this field is specified, the `_source` property defaults to
`false`. You can pass `_source: true` to return both source fields and stored
fields in the search response.
:param suggest: Defines a suggester that provides similar looking terms based
on a provided text.
:param suggest_field: The field to use for suggestions.
:param suggest_mode: The suggest mode. This parameter can be used only when the
`suggest_field` and `suggest_text` query string parameters are specified.
:param suggest_size: The number of suggestions to return. This parameter can
be used only when the `suggest_field` and `suggest_text` query string parameters
are specified.
:param suggest_text: The source text for which the suggestions should be returned.
This parameter can be used only when the `suggest_field` and `suggest_text`
query string parameters are specified.
:param terminate_after: The maximum number of documents to collect for each shard.
If a query reaches this limit, Elasticsearch terminates the query early.
Elasticsearch collects documents before sorting. IMPORTANT: Use with caution.
Elasticsearch applies this property to each shard handling the request. When
possible, let Elasticsearch perform early termination automatically. Avoid
specifying this property for requests that target data streams with backing
indices across multiple data tiers. If set to `0` (default), the query does
not terminate early.
:param timeout: The period of time to wait for a response from each shard. If
no response is received before the timeout expires, the request fails and
returns an error. Defaults to no timeout.
:param track_scores: If `true`, calculate and return document scores, even if
the scores are not used for sorting.
:param track_total_hits: Number of hits matching the query to count accurately.
If `true`, the exact number of hits is returned at the cost of some performance.
If `false`, the response does not include the total number of hits matching
the query.
:param typed_keys: If `true`, aggregation and suggester names are be prefixed
by their respective types in the response.
:param version: If `true`, the request returns the document version as part of
a hit.
"""
__path_parts: t.Dict[str, str]
if index not in SKIP_IN_PATH:
__path_parts = {"index": _quote(index)}
__path = f'/{__path_parts["index"]}/_search'
else:
__path_parts = {}
__path = "/_search"
__query: t.Dict[str, t.Any] = {}
__body: t.Dict[str, t.Any] = body if body is not None else {}
# The 'sort' parameter with a colon can't be encoded to the body.
if sort is not None and (
(isinstance(sort, str) and ":" in sort)
or (
isinstance(sort, (list, tuple))
and all(isinstance(_x, str) for _x in sort)
and any(":" in _x for _x in sort)
)
):
__query["sort"] = sort
sort = None
if allow_no_indices is not None:
__query["allow_no_indices"] = allow_no_indices
if allow_partial_search_results is not None:
__query["allow_partial_search_results"] = allow_partial_search_results
if analyze_wildcard is not None:
__query["analyze_wildcard"] = analyze_wildcard
if analyzer is not None:
__query["analyzer"] = analyzer
if batched_reduce_size is not None:
__query["batched_reduce_size"] = batched_reduce_size
if ccs_minimize_roundtrips is not None:
__query["ccs_minimize_roundtrips"] = ccs_minimize_roundtrips
if default_operator is not None:
__query["default_operator"] = default_operator
if df is not None:
__query["df"] = df
if error_trace is not None:
__query["error_trace"] = error_trace
if expand_wildcards is not None:
__query["expand_wildcards"] = expand_wildcards
if filter_path is not None:
__query["filter_path"] = filter_path
if force_synthetic_source is not None:
__query["force_synthetic_source"] = force_synthetic_source
if human is not None:
__query["human"] = human
if ignore_throttled is not None:
__query["ignore_throttled"] = ignore_throttled
if ignore_unavailable is not None:
__query["ignore_unavailable"] = ignore_unavailable
if include_named_queries_score is not None:
__query["include_named_queries_score"] = include_named_queries_score
if lenient is not None:
__query["lenient"] = lenient
if max_concurrent_shard_requests is not None:
__query["max_concurrent_shard_requests"] = max_concurrent_shard_requests
if pre_filter_shard_size is not None:
__query["pre_filter_shard_size"] = pre_filter_shard_size
if preference is not None:
__query["preference"] = preference
if pretty is not None:
__query["pretty"] = pretty
if q is not None:
__query["q"] = q
if request_cache is not None:
__query["request_cache"] = request_cache
if rest_total_hits_as_int is not None:
__query["rest_total_hits_as_int"] = rest_total_hits_as_int
if routing is not None:
__query["routing"] = routing
if scroll is not None:
__query["scroll"] = scroll
if search_type is not None:
__query["search_type"] = search_type
if source_excludes is not None:
__query["_source_excludes"] = source_excludes
if source_includes is not None:
__query["_source_includes"] = source_includes
if suggest_field is not None:
__query["suggest_field"] = suggest_field
if suggest_mode is not None:
__query["suggest_mode"] = suggest_mode
if suggest_size is not None:
__query["suggest_size"] = suggest_size
if suggest_text is not None:
__query["suggest_text"] = suggest_text
if typed_keys is not None:
__query["typed_keys"] = typed_keys
if not __body:
if aggregations is not None:
__body["aggregations"] = aggregations
if aggs is not None:
__body["aggs"] = aggs
if collapse is not None:
__body["collapse"] = collapse
if docvalue_fields is not None:
__body["docvalue_fields"] = docvalue_fields
if explain is not None:
__body["explain"] = explain
if ext is not None:
__body["ext"] = ext
if fields is not None:
__body["fields"] = fields
if from_ is not None:
__body["from"] = from_
if highlight is not None:
__body["highlight"] = highlight
if indices_boost is not None:
__body["indices_boost"] = indices_boost
if knn is not None:
__body["knn"] = knn
if min_score is not None:
__body["min_score"] = min_score
if pit is not None:
__body["pit"] = pit
if post_filter is not None:
__body["post_filter"] = post_filter
if profile is not None:
__body["profile"] = profile
if query is not None:
__body["query"] = query
if rank is not None:
__body["rank"] = rank
if rescore is not None:
__body["rescore"] = rescore
if retriever is not None:
__body["retriever"] = retriever
if runtime_mappings is not None:
__body["runtime_mappings"] = runtime_mappings
if script_fields is not None:
__body["script_fields"] = script_fields
if search_after is not None:
__body["search_after"] = search_after
if seq_no_primary_term is not None:
__body["seq_no_primary_term"] = seq_no_primary_term
if size is not None:
__body["size"] = size
if slice is not None:
__body["slice"] = slice
if sort is not None:
__body["sort"] = sort
if source is not None:
__body["_source"] = source
if stats is not None:
__body["stats"] = stats
if stored_fields is not None:
__body["stored_fields"] = stored_fields
if suggest is not None:
__body["suggest"] = suggest
if terminate_after is not None:
__body["terminate_after"] = terminate_after
if timeout is not None:
__body["timeout"] = timeout
if track_scores is not None:
__body["track_scores"] = track_scores
if track_total_hits is not None:
__body["track_total_hits"] = track_total_hits
if version is not None:
__body["version"] = version
if not __body:
__body = None # type: ignore[assignment]
__headers = {"accept": "application/json"}
if __body is not None:
__headers["content-type"] = "application/json"
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -