Add body field parameters to 'search' API

Author: sethmlarson

docs/guide/examples.asciidoc

@@ -67,7 +67,7 @@ The `search()` method returns results that are matching a query:
 
 [source,py]
 ----------------------------
-res = es.search(index="test-index", body={"query": {"match_all": {}}})
+res = es.search(index="test-index", query={"match_all": {}})
 print("Got %d Hits:" % res['hits']['total']['value'])
 for hit in res['hits']['hits']:
     print("%(timestamp)s %(author)s: %(text)s" % hit["_source"])

docs/sphinx/async.rst

@@ -36,7 +36,7 @@ and are used in the same way as other APIs, just with an extra ``await``:
     async def main():
         resp = await es.search(
             index="documents",
-            body={"query": {"match_all": {}}},
+            query={"match_all": {}},
             size=20,
         )
         print(resp)

docs/sphinx/index.rst

@@ -61,7 +61,7 @@ Example Usage
 
     es.indices.refresh(index="test-index")
 
-    res = es.search(index="test-index", body={"query": {"match_all": {}}})
+    res = es.search(index="test-index", query={"match_all": {}})
     print("Got %d Hits:" % res['hits']['total']['value'])
     for hit in res['hits']['hits']:
         print("%(timestamp)s %(author)s: %(text)s" % hit["_source"])

elasticsearch/_async/client/__init__.py

@@ -1561,6 +1561,39 @@ async def scroll(self, body=None, scroll_id=None, params=None, headers=None):
         "track_total_hits",
         "typed_keys",
         "version",
