View Source ElasticsearchEx.Api.Search (Elasticsearch_ex v1.3.0)
Search APIs are used to search and aggregate data stored in Elasticsearch indices and data streams. For an overview and related tutorials, see The search API.
Most search APIs support multi-target syntax, with the exception of the explain API.
Summary
Functions
Executes a search request asynchronously. It accepts the same parameters and request body as the search API.
Clears the search context and results for a scrolling search.
Point-in-time is automatically closed when its keep_alive
has been elapsed. However keeping
point-in-times has a cost. Point-in-times should be closed as soon as they are no longer used in
search requests.
A search request by default executes against the most recent visible data of the target indices,
which is called point in time. Elasticsearch pit
(point in time) is a lightweight view into the
state of the data as it existed when initiated. In some cases, it’s preferred to perform multiple
search requests using the same point in time. For example, if refreshes happen between
search_after
requests, then the results of those requests might not be consistent as changes
happening between searches are only visible to the more recent point in time.
You can use the delete async search API to manually delete an async search by ID. If the search is still running, the search request will be cancelled. Otherwise, the saved search results are deleted.
Returns information about why a specific document matches (or doesn’t match) a query.
Allows you to retrieve the capabilities of fields among multiple indices. For data streams, the API returns field capabilities among the stream’s backing indices.
The get async search API retrieves the results of a previously submitted async search request given its id.
The get async search status API, without retrieving search results, shows only the status of a previously submitted async search request given its id.
Point-in-time is automatically closed when its keep_alive
has been elapsed. However keeping
point-in-times has a cost. Point-in-times should be closed as soon as they are no longer used in
search requests.
Executes several searches with a single API request.
Runs multiple templated searches with a single request.
Provides detailed timing information about the execution of individual components in a search request.
Allows you to evaluate the quality of ranked search results over a set of typical search queries.
Renders a search template as a search request body.
Returns search hits that match the query defined in the request.
Returns the indices and shards that a search request would be executed against.
Runs a search with a search template.
Searches a vector tile for geospatial values. Returns results as a binary Mapbox vector tile.
The terms enum API can be used to discover terms in the index that match a partial string.
Validates a potentially expensive query without executing it.
Types
@type document_id() :: ElasticsearchEx.document_id()
@type index() :: ElasticsearchEx.index()
@type opts() :: ElasticsearchEx.opts()
@type query() :: ElasticsearchEx.query()
Functions
@spec async_search(query(), nil | index(), opts()) :: ElasticsearchEx.response()
Executes a search request asynchronously. It accepts the same parameters and request body as the search API.
Query parameters
Refer to the official documentation for a detailed list of the parameters.
Request body
Refer to the official documentation for a detailed list of the parameters.
Examples
iex> ElasticsearchEx.Api.Search.async_search(
...> %{
...> aggs: %{sale_date: %{date_histogram: %{calendar_interval: "1d", field: "date"}}},
...> sort: [%{date: %{order: "asc"}}]
...> },
...> size: 0
...> )
{:ok,
%{
"expiration_time_in_millis" => 1584377890986,
"id" => "FmRldE8zREVEUzA2ZVpUeGs2ejJFUFEaMkZ5QTVrSTZSaVN3WlNFVmtlWHJsdzoxMDc=",
"is_partial" => true,
"is_running" => true,
"response" => %{
"_shards" => %{
"failed" => 0,
"skipped" => 0,
"successful" => 3,
"total" => 562
},
"hits" => %{
"hits" => [],
"max_score" => nil,
"total" => %{"relation" => "gte", "value" => 157483}
},
"num_reduce_phases" => 0,
"timed_out" => false,
"took" => 1122
},
"start_time_in_millis" => 1583945890986
}}
@spec clear_scroll(binary(), opts()) :: ElasticsearchEx.response()
Clears the search context and results for a scrolling search.
Examples
iex> ElasticsearchEx.Api.Search.clear_scroll(
...> "FGluY2x1ZGVfY29udGV4dF91dWlkDXF1ZXJ5QW5kRmV0Y2gBFnZaRlo5M2xHUzN1VFdLUUxTUDFXOUEAAAAAAAAAWRZBdENUeTlIalF2bWs4WGlOaEVFZTd3"
...> )
{:ok, %{"num_freed" => 1, "succeeded" => true}}
@spec close_pit(binary(), opts()) :: ElasticsearchEx.response()
Point-in-time is automatically closed when its keep_alive
has been elapsed. However keeping
point-in-times has a cost. Point-in-times should be closed as soon as they are no longer used in
search requests.
Examples
iex> ElasticsearchEx.Api.Search.close_pit("gcSHBAEJb2Jhbl9qb2JzFmJsOTBBMHEwUTVld19yQ3RBYkEtSVEAFkF0Q1R5OUhqUXZtazhYaU5oRUVlN3cAAAAAAAAAAFUWdlpGWjkzbEdTM3VUV0tRTFNQMVc5QQABFmJsOTBBMHEwUTVld19yQ3RBYkEtSVEAAA==")
{:ok, %{"num_freed" => 1, "succeeded" => true}}
@spec create_pit(index(), opts()) :: ElasticsearchEx.response()
A search request by default executes against the most recent visible data of the target indices,
which is called point in time. Elasticsearch pit
(point in time) is a lightweight view into the
state of the data as it existed when initiated. In some cases, it’s preferred to perform multiple
search requests using the same point in time. For example, if refreshes happen between
search_after
requests, then the results of those requests might not be consistent as changes
happening between searches are only visible to the more recent point in time.
Examples
iex> ElasticsearchEx.Api.Search.create_pit(index: :my-index-000001, keep_alive: "5m")
{:ok,
%{
"id" => "gcSHBAEJb2Jhbl9qb2JzFmJsOTBBMHEwUTVld19yQ3RBYkEtSVEAFkF0Q1R5OUhqUXZtazhYaU5oRUVlN3cAAAAAAAAAAFUWdlpGWjkzbEdTM3VUV0tRTFNQMVc5QQABFmJsOTBBMHEwUTVld19yQ3RBYkEtSVEAAA=="
}}
@spec delete_async_search(binary(), opts()) :: ElasticsearchEx.response()
You can use the delete async search API to manually delete an async search by ID. If the search is still running, the search request will be cancelled. Otherwise, the saved search results are deleted.
Examples
iex> ElasticsearchEx.Api.Search.delete_async_search("FmRldE8zREVEUzA2ZVpUeGs2ejJFUFEaMkZ5QTVrSTZSaVN3WlNFVmtlWHJsdzoxMDc=")
nil
@spec explain(query(), index(), document_id(), opts()) :: ElasticsearchEx.response()
Returns information about why a specific document matches (or doesn’t match) a query.
Query parameters
Refer to the official documentation for a detailed list of the parameters.
Request body
Refer to the official documentation for a detailed list of the body values.
field_capabilities(fields, index \\ nil, opts \\ [])
View Source (since 1.0.0)@spec field_capabilities(binary() | [binary()], nil | index(), opts()) :: ElasticsearchEx.response()
Allows you to retrieve the capabilities of fields among multiple indices. For data streams, the API returns field capabilities among the stream’s backing indices.
The query parameter fields
is provided via the first argument fields
.
Query parameters
Refer to the official documentation for a detailed list of the parameters.
@spec get_async_search(binary(), opts()) :: ElasticsearchEx.response()
The get async search API retrieves the results of a previously submitted async search request given its id.
Examples
iex> ElasticsearchEx.Api.Search.get_async_search("FmRldE8zREVEUzA2ZVpUeGs2ejJFUFEaMkZ5QTVrSTZSaVN3WlNFVmtlWHJsdzoxMDc=")
{:ok,
%{
"completion_time_in_millis" => 1583945903130,
"expiration_time_in_millis" => 1584377890986,
"id" => "FmRldE8zREVEUzA2ZVpUeGs2ejJFUFEaMkZ5QTVrSTZSaVN3WlNFVmtlWHJsdzoxMDc=",
"is_partial" => false,
"is_running" => false,
"response" => %{
"_shards" => %{
"failed" => 0,
"skipped" => 0,
"successful" => 188,
"total" => 562
},
"aggregations" => %{"sale_date" => %{"buckets" => []}},
"hits" => %{
"hits" => [],
"max_score" => nil,
"total" => %{"relation" => "eq", "value" => 456433}
},
"num_reduce_phases" => 46,
"timed_out" => false,
"took" => 12144
},
"start_time_in_millis" => 1583945890986
}}
get_async_search_status(async_search_id, opts \\ [])
View Source (since 1.0.0)@spec get_async_search_status(binary(), opts()) :: ElasticsearchEx.response()
The get async search status API, without retrieving search results, shows only the status of a previously submitted async search request given its id.
Examples
iex> ElasticsearchEx.Api.Search.get_async_search_status("FmRldE8zREVEUzA2ZVpUeGs2ejJFUFEaMkZ5QTVrSTZSaVN3WlNFVmtlWHJsdzoxMDc=")
{:ok,
%{
"_shards" => %{
"failed" => 0,
"skipped" => 0,
"successful" => 188,
"total" => 562
},
"expiration_time_in_millis" => 1584377890986,
"id" => "FmRldE8zREVEUzA2ZVpUeGs2ejJFUFEaMkZ5QTVrSTZSaVN3WlNFVmtlWHJsdzoxMDc=",
"is_partial" => true,
"is_running" => true,
"start_time_in_millis" => 1583945890986
}}
@spec get_scroll(binary(), opts()) :: ElasticsearchEx.response()
Point-in-time is automatically closed when its keep_alive
has been elapsed. However keeping
point-in-times has a cost. Point-in-times should be closed as soon as they are no longer used in
search requests.
Examples
iex> ElasticsearchEx.Api.Search.get_scroll(
...> "FGluY2x1ZGVfY29udGV4dF91dWlkDXF1ZXJ5QW5kRmV0Y2gBFnZaRlo5M2xHUzN1VFdLUUxTUDFXOUEAAAAAAAAAWRZBdENUeTlIalF2bWs4WGlOaEVFZTd3",
...> scroll: "1m"
...> )
{:ok,
%{
"_scroll_id" => "FGluY2x1ZGVfY29udGV4dF91dWlkDXF1ZXJ5QW5kRmV0Y2gBFnZaRlo5M2xHUzN1VFdLUUxTUDFXOUEAAAAAAAAAXRZBdENUeTlIalF2bWs4WGlOaEVFZTd3",
"_shards" => %{
"failed" => 0,
"skipped" => 0,
"successful" => 1,
"total" => 1
},
"hits" => %{
"hits" => [],
"max_score" => nil,
"total" => %{"relation" => "eq", "value" => 3}
},
"timed_out" => false,
"took" => 1
}}
@spec multi_search([query()], nil | index(), opts()) :: ElasticsearchEx.response()
Executes several searches with a single API request.
Query parameters
Refer to the official documentation for a detailed list of the parameters.
Request body
Refer to the official documentation for a detailed list of the body values.
Examples
iex> ElasticsearchEx.Api.Search.multi_search(
...> [
...> %{},
...> %{"query" => %{"match" => %{"message" => "this is a test"}}},
...> %{"index" => "my-index-000002"},
...> %{"query" => %{"match_all" => %{}}}
...> ],
...> allow_no_indices: false
...> )
{:ok,
%{
"responses" => [
%{
"_shards" => %{
"failed" => 0,
"skipped" => 0,
"successful" => 2,
"total" => 2
},
"hits" => %{
"hits" => [
%{
"_id" => "8-aORIwBU7w6JJjT4O86",
"_index" => "my-index-000001",
"_score" => 1.0,
"_source" => %{
"message": "this is a test"
}
}
],
"max_score" => nil,
"total" => %{"relation" => "eq", "value" => 0}
},
"status" => 200,
"timed_out" => false,
"took" => 14
},
%{
"_shards" => %{
"failed" => 0,
"skipped" => 0,
"successful" => 1,
"total" => 1
},
"hits" => %{
"hits" => [
%{
"_id" => "8uaORIwBU7w6JJjTX-8-",
"_index" => "my-index-000002",
"_score" => 1.0,
"_source" => %{
"message": "this another test"
}
}
],
"max_score" => 1.0,
"total" => %{"relation" => "eq", "value" => 3}
},
"status" => 200,
"timed_out" => false,
"took" => 11
}
],
"took" => 21
}}
multi_search_template(body, index \\ nil, opts \\ [])
View Source (since 1.0.0)@spec multi_search_template(Enumerable.t(), nil | index(), opts()) :: ElasticsearchEx.response()
Runs multiple templated searches with a single request.
Query parameters
Refer to the official documentation for a detailed list of the parameters.
@spec profile(query(), nil | index(), opts()) :: ElasticsearchEx.response()
Provides detailed timing information about the execution of individual components in a search request.
Warning: The Profile API is a debugging tool and adds significant overhead to search execution.
@spec rank_evaluation(map(), index(), opts()) :: ElasticsearchEx.response()
Allows you to evaluate the quality of ranked search results over a set of typical search queries.
Query parameters
Refer to the official documentation for a detailed list of the parameters.
render_search_template(body, template_id \\ nil, opts \\ [])
View Source (since 1.0.0)@spec render_search_template(map(), nil | binary(), opts()) :: ElasticsearchEx.response()
Renders a search template as a search request body.
Request body
Refer to the official documentation for a detailed list of the request body.
@spec search(query(), index(), opts()) :: ElasticsearchEx.response()
Returns search hits that match the query defined in the request.
It expects the first argument to be a valid Elasticsearch query represented by an Elixir Map
.
Query parameters
Refer to the official documentation for a detailed list of the parameters.
Request body
Refer to the official documentation for a detailed list of the body values.
Examples
iex> ElasticsearchEx.Api.Search.search(%{query: %{term: %{"user.id": "kimchy"}}},
...> from: 40,
...> size: 20
...> )
{:ok,
%{
"_shards" => %{
"failed" => 0,
"skipped" => 0,
"successful" => 1,
"total" => 1
},
"hits" => %{
"hits" => [
%{
"_id" => "0",
"_index" => "my-index-000001",
"_score" => 1.3862942,
"_source" => %{
"@timestamp" => "2099-11-15T14:12:12",
"http" => %{
"request" => %{"method" => "get"},
"response" => %{"bytes" => 1070000, "status_code" => 200},
"version" => "1.1"
},
"message" => "GET /search HTTP/1.1 200 1070000",
"source" => %{"ip" => "127.0.0.1"},
"user" => %{"id" => "kimchy"}
}
},
...
],
"max_score" => 1.3862942,
"total" => %{"relation" => "eq", "value" => 20}
},
"timed_out" => false,
"took" => 5
}}
@spec search_shards(index(), opts()) :: ElasticsearchEx.response()
Returns the indices and shards that a search request would be executed against.
Query parameters
Refer to the official documentation for a detailed list of the parameters.
@spec search_template(map(), nil | index(), opts()) :: ElasticsearchEx.response()
Runs a search with a search template.
Query parameters
Refer to the official documentation for a detailed list of the parameters.
search_vector_tile(index, field, zoom, x, y, opts \\ [])
View Source (since 1.0.0)@spec search_vector_tile( index(), atom() | binary(), integer(), integer(), integer(), opts() ) :: ElasticsearchEx.response()
Searches a vector tile for geospatial values. Returns results as a binary Mapbox vector tile.
Query parameters
Refer to the official documentation for a detailed list of the parameters.
@spec terms_enum(map(), index(), opts()) :: ElasticsearchEx.response()
The terms enum API can be used to discover terms in the index that match a partial string.
Supported field types are keyword
, constant_keyword
, flattened
, version
and ip
.
This is used for auto-complete.
Examples
iex> ElasticsearchEx.Api.Search.terms_enum(%{"field" => "tags", "string" => "kiba"},
...> index: "stackoverflow"
...> )
{:ok,
%{
"_shards" => %{"failed" => 0, "successful" => 1, "total" => 1},
"complete" => true,
"terms" => ["kibana"]
}}
@spec validate(query(), nil | index(), opts()) :: ElasticsearchEx.response()
Validates a potentially expensive query without executing it.
Query parameters
Refer to the official documentation for a detailed list of the parameters.