Elasticsearch (elasticsearch v1.1.0) View Source

Entry-point for interacting with your Elasticsearch cluster(s).

You should configure at least one Elasticsearch.Cluster in order to use the functions in this module, or else you'll need to pass all the configuration for the cluster into each function call.

Telemetry

The following events are published:

[:elasticsearch, :request, :start] - emitted at the beginning of the request to Elasticsearch.
- Measurement: %{system_time: System.system_time()}
- Metadata: %{telemetry_span_context: term(), config: Elasticsearch.Cluster.config(), method: Elasticsearch.API.method(), url: Elasticsearch.API.url(), data: Elasticsearch.API.data()}
[:elasticsearch, :request, :stop] - emitted at the end of the request to Elasticsearch.
- Measurement: %{duration: native_time}
- Metadata: %{telemetry_span_context: term(), result: Elasticsearch.API.response()}
[:elasticsearch, :request, :exception] - emitted when an exception has been raised.
- Measurement: %{system_time: System.system_time()}
- Metadata: %{telemetry_span_context: term(), kind: Exception.kind(), reason: term(), stacktrace: Exception.stacktrace()}

Link to this section Summary

Types

data()

index_name()

opts()

response()

url()

Functions

delete(cluster, url, opts \\ [])

Deletes data at a given Elasticsearch URL.

delete!(cluster, url, opts \\ [])

Same as delete/1, but returns the response and raises errors.

delete_document(cluster, document, index)

Deletes a document from a given index.

delete_document!(cluster, document, index)

Same as delete_document/2, but raises on errors.

get(cluster, url, opts \\ [])

Gets the contents of a path from the Elasticsearch API.

get!(cluster, url, opts \\ [])

The same as get/1, but returns the response instead of a tuple. Raises on errors.

head(cluster, url, opts \\ [])

Determines whether a resource exists at a given Elasticsearch path

head!(cluster, url, opts \\ [])

Same as head/1, but returns the response and raises errors.

post(cluster, url, data, opts \\ [])

Posts data or queries to a given Elasticsearch path.

post!(cluster, url, data, opts \\ [])

The same as post/1, but returns the response. Raises on errors.

post_document(cluster, document, index)

Creates a document in a given index. Use this function when your documents do not have IDs or you want to use Elasticsearch's automatic ID generation.

put(cluster, url, data, opts \\ [])

Puts data to a given Elasticsearch API path.

put!(cluster, url, data, opts \\ [])

The same as put/2, but returns the response instead of a tuple. Raises on errors.

put_document(cluster, document, index)

Creates or updates a document in a given index.

put_document!(cluster, document, index)

Same as put_document/2, but raises on errors.

wait_for_boot(cluster, tries, count \\ 0)

Waits for a given Elasticsearch cluster to be available.

Link to this section Types

data()

Specs

data() :: map() | String.t()

index_name()

Specs

index_name() :: String.t()

opts()

Specs

opts() :: Keyword.t()

response()

Specs

response() :: {:ok, map()} | {:error, Elasticsearch.Exception.t()}

url()

Specs

url() :: Path.t()

Link to this section Functions

delete(cluster, url, opts \\ [])

Specs

delete(Elasticsearch.Cluster.t(), url(), opts()) :: response()

Deletes data at a given Elasticsearch URL.

Examples

iex> Index.create_from_file(Cluster, "posts", "test/support/settings/posts.json")
...> Elasticsearch.delete(Cluster, "/posts")
{:ok, %{"acknowledged" => true}}

It returns an error if the given resource does not exist.

iex> Elasticsearch.delete(Cluster, "/nonexistent")
{:error,
 %Elasticsearch.Exception{col: nil, line: nil,
  message: "no such index", query: nil,
  raw: %{"error" => %{"index" => "nonexistent",
      "index_uuid" => "_na_", "reason" => "no such index",
      "resource.id" => "nonexistent",
      "resource.type" => "index_or_alias",
      "root_cause" => [%{"index" => "nonexistent",
         "index_uuid" => "_na_", "reason" => "no such index",
         "resource.id" => "nonexistent",
         "resource.type" => "index_or_alias",
         "type" => "index_not_found_exception"}],
      "type" => "index_not_found_exception"}, "status" => 404},
  status: 404, type: "index_not_found_exception"}}

delete!(cluster, url, opts \\ [])

Specs

delete!(Elasticsearch.Cluster.t(), url(), opts()) :: map() | no_return()

Same as delete/1, but returns the response and raises errors.

Examples

iex> Index.create_from_file(Cluster, "posts", "test/support/settings/posts.json")
...> Elasticsearch.delete!(Cluster, "/posts")
%{"acknowledged" => true}

Raises an error if the resource is invalid.

iex> Elasticsearch.delete!(Cluster, "/nonexistent")
** (Elasticsearch.Exception) (index_not_found_exception) no such index

delete_document(cluster, document, index)

Specs

delete_document(
  Elasticsearch.Cluster.t(),
  Elasticsearch.Document.t(),
  index_name()
) :: response()

Deletes a document from a given index.

The document must implement the Elasticsearch.Document protocol.

Example