+        body_params=[
+            "_source",
+            "aggregations",
+            "aggs",
+            "collapse",
+            "docvalue_fields",
+            "explain",
+            "fields",
+            "from_",
+            "highlight",
+            "indices_boost",
+            "min_score",
+            "pit",
+            "post_filter",
+            "profile",
+            "query",
+            "rescore",
+            "runtime_mappings",
+            "script_fields",
+            "search_after",
+            "seq_no_primary_term",
+            "size",
+            "slice",
+            "sort",
+            "stats",
+            "stored_fields",
+            "suggest",
+            "terminate_after",
+            "timeout",
+            "track_scores",
+            "track_total_hits",
+            "version",
+        ],
     )
     async def search(
         self, body=None, index=None, doc_type=None, params=None, headers=None
@@ -1575,12 +1608,13 @@ async def search(
             `_all` or empty string to perform the operation on all indices
         :arg doc_type: A comma-separated list of document types to
             search; leave empty to perform the operation on all types
-        :arg _source: True or false to return the _source field or not,
-            or a list of fields to return
+        :arg _source:
         :arg _source_excludes: A list of fields to exclude from the
             returned _source field
         :arg _source_includes: A list of fields to extract and return
             from the _source field
+        :arg aggregations:
+        :arg aggs:
         :arg allow_no_indices: Whether to ignore if a wildcard indices
             expression resolves into no concrete indices. (This includes `_all`
             string or when no indices have been specified)
@@ -1598,22 +1632,24 @@ async def search(
         :arg ccs_minimize_roundtrips: Indicates whether network round-
             trips should be minimized as part of cross-cluster search requests
             execution  Default: true
+        :arg collapse:
         :arg default_operator: The default operator for query string
             query (AND or OR)  Valid choices: AND, OR  Default: OR
         :arg df: The field to use as default where no field prefix is
             given in the query string
-        :arg docvalue_fields: A comma-separated list of fields to return
-            as the docvalue representation of a field for each hit
+        :arg docvalue_fields:
         :arg expand_wildcards: Whether to expand wildcard expression to
             concrete indices that are open, closed or both.  Valid choices: open,
             closed, hidden, none, all  Default: open
-        :arg explain: Specify whether to return detailed information
-            about score computation as part of a hit
-        :arg from_: Starting offset (default: 0)
+        :arg explain:
+        :arg fields:
+        :arg from_:
+        :arg highlight:
         :arg ignore_throttled: Whether specified concrete, expanded or
             aliased indices should be ignored when throttled
         :arg ignore_unavailable: Whether specified concrete indices
             should be ignored when unavailable (missing or closed)
+        :arg indices_boost:
         :arg lenient: Specify whether format-based query failures (such
             as providing text to a numeric field) should be ignored
         :arg max_concurrent_shard_requests: The number of concurrent
@@ -1623,6 +1659,9 @@ async def search(
         :arg min_compatible_shard_node: The minimum compatible version
             that all shards involved in search should have for this request to be
             successful
+        :arg min_score:
+        :arg pit:
+        :arg post_filter:
         :arg 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
@@ -1632,42 +1671,42 @@ async def search(
             shard bounds and the query are disjoint.
         :arg preference: Specify the node or shard the operation should
             be performed on (default: random)
+        :arg profile:
         :arg q: Query in the Lucene query string syntax
+        :arg query:
         :arg request_cache: Specify if request cache should be used for
             this request or not, defaults to index level setting
+        :arg rescore:
         :arg rest_total_hits_as_int: Indicates whether hits.total should
             be rendered as an integer or an object in the rest search response
         :arg routing: A comma-separated list of specific routing values
+        :arg runtime_mappings:
+        :arg script_fields:
         :arg scroll: Specify how long a consistent view of the index
             should be maintained for scrolled search
+        :arg search_after:
         :arg search_type: Search operation type  Valid choices:
             query_then_fetch, dfs_query_then_fetch
-        :arg seq_no_primary_term: Specify whether to return sequence
-            number and primary term of the last modification of each hit
-        :arg size: Number of hits to return (default: 10)
-        :arg sort: A comma-separated list of <field>:<direction> pairs
-        :arg stats: Specific 'tag' of the request for logging and
-            statistical purposes
-        :arg stored_fields: A comma-separated list of stored fields to
-            return as part of a hit
+        :arg seq_no_primary_term:
+        :arg size:
+        :arg slice:
+        :arg sort:
+        :arg stats:
+        :arg stored_fields:
+        :arg suggest:
         :arg suggest_field: Specify which field to use for suggestions
         :arg suggest_mode: Specify suggest mode  Valid choices: missing,
             popular, always  Default: missing
         :arg suggest_size: How many suggestions to return in response
         :arg suggest_text: The source text for which the suggestions
             should be returned
-        :arg terminate_after: The maximum number of documents to collect
-            for each shard, upon reaching which the query execution will terminate
-            early.
-        :arg timeout: Explicit operation timeout
-        :arg track_scores: Whether to calculate and return scores even
-            if they are not used for sorting
-        :arg track_total_hits: Indicate if the number of documents that
-            match the query should be tracked
+        :arg terminate_after:
+        :arg timeout:
+        :arg track_scores:
+        :arg track_total_hits:
         :arg typed_keys: Specify whether aggregation and suggester names
             should be prefixed by their respective types in the response
-        :arg version: Specify whether to return document version as part
-            of a hit
+        :arg version:
         """
         if "from_" in params:
             params["from"] = params.pop("from_")

elasticsearch/_async/client/__init__.pyi

@@ -23,6 +23,7 @@ from typing import (
     Any,
     Collection,
     Dict,
+    List,
     Mapping,
     MutableMapping,
     Optional,
@@ -32,6 +33,8 @@ from typing import (
     Union,
 )
 
+from typing_extensions import Literal
+
 from ..transport import AsyncTransport
 from .async_search import AsyncSearchClient
 from .autoscaling import AutoscalingClient
@@ -841,49 +844,78 @@ class AsyncElasticsearch(object):
         self,
         *,
         body: Optional[Mapping[str, Any]] = ...,
-        index: Optional[Any] = ...,
-        doc_type: Optional[Any] = ...,
-        _source: Optional[Any] = ...,
-        _source_excludes: Optional[Any] = ...,
-        _source_includes: Optional[Any] = ...,
+        index: Optional[Union[List[str], str]] = ...,
+        doc_type: Optional[Union[List[str], str]] = ...,
+        _source: Optional[Union[Union[List[str], str], bool]] = ...,
+        _source_excludes: Optional[Union[List[str], str]] = ...,
+        _source_includes: Optional[Union[List[str], str]] = ...,
+        aggregations: Optional[Mapping[str, Mapping[str, Any]]] = ...,
+        aggs: Optional[Mapping[str, Mapping[str, Any]]] = ...,
         allow_no_indices: Optional[bool] = ...,
         allow_partial_search_results: Optional[bool] = ...,
         analyze_wildcard: Optional[bool] = ...,
-        analyzer: Optional[Any] = ...,
-        batched_reduce_size: Optional[Any] = ...,
+        analyzer: Optional[str] = ...,
+        batched_reduce_size: Optional[int] = ...,
         ccs_minimize_roundtrips: Optional[bool] = ...,
-        default_operator: Optional[Any] = ...,
-        df: Optional[Any] = ...,
-        docvalue_fields: Optional[Any] = ...,
-        expand_wildcards: Optional[Any] = ...,
+        collapse: Optional[Mapping[str, Any]] = ...,
+        default_operator: Optional[Union[Literal["AND", "OR"], str]] = ...,
+        df: Optional[str] = ...,
+        docvalue_fields: Optional[Union[List[str], str]] = ...,
+        expand_wildcards: Optional[
+            Union[
+                List[Union[Literal["all", "open", "closed", "hidden", "none"], str]],
+                Union[Literal["all", "open", "closed", "hidden", "none"], str],
+                str,
+            ]
+        ] = ...,
         explain: Optional[bool] = ...,
-        from_: Optional[Any] = ...,
+        fields: Optional[List[Union[Mapping[str, Any], str]]] = ...,
+        from_: Optional[int] = ...,
+        highlight: Optional[Mapping[str, Any]] = ...,
         ignore_throttled: Optional[bool] = ...,
         ignore_unavailable: Optional[bool] = ...,
+        indices_boost: Optional[List[Mapping[str, float]]] = ...,
         lenient: Optional[bool] = ...,
-        max_concurrent_shard_requests: Optional[Any] = ...,
-        min_compatible_shard_node: Optional[Any] = ...,
-        pre_filter_shard_size: Optional[Any] = ...,
-        preference: Optional[Any] = ...,
-        q: Optional[Any] = ...,
+        max_concurrent_shard_requests: Optional[int] = ...,
+        min_compatible_shard_node: Optional[str] = ...,
+        min_score: Optional[float] = ...,
+        pit: Optional[Mapping[str, Any]] = ...,
+        post_filter: Optional[Mapping[str, Any]] = ...,
+        pre_filter_shard_size: Optional[int] = ...,
+        preference: Optional[str] = ...,
+        profile: Optional[bool] = ...,
+        q: Optional[str] = ...,
+        query: Optional[Mapping[str, Any]] = ...,
         request_cache: Optional[bool] = ...,
+        rescore: Optional[Union[List[Mapping[str, Any]], Mapping[str, Any]]] = ...,
         rest_total_hits_as_int: Optional[bool] = ...,
-        routing: Optional[Any] = ...,
-        scroll: Optional[Any] = ...,
-        search_type: Optional[Any] = ...,
+        routing: Optional[str] = ...,
+        runtime_mappings: Optional[Mapping[str, Mapping[str, Any]]] = ...,
+        script_fields: Optional[Mapping[str, Mapping[str, Any]]] = ...,
+        scroll: Optional[Union[int, str]] = ...,
+        search_after: Optional[List[Union[None, float, int, str]]] = ...,
+        search_type: Optional[
+            Union[Literal["query_then_fetch", "dfs_query_then_fetch"], str]
+        ] = ...,
         seq_no_primary_term: Optional[bool] = ...,
-        size: Optional[Any] = ...,
-        sort: Optional[Any] = ...,
-        stats: Optional[Any] = ...,
-        stored_fields: Optional[Any] = ...,
-        suggest_field: Optional[Any] = ...,
-        suggest_mode: Optional[Any] = ...,
-        suggest_size: Optional[Any] = ...,
-        suggest_text: Optional[Any] = ...,
-        terminate_after: Optional[Any] = ...,
-        timeout: Optional[Any] = ...,
+        size: Optional[int] = ...,
+        slice: Optional[Mapping[str, Any]] = ...,
+        sort: Optional[Union[List[str], str]] = ...,
+        stats: Optional[List[str]] = ...,
+        stored_fields: Optional[Union[List[str], str]] = ...,
+        suggest: Optional[
+            Union[Mapping[str, Any], Mapping[str, Mapping[str, Any]]]
+        ] = ...,
+        suggest_field: Optional[str] = ...,
+        suggest_mode: Optional[
+            Union[Literal["missing", "popular", "always"], str]
+        ] = ...,
+        suggest_size: Optional[int] = ...,
+        suggest_text: Optional[str] = ...,
+        terminate_after: Optional[int] = ...,
+        timeout: Optional[Union[int, str]] = ...,
         track_scores: Optional[bool] = ...,
-        track_total_hits: Optional[bool] = ...,
+        track_total_hits: Optional[Union[bool, int]] = ...,
         typed_keys: Optional[bool] = ...,
         version: Optional[bool] = ...,
         pretty: Optional[bool] = ...,

elasticsearch/_async/helpers.py

@@ -353,8 +353,11 @@ async def async_scan(
             scroll_kwargs.setdefault(key, val)
 
     # initial search
+    search_kwargs = kwargs.copy()
+    if query:
+        search_kwargs.update(query)
     resp = await client.search(
-        body=query, scroll=scroll, size=size, request_timeout=request_timeout, **kwargs
+        scroll=scroll, size=size, request_timeout=request_timeout, **search_kwargs
     )
     scroll_id = resp.get("_scroll_id")