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()}
- Measurement:
[: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()}
- Measurement:
[: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()}
- Measurement:
Link to this section Summary
Functions
Deletes data at a given Elasticsearch URL.
Same as delete/1
, but returns the response and raises errors.
Deletes a document from a given index.
Same as delete_document/2
, but raises on errors.
Gets the contents of a path from the Elasticsearch API.
The same as get/1
, but returns the response instead of a tuple. Raises on
errors.
Determines whether a resource exists at a given Elasticsearch path
Same as head/1
, but returns the response and raises errors.
Posts data or queries to a given Elasticsearch path.
The same as post/1
, but returns the response. Raises on errors.
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.
Puts data to a given Elasticsearch API path.
The same as put/2
, but returns the response instead of a tuple. Raises on
errors.
Creates or updates a document in a given index.
Same as put_document/2
, but raises on errors.
Waits for a given Elasticsearch cluster to be available.
Link to this section Types
Specs
Specs
index_name() :: String.t()
Specs
opts() :: Keyword.t()
Specs
response() :: {:ok, map()} | {:error, Elasticsearch.Exception.t()}
Specs
url() :: Path.t()
Link to this section Functions
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"}}
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
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"
}}
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"
}
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"}}
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
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
}}
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)
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"]
[]
Specs
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
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.
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"
# => }}
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}}
Specs
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]
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"
}}
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"
}
Waits for a given Elasticsearch cluster to be available.
It will try a given number of times, with 1sec delay between tries.