iex> Index.create_from_file(Cluster, "posts-1", "test/support/settings/posts.json")
...> struct = %Post{id: 123, title: "Post", author: "Author"}
...> Elasticsearch.put_document!(Cluster, struct, "posts-1")
...> Elasticsearch.delete_document(Cluster, struct, "posts-1")
{:ok,
  %{
    "_id" => "123",
    "_index" => "posts-1",
    "_primary_term" => 1,
    "_seq_no" => 1,
    "_shards" => %{"failed" => 0, "successful" => 1, "total" => 2},
    "_type" => "_doc",
    "_version" => 2,
    "result" => "deleted"
  }}

delete_document!(cluster, document, index)

Specs

delete_document!(
  Elasticsearch.Cluster.t(),
  Elasticsearch.Document.t(),
  index_name()
) :: map() | no_return()

Same as delete_document/2, but raises on errors.

Example

iex> Index.create_from_file(Cluster, "posts-1", "test/support/settings/posts.json")
...> struct = %Post{id: 123, title: "Post", author: "Author"}
...> Elasticsearch.put_document!(Cluster, struct, "posts-1")
...> Elasticsearch.delete_document!(Cluster, struct, "posts-1")
%{
  "_id" => "123",
  "_index" => "posts-1",
  "_primary_term" => 1,
  "_seq_no" => 1,
  "_shards" => %{"failed" => 0, "successful" => 1, "total" => 2},
  "_type" => "_doc",
  "_version" => 2,
  "result" => "deleted"
}

get(cluster, url, opts \\ [])

Specs

get(Elasticsearch.Cluster.t(), url(), opts()) :: response()

Gets the contents of a path from the Elasticsearch API.

Examples

iex> {:ok, resp} = Elasticsearch.get(Cluster, "/_cat/health?format=json")
...> is_list(resp)
true

iex> Elasticsearch.get(Cluster, "/nonexistent")
{:error,
 %Elasticsearch.Exception{col: nil, line: nil,
  message: "no such index", query: nil,
  raw: %{"error" => %{"index" => "nonexistent",
      "index_uuid" => "_na_", "reason" => "no such index",
      "resource.id" => "nonexistent",
      "resource.type" => "index_or_alias",
      "root_cause" => [%{"index" => "nonexistent",
         "index_uuid" => "_na_", "reason" => "no such index",
         "resource.id" => "nonexistent",
         "resource.type" => "index_or_alias",
         "type" => "index_not_found_exception"}],
      "type" => "index_not_found_exception"}, "status" => 404},
  status: 404, type: "index_not_found_exception"}}

get!(cluster, url, opts \\ [])

Specs

get!(Elasticsearch.Cluster.t(), url(), opts()) :: map() | no_return()

The same as get/1, but returns the response instead of a tuple. Raises on errors.

Examples

iex> resp = Elasticsearch.get!(Cluster, "/_cat/health?format=json")
...> is_list(resp)
true

iex> Elasticsearch.get!(Cluster, "/nonexistent")
** (Elasticsearch.Exception) (index_not_found_exception) no such index

head(cluster, url, opts \\ [])

Specs

head(Elasticsearch.Cluster.t(), url(), opts()) :: response()

Determines whether a resource exists at a given Elasticsearch path

Examples

iex> Index.create_from_file(Cluster, "posts", "test/support/settings/posts.json")
...> Elasticsearch.head(Cluster, "/posts")
{:ok, ""}

It returns an error if the given resource does not exist.

iex> Elasticsearch.head(Cluster, "/nonexistent")
{:error,
%Elasticsearch.Exception{
  col: nil,
  line: nil,
  message: "",
  query: nil,
  raw: nil,
  status: nil,
  type: nil
}}

head!(cluster, url, opts \\ [])

Specs

head!(Elasticsearch.Cluster.t(), url(), opts()) :: map() | no_return()

Same as head/1, but returns the response and raises errors.

Examples

iex> Index.create_from_file(Cluster, "posts", "test/support/settings/posts.json")
...> Elasticsearch.head!(Cluster, "/posts")
""

Raises an error if the resource is invalid.

iex> Elasticsearch.head!(Cluster, "/nonexistent")
** (Elasticsearch.Exception)

post(cluster, url, data, opts \\ [])

Specs

post(Elasticsearch.Cluster.t(), url(), data(), opts()) :: response()

Posts data or queries to a given Elasticsearch path.

Examples

iex> Index.create_from_file(Cluster, "posts", "test/support/settings/posts.json")
...> query = %{"query" => %{"match_all" => %{}}}
...> {:ok, resp} = Elasticsearch.post(Cluster, "/posts/_search", query)
...> resp["hits"]["hits"]
[]

post!(cluster, url, data, opts \\ [])

Specs

post!(Elasticsearch.Cluster.t(), url(), data(), opts()) :: map() | no_return()

The same as post/1, but returns the response. Raises on errors.

Examples

iex> Index.create_from_file(Cluster, "posts", "test/support/settings/posts.json")
...> query = %{"query" => %{"match_all" => %{}}}
...> resp = Elasticsearch.post!(Cluster, "/posts/_search", query)
...> is_map(resp)
true

