--- type: api title: Run a search with a search template description: **All methods and paths for this operation:** url: https://www.elastic.co/elastic/docs-builder/docs/4493/api/doc/elasticsearch/v8/operation/operation-search-template resource: https://www.elastic.co/elastic/docs-builder/docs/4493/api/doc/elasticsearch/v8/operation/operation-search-template products: - Elasticsearch --- # Run a search with a search template Availability: Generally available since 2.0 ## Paths - `POST` (also `GET`) `/{index}/_search/template` - `POST` (also `GET`) `/_search/template` #### Path parameters - `index` (union string | string[]) — optional, leave it out to use `/_search/template` A comma-separated list of data streams, indices, and aliases to search. It supports wildcards (`*`). ## Description [Read the reference documentation](https://www.elastic.co/guide/en/elasticsearch/reference/8.19/search-template.html) ## Required authorization - Index privileges: `read` ## Authentication - Api key: `Authorization: ` Elasticsearch APIs support key-based authentication. You must create an API key and use the encoded value in the request header. For example: ``` curl -X GET "${ES_URL}/_cat/indices?v=true" \ -H "Authorization: ApiKey ${API_KEY}" ``` To get API keys, use the `/_security/api_key` APIs. - Basic: `Authorization: Basic ` - Bearer: `Authorization: Bearer ` Elasticsearch APIs support the use of bearer tokens in the `Authorization` HTTP header to authenticate with the API. For examples, refer to [Token-based authentication services](https://www.elastic.co/guide/en/elasticsearch/reference/current/token-authentication-services.html) ## Query string parameters - `allow_no_indices` (boolean · default: true) — optional 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`. - `ccs_minimize_roundtrips` (boolean · default: false) — optional If `true`, network round-trips are minimized for cross-cluster search requests. - `expand_wildcards` (string · default: open) — optional 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. Supports comma-separated values, such as `open,hidden`. Supported values include: - `all`: Match any data stream or index, including hidden ones. - `open`: Match open, non-hidden indices. Also matches any non-hidden data stream. - `closed`: Match closed, non-hidden indices. Also matches any non-hidden data stream. Data streams cannot be closed. - `hidden`: Match hidden data streams and hidden indices. Must be combined with `open`, `closed`, or `both`. - `none`: Wildcard expressions are not accepted. Values: `all`, `open`, `closed`, `hidden`, `none` - `explain` (boolean · default: false) — optional If `true`, the response includes additional details about score computation as part of a hit. - `ignore_throttled` (boolean · default: true) — optional — deprecated If `true`, specified concrete, expanded, or aliased indices are not included in the response when throttled. - `ignore_unavailable` (boolean · default: false) — optional If `false`, the request returns an error if it targets a missing or closed index. - `preference` (string) — optional The node or shard the operation should be performed on. It is random by default. - `profile` (boolean · default: false) — optional If `true`, the query execution is profiled. - `routing` (string) — optional A custom value used to route operations to a specific shard. - `scroll` (string) — optional Specifies how long a consistent view of the index should be maintained for scrolled search. - `search_type` (enum) — optional The type of the search operation. Supported values include: - `query_then_fetch`: Documents are scored using local term and document frequencies for the shard. This is usually faster but less accurate. - `dfs_query_then_fetch`: Documents are scored using global term and document frequencies across all shards. This is usually slower but more accurate. Values: `query_then_fetch`, `dfs_query_then_fetch` - `rest_total_hits_as_int` (boolean · default: false) — optional If `true`, `hits.total` is rendered as an integer in the response. If `false`, it is rendered as an object. - `typed_keys` (boolean · default: false) — optional If `true`, the response prefixes aggregation and suggester names with their respective types. ## Request body `application/json` - `explain` (boolean · default: false) — optional If `true`, returns detailed information about score calculation as part of each hit. If you specify both this and the `explain` query parameter, the API uses only the query parameter. - `id` (string) — optional The ID of the search template to use. If no `source` is specified, this parameter is required. - `params` (map string to object) — optional Key-value pairs used to replace Mustache variables in the template. The key is the variable name. The value is the variable value. - `profile` (boolean · default: false) — optional If `true`, the query execution is profiled. - `source` (string) — optional An inline search template. Supports the same parameters as the search API's request body. It also supports Mustache variables. If no `id` is specified, this parameter is required. ## Response `application/json` - `took` (number) - `timed_out` (boolean) - `_shards` (object) - `failed` (number) The number of shards the operation or search attempted to run on but failed. - `successful` (number) The number of shards the operation or search succeeded on. - `total` (number) The number of shards the operation or search will run on overall. - `failures` (object[]) - `index` (string) - `node` (string) - `reason` (object) - `type` (string) The type of error - `reason` (union string) — nullable A human-readable explanation of the error, in English. One of: `string` - `stack_trace` (string) The server stack trace. Present only if the `error_trace=true` parameter was sent with the request. - `caused_by` (object) — recursive Same fields as `reason` in `failures` - `root_cause` (object[]) — recursive Same fields as `reason` in `failures` - `suppressed` (object[]) — recursive Same fields as `reason` in `failures` - `shard` (number) - `status` (string) - `primary` (boolean) - `skipped` (number) - `hits` (object) - `total` (union oneOf) Total hit count information, present only if `track_total_hits` wasn't `false` in the search request. - **{ relation, value }** - `relation` (enum) Supported values include: - `eq`: Accurate - `gte`: Lower bound, including returned events or sequences Values: `eq`, `gte` - `value` (number) - **number** - `hits` (object[]) - `_index` (string) - `_id` (string) - `_score` (union number | string) — nullable - `_explanation` (object) - `description` (string) - `details` (object[]) - `description` (string) - `details` (object[]) — recursive Same fields as `details` in `_explanation` - `value` (number) - `value` (number) - `fields` (map string to object) - `highlight` (map string to string) - `inner_hits` (map string to object) Map values (object) - `hits` (object) — recursive Same fields as `hits` - `matched_queries` (union oneOf) One of: `string[]` or `string to number` - `_nested` (object) - `field` (string) - `offset` (number) - `_nested` (object) — recursive Same fields as `_nested` in `hits` - `_ignored` (string[]) - `ignored_field_values` (map string to oneOf) - `_shard` (string) - `_node` (string) - `_routing` (string) - `_source` (object) - `_rank` (number) - `_seq_no` (number) - `_primary_term` (number) - `_version` (number) - `sort` (union[]) - `max_score` (union number | string) — nullable - `aggregations` (map string to {} Aggregation result) See [Aggregation result](https://www.elastic.co/elastic/docs-builder/docs/4493/api/doc/elasticsearch/v8/types/_types-aggregations-aggregate) - `_clusters` (object) - `skipped` (number) - `successful` (number) - `total` (number) - `running` (number) - `partial` (number) - `failed` (number) - `details` (map string to object) Map values (object) - `status` (enum) Values: `running`, `successful`, `partial`, `skipped`, `failed` - `indices` (string) - `took` (number) - `timed_out` (boolean) - `_shards` (object) Same fields as `_shards` - `failures` (object[]) Same fields as `failures` in `_shards` - `fields` (map string to object) - `max_score` (number) - `num_reduce_phases` (number) - `profile` (object) - `shards` (object[]) - `aggregations` (object[]) - `breakdown` (object) - `build_aggregation` (number) - `build_aggregation_count` (number) - `build_leaf_collector` (number) - `build_leaf_collector_count` (number) - `collect` (number) - `collect_count` (number) - `initialize` (number) - `initialize_count` (number) - `post_collection` (number) - `post_collection_count` (number) - `reduce` (number) - `reduce_count` (number) - `description` (string) - `time_in_nanos` (number) - `type` (string) - `debug` (object) - `segments_with_multi_valued_ords` (number) - `collection_strategy` (string) - `segments_with_single_valued_ords` (number) - `total_buckets` (number) - `built_buckets` (number) - `result_strategy` (string) - `has_filter` (boolean) - `delegate` (string) - `delegate_debug` (object) — recursive Same fields as `debug` in `aggregations` - `chars_fetched` (number) - `extract_count` (number) - `extract_ns` (number) - `values_fetched` (number) - `collect_analyzed_ns` (number) - `collect_analyzed_count` (number) - `surviving_buckets` (number) - `ordinals_collectors_used` (number) - `ordinals_collectors_overhead_too_high` (number) - `string_hashing_collectors_used` (number) - `numeric_collectors_used` (number) - `empty_collectors_used` (number) - `deferred_aggregators` (string[]) - `segments_with_doc_count_field` (number) - `segments_with_deleted_docs` (number) - `filters` (object[]) - `results_from_metadata` (number) - `query` (string) - `specialized_for` (string) - `segments_counted_in_constant_time` (number) - `segments_counted` (number) - `segments_collected` (number) - `map_reducer` (string) - `brute_force_used` (number) - `dynamic_pruning_attempted` (number) - `dynamic_pruning_used` (number) - `skipped_due_to_no_data` (number) - `children` (object[]) — recursive Same fields as `aggregations` in `shards` - `cluster` (string) - `dfs` (object) - `statistics` (object) - `type` (string) - `description` (string) - `time` (string) - `time_in_nanos` (number) - `breakdown` (object) - `collection_statistics` (number) - `collection_statistics_count` (number) - `create_weight` (number) - `create_weight_count` (number) - `rewrite` (number) - `rewrite_count` (number) - `term_statistics` (number) - `term_statistics_count` (number) - `debug` (map string to object) - `children` (object[]) — recursive Same fields as `statistics` in `dfs` - `knn` (object[]) - `vector_operations_count` (number) - `query` (object[]) - `type` (string) - `description` (string) - `time` (string) - `time_in_nanos` (number) - `breakdown` (object) - `advance` (number) - `advance_count` (number) - `build_scorer` (number) - `build_scorer_count` (number) - `compute_max_score` (number) - `compute_max_score_count` (number) - `count_weight` (number) - `count_weight_count` (number) - `create_weight` (number) - `create_weight_count` (number) - `match` (number) - `match_count` (number) - `next_doc` (number) - `next_doc_count` (number) - `score` (number) - `score_count` (number) - `set_min_competitive_score` (number) - `set_min_competitive_score_count` (number) - `shallow_advance` (number) - `shallow_advance_count` (number) - `debug` (map string to object) - `children` (object[]) — recursive Same fields as `query` in `knn` - `rewrite_time` (number) - `collector` (object[]) - `name` (string) - `reason` (string) - `time` (string) - `time_in_nanos` (number) - `children` (object[]) — recursive Same fields as `collector` in `knn` - `fetch` (object) - `type` (string) - `description` (string) - `time_in_nanos` (number) - `breakdown` (object) - `load_source` (number) - `load_source_count` (number) - `load_stored_fields` (number) - `load_stored_fields_count` (number) - `next_reader` (number) - `next_reader_count` (number) - `process_count` (number) - `process` (number) - `debug` (object) - `stored_fields` (string[]) - `fast_path` (number) - `children` (object[]) — recursive Same fields as `fetch` in `shards` - `id` (string) - `index` (string) - `node_id` (string) - `searches` (object[]) - `collector` (object[]) - `name` (string) - `reason` (string) - `time_in_nanos` (number) - `children` (object[]) — recursive Same fields as `collector` in `searches` - `query` (object[]) - `breakdown` (object) - `advance` (number) - `advance_count` (number) - `build_scorer` (number) - `build_scorer_count` (number) - `create_weight` (number) - `create_weight_count` (number) - `match` (number) - `match_count` (number) - `shallow_advance` (number) - `shallow_advance_count` (number) - `next_doc` (number) - `next_doc_count` (number) - `score` (number) - `score_count` (number) - `compute_max_score` (number) - `compute_max_score_count` (number) - `count_weight` (number) - `count_weight_count` (number) - `set_min_competitive_score` (number) - `set_min_competitive_score_count` (number) - `description` (string) - `time_in_nanos` (number) - `type` (string) - `children` (object[]) — recursive Same fields as `query` in `searches` - `rewrite_time` (number) - `shard_id` (number) - `pit_id` (string) - `_scroll_id` (string) - `suggest` (map string to oneOf) - `terminated_early` (boolean) ## Code examples #### Console ```console POST my-index/_search/template { "id": "my-search-template", "params": { "query_string": "hello world", "from": 0, "size": 10 } } ``` #### JavaScript ```javascript const response = await client.searchTemplate({ index: "my-index", id: "my-search-template", params: { query_string: "hello world", from: 0, size: 10, }, }); ``` #### Python ```python resp = client.search_template( index="my-index", id="my-search-template", params={ "query_string": "hello world", "from": 0, "size": 10 }, ) ``` #### curl ```curl curl -X POST "$ELASTICSEARCH_URL/my-index/_search/template" \ -H "Authorization: ApiKey $ELASTIC_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "id": "my-search-template", "params": { "query_string": "hello world", "from": 0, "size": 10 } }' ``` #### Java ```java client.searchTemplate(s -> s .id("my-search-template") .index("my-index") .params(Map.of("size", JsonData.fromJson("10"),"from", JsonData.fromJson("0"),"query_string", JsonData.fromJson("\"hello world\""))) ); ``` #### C# ```c# var response = await client .SearchTemplateAsync(d1 => d1 .Indices(new[] { "my-index" }) .Id("my-search-template") .Params(new Dictionary() { { "query_string", "hello world" }, { "from", 0 }, { "size", 10 } }) ); ``` #### PHP ```php $resp = $client->searchTemplate([ "index" => "my-index", "body" => [ "id" => "my-search-template", "params" => [ "query_string" => "hello world", "from" => 0, "size" => 10, ], ], ]); ``` #### Ruby ```ruby response = client.search_template( index: "my-index", body: { "id": "my-search-template", "params": { "query_string": "hello world", "from": 0, "size": 10 } } ) ```