Dowser.
View Source
The OpenSearch compact and aligned text (CAT) APIs — every endpoint tagged
CAT in the
OpenSearch OpenAPI specification.
Built on Dowser.Client. The cat endpoints take no request body and no
required attribute: each one's optional path parameter is an option, so every
function has the same opts-only signature.
JSON, not text
The cat APIs are meant for humans at a terminal and answer in aligned text by
default — but they honour the accept header Dowser.Client already sends,
so the response comes back as JSON and is decoded like every other endpoint:
a list of maps, one per row.
Dowser.Opensearch.Cat.indices!(index: "posts*")
#=> [%{"index" => "posts", "health" => "green", "docs.count" => "42", ...}]Every value in those maps is a string — that is what the cat APIs emit, JSON
or not. For the aligned text a terminal wants, ask for it explicitly: the
format query parameter wins over the header, and resp_format: :raw keeps
the body from being parsed as JSON.
Dowser.Opensearch.Cat.indices!(params: [format: "text", v: true], resp_format: :raw)Large clusters
A cat response is built whole in the coordinating node's heap before being
sent. Where the number of indices or shards is large or unbounded, use
Dowser.Opensearch.List.indices/1 and Dowser.Opensearch.List.shards/1
instead — OpenSearch's paginated counterparts to indices/1 and shards/1.
Shared options
Most cat endpoints accept the same query parameters, passed through :params:
v— add the column headers.h— the columns to return, e.g.h: "index,docs.count".s— the columns to sort on, e.g.s: "docs.count:desc".bytes/time— the unit sizes and durations are expressed in ("kb","gb","s","ms", …).format— see above.
Use help/1 to ask which cat endpoints the cluster serves.
All remaining options are forwarded to Dowser.Client.request/4, e.g.
:context, :params (query-string parameters), :format, :keys and
:http_opts (including :headers).
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. Each function has
a bang variant that returns the body directly or raises the error exception.
Summary
Functions
Lists aliases with the indices they point at (CAT aliases).
Like aliases/1, but returns the body directly or raises the error
exception.
Lists the segments of every point-in-time context in the cluster (CAT PIT segments).
Like all_pit_segments/1, but returns the body directly or raises the error
exception.
Reports the disk space and shard count allocated to each node (CAT allocation).
Like allocation/1, but returns the body directly or raises the error
exception.
Reports the node currently elected cluster manager (CAT cluster manager).
Like cluster_manager/1, but returns the body directly or raises the error
exception.
Counts the documents of one, several, or all indices (CAT count).
Like count/1, but returns the body directly or raises the error exception.
Reports the heap used by each field's field data (CAT field data).
Like fielddata/1, but returns the body directly or raises the error
exception.
Reports the cluster's health in one row (CAT health).
Like health/1, but returns the body directly or raises the error exception.
Lists the available cat APIs — GET /_cat
(CAT API).
Like help/1, but returns the endpoints directly or raises the error
exception.
Lists indices with their health, status, counts and sizes (CAT indices).
Like indices/1, but returns the body directly or raises the error
exception.
Reports the elected cluster manager, under its pre-2.0 name (CAT master).
Like master/1, but returns the body directly or raises the error exception.
Lists the custom attributes of each node (CAT node attributes).
Like nodeattrs/1, but returns the body directly or raises the error
exception.
Lists the nodes of the cluster with their roles and load (CAT nodes).
Like nodes/1, but returns the body directly or raises the error exception.
Lists the cluster-level changes still queued (CAT pending tasks).
Like pending_tasks/1, but returns the body directly or raises the error
exception.
Lists the segments of the point-in-time contexts on this node (CAT PIT segments).
Like pit_segments/1, but returns the body directly or raises the error
exception.
Lists the installed plugins of each node (CAT plugins).
Like plugins/1, but returns the body directly or raises the error
exception.
Reports on ongoing and completed shard recoveries (CAT recovery).
Like recovery/1, but returns the body directly or raises the error
exception.
Lists the registered snapshot repositories (CAT repositories).
Like repositories/1, but returns the body directly or raises the error
exception.
Reports on segment replication between primaries and replicas (CAT segment replication).
Like segment_replication/1, but returns the body directly or raises the
error exception.
Lists the Lucene segments of each shard (CAT segments).
Like segments/1, but returns the body directly or raises the error
exception.
Lists shards with their state, node and size (CAT shards).
Like shards/1, but returns the body directly or raises the error exception.
Lists the snapshots of a repository (CAT snapshots).
Like snapshots/1, but returns the body directly or raises the error
exception.
Lists the tasks currently running (CAT tasks).
Like tasks/1, but returns the body directly or raises the error exception.
Lists index templates (CAT templates).
Like templates/1, but returns the body directly or raises the error
exception.
Reports the thread pools of each node (CAT thread pool).
Like thread_pool/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()
A path parameter: a single name, or several (joined with ,).
@type result() :: {:ok, body()} | {:error, Exception.t()}
Functions
Lists aliases with the indices they point at (CAT aliases).
Options
:name— restrict the result to one or several alias names.
Like aliases/1, but returns the body directly or raises the error
exception.
Lists the segments of every point-in-time context in the cluster (CAT PIT segments).
Like all_pit_segments/1, but returns the body directly or raises the error
exception.
Reports the disk space and shard count allocated to each node (CAT allocation).
Options
:node_id— restrict the result to one or several nodes.
Like allocation/1, but returns the body directly or raises the error
exception.
Reports the node currently elected cluster manager (CAT cluster manager).
This is the endpoint to use: master/1 is the pre-2.0 spelling of the same
thing, kept only for compatibility.
Like cluster_manager/1, but returns the body directly or raises the error
exception.
Counts the documents of one, several, or all indices (CAT count).
Options
:index— index target; absent for all indices.
Like count/1, but returns the body directly or raises the error exception.
Reports the heap used by each field's field data (CAT field data).
Options
:fields— restrict the result to one or several fields.
Like fielddata/1, but returns the body directly or raises the error
exception.
Reports the cluster's health in one row (CAT health).
Like health/1, but returns the body directly or raises the error exception.
@spec help(keyword()) :: {:ok, [String.t()]} | {:error, Exception.t()}
Lists the available cat APIs — GET /_cat
(CAT API).
This one endpoint answers in plain text whatever the accept header says —
a banner line, then one endpoint per line — so the response format defaults
to :raw and the body is parsed here into the list of endpoints:
Dowser.Opensearch.Cat.help!()
#=> ["/_cat/allocation", "/_cat/shards", "/_cat/shards/{index}", ...]Pass resp_format: :json (or :ndjson) to opt out of both the :raw
default and the parsing, and get whatever Dowser.Client decodes instead.
Like help/1, but returns the endpoints directly or raises the error
exception.
Lists indices with their health, status, counts and sizes (CAT indices).
See the module documentation on large clusters — prefer
Dowser.Opensearch.List.indices/1 where the index count is unbounded.
Options
:index— index target; absent for all indices.
Like indices/1, but returns the body directly or raises the error
exception.
Reports the elected cluster manager, under its pre-2.0 name (CAT master).
Deprecated in OpenSearch in favour of cluster_manager/1, which this is an
alias of. Kept for clusters still serving the old path.
Like master/1, but returns the body directly or raises the error exception.
Lists the custom attributes of each node (CAT node attributes).
Like nodeattrs/1, but returns the body directly or raises the error
exception.
Lists the nodes of the cluster with their roles and load (CAT nodes).
Like nodes/1, but returns the body directly or raises the error exception.
Lists the cluster-level changes still queued (CAT pending tasks).
Like pending_tasks/1, but returns the body directly or raises the error
exception.
Lists the segments of the point-in-time contexts on this node (CAT PIT segments).
An OpenSearch addition, alongside
Dowser.Opensearch.Search.create_pit/3. Use all_pit_segments/1 for every
node's.
Like pit_segments/1, but returns the body directly or raises the error
exception.
Lists the installed plugins of each node (CAT plugins).
Like plugins/1, but returns the body directly or raises the error
exception.
Reports on ongoing and completed shard recoveries (CAT recovery).
Options
:index— index target; absent for all indices.
Like recovery/1, but returns the body directly or raises the error
exception.
Lists the registered snapshot repositories (CAT repositories).
Like repositories/1, but returns the body directly or raises the error
exception.
Reports on segment replication between primaries and replicas (CAT segment replication).
This is an OpenSearch addition, and reports on its segment-replication strategy — the alternative to document replication — so it has nothing to say about an index using the default.
Options
:index— index target; absent for all indices.
Like segment_replication/1, but returns the body directly or raises the
error exception.
Lists the Lucene segments of each shard (CAT segments).
Options
:index— index target; absent for all indices.
Like segments/1, but returns the body directly or raises the error
exception.
Lists shards with their state, node and size (CAT shards).
See the module documentation on large clusters — prefer
Dowser.Opensearch.List.shards/1 where the shard count is unbounded.
Options
:index— index target; absent for all indices.
Like shards/1, but returns the body directly or raises the error exception.
Lists the snapshots of a repository (CAT snapshots).
Options
:repository— restrict the result to one or several repositories.
Like snapshots/1, but returns the body directly or raises the error
exception.
Lists the tasks currently running (CAT tasks).
Like tasks/1, but returns the body directly or raises the error exception.
Lists index templates (CAT templates).
Options
:name— restrict the result to one or several template names.
Like templates/1, but returns the body directly or raises the error
exception.
Reports the thread pools of each node (CAT thread pool).
Options
:thread_pool_patterns— restrict the result to one or several pools.
Like thread_pool/1, but returns the body directly or raises the error
exception.