Raises an error if the path is invalid or another error occurs:

iex> query = %{"query" => %{"match_all" => %{}}}
...> Elasticsearch.post!(Cluster, "/nonexistent/_search", query)
** (Elasticsearch.Exception) (index_not_found_exception) no such index

post_document(cluster, document, index)

Specs

post_document(
  Elasticsearch.Cluster.t(),
  Elasticsearch.Document.t(),
  index_name()
) :: response()

Creates a document in a given index. Use this function when your documents do not have IDs or you want to use Elasticsearch's automatic ID generation.

https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-index_.html#_automatic_id_generation

The document must implement the Elasticsearch.Document. protocol.

Example

Index.create_from_file(Cluster, "posts-1", "test/support/settings/posts.json")
Elasticsearch.post_document(Cluster, %Post{title: "Post"}, "posts-1")
# => {:ok,
# =>   %{
# =>     "_id" => "W0tpsmIBdwcYyG50zbta",
# =>     "_index" => "posts-1",
# =>     "_primary_term" => 1,
# =>     "_seq_no" => 0,
# =>     "_shards" => %{"failed" => 0, "successful" => 1, "total" => 2},
# =>     "_type" => "_doc",
# =>     "_version" => 1,
# =>     "result" => "created"
# =>   }}

put(cluster, url, data, opts \\ [])

Specs

put(Elasticsearch.Cluster.t(), url(), data(), opts()) :: response()

Puts data to a given Elasticsearch API path.

Examples

iex> Index.create_from_file(Cluster, "posts-1", "test/support/settings/posts.json")
...> Elasticsearch.put(Cluster, "/posts-1/_doc/id", %{"title" => "title", "author" => "author"})
{:ok,
  %{
    "_id" => "id",
    "_index" => "posts-1",
    "_primary_term" => 1,
    "_seq_no" => 0,
    "_shards" => %{"failed" => 0, "successful" => 1, "total" => 2},
    "_type" => "_doc",
    "_version" => 1,
    "result" => "created"
  }}

iex> Elasticsearch.put(Cluster, "/bad/url", %{"title" => "title", "author" => "author"})
{:error,
 %Elasticsearch.Exception{col: nil, line: nil,
  message: "Incorrect HTTP method for uri [/bad/url] and method [PUT], allowed: [POST]",
  query: nil, raw: nil, status: nil, type: nil}}

put!(cluster, url, data, opts \\ [])

Specs

put!(Elasticsearch.Cluster.t(), url(), data(), opts()) :: map() | no_return()

The same as put/2, but returns the response instead of a tuple. Raises on errors.

Examples

iex> Index.create_from_file(Cluster, "posts", "test/support/settings/posts.json")
...> Elasticsearch.put!(Cluster, "/posts/_doc/id", %{"name" => "name", "author" => "author"})
%{
  "_id" => "id",
  "_index" => "posts",
  "_primary_term" => 1,
  "_seq_no" => 0,
  "_shards" => %{"failed" => 0, "successful" => 1, "total" => 2},
  "_type" => "_doc",
  "_version" => 1,
  "result" => "created"
}

iex> Elasticsearch.put!(Cluster, "/bad/url", %{"data" => "here"})
** (Elasticsearch.Exception) Incorrect HTTP method for uri [/bad/url] and method [PUT], allowed: [POST]

put_document(cluster, document, index)

Specs

put_document(
  Elasticsearch.Cluster.t(),
  Elasticsearch.Document.t(),
  index_name()
) :: response()

Creates or updates a document in a given index.

The document must implement the Elasticsearch.Document protocol.

Example

iex> Index.create_from_file(Cluster, "posts-1", "test/support/settings/posts.json")
...> struct = %Post{id: 123, title: "Post", author: "Author"}
...> Elasticsearch.put_document(Cluster, struct, "posts-1")
{:ok,
  %{
    "_id" => "123",
    "_index" => "posts-1",
    "_primary_term" => 1,
    "_seq_no" => 0,
    "_shards" => %{"failed" => 0, "successful" => 1, "total" => 2},
    "_type" => "_doc",
    "_version" => 1,
    "result" => "created"
  }}

put_document!(cluster, document, index)

Specs

put_document!(
  Elasticsearch.Cluster.t(),
  Elasticsearch.Document.t(),
  index_name()
) :: map() | no_return()

Same as put_document/2, but raises on errors.

Example

iex> Index.create_from_file(Cluster, "posts-1", "test/support/settings/posts.json")
...> struct = %Post{id: 123, title: "Post", author: "Author"}
...> Elasticsearch.put_document!(Cluster, struct, "posts-1")
%{
  "_id" => "123",
  "_index" => "posts-1",
  "_primary_term" => 1,
  "_seq_no" => 0,
  "_shards" => %{"failed" => 0, "successful" => 1, "total" => 2},
  "_type" => "_doc",
  "_version" => 1,
  "result" => "created"
}

wait_for_boot(cluster, tries, count \\ 0)

Waits for a given Elasticsearch cluster to be available.

It will try a given number of times, with 1sec delay between tries.