# Dowser.Elasticsearch `dowser_elasticsearch` is an Elixir client library for the Elasticsearch API, built on top of [`dowser_client`](https://hex.pm/packages/dowser_client). It gives you one function per Elasticsearch endpoint — named and shaped after the endpoint itself — instead of a hand-rolled query builder. - **Predictable functions.** Every endpoint maps to one function, named after Elasticsearch's own operation names (`create_index`, `get_alias`, `search`, …). Required attributes are positional arguments; everything optional lives in an `opts` keyword list. - **Every function has a bang variant.** `search/2` returns `{:ok, body}`/`{:error, error}`; `search!/2` returns the body directly or raises. `HEAD` existence checks follow the same idea with a `?` variant instead of `!`. - **A repository pattern for free.** `Dowser.Elasticsearch.Repository` binds the index-related functions of `Search`, `Document`, and `Index` to a fixed or computed index, so your code stops repeating `index: "posts"` on every call. - **Optional automatic type casting.** `Dowser.Elasticsearch.TypeCodec` casts dates, IPs, and other Elasticsearch types to and from native Elixir terms, per index mapping, with no per-call option needed. - **Bring your own HTTP/JSON stack.** Transport is handled by `dowser_client`, which defaults to Erlang's built-in `:httpc` and Elixir's built-in `JSON` module, or can be pointed at `Req`/`:hackney` and `Jason`/`Poison`. ## Installation Add `dowser_elasticsearch` to your list of dependencies in `mix.exs`: ```elixir def deps do [ {:dowser_elasticsearch, "~> 0.1.0"} ] end ``` Documentation can be generated with [ExDoc](https://github.com/elixir-lang/ex_doc) and published on [HexDocs](https://hexdocs.pm). Once published, the docs can be found at . ## Configuration Point the client at your cluster via `dowser_client`'s `:configs` config — see [its README](https://hexdocs.pm/dowser_client) for the full set of options (auth, headers, HTTP/JSON adapters): ```elixir config :dowser_client, configs: [ default: [endpoint: "http://localhost:9200", auth: {:basic, "user", "changeme"}] ] ``` Every API function accepts a `:config` option to target a specific entry (or an ad-hoc inline config) instead of `:default`. ## Usage Each module maps to one Elasticsearch API tag. Request bodies come first so calls pipe naturally; the index (when required) follows; everything optional goes in `opts`. ### Search ```elixir alias Dowser.Elasticsearch.Search %{query: %{match: %{title: "hello"}}} |> Search.search(index: "posts") # {:ok, %{"hits" => %{...}}} Search.count!(%{query: %{term: %{status: "published"}}}, index: "posts") # %{"count" => 42, "_shards" => %{...}} ``` ### Document ```elixir alias Dowser.Elasticsearch.Document {:ok, %{"_id" => id}} = Document.index(%{title: "hello"}, "posts") Document.get!("posts", id) # %{"_source" => %{"title" => "hello"}, ...} Document.exists?("posts", id) # true Document.delete("posts", id) ``` ### Index ```elixir alias Dowser.Elasticsearch.Index Index.create_index!(%{mappings: %{properties: %{title: %{type: "text"}}}}, "posts") Index.index_exists?("posts") # true Index.refresh(index: "posts") Index.delete_index("posts") ``` ## Repository pattern Calling `Search`, `Document`, and `Index` directly means repeating `index: "posts"` (or recomputing it) on every call. `use Dowser.Elasticsearch.Repository` generates index-bound versions of those functions instead: ```elixir defmodule MyApp.Posts do use Dowser.Elasticsearch.Repository, index: "posts", only: [ search: [:search, :count], document: [:index, :get, :delete, :exists], index: [:create_index, :refresh] ] end MyApp.Posts.create_index!(%{mappings: %{properties: %{title: %{type: "text"}}}}) # PUT /posts {:ok, %{"_id" => id}} = MyApp.Posts.index(%{title: "hello"}) # POST /posts/_doc MyApp.Posts.search!(%{query: %{match_all: %{}}}) # GET /posts/_search MyApp.Posts.exists?(id) # HEAD /posts/_doc/:id — true/false ``` `:index` also accepts a 1-arity function for a *dynamic* (e.g. per-tenant or time-based) index. The generated functions then take a *term* — positionally or via the `:index` option — and resolve it through that function: ```elixir defmodule MyApp.TenantLogs do use Dowser.Elasticsearch.Repository, index: &__MODULE__.index_name/1, only: [search: [:search], document: [:index]] def index_name(tenant), do: "logs_#{tenant}" end MyApp.TenantLogs.index(%{message: "boom"}, "acme") # POST /logs_acme/_doc MyApp.TenantLogs.search(%{query: %{match_all: %{}}}, index: "acme") # GET /logs_acme/_search ``` Without `:only`/`:except`, every index-related function of `Search`, `Document`, and `Index` is generated. Functions that don't target an index (templates, `reindex`, `scroll`, …) are never generated — call their module directly. ## Type casting By default, response bodies come back as plain decoded JSON — dates, IPs and other Elasticsearch types stay strings. Setting `Dowser.Elasticsearch.TypeCodec` as `:codec_adapter` casts them automatically, per index mapping, on every call to `Search` and `Document`: ```elixir config :dowser_client, configs: [ default: [ endpoint: "http://localhost:9200", codec_adapter: Dowser.Elasticsearch.TypeCodec ] ] ``` ```elixir Document.get!("posts", "1") # %{"_source" => %{"published_at" => ~U[2026-08-11 00:00:00Z]}, ...} ``` Mappings are fetched once and cached by `Dowser.Elasticsearch.MappingCacher`, which the application supervises automatically. `date`, `date_range`, `ip`, `binary`, `geo_point` and `integer_range` fields are cast out of the box; see `Dowser.Elasticsearch.Codec` for how to add your own field types. ## Compatibility ### Elasticsearch version Tested against Elasticsearch 9.x. Earlier versions haven't been tested but should work, since the wrapped endpoints are stable across releases. ### Endpoint coverage Elasticsearch groups its API into tags; only `Search`, `Document`, and `Index` are currently implemented. | Endpoint tag | Supported | | ------------------------------------------ | :-------: | | Behavioral analytics | ❌ | | Compact and aligned text (CAT) | ❌ | | Cluster | ❌ | | Cluster - Health | ❌ | | Connector | ❌ | | Cross-cluster replication | ❌ | | Data stream | ❌ | | Document | ✅ | | Enrich | ❌ | | EQL | ❌ | | ES\|QL | ❌ | | Features | ❌ | | Fleet | ❌ | | Graph explore | ❌ | | Index | ✅ | | Index lifecycle management | ❌ | | Inference | ❌ | | Info | ❌ | | Ingest | ❌ | | Licensing | ❌ | | Logstash | ❌ | | Machine learning | ❌ | | Machine learning anomaly detection | ❌ | | Machine learning data frame analytics | ❌ | | Machine learning trained model | ❌ | | Migration | ❌ | | Query rules | ❌ | | Reindex | ❌ | | Rollup | ❌ | | Script | ❌ | | Search | ✅ | | Search application | ❌ | | Searchable snapshots | ❌ | | Security | ❌ | | Snapshot and restore | ❌ | | Snapshot lifecycle management | ❌ | | SQL | ❌ | | Streams | ❌ | | Synonyms | ❌ | | Task management | ❌ | | Text structure | ❌ | | Transform | ❌ | | Usage | ❌ | | Watcher | ❌ | ## Trademark Notice This project is an independent, community-maintained library and is not affiliated with, endorsed by, or sponsored by Elasticsearch B.V. **Elasticsearch** is a trademark of Elasticsearch B.V., registered in the U.S. and in other countries.