elasticsearch/docs/reference/index-modules/blocks.asciidoc

[[index-modules-blocks]]
== Index blocks

Index blocks limit the kind of operations that are available on a certain
index. The blocks come in different flavours, allowing to block write,
read, or metadata operations. The blocks can be set / removed using dynamic
index settings, or can be added using a dedicated API, which also ensures
for write blocks that, once successfully returning to the user, all shards
of the index are properly accounting for the block, for example that all
in-flight writes to an index have been completed after adding the write
block.

[discrete]
[[index-block-settings]]
=== Index block settings

The following _dynamic_ index settings determine the blocks present on an
index:

[[index-blocks-read-only]]
`index.blocks.read_only`::

    Set to `true` to make the index and index metadata read only, `false` to
    allow writes and metadata changes.

`index.blocks.read_only_allow_delete`::

    Similar to `index.blocks.write`, but also allows deleting the index to
    make more resources available. The <<disk-based-shard-allocation,disk-based shard
    allocator>> may add and remove this block automatically.
+
Deleting documents from an index to release resources - rather than deleting
the index itself - can increase the index size over time. When
`index.blocks.read_only_allow_delete` is set to `true`, deleting documents is
not permitted. However, deleting the index itself releases the read-only index
block and makes resources available almost immediately.
+
IMPORTANT: {es} adds the read-only index block automatically when the disk
utilization exceeds the flood stage watermark, controlled by the
<<cluster-routing-flood-stage,cluster.routing.allocation.disk.watermark.flood_stage>>
and <<cluster-routing-flood-stage,cluster.routing.allocation.disk.watermark.flood_stage.max_headroom>>
settings, and removes the block automatically when the disk utilization falls
under the high watermark, controlled by the
<<cluster-routing-flood-stage,cluster.routing.allocation.disk.watermark.high>>
and <<cluster-routing-flood-stage,cluster.routing.allocation.disk.watermark.high.max_headroom>>
settings. Refer to <<fix-watermark-errors,Fix watermark errors>> to resolve 
watermark issues.

`index.blocks.read`::

    Set to `true` to disable read operations against the index.

`index.blocks.write`::

    Set to `true` to disable data write operations against the index. Unlike
    `read_only`, this setting does not affect metadata. For instance, you can
    adjust the settings of an index with a `write` block, but you cannot adjust
    the settings of an index with a `read_only` block.

`index.blocks.metadata`::

    Set to `true` to disable index metadata reads and writes.

[discrete]
[[add-index-block]]
=== Add index block API

Adds an index block to an index.

[source,console]
--------------------------------------------------
PUT /my-index-000001/_block/write
--------------------------------------------------
// TEST[setup:my_index]


[discrete]
[[add-index-block-api-request]]
==== {api-request-title}

`PUT /<index>/_block/<block>`


[discrete]
[role="child_attributes"]
[[add-index-block-api-path-params]]
==== {api-path-parms-title}

include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=index]
+
By default, you must explicitly name the indices you are adding blocks to.
To allow the adding of blocks to indices with `_all`, `*`, or other wildcard
expressions, change the `action.destructive_requires_name` setting to `false`.
You can update this setting in the `elasticsearch.yml` file
or using the <<cluster-update-settings,cluster update settings>> API.
`<block>`::
(Required, string)
Block type to add to the index.
+
.Valid values for `<block>`
[%collapsible%open]
====
`metadata`::
Disable metadata changes, such as closing the index.

`read`::
Disable read operations.

`read_only`::
Disable write operations and metadata changes.

`write`::
Disable write operations. However, metadata changes are still allowed.
====
[discrete]
[[add-index-block-api-query-params]]
==== {api-query-parms-title}

include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=allow-no-indices]
+
Defaults to `true`.

include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=expand-wildcards]
+
Defaults to `open`.

include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=index-ignore-unavailable]

include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=timeoutparms]

[discrete]
[[add-index-block-api-example]]
==== {api-examples-title}

The following example shows how to add an index block:

[source,console]
--------------------------------------------------
PUT /my-index-000001/_block/write
--------------------------------------------------
// TEST[s/^/PUT my-index-000001\n/]

The API returns following response:

[source,console-result]
--------------------------------------------------
{
  "acknowledged" : true,
  "shards_acknowledged" : true,
  "indices" : [ {
    "name" : "my-index-000001",
    "blocked" : true
  } ]
}
--------------------------------------------------