View Source ElasticsearchEx.Api.Search.Core (Elasticsearch_ex v0.3.1)

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

Types

Represents the body expected by the async_search API.

Represents the ID returned by the async_search function.

The possible individual options accepted by the async_search function.

The possible options accepted by the async_search function.

The possible individual options accepted by the create_pit function

The possible options accepted by the create_pit function

Represents the body expected by the multi_search API.

The possible individual options accepted by the multi_search function.

The possible options accepted by the multi_search function.

The identifier for a Point in Time

The identifier for a scroll

Represents the body expected by the search API.

The possible individual options accepted by the search function.

The possible options accepted by the search function.

Represents the body expected by the terms_enum API

The possible individual options accepted by the terms_enum function

The possible options accepted by the terms_enum function

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.

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.

Returns search hits that match the query defined in the request.

The terms enum API can be used to discover terms in the index that match a partial string.

Types

@type async_search_body() :: map()

Represents the body expected by the async_search API.

@type async_search_id() :: binary()

Represents the ID returned by the async_search function.

@type async_search_opt() :: {:index, atom() | binary()}

The possible individual options accepted by the async_search function.

@type async_search_opts() :: [
  async_search_opt() | {:http_opts, keyword()} | {atom(), any()}
]

The possible options accepted by the async_search function.

@type create_pit_opt() :: {:index, atom() | binary()} | {:keep_alive, binary()}

The possible individual options accepted by the create_pit function

@type create_pit_opts() :: [
  create_pit_opt() | {:http_opts, keyword()} | {atom(), any()}
]

The possible options accepted by the create_pit function

@type multi_search_body() :: Enumerable.t()

Represents the body expected by the multi_search API.

@type multi_search_opt() :: {:index, atom() | binary()}

The possible individual options accepted by the multi_search function.

@type multi_search_opts() :: [
  search_opt() | {:http_opts, keyword()} | {atom(), any()}
]

The possible options accepted by the multi_search function.

@type pit_id() :: binary()

The identifier for a Point in Time

@type scroll_id() :: binary()

The identifier for a scroll

@type search_body() :: map()

Represents the body expected by the search API.

@type search_opt() :: {:index, atom() | binary()}

The possible individual options accepted by the search function.

@type search_opts() :: [search_opt() | {:http_opts, keyword()} | {atom(), any()}]

The possible options accepted by the search function.

@type terms_enum_body() :: map()

Represents the body expected by the terms_enum API

@type terms_enum_opt() :: {:index, atom() | binary()}

The possible individual options accepted by the terms_enum function

@type terms_enum_opts() :: [
  terms_enum_opt() | {:http_opts, keyword()} | {atom(), any()}
]

The possible options accepted by the terms_enum function

Functions

Link to this function

async_search(query, opts \\ [])

View Source
@spec async_search(async_search_body(), async_search_opts()) ::
  ElasticsearchEx.Client.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.Core.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
 }}
Link to this function

clear_scroll(scroll_id, opts \\ [])

View Source
@spec clear_scroll(scroll_id(), [{:http_opts, keyword()} | {atom(), any()}]) ::
  ElasticsearchEx.Client.response()

Clears the search context and results for a scrolling search.

Examples

iex> ElasticsearchEx.Api.Search.Core.clear_scroll(
...>   "FGluY2x1ZGVfY29udGV4dF91dWlkDXF1ZXJ5QW5kRmV0Y2gBFnZaRlo5M2xHUzN1VFdLUUxTUDFXOUEAAAAAAAAAWRZBdENUeTlIalF2bWs4WGlOaEVFZTd3"
...> )
{:ok, %{"num_freed" => 1, "succeeded" => true}}
Link to this function

close_pit(pit_id, opts \\ [])

View Source
@spec close_pit(pit_id(), [{:http_opts, keyword()} | {atom(), any()}]) ::
  ElasticsearchEx.Client.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.Core.close_pit("gcSHBAEJb2Jhbl9qb2JzFmJsOTBBMHEwUTVld19yQ3RBYkEtSVEAFkF0Q1R5OUhqUXZtazhYaU5oRUVlN3cAAAAAAAAAAFUWdlpGWjkzbEdTM3VUV0tRTFNQMVc5QQABFmJsOTBBMHEwUTVld19yQ3RBYkEtSVEAAA==")
{:ok, %{"num_freed" => 1, "succeeded" => true}}
@spec create_pit(create_pit_opts()) :: ElasticsearchEx.Client.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.Core.create_pit(index: :my-index-000001, keep_alive: "5m")
{:ok,
 %{
   "id" => "gcSHBAEJb2Jhbl9qb2JzFmJsOTBBMHEwUTVld19yQ3RBYkEtSVEAFkF0Q1R5OUhqUXZtazhYaU5oRUVlN3cAAAAAAAAAAFUWdlpGWjkzbEdTM3VUV0tRTFNQMVc5QQABFmJsOTBBMHEwUTVld19yQ3RBYkEtSVEAAA=="
 }}
Link to this function

delete_async_search(async_search_id, opts \\ [])

View Source
@spec delete_async_search(async_search_id(), [
  {:http_opts, keyword()} | {atom(), any()}
]) ::
  ElasticsearchEx.Client.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.Core.delete_async_search("FmRldE8zREVEUzA2ZVpUeGs2ejJFUFEaMkZ5QTVrSTZSaVN3WlNFVmtlWHJsdzoxMDc=")
nil
Link to this function

get_async_search(async_search_id, opts \\ [])

View Source
@spec get_async_search(async_search_id(), [{:http_opts, keyword()} | {atom(), any()}]) ::
  ElasticsearchEx.Client.response()

The get async search API retrieves the results of a previously submitted async search request given its id.

Examples

iex> ElasticsearchEx.Api.Search.Core.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
 }}
Link to this function

get_async_search_status(async_search_id, opts \\ [])

View Source
@spec get_async_search_status(async_search_id(), [
  {:http_opts, keyword()} | {atom(), any()}
]) ::
  ElasticsearchEx.Client.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.Core.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
 }}
Link to this function

get_scroll(scroll_id, opts \\ [])

View Source
@spec get_scroll(scroll_id(), [{:http_opts, keyword()} | {atom(), any()}]) ::
  ElasticsearchEx.Client.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.Core.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
 }}
Link to this function

multi_search(queries, opts \\ [])

View Source
@spec multi_search(multi_search_body(), multi_search_opts()) ::
  ElasticsearchEx.Client.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.Core.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
 }}
Link to this function

search(query, opts \\ [])

View Source
@spec search(search_body(), search_opts()) :: ElasticsearchEx.Client.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.Core.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
 }}
Link to this function

terms_enum(query, opts \\ [])

View Source
@spec terms_enum(terms_enum_body(), terms_enum_opts()) ::
  ElasticsearchEx.Client.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.Core.terms_enum(%{"field" => "tags", "string" => "kiba"},
...>   index: "stackoverflow"
...> )
{:ok,
 %{
   "_shards" => %{"failed" => 0, "successful" => 1, "total" => 1},
   "complete" => true,
   "terms" => ["kibana"]
 }}