Dowser.
View Source
The OpenSearch cluster APIs — every endpoint tagged Cluster in the
OpenSearch OpenAPI specification
(health, state, settings, routing and the awareness controls).
Built on Dowser.Client. Required OpenSearch attributes are positional
arguments; everything optional lives in opts.
For the node name, cluster name and version, see
Dowser.Opensearch.Info.info/1 (GET /).
Shared conventions
- Endpoints that accept a request body take it as their first argument,
required — pass
%{}to send nothing. - Optional path parameters are options (
:index,:metric,:node_id). Where OpenSearch reads one segment as the position after another —state/1's index after its metric — naming the inner one without the outer is anArgumentErrorrather than a silently wrong path.
All remaining options are forwarded to Dowser.Client.request/4, e.g.
:context, :params (query-string parameters), :format, :keys and
:http_opts (including :headers) — plus :codec, this package's own,
which picks the per-field codec for this one request (see
Dowser.Opensearch.Codec).
On a 2xx response every function returns {:ok, body} with the decoded
response body. A non-2xx response returns
{:error, %Dowser.Opensearch.Error{}}; a transport, encoding or decoding
failure returns {:error, exception} from Dowser.Client. A required
argument that is missing or empty is reported the same way, before any
request is made: {:error, %ArgumentError{}}. Each function has a bang
variant that returns the body directly or raises the error exception.
Summary
Functions
Explains why a shard is or is not allocated where it is (Cluster allocation explain API).
Like allocation_explain/2, but returns the body directly or raises the
error exception.
Recommissions every decommissioned zone (Decommission API).
Like delete_decommission_awareness/1, but returns the body directly or
raises the error exception.
Clears the voting configuration exclusions (Voting configuration exclusions API).
Like delete_voting_config_exclusions/1, but returns the body directly or
raises the error exception.
Clears the weighted routing configuration (Weighted routing API).
Like delete_weighted_routing/1, but returns the body directly or raises the
error exception.
Returns the status of a zone decommission (Decommission API).
Like get_decommission_awareness/2, but returns the body directly or raises
the error exception.
Returns the cluster settings (Cluster settings API).
Like get_settings/1, but returns the body directly or raises the error
exception.
Returns the weights of an awareness attribute's zones (Weighted routing API).
Like get_weighted_routing/2, but returns the body directly or raises the
error exception.
Returns the health of the cluster, or of one or several indices (Cluster health API).
Like health/1, but returns the body directly or raises the error exception.
Returns the cluster-level changes not yet executed (Pending tasks API).
Like pending_tasks/1, but returns the body directly or raises the error
exception.
Excludes nodes from the voting configuration (Voting configuration exclusions API).
Like post_voting_config_exclusions/1, but returns the body directly or
raises the error exception.
Decommissions a zone, taking its nodes out of the cluster (Decommission API).
Like put_decommission_awareness/3, but returns the body directly or raises
the error exception.
Updates the cluster settings (Cluster settings API).
Like put_settings/2, but returns the body directly or raises the error
exception.
Sets the search-traffic weights of an awareness attribute's zones (Weighted routing API).
Like put_weighted_routing/3, but returns the body directly or raises the
error exception.
Returns the configured remote clusters (Remote cluster info API).
Like remote_info/1, but returns the body directly or raises the error
exception.
Moves, allocates or cancels shards by hand (Cluster reroute API).
Like reroute/2, but returns the body directly or raises the error
exception.
Returns the cluster state — the metadata the cluster manager holds (Cluster state API).
Like state/1, but returns the body directly or raises the error exception.
Returns cluster-wide statistics — indices, nodes, shards, and the plugins installed (Cluster stats API).
Like stats/1, but returns the body directly or raises the error exception.
Types
@type body() :: term()
@type index() :: Dowser.Opensearch.Target.t()
@type name() :: Dowser.Opensearch.Target.name()
@type result() :: {:ok, body()} | {:error, Exception.t()}
Functions
Explains why a shard is or is not allocated where it is (Cluster allocation explain API).
body names the shard to explain, e.g.
%{index: "posts", shard: 0, primary: true}; pass %{} to have OpenSearch
pick the first unassigned shard it finds — which is usually the one you are
asking about.
Like allocation_explain/2, but returns the body directly or raises the
error exception.
Recommissions every decommissioned zone (Decommission API).
As with delete_weighted_routing/1, OpenSearch serves this on the unscoped
path, so it clears every decommission rather than one attribute's.
Like delete_decommission_awareness/1, but returns the body directly or
raises the error exception.
Clears the voting configuration exclusions (Voting configuration exclusions API).
Like delete_voting_config_exclusions/1, but returns the body directly or
raises the error exception.
Clears the weighted routing configuration (Weighted routing API).
Note that OpenSearch serves the delete on the unscoped path, with no attribute segment — so this clears the whole configuration rather than one attribute's.
Like delete_weighted_routing/1, but returns the body directly or raises the
error exception.
Returns the status of a zone decommission (Decommission API).
Like get_decommission_awareness/2, but returns the body directly or raises
the error exception.
Returns the cluster settings (Cluster settings API).
Options
:params— e.g.include_defaults: trueto see the settings nobody has changed, which is otherwise omitted.
Like get_settings/1, but returns the body directly or raises the error
exception.
Returns the weights of an awareness attribute's zones (Weighted routing API).
Like get_weighted_routing/2, but returns the body directly or raises the
error exception.
Returns the health of the cluster, or of one or several indices (Cluster health API).
Options
:index— index target; absent for the whole cluster.:params— e.g.level,wait_for_status,timeout.
wait_for_status is what makes this endpoint useful in a setup script: it
blocks until the cluster reaches the status asked for, or the timeout
elapses.
Dowser.Opensearch.Cluster.health!(params: [wait_for_status: "yellow", timeout: "30s"])Like health/1, but returns the body directly or raises the error exception.
Returns the cluster-level changes not yet executed (Pending tasks API).
Like pending_tasks/1, but returns the body directly or raises the error
exception.
Excludes nodes from the voting configuration (Voting configuration exclusions API).
The nodes to exclude are named through :params — node_names or
node_ids. This is the step before removing cluster-manager-eligible nodes,
so the remaining ones can still elect a manager.
Like post_voting_config_exclusions/1, but returns the body directly or
raises the error exception.
Decommissions a zone, taking its nodes out of the cluster (Decommission API).
An OpenSearch addition with no Elasticsearch counterpart.
awareness_attribute_name is the attribute (typically "zone") and
awareness_attribute_value the zone to decommission.
Weight the zone down with put_weighted_routing/3 first: decommissioning
moves traffic off its nodes and then excludes them, and doing it to a zone
still taking searches drops the ones in flight.
Like put_decommission_awareness/3, but returns the body directly or raises
the error exception.
Updates the cluster settings (Cluster settings API).
settings is the settings body, under persistent or transient:
%{persistent: %{"cluster.routing.allocation.enable" => "all"}}
|> Dowser.Opensearch.Cluster.put_settings()persistent survives a full cluster restart, transient does not. Setting a
value to nil resets it to its default.
Like put_settings/2, but returns the body directly or raises the error
exception.
Sets the search-traffic weights of an awareness attribute's zones (Weighted routing API).
An OpenSearch addition with no Elasticsearch counterpart. attribute is the
awareness attribute (typically "zone"), and body the weights, e.g.
%{weights: %{"us-east-1a" => "1", "us-east-1b" => "0"}} — a weight of 0
takes a zone out of search rotation without removing its nodes.
Like put_weighted_routing/3, but returns the body directly or raises the
error exception.
Returns the configured remote clusters (Remote cluster info API).
Note the path: this one endpoint lives at /_remote/info, not under
/_cluster.
Like remote_info/1, but returns the body directly or raises the error
exception.
Moves, allocates or cancels shards by hand (Cluster reroute API).
body is the request body, typically %{commands: [...]}; pass %{} to let
OpenSearch retry the allocations it had given up on.
Use params: [dry_run: true] to see what the commands would do without
applying them, and params: [explain: true] for why each one was accepted or
rejected.
Like reroute/2, but returns the body directly or raises the error
exception.
Returns the cluster state — the metadata the cluster manager holds (Cluster state API).
Options
:metric— restrict the state to one or several metrics (metadata,routing_table,nodes, …).:index— index target. OpenSearch reads it as the segment after the metric, so it needs one: passing an index with no metric is anArgumentError. Usemetric: "_all"to ask for everything.
The full state of a large cluster is a big document; naming a metric is usually what you want.
Like state/1, but returns the body directly or raises the error exception.
Returns cluster-wide statistics — indices, nodes, shards, and the plugins installed (Cluster stats API).
Options
:node_id— restrict the statistics to one or several nodes.
Like stats/1, but returns the body directly or raises the error exception.