ElasticsearchEx.Client (Elasticsearch v1.9.1)

View Source

Provides functions to make HTTP requests to an Elasticsearch cluster.

This module handles HTTP requests (GET, POST, PUT, DELETE, HEAD) to Elasticsearch, supporting JSON and NDJSON content types. Cluster configuration is fetched from the :elasticsearch_ex application environment or provided via options.

Configuration

Configure clusters in config.exs:

config :elasticsearch_ex, :clusters,
  default: %{
    endpoint: "http://localhost:9200",
    headers: %{"x-custom-header" => "value"},
    req_opts: [timeout: 5000]
  }

Supported Options

  • :cluster: Cluster name (atom) or configuration map (defaults to :default).
  • :headers: Additional HTTP headers (map).
  • :req_opts: Req library options (e.g., [timeout: 5000]).
  • :ndjson: Set to true for NDJSON content type.
  • :keys_as_atoms: Set to true to convert string keys to atoms.
  • :deserialize: Set to true to deserialize responses using ElasticsearchEx.Deserializer.

Examples

# GET request
request(:get, "/my_index/_search")
# => {:ok, %{"hits" => ...}}

# POST request with JSON body
request(:post, "/my_index/_doc", %{"field" => "value"})
# => {:ok, %{"_id" => ...}}

# NDJSON bulk request
request(:post, "/_bulk", [%{"index" => %{"_index" => "my_index"}}, %{"field" => "value"}], ndjson: true)
# => {:ok, %{"items" => ...}}

# Deserialize with mappings
request(:get, "/my_index/_doc/1", nil, deserialize: true)
# => {:ok, %{"_index" => "my_index", "_source" => %{"field" => value}}}

Summary

Types

Request body, typically a map, list, or nil for JSON/NDJSON encoding.

Cluster configuration with a required :endpoint (URL string) and optional :headers and :req_opts.

HTTP headers as a string-keyed map.

HTTP method for the request.

Request options, including :cluster, :headers, :req_opts, :ndjson, :keys, :deserialize, :mapper.

URL path for the Elasticsearch endpoint (e.g., "/index/_search").

Functions

Makes an HTTP request to an Elasticsearch cluster.

Types

body()

@type body() :: any()

Request body, typically a map, list, or nil for JSON/NDJSON encoding.

cluster_config()

@type cluster_config() :: %{
  :endpoint => binary(),
  optional(:headers) => headers(),
  optional(:req_opts) => keyword()
}

Cluster configuration with a required :endpoint (URL string) and optional :headers and :req_opts.

headers()

@type headers() :: %{required(binary()) => binary()}

HTTP headers as a string-keyed map.

method()

@type method() :: :head | :get | :post | :put | :delete

HTTP method for the request.

opts()

@type opts() :: keyword()

Request options, including :cluster, :headers, :req_opts, :ndjson, :keys, :deserialize, :mapper.

path()

@type path() :: iodata()

URL path for the Elasticsearch endpoint (e.g., "/index/_search").

Functions

request(method, path, body \\ nil, opts \\ [])

@spec request(method(), path(), body(), opts()) ::
  {:ok, term()} | {:error, Exception.t()}

Makes an HTTP request to an Elasticsearch cluster.

Parameters

  • method: HTTP method (:head, :get, :post, :put, :delete).
  • path: URL path (e.g., "/index/_search").
  • body: Request body (map, list, or nil; defaults to nil).
  • opts: Options for cluster, headers, deserialization, etc. See module documentation for details.

Returns

  • {:ok, term()}: Successful response, potentially deserialized.
  • {:error, Exception.t()}: HTTP error (status 300-599) or network error.

Examples

# Simple GET request
request(:get, "/my_index/_mapping")
# => {:ok, %{"my_index" => %{"mappings" => ...}}}

# POST with JSON body and atom keys
request(:post, "/my_index/_doc", %{"field" => "value"}, keys: :atoms)
# => {:ok, %{_id: "...", _source: %{field: "value"}}}

# Bulk NDJSON request
body = [%{"index" => %{"_index" => "my_index"}}, %{"field" => "value"}]
request(:post, "/_bulk", body, ndjson: true)
# => {:ok, %{"items" => ...}}

# Deserialize with custom mapper
mapper = fn _index -> %{"properties" => %{"field" => %{"type" => "text"}}} end
request(:get, "/my_index/_doc/1", nil, mapper: mapper)
# => {:ok, %{"_index" => "my_index", "_source" => %{"field" => "value"}}}