Dowser.Opensearch.Index (Dowser.Opensearch v0.1.0)

The OpenSearch index APIs — the endpoints tagged Index in the OpenSearch OpenAPI specification (index lifecycle, resizing, rollover, maintenance and monitoring).

Built on Dowser.Client. Required OpenSearch attributes are positional arguments; everything optional lives in opts.

OpenSearch splits what Elasticsearch tags as one indices group into several tags, so the neighbouring APIs live in modules of their own: Dowser.Opensearch.Mappings, Dowser.Opensearch.IndexSettings, Dowser.Opensearch.Alias, Dowser.Opensearch.IndexTemplate, Dowser.Opensearch.DataStream and Dowser.Opensearch.DanglingIndices. The index-target helper they all share is Dowser.Opensearch.Target.

Shared conventions

An index target may be nil (all indices), a single index/alias/ data-stream name (string or atom), or a list of them (joined with ,). Endpoints that accept an optional target take it as the :index option; endpoints that require one take it as the first argument.
Path parameters such as target, metric or block accept the same shapes as an index target.
Endpoints that accept a request body take it as their first argument, required — pass %{} to send nothing.
HEAD existence checks come as a pair where the ? variant plays the bang role: index_exists/2 returns {:ok, boolean()} or {:error, exception}, index_exists?/2 returns the bare boolean (404 → false) and raises on genuine errors.

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

Types

body()

exists_result()

name()

result()

t()

Functions

add_block(index, block, opts \\ [])

Adds an index block to one or several indices (Add index block API).

add_block!(index, block, opts \\ [])

Like add_block/3, but returns the body directly or raises the error exception.

clear_cache(opts \\ [])

Clears the caches of one, several, or all indices (Clear cache API).

clear_cache!(opts \\ [])

Like clear_cache/1, but returns the body directly or raises the error exception.

clone(body, index, target, opts \\ [])

Clones the index index into target (Clone index API).

clone!(body, index, target, opts \\ [])

Like clone/4, but returns the body directly or raises the error exception.

close(index, opts \\ [])

Closes one or several indices (Close index API).

close!(index, opts \\ [])

Like close/2, but returns the body directly or raises the error exception.

create_index(body, index, opts \\ [])

Creates the index index (Create index API).

create_index!(body, index, opts \\ [])

Like create_index/3, but returns the body directly or raises the error exception.

delete_index(index, opts \\ [])

Deletes one or several indices (Delete index API).

delete_index!(index, opts \\ [])

Like delete_index/2, but returns the body directly or raises the error exception.

flush(opts \\ [])

Flushes one, several, or all indices (Flush API).

flush!(opts \\ [])

Like flush/1, but returns the body directly or raises the error exception.

forcemerge(opts \\ [])

Force-merges the segments of one, several, or all indices (Force merge API).

forcemerge!(opts \\ [])

Like forcemerge/1, but returns the body directly or raises the error exception.

get_index(index, opts \\ [])

Returns the definition of one or several indices (Get index API).

get_index!(index, opts \\ [])

Like get_index/2, but returns the body directly or raises the error exception.

index_exists(index, opts \\ [])

Checks whether one or several indices exist (Index exists API).

index_exists?(index, opts \\ [])

Like index_exists/2, but returns the boolean directly (404 → false) or raises the error exception.

open(index, opts \\ [])

Opens one or several closed indices (Open index API).

open!(index, opts \\ [])

Like open/2, but returns the body directly or raises the error exception.

recovery(opts \\ [])

Returns information about ongoing and completed shard recoveries (Recovery API).

recovery!(opts \\ [])

Like recovery/1, but returns the body directly or raises the error exception.

refresh(opts \\ [])

Refreshes one, several, or all indices (Refresh API).

refresh!(opts \\ [])

Like refresh/1, but returns the body directly or raises the error exception.

resolve_index(name, opts \\ [])

Resolves name — which may include wildcards — into the concrete indices, aliases and data streams it matches (Resolve index API).

resolve_index!(name, opts \\ [])

Like resolve_index/2, but returns the body directly or raises the error exception.

rollover(body, target, opts \\ [])

Rolls the rollover target target (an alias or data stream) over to a new index (Rollover API).

rollover!(body, target, opts \\ [])

Like rollover/3, but returns the body directly or raises the error exception.

segments(opts \\ [])

Returns the shard segments of one, several, or all indices (Segments API).

