---
type: api
title: Split an index
description: **All methods and paths for this operation:**
url: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v9/operation/operation-indices-split
resource: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v9/operation/operation-indices-split
products:
  - Elasticsearch
---

# Split an index


Availability: 6.1+

## Paths

- `POST` (also `PUT`) `/{index}/_split/{target}`

- [Api key auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v9/authentication#apikeyauth)
- [Basic auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v9/authentication#basicauth)
- [Bearer auth](/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v9/authentication#bearerauth)

#### Path Parameters

- `index` (string IndexName)
  Name of the source index to split.
- `target` (string IndexName)
  Name of the target index to create.

## Description

Split an index into a new index with more primary shards.
* Before you can split an index:

* The index must be read-only.
* The cluster health status must be green.

You can do make an index read-only with the following request using the add index block API:

```
PUT /my_source_index/_block/write
```

The current write index on a data stream cannot be split.
In order to split the current write index, the data stream must first be rolled over so that a new write index is created and then the previous write index can be split.

The number of times the index can be split (and the number of shards that each original shard can be split into) is determined by the `index.number_of_routing_shards` setting.
The number of routing shards specifies the hashing space that is used internally to distribute documents across shards with consistent hashing.
For instance, a 5 shard index with `number_of_routing_shards` set to 30 (5 x 2 x 3) could be split by a factor of 2 or 3.

A split operation:

* Creates a new target index with the same definition as the source index, but with a larger number of primary shards.
* Hard-links segments from the source index into the target index. If the file system doesn't support hard-linking, all segments are copied into the new index, which is a much more time consuming process.
* Hashes all documents again, after low level files are created, to delete documents that belong to a different shard.
* Recovers the target index as though it were a closed index which had just been re-opened.

IMPORTANT: Indices can only be split if they satisfy the following requirements:

* The target index must not exist.
* The source index must have fewer primary shards than the target index.
* The number of primary shards in the target index must be a multiple of the number of primary shards in the source index.
* The number of primary shards in the target index must be a divisor of the source index's `index.number_of_routing_shards`.
* The node handling the split process must have sufficient free disk space to accommodate a second copy of the existing index.

## Required authorization

* Index privileges: `manage`

## Query String Parameters

- `master_timeout` (string Duration · default: 30s)
  Period to wait for a connection to the master node.
If no response is received before the timeout expires, the request fails and returns an error.
- `timeout` (string Duration · default: 30s)
  Period to wait for a response.
If no response is received before the timeout expires, the request fails and returns an error.
- `wait_for_active_shards` (WaitForActiveShards · default: 1)
  The number of shard copies that must be active before proceeding with the operation.
Set to `all` or any positive integer up to the total number of shards in the index (`number_of_replicas+1`).
  Values: `all`, `index-setting`

## Request Body

`application/json`

- `aliases` (map string to Alias) — optional
  Aliases for the resulting index.
  Map values ({} Alias)
  - `filter` ({} QueryContainer) — optional
    Query used to limit documents the alias can access.
    See [QueryContainer](https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/elasticsearch/v9/types/_types-query_dsl-querycontainer)
  - `index_routing` (string) — optional
    Value used to route indexing operations to a specific shard.
If specified, this overwrites the `routing` value for indexing operations.
  - `is_hidden` (boolean · default: false) — optional
    If `true`, the alias is hidden.
All indices for the alias must have the same `is_hidden` value.
  - `is_write_index` (boolean · default: false) — optional
    If `true`, the index is the write index for the alias.
  - `routing` (string) — optional
    Value used to route indexing and search operations to a specific shard.
  - `search_routing` (string) — optional
    Value used to route search operations to a specific shard.
If specified, this overwrites the `routing` value for search operations.
- `settings` (map string to object) — optional
  Configuration options for the target index.

## Response

`application/json`

- `acknowledged` (boolean)
- `shards_acknowledged` (boolean)
- `index` (string IndexName)
## Code Examples

#### Console

```console
POST /my-index-000001/_split/split-my-index-000001
{
  "settings": {
    "index.number_of_shards": 2
  }
}
```

#### JavaScript

```javascript
const response = await client.indices.split({
  index: "my-index-000001",
  target: "split-my-index-000001",
  settings: {
    "index.number_of_shards": 2,
  },
});
```

#### Python

```python
resp = client.indices.split(
    index="my-index-000001",
    target="split-my-index-000001",
    settings={
        "index.number_of_shards": 2
    },
)
```

#### curl

```curl
curl -X POST "$ELASTICSEARCH_URL/my-index-000001/_split/split-my-index-000001" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "settings": {
      "index.number_of_shards": 2
    }
  }'
```

#### Java

```java
client.indices().split(s -> s
    .index("my-index-000001")
    .settings("index.number_of_shards", JsonData.fromJson("2"))
    .target("split-my-index-000001")
);
```

#### C#

```c#
var response = await client.Indices
    .SplitAsync(index: "my-index-000001", target: "split-my-index-000001", d1 => d1
        .Settings(new Dictionary<string, object>()
        {
            { "index.number_of_shards", 2 }
        })
    );
```

#### PHP

```php
$resp = $client->indices()->split([
    "index" => "my-index-000001",
    "target" => "split-my-index-000001",
    "body" => [
        "settings" => [
            "index.number_of_shards" => 2,
        ],
    ],
]);
```

#### Ruby

```ruby
response = client.indices.split(
  index: "my-index-000001",
  target: "split-my-index-000001",
  body: {
    "settings": {
      "index.number_of_shards": 2
    }
  }
)
```