Dowser.
View Source
The Elasticsearch cluster APIs — every endpoint tagged cluster in the
Elasticsearch OpenAPI specification:
cluster health, settings, state and statistics, shard allocation and
rerouting, voting configuration exclusions, remote clusters, and the
_nodes endpoints, which the specification tags cluster too.
Built on Dowser.Client. Required Elasticsearch attributes are positional
arguments; everything optional lives in opts.
Shared conventions
:node_id— where an endpoint accepts an optional node target: absent for every node, a single node id/name/pattern, or a list of them (joined with,). The two repositories-metering endpoints require a node target and take it as their first argument instead.:metric— where an endpoint accepts a metric filter: a single metric or a list./_cluster/stateand/_nodes/.../statsnest a second filter under it (:indexand:index_metric), which Elasticsearch can only read as the segment after a metric — passing one without:metricis reported as{:error, %ArgumentError{}}.- Endpoints that accept a request body take it as their first argument,
required — pass
%{}to send nothing. ping/1is theHEAD /check, and comes as the pair the rest of the library uses:ping/1returns{:ok, boolean()}or{:error, exception},ping?/1returns the bare boolean and raises on a genuine error.
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.Elasticsearch.Codec).
On a 2xx response every function returns {:ok, body} with the decoded
response body. A non-2xx response returns
{:error, %Dowser.Elasticsearch.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
Types
A path parameter: a single name, or several (joined with ,).
Functions
Explains why a shard is assigned to a node, or why it is unassigned (Cluster allocation explain API).
Like allocation_explain/2, but returns the body directly or raises the
error exception.
Clears the voting configuration exclusions (Clear voting configuration exclusions API).
Like clear_voting_config_exclusions/1, but returns the body directly or
raises the error exception.
Returns the cluster-wide settings (Get cluster settings API).
Like get_settings/1, but returns the body directly or raises the error
exception.
Returns the health status of the cluster (Cluster health API).
Like health/1, but returns the body directly or raises the error exception.
Returns the cluster information of one or several targets — _all, or any
of http, ingest, thread_pool and script
(Cluster info API).
Like info/2, but returns the body directly or raises the error exception.
Clears the archived repositories metering of one or several nodes, up to and
including max_archive_version
(Clear repositories metering archive API).
Like nodes_clear_repositories_metering_archive/3, but returns the body
directly or raises the error exception.
Returns the snapshot repositories metering of one or several nodes — how much each repository has been read from and written to (Get repositories metering API).
Like nodes_get_repositories_metering_info/2, but returns the body directly
or raises the error exception.
Returns the hot threads of each node — the threads taking the most CPU, with their stack traces (Nodes hot threads API).
Like nodes_hot_threads/1, but returns the body directly or raises the
error exception.
Returns information about the nodes of the cluster (Nodes info API).
Like nodes_info/1, but returns the body directly or raises the error
exception.
Reloads the keystore of one or several nodes, so secure settings changed on disk take effect without a restart (Nodes reload secure settings API).
Like nodes_reload_secure_settings/2, but returns the body directly or
raises the error exception.
Returns the statistics of the nodes of the cluster (Nodes stats API).
Like nodes_stats/1, but returns the body directly or raises the error
exception.
Returns how often each feature of the cluster has been used since each node started (Nodes feature usage API).
Like nodes_usage/1, but returns the body directly or raises the error
exception.
Returns the cluster-level changes not yet executed (Pending cluster tasks API).
Like pending_tasks/1, but returns the body directly or raises the error
exception.
Checks whether the cluster answers — HEAD /
(Ping API).
Like ping/1, but returns the boolean directly (404 → false) or raises
the error exception.
Updates the cluster-wide settings (Update cluster settings API).
Like put_settings/2, but returns the body directly or raises the error
exception.
Returns the configured remote clusters and whether each one is connected (Remote cluster info API).
Like remote_info/1, but returns the body directly or raises the error
exception.
Moves, cancels or allocates shards by hand (Cluster reroute API).
Like reroute/2, but returns the body directly or raises the error
exception.
Returns the internal state of the cluster (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.
Excludes master-eligible nodes from the voting configuration, so they can be shut down without losing the quorum (Update voting configuration exclusions API).
Like update_voting_config_exclusions/1, but returns the body directly or
raises the error exception.
Types
@type body() :: term()
@type exists_result() :: {:ok, boolean()} | {:error, Exception.t()}
@type index() :: Dowser.Elasticsearch.Index.t()
@type name() :: Dowser.Elasticsearch.Index.name()
A path parameter: a single name, or several (joined with ,).
@type result() :: {:ok, body()} | {:error, Exception.t()}
Functions
Explains why a shard is assigned to a node, or why it is unassigned (Cluster allocation explain API).
body names the shard (index, shard, primary, …); pass %{} to let
Elasticsearch pick the first unassigned shard it finds.
%{index: "posts", shard: 0, primary: true}
|> Dowser.Elasticsearch.Cluster.allocation_explain()Like allocation_explain/2, but returns the body directly or raises the
error exception.
Clears the voting configuration exclusions (Clear voting configuration exclusions API).
Options
:params—wait_for_removal: falseclears the list without waiting for the excluded nodes to leave the cluster.
Like clear_voting_config_exclusions/1, but returns the body directly or
raises the error exception.
Returns the cluster-wide settings (Get cluster settings API).
Options
:params— e.g.flat_settings,include_defaults.
Like get_settings/1, but returns the body directly or raises the error
exception.
Returns the health status of the cluster (Cluster health API).
Options
:index— index target; absent for the whole cluster.:params— e.g.level,wait_for_status,wait_for_nodes,timeout.
Like health/1, but returns the body directly or raises the error exception.
Returns the cluster information of one or several targets — _all, or any
of http, ingest, thread_pool and script
(Cluster info API).
target is required. For the node name, cluster name and version, see
Dowser.Elasticsearch.Info.info/1 (GET /).
Like info/2, but returns the body directly or raises the error exception.
Clears the archived repositories metering of one or several nodes, up to and
including max_archive_version
(Clear repositories metering archive API).
Both node_id and max_archive_version are required.
Like nodes_clear_repositories_metering_archive/3, but returns the body
directly or raises the error exception.
Returns the snapshot repositories metering of one or several nodes — how much each repository has been read from and written to (Get repositories metering API).
node_id is required, unlike the other _nodes endpoints.
Like nodes_get_repositories_metering_info/2, but returns the body directly
or raises the error exception.
Returns the hot threads of each node — the threads taking the most CPU, with their stack traces (Nodes hot threads API).
This endpoint answers in plain text, so the response format defaults to
:raw and the body comes back as a binary to print.
Options
:node_id— node target; absent for every node.:params— e.g.threads,interval,snapshots,type,sort,ignore_idle_threads.
Like nodes_hot_threads/1, but returns the body directly or raises the
error exception.
Returns information about the nodes of the cluster (Nodes info API).
Options
:node_id— node target; absent for every node.:metric— restrict the result to one or several metrics (settings,os,jvm,plugins, …).:params— e.g.flat_settings,timeout.
Like nodes_info/1, but returns the body directly or raises the error
exception.
Reloads the keystore of one or several nodes, so secure settings changed on disk take effect without a restart (Nodes reload secure settings API).
body carries the secure_settings_password when the keystore is password
protected; pass %{} when it isn't.
Options
:node_id— node target; absent for every node.
Like nodes_reload_secure_settings/2, but returns the body directly or
raises the error exception.
Returns the statistics of the nodes of the cluster (Nodes stats API).
Options
:node_id— node target; absent for every node.:metric— restrict the result to one or several metrics (indices,os,jvm,thread_pool, …).:index_metric— restrict theindicesmetric to one or several index metrics (docs,store,search, …), only alongside:metric— Elasticsearch reads it as the segment after one. Without:metric, returns{:error, %ArgumentError{}}.:params— e.g.level,fields,groups,types,timeout.
Like nodes_stats/1, but returns the body directly or raises the error
exception.
Returns how often each feature of the cluster has been used since each node started (Nodes feature usage API).
Options
:node_id— node target; absent for every node.:metric— restrict the result to one or several metrics (_all,rest_actions).
Like nodes_usage/1, but returns the body directly or raises the error
exception.
Returns the cluster-level changes not yet executed (Pending cluster tasks API).
Like pending_tasks/1, but returns the body directly or raises the error
exception.
@spec ping(keyword()) :: exists_result()
Checks whether the cluster answers — HEAD /
(Ping API).
Returns {:ok, true}, {:ok, false} or {:error, exception}.
Like ping/1, but returns the boolean directly (404 → false) or raises
the error exception.
Updates the cluster-wide settings (Update cluster settings API).
settings is the request body, with the settings under persistent and/or
transient:
Dowser.Elasticsearch.Cluster.put_settings(%{
persistent: %{"indices.recovery.max_bytes_per_sec" => "50mb"}
})Like put_settings/2, but returns the body directly or raises the error
exception.
Returns the configured remote clusters and whether each one is connected (Remote cluster info API).
Like remote_info/1, but returns the body directly or raises the error
exception.
Moves, cancels or allocates shards by hand (Cluster reroute API).
body carries the commands to apply; pass %{} to run the allocation
logic without any (e.g. with params: [retry_failed: true]).
%{commands: [%{move: %{index: "posts", shard: 0, from_node: "n1", to_node: "n2"}}]}
|> Dowser.Elasticsearch.Cluster.reroute()Like reroute/2, but returns the body directly or raises the error
exception.
Returns the internal state of the cluster (Cluster state API).
Options
:metric— restrict the state to one or several metrics (metadata,routing_table,nodes, …); absent for all of them.:index— index target, only alongside:metric— Elasticsearch reads it as the segment after one. Without:metric, returns{:error, %ArgumentError{}}.
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.:params— e.g.include_remotes,timeout.
Like stats/1, but returns the body directly or raises the error exception.
Excludes master-eligible nodes from the voting configuration, so they can be shut down without losing the quorum (Update voting configuration exclusions API).
The nodes to exclude go in :params, as node_names or node_ids:
Dowser.Elasticsearch.Cluster.update_voting_config_exclusions(
params: [node_names: "node-1,node-2"]
)Like update_voting_config_exclusions/1, but returns the body directly or
raises the error exception.