segments!(opts \\ [])

Like segments/1, but returns the body directly or raises the error exception.

shard_stores(opts \\ [])

Returns store information for the shards of one, several, or all indices (Shard stores API).

shard_stores!(opts \\ [])

Like shard_stores/1, but returns the body directly or raises the error exception.

shrink(body, index, target, opts \\ [])

Shrinks the index index into target, with fewer primary shards (Shrink index API).

shrink!(body, index, target, opts \\ [])

Like shrink/4, but returns the body directly or raises the error exception.

split(body, index, target, opts \\ [])

Splits the index index into target, with more primary shards (Split index API).

split!(body, index, target, opts \\ [])

Like split/4, but returns the body directly or raises the error exception.

stats(opts \\ [])

Returns statistics for one, several, or all indices (Index stats API).

stats!(opts \\ [])

Like stats/1, but returns the body directly or raises the error exception.

Types

body()

@type body() :: term()

exists_result()

@type exists_result() :: {:ok, boolean()} | {:error, Exception.t()}

name()

@type name() :: Dowser.Opensearch.Target.name()

result()

@type result() :: {:ok, body()} | {:error, Exception.t()}

t()

@type t() :: Dowser.Opensearch.Target.t()

Functions

add_block(index, block, opts \\ [])

@spec add_block(t(), name(), keyword()) :: result()

Adds an index block to one or several indices (Add index block API).

block is the block to add — "read_only", "read_only_allow_delete", "read", "write" or "metadata".

Dowser.Opensearch.Index.add_block("posts", "write")

OpenSearch has no endpoint for removing a block: clear one by setting the corresponding index.blocks.* setting to nil through Dowser.Opensearch.IndexSettings.put_settings/2.

add_block!(index, block, opts \\ [])

@spec add_block!(t(), name(), keyword()) :: body()

Like add_block/3, but returns the body directly or raises the error exception.

clear_cache(opts \\ [])

@spec clear_cache(keyword()) :: result()

Clears the caches of one, several, or all indices (Clear cache API).

Options

:index — index target; absent for all indices.

clear_cache!(opts \\ [])

@spec clear_cache!(keyword()) :: body()

Like clear_cache/1, but returns the body directly or raises the error exception.

clone(body, index, target, opts \\ [])

@spec clone(map(), t(), name(), keyword()) :: result()

Clones the index index into target (Clone index API).

body is the request body (e.g. settings, aliases); pass %{} to send nothing. The source index must be blocked for writes first — see add_block/3.

clone!(body, index, target, opts \\ [])

@spec clone!(map(), t(), name(), keyword()) :: body()

Like clone/4, but returns the body directly or raises the error exception.

close(index, opts \\ [])

@spec close(t(), keyword()) :: result()

Closes one or several indices (Close index API).

close!(index, opts \\ [])

@spec close!(t(), keyword()) :: body()

Like close/2, but returns the body directly or raises the error exception.

create_index(body, index, opts \\ [])

@spec create_index(map(), t(), keyword()) :: result()

Creates the index index (Create index API).

body is the request body (e.g. settings, mappings, aliases); pass %{} to send nothing.

%{settings: %{number_of_shards: 3}, mappings: %{properties: %{title: %{type: "text"}}}}
|> Dowser.Opensearch.Index.create_index("posts")

create_index!(body, index, opts \\ [])

@spec create_index!(map(), t(), keyword()) :: body()

Like create_index/3, but returns the body directly or raises the error exception.

delete_index(index, opts \\ [])

@spec delete_index(t(), keyword()) :: result()

Deletes one or several indices (Delete index API).

delete_index!(index, opts \\ [])

@spec delete_index!(t(), keyword()) :: body()

Like delete_index/2, but returns the body directly or raises the error exception.

flush(opts \\ [])

@spec flush(keyword()) :: result()

Flushes one, several, or all indices (Flush API).

Options

:index — index target; absent for all indices.

flush!(opts \\ [])

@spec flush!(keyword()) :: body()

Like flush/1, but returns the body directly or raises the error exception.

forcemerge(opts \\ [])

@spec forcemerge(keyword()) :: result()

Force-merges the segments of one, several, or all indices (Force merge API).

Options

:index — index target; absent for all indices.

forcemerge!(opts \\ [])

@spec forcemerge!(keyword()) :: body()

Like forcemerge/1, but returns the body directly or raises the error exception.

get_index(index, opts \\ [])

