[[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`, except that you can delete the index when
    this block is in place. Do not set or remove this block yourself. The
    <<disk-based-shard-allocation,disk-based shard allocator>> sets and removes
    this block automatically according to the available disk space.
+
Deleting documents from an index to release resources - rather than deleting
the index itself - increases the index size temporarily, and therefore may not
be possible when nodes are low on disk space. When
`index.blocks.read_only_allow_delete` is set to `true`, deleting documents is
not permitted. However, deleting the index entirely requires very little extra
disk space and frees up the disk space consumed by the index almost immediately
so this is still permitted.
+
IMPORTANT: {es} adds the read-only-allow-delete index block automatically when
the disk utilization exceeds the flood stage watermark, and removes this block
automatically when the disk utilization falls under the high watermark. See
<<disk-based-shard-allocation,Disk-based shard allocation>> for more
information about watermarks, and <<fix-watermark-errors,Fix watermark errors>>
for help with resolving watermark issues.

`index.blocks.read`::

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

[[index-blocks-write]]
`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-ref-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-ref-dir}/rest-api/common-parms.asciidoc[tag=allow-no-indices]
+
Defaults to `true`.

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

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

include::{es-ref-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
  } ]
}
--------------------------------------------------