View Source ElasticsearchEx.API.Search (Elasticsearch_ex v1.8.3)
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
Check async_search/3
for more information.
Check async_search/3
for more information.
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.
Check create_pit/2
for more information.
Check create_pit/2
for more information.
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.
Check field_capabilities/3
for more information.
Check field_capabilities/3
for more information.
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.
Retrieves the next batch of results for a scrolling search.
Check multi_search/3
for more information.
Check multi_search/3
for more information.
Executes several searches with a single API request.
Check multi_search_template/3
for more information.
Check multi_search_template/3
for more information.
Runs multiple templated searches with a single request.
Check profile/3
for more information.
Check profile/3
for more information.
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.
Check render_search_template/3
for more information.
Check render_search_template/3
for more information.
Renders a search template as a search request body.
Check search/3
for more information.
Check search/3
for more information.
Returns search hits that match the query defined in the request.
Returns the indices and shards that a search request would be executed against.
Check search_template/3
for more information.
Check search_template/3
for more information.
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()
@type response() :: ElasticsearchEx.response()
Functions
Check async_search/3
for more information.
@spec async_search(query(), nil | index()) :: response()
@spec async_search(query(), opts()) :: response()
Check async_search/3
for more information.
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
}}
Clears the search context and results for a scrolling search.
Examples
iex> ElasticsearchEx.API.Search.clear_scroll(
...> "FGluY2x1ZGVfY29udGV4dF91dWlkDXF1ZXJ5QW5kRmV0Y2gBFnZaRlo5M2xHUzN1VFdLUUxTUDFXOUEAAAAAAAAAWRZBdENUeTlIalF2bWs4WGlOaEVFZTd3"
...> )
{:ok, %{"num_freed" => 1, "succeeded" => true}}
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() :: response()
Check create_pit/2
for more information.
Check create_pit/2
for more information.
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=="
}}
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()) :: 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.
Check field_capabilities/3
for more information.
@spec field_capabilities(fields, nil | index()) :: response() when fields: binary() | [binary()]
@spec field_capabilities(fields, opts()) :: response() when fields: binary() | [binary()]
Check field_capabilities/3
for more information.
@spec field_capabilities(fields, nil | index(), opts()) :: response() when fields: binary() | [binary()]
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.
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
}}
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
}}
Retrieves the next batch of results for a scrolling search.
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(Enumerable.t()) :: response()
Check multi_search/3
for more information.
@spec multi_search(Enumerable.t(), nil | index()) :: response()
@spec multi_search(Enumerable.t(), opts()) :: response()
Check multi_search/3
for more information.
@spec multi_search(Enumerable.t(), nil | index(), opts()) :: 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
}}
@spec multi_search_template(Enumerable.t()) :: response()
Check multi_search_template/3
for more information.
@spec multi_search_template(Enumerable.t(), nil | index()) :: response()
@spec multi_search_template(Enumerable.t(), opts()) :: response()
Check multi_search_template/3
for more information.
@spec multi_search_template(Enumerable.t(), nil | index(), opts()) :: response()
Runs multiple templated searches with a single request.
Query parameters
Refer to the official documentation for a detailed list of the parameters.
Check profile/3
for more information.
Check profile/3
for more information.
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.
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.
Check render_search_template/3
for more information.
@spec render_search_template(map(), nil | binary()) :: response()
@spec render_search_template(map(), opts()) :: response()
Check render_search_template/3
for more information.
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() :: response()
Check search/3
for more information.
Examples
iex> ElasticsearchEx.API.Search.search()
{:ok, %{"hits" => %{"hits" => [%{"_id" => "0", "_index" => "my-index-000001", "_source" => %{}}]}}}
@spec search(query()) :: response()
@spec search(index()) :: response()
@spec search(opts()) :: response()
Check search/3
for more information.
Examples
With a query:
iex> ElasticsearchEx.API.Search.search(%{query: %{term: %{"user.id": "kimchy"}}})
{:ok, %{"hits" => %{"hits" => [%{"_id" => "0", "_index" => "my-index-000001", "_source" => %{}}]}}}
With a index:
iex> ElasticsearchEx.API.Search.search("my-index-000001")
{:ok, %{"hits" => %{"hits" => [%{"_id" => "0", "_index" => "my-index-000001", "_source" => %{}}]}}}
With options:
iex> ElasticsearchEx.API.Search.search(_source: false)
{:ok, %{"hits" => %{"hits" => [%{"_id" => "0", "_index" => "my-index-000001"}]}}}
@spec search(query(), nil | index()) :: response()
@spec search(nil | index(), opts()) :: response()
@spec search(query(), opts()) :: response()
Check search/3
for more information.
Examples
With a query and index:
iex> ElasticsearchEx.API.Search.search(%{query: %{term: %{"user.id": "kimchy"}}}, "my-index-000001")
{:ok, %{"hits" => %{"hits" => [%{"_id" => "0", "_index" => "my-index-000001", "_source" => %{}}]}}}
With a index and options:
iex> ElasticsearchEx.API.Search.search("my-index-000001", _source: false)
{:ok, %{"hits" => %{"hits" => [%{"_id" => "0", "_index" => "my-index-000001"}]}}}
With a query and options:
iex> ElasticsearchEx.API.Search.search(%{query: %{term: %{"user.id": "kimchy"}}}, _source: false)
{:ok, %{"hits" => %{"hits" => [%{"_id" => "0", "_index" => "my-index-000001"}]}}}
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"}}},
...> "my-index-000001",
...> 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
}}
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.
Check search_template/3
for more information.
@spec search_template(map(), nil | index()) :: response()
@spec search_template(map(), opts()) :: response()
Check search_template/3
for more information.
Runs a search with a search template.
Query parameters
Refer to the official documentation for a detailed list of the parameters.
@spec search_vector_tile( index(), atom() | binary(), integer(), integer(), integer(), opts() ) :: 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.
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.
Request body
Refer to the official documentation for a detailed list of the body values.
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"]
}}
Validates a potentially expensive query without executing it.
Query parameters
Refer to the official documentation for a detailed list of the parameters.