@spec get_index(t(), keyword()) :: result()

Returns the definition of one or several indices (Get index API).

get_index!(index, opts \\ [])

@spec get_index!(t(), keyword()) :: body()

Like get_index/2, but returns the body directly or raises the error exception.

index_exists(index, opts \\ [])

@spec index_exists(t(), keyword()) :: exists_result()

Checks whether one or several indices exist (Index exists API).

Returns {:ok, true}, {:ok, false} or {:error, exception}.

index_exists?(index, opts \\ [])

@spec index_exists?(t(), keyword()) :: boolean()

Like index_exists/2, but returns the boolean directly (404 → false) or raises the error exception.

open(index, opts \\ [])

@spec open(t(), keyword()) :: result()

Opens one or several closed indices (Open index API).

open!(index, opts \\ [])

@spec open!(t(), keyword()) :: body()

Like open/2, but returns the body directly or raises the error exception.

recovery(opts \\ [])

@spec recovery(keyword()) :: result()

Returns information about ongoing and completed shard recoveries (Recovery API).

Options

:index — index target; absent for all indices.

recovery!(opts \\ [])

@spec recovery!(keyword()) :: body()

Like recovery/1, but returns the body directly or raises the error exception.

refresh(opts \\ [])

@spec refresh(keyword()) :: result()

Refreshes one, several, or all indices (Refresh API).

Options

:index — index target; absent for all indices.

refresh!(opts \\ [])

@spec refresh!(keyword()) :: body()

Like refresh/1, but returns the body directly or raises the error exception.

resolve_index(name, opts \\ [])

@spec resolve_index(name(), keyword()) :: result()

Resolves name — which may include wildcards — into the concrete indices, aliases and data streams it matches (Resolve index API).

Dowser.Opensearch.Index.resolve_index!("logs-*")
#=> %{"indices" => [...], "aliases" => [...], "data_streams" => [...]}

resolve_index!(name, opts \\ [])

@spec resolve_index!(name(), keyword()) :: body()

Like resolve_index/2, but returns the body directly or raises the error exception.

rollover(body, target, opts \\ [])

@spec rollover(map(), name(), keyword()) :: result()

Rolls the rollover target target (an alias or data stream) over to a new index (Rollover API).

body is the request body (e.g. conditions, settings, mappings, aliases); pass %{} to send nothing.

Options

:new_index — explicit name for the new index; absent to let OpenSearch derive it.

rollover!(body, target, opts \\ [])

@spec rollover!(map(), name(), keyword()) :: body()

Like rollover/3, but returns the body directly or raises the error exception.

segments(opts \\ [])

@spec segments(keyword()) :: result()

Returns the shard segments of one, several, or all indices (Segments API).

Options

:index — index target; absent for all indices.

segments!(opts \\ [])

@spec segments!(keyword()) :: body()

Like segments/1, but returns the body directly or raises the error exception.

shard_stores(opts \\ [])

@spec shard_stores(keyword()) :: result()

Returns store information for the shards of one, several, or all indices (Shard stores API).

Options

:index — index target; absent for all indices.

shard_stores!(opts \\ [])

@spec shard_stores!(keyword()) :: body()

Like shard_stores/1, but returns the body directly or raises the error exception.

shrink(body, index, target, opts \\ [])

@spec shrink(map(), t(), name(), keyword()) :: result()

Shrinks the index index into target, with fewer primary shards (Shrink index API).

body is the request body (e.g. settings, aliases); pass %{} to send nothing.

shrink!(body, index, target, opts \\ [])

@spec shrink!(map(), t(), name(), keyword()) :: body()

Like shrink/4, but returns the body directly or raises the error exception.

split(body, index, target, opts \\ [])

@spec split(map(), t(), name(), keyword()) :: result()

Splits the index index into target, with more primary shards (Split index API).

body is the request body (e.g. settings, aliases); pass %{} to send nothing.

split!(body, index, target, opts \\ [])

@spec split!(map(), t(), name(), keyword()) :: body()

Like split/4, but returns the body directly or raises the error exception.

stats(opts \\ [])

@spec stats(keyword()) :: result()

Returns statistics for one, several, or all indices (Index stats API).

Options

:index — index target; absent for all indices.
:metric — restrict the result to one or several metrics.

stats!(opts \\ [])

@spec stats!(keyword()) :: body()

Like stats/1, but returns the body directly or raises the error exception.