@spec add_policy(map(), keyword()) :: result()

Puts indices under the management of a policy (Add policy API).

body names the policy, %{policy_id: "logs-lifecycle"}.

Options

• :index — index target; absent to apply to every index the request resolves to.

This attaches the policy as it stands now: the index keeps running that snapshot of it even if the policy is edited afterwards.

@spec add_policy!(map(), keyword()) :: body()

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

@spec change_policy(map(), keyword()) :: result()

Changes which policy — or which state of it — manages indices (Change policy API).

body names the new policy and, optionally, which indices it applies to: %{policy_id: "v2", state: "hot", include: [%{state: "warm"}]}.

This is what moves indices already managed onto an edited policy, which put_policy/3 alone does not do. The change is queued: ISM applies it when each index next finishes the action it is in, so a long-running force-merge finishes first.

Options

• :index — index target; absent to apply to every managed index.

@spec change_policy!(map(), keyword()) :: body()

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

@spec delete_policy(policy_id(), keyword()) :: result()

Deletes the policy policy_id (Delete policy API).

The indices already managed by it keep running their copy of it until they are removed from it with remove_policy/1.

@spec delete_policy!(policy_id(), keyword()) :: body()

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

@spec explain_policy(keyword()) :: result()

Explains how ISM is managing indices — which policy, which state, and what failed (Explain API).

The first place to look when an index is not moving through its policy:

{:ok, explanation} =
  Dowser.Opensearch.IndexStateManagement.explain_policy(index: "logs-000001")

Options

• :index — index target; absent for every managed index.
• :params — e.g. show_policy: true to include each policy in full.

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

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

@spec get_policies(keyword()) :: result()

Returns every policy (Get policies API).

Options

• :params — e.g. from, size, sortField, sortOrder, queryString.

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

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

@spec get_policy(policy_id(), keyword()) :: result()

Returns the policy policy_id (Get policy API).

The response carries _seq_no and _primary_term alongside the policy, which is what put_policy/3 needs to update it.

@spec get_policy!(policy_id(), keyword()) :: body()

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

@spec policy_exists(policy_id(), keyword()) :: exists_result()

Checks whether the policy policy_id exists.

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

@spec policy_exists?(policy_id(), keyword()) :: boolean()

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

@spec put_policies(map(), keyword()) :: result()

Creates or updates several policies in one request (Create policy API).

body is the request body holding the policies to write.

@spec put_policies!(map(), keyword()) :: body()

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

@spec put_policy(map(), policy_id(), keyword()) :: result()

Creates or updates the policy policy_id (Create policy API).

policy is the request body, %{policy: %{...}}:

%{
  policy: %{
    description: "hot-warm-delete",
    default_state: "hot",
    states: [
      %{name: "hot", actions: [], transitions: [%{state_name: "delete", conditions: %{min_index_age: "30d"}}]},
      %{name: "delete", actions: [%{delete: %{}}], transitions: []}
    ]
  }
}
|> Dowser.Opensearch.IndexStateManagement.put_policy("logs-lifecycle")

Updating an existing policy needs its current version, passed as params: [if_seq_no: seq_no, if_primary_term: primary_term] — get_policy/2 returns both. Without them OpenSearch refuses the update rather than clobbering a concurrent change.

Note that changing a policy does not move the indices already managed by it onto the new version: change_policy/2 is what does that.

@spec put_policy!(map(), policy_id(), keyword()) :: body()

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

@spec refresh_search_analyzers(index(), keyword()) :: result()

Reloads the search analyzers of one or several indices (Refresh search analyzers API).

Picks up changes to the synonym files a search_time analyzer reads, without closing and reopening the index. Note that this lives under /_plugins directly rather than under /_plugins/_ism.

@spec refresh_search_analyzers!(index(), keyword()) :: body()

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

@spec remove_policy(keyword()) :: result()

Removes indices from the management of their policy (Remove policy API).

The endpoint takes no request body.

Options

• :index — index target; absent to apply to every managed index.

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

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

@spec retry_index(map(), keyword()) :: result()

Retries the failed action of managed indices (Retry failed index API).

body may name the state to retry from, %{state: "warm"}; pass %{} to retry the action that failed.

An index whose action fails stops there until it is retried — ISM does not retry on its own past the policy's own retry settings — so this is the way out once whatever caused the failure is fixed.

Options

• :index — index target; absent to retry every failed index.

@spec retry_index!(map(), keyword()) :: body()

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