インデックスAPI - ロールオーバー（Rollover） - 《Elasticsearchガイドv8.15》日本語

Rollover API
Request
Prerequisites
Description
- Increment index names for an alias
- Wait for active shards
Path parameters
Query parameters
Request body
Response body
Examples

Rollover API

データストリーム（data stream）またはインデックスエイリアス（index alias）の新しいインデックスを作成します。

Python

resp = client.indices.rollover(
   alias="my-data-stream",
)
print(resp)

Ruby

response = client.indices.rollover(
  alias: 'my-data-stream'
)
puts response

Js

const response = await client.indices.rollover({
  alias: "my-data-stream",
});
console.log(response);

Console

POST my-data-stream/_rollover

Request

POST /<rollover-target>/_rollover/

POST /<rollover-target>/_rollover/<target-index>

Prerequisites

Elasticsearchのセキュリティ機能が有効になっている場合、ロールオーバーターゲットのためにmanage インデックス特権を持っている必要があります。

Description

ILMのrolloverアクションを使用してロールオーバーを自動化することをお勧めします。インデックスライフサイクルを参照してください。

ロールオーバーAPIは、データストリームまたはインデックスエイリアスの新しいインデックスを作成します。APIの動作はロールオーバーターゲットによって異なります。

データストリームをロールオーバーする

データストリームをロールオーバーすると、APIはストリームの新しい書き込みインデックスを作成します。ストリームの以前の書き込みインデックスは通常のバックインデックスになります。ロールオーバーはデータストリームの世代も増加させます。ロールオーバーを参照してください。

書き込みインデックスを持つインデックスエイリアスをロールオーバーする

Elasticsearch 7.9以前では、通常、書き込みインデックスを持つインデックスエイリアスを使用して時系列データを管理していました。データストリームはこの機能を置き換え、メンテナンスが少なく、データティアと自動的に統合されます。

インデックスエイリアスをデータストリームに変換するを参照してください。

インデックスエイリアスが複数のインデックスを指している場合、そのインデックスの1つは書き込みインデックスでなければなりません。ロールオーバーAPIは、is_write_indexがtrueに設定されたエイリアスの新しい書き込みインデックスを作成します。APIはまた、以前の書き込みインデックスのis_write_indexをfalseに設定します。

1つのインデックスを持つインデックスエイリアスをロールオーバーする

1つのインデックスを指すインデックスエイリアスをロールオーバーすると、APIはエイリアスの新しいインデックスを作成し、元のインデックスをエイリアスから削除します。

Increment index names for an alias

インデックスエイリアスをロールオーバーすると、新しいインデックスの名前を指定できます。名前を指定しない場合、現在のインデックスが-で数字（my-index-000001やmy-index-3など）で終わる場合、新しいインデックス名はその数字をインクリメントします。たとえば、my-index-000001という現在のインデックスを持つエイリアスをロールオーバーすると、ロールオーバーはmy-index-000002という名前の新しいインデックスを作成します。この数字は常に6文字で、ゼロパディングされます。前のインデックスの名前に関係なく、常に6文字です。

インデックスエイリアスのロールオーバーに日付数学を使用する

時系列データにインデックスエイリアスを使用する場合、ロールオーバー日を追跡するためにインデックス名に日付数学を使用できます。たとえば、<my-index-{now/d}-000001>という名前のインデックスを指すエイリアスを作成できます。2099年5月6日にインデックスを作成すると、インデックスの名前はmy-index-2099.05.06-000001になります。2099年5月7日にエイリアスをロールオーバーすると、新しいインデックスの名前はmy-index-2099.05.07-000002になります。例については、書き込みインデックスを持つインデックスエイリアスをロールオーバーするを参照してください。

Wait for active shards

ロールオーバーは新しいインデックスを作成し、wait_for_active_shards設定の影響を受けます。

Path parameters

<rollover-target>
（必須、文字列）ロールオーバーするデータストリームまたはインデックスエイリアスの名前。
<target-index>
（オプション、文字列）作成するインデックスの名前。日付数学をサポートします。データストリームはこのパラメータをサポートしていません。
エイリアスの現在の書き込みインデックスの名前が-やmy-index-000001、my-index-3のように数字で終わらない場合、このパラメータは必須です。
インデックス名は次の基準を満たす必要があります：
- 小文字のみ
- \、/、*、?、"、<、>、|、（スペース文字）、,、#を含むことはできません
- 7.0以前のインデックスにはコロン（:）を含めることができましたが、これは非推奨となり、7.0以降はサポートされません
- -、_、+で始めることはできません
- .または..であることはできません
- 255バイトを超えることはできません（バイト数であるため、マルチバイト文字は255の制限に早くカウントされます）
- .で始まる名前は非推奨ですが、隠しインデックスやプラグインによって管理される内部インデックスを除きます。

Query parameters

dry_run
（オプション、ブール値）trueの場合、現在のインデックスが指定されたconditionsを満たしているかどうかを確認しますが、ロールオーバーは実行しません。デフォルトはfalseです。
lazy
（オプション、ブール値）trueの場合、次のインデックス操作が発生したときにデータストリームがロールオーバーされることを示します。データストリームのみに適用されます。デフォルトはfalseです。
wait_for_active_shards
（オプション、文字列）操作を進める前にアクティブでなければならないシャードコピーの数。allまたはインデックス内のシャードの総数（number_of_replicas+1）までの任意の正の整数に設定します。デフォルト：1、プライマリシャード。
アクティブシャードを参照してください。
master_timeout
（オプション、時間単位）マスターノードを待機する期間。マスターノードがタイムアウトが切れる前に利用できない場合、リクエストは失敗し、エラーが返されます。デフォルトは30sです。リクエストがタイムアウトしないことを示すために-1に設定することもできます。
timeout
（オプション、時間単位）クラスタメタデータを更新した後、クラスタ内のすべての関連ノードからの応答を待機する期間。タイムアウトが切れる前に応答が受信されない場合、クラスタメタデータの更新は適用されますが、応答は完全に承認されなかったことを示します。デフォルトは30sです。リクエストがタイムアウトしないことを示すために-1に設定することもできます。

Request body

aliases
（オプション、オブジェクトのオブジェクト）ターゲットインデックスのエイリアス。データストリームはこのパラメータをサポートしていません。
```
-   `````<alias>
```
- （必須、オブジェクト）キーはエイリアス名です。インデックスエイリアス名は日付数学をサポートします。
  オブジェクトボディにはエイリアスのオプションが含まれます。空のオブジェクトをサポートします。
```
-   `````filter
```
  - （オプション、クエリDSLオブジェクト）エイリアスがアクセスできるドキュメントを制限するために使用されるクエリ。
  - index_routing
  - （オプション、文字列）インデックス操作を特定のシャードにルーティングするために使用される値。指定された場合、これはインデックス操作のrouting値を上書きします。
  - is_hidden
  - （オプション、ブール値）trueの場合、エイリアスは隠しです。デフォルトはfalseです。エイリアスのすべてのインデックスは同じis_hidden値を持っている必要があります。
  - is_write_index
  - （オプション、ブール値）trueの場合、インデックスはエイリアスの書き込みインデックスです。デフォルトはfalseです。
  - routing
  - （オプション、文字列）インデックス操作と検索操作を特定のシャードにルーティングするために使用される値。
  - search_routing
  - （オプション、文字列）検索操作を特定のシャードにルーティングするために使用される値。指定された場合、これは検索操作のrouting値を上書きします。
conditions
（オプション、オブジェクト）ロールオーバーの条件。指定された場合、Elasticsearchは現在のインデックスがこれらの条件を満たす場合にのみロールオーバーを実行します。このパラメータが指定されていない場合、Elasticsearchは無条件にロールオーバーを実行します。
条件が指定されている場合、少なくとも1つはmax*条件でなければなりません。インデックスは、任意のmax条件が満たされ、すべてのmin_条件が満たされる場合にロールオーバーします。
ロールオーバーをトリガーするには、リクエスト時に現在のインデックスがこれらの条件を満たしている必要があります。ElasticsearchはAPI応答後にインデックスを監視しません。ロールオーバーを自動化するには、ILMのrolloverを使用してください。
```
-   `````max_age
```
- （オプション、時間単位）インデックス作成からの最大経過時間に達した後にロールオーバーをトリガーします。経過時間は常にインデックス作成時から計算されます。インデックスの発生日がカスタム日付に設定されている場合でも、たとえば、index.lifecycle.parse_origination_dateやindex.lifecycle.origination_date設定を使用する場合でも、常にインデックス作成時から計算されます。
- max_docs
- （オプション、整数）指定された最大ドキュメント数に達した後にロールオーバーをトリガーします。最後のリフレッシュ以降に追加されたドキュメントはドキュメント数に含まれません。ドキュメント数にはレプリカシャードのドキュメントは含まれません。
- max_size
- （オプション、バイト単位）インデックスが特定のサイズに達したときにロールオーバーをトリガーします。これはインデックス内のすべてのプライマリシャードの合計サイズです。レプリカは最大インデックスサイズにカウントされません。
  現在のインデックスサイズを確認するには、_cat indices APIを使用します。pri.store.size値はすべてのプライマリシャードの合計サイズを示します。
- max_primary_shard_size
- （オプション、バイト単位）インデックス内の最大プライマリシャードが特定のサイズに達したときにロールオーバーをトリガーします。これはインデックス内のプライマリシャードの最大サイズです。max_sizeと同様に、レプリカは無視されます。
  現在のシャードサイズを確認するには、_cat shards APIを使用します。store値は各シャードのサイズを示し、prirepはシャードがプライマリ（p）かレプリカ（r）かを示します。
- max_primary_shard_docs
- （オプション、整数）インデックス内の最大プライマリシャードが特定のドキュメント数に達したときにロールオーバーをトリガーします。これはインデックス内のプライマリシャードの最大ドキュメント数です。max_docsと同様に、レプリカは無視されます。
  現在のシャードドキュメントを確認するには、_cat shards APIを使用します。docs値は各シャードのドキュメント数を示します。
- min_age
- （オプション、時間単位）インデックス作成からの最小経過時間に達するまでロールオーバーを防ぎます。max_ageに関する注意を参照してください。
- min_docs
- （オプション、整数）指定された最小ドキュメント数に達するまでロールオーバーを防ぎます。max_docsに関する注意を参照してください。
- min_size
- （オプション、バイト単位）インデックスが特定のサイズに達するまでロールオーバーを防ぎます。max_sizeに関する注意を参照してください。
- min_primary_shard_size
- （オプション、バイト単位）インデックス内の最大プライマリシャードが特定のサイズに達するまでロールオーバーを防ぎます。max_primary_shard_sizeに関する注意を参照してください。
- min_primary_shard_docs
- （オプション、整数）インデックス内の最大プライマリシャードが特定のドキュメント数に達するまでロールオーバーを防ぎます。max_primary_shard_docsに関する注意を参照してください。
mappings
（オプション、マッピングオブジェクト）インデックス内のフィールドのマッピング。指定された場合、このマッピングには次のものが含まれる場合があります：
- フィールド名
- フィールドデータ型
- マッピングパラメータ
   マッピングを参照してください。
  データストリームはこのパラメータをサポートしていません。
settings
（オプション、インデックス設定オブジェクト）インデックスの構成オプション。インデックス設定を参照してください。
データストリームはこのパラメータをサポートしていません。

Response body

acknowledged
（ブール値）trueの場合、リクエストはtimeout期間内にマスターノードから応答を受け取りました。
shards_acknowledged
（ブール値）trueの場合、リクエストはmaster_timeout期間内にアクティブシャードから応答を受け取りました。
old_index
（文字列）データストリームまたはインデックスエイリアスの以前のインデックス。データストリームおよび書き込みインデックスを持つインデックスエイリアスの場合、これは以前の書き込みインデックスです。
new_index
（文字列）ロールオーバーによって作成されたインデックス。データストリームおよび書き込みインデックスを持つインデックスエイリアスの場合、これは現在の書き込みインデックスです。
rolled_over
（ブール値）trueの場合、データストリームまたはインデックスエイリアスがロールオーバーされました。
dry_run
（ブール値）trueの場合、Elasticsearchはロールオーバーを実行しませんでした。
condition
（オブジェクト）リクエストのconditionsで指定された各条件の結果。条件が指定されていない場合、これは空のオブジェクトです。
```
-   `````<condition>
```
- （ブール値）キーは各条件です。値はその結果です。trueの場合、インデックスは条件を満たしました。
lazy
（ブール値）trueの場合、Elasticsearchはロールオーバーを実行しませんでしたが、次のインデックスイベントでロールオーバーされるようにデータストリームを正常にマークしました。

Examples

Roll over a data stream

次のリクエストは、データストリームを無条件にロールオーバーします。

Python

resp = client.indices.rollover(
   alias="my-data-stream",
)
print(resp)

Ruby

response = client.indices.rollover(
  alias: 'my-data-stream'
)
puts response

Js

const response = await client.indices.rollover({
  alias: "my-data-stream",
});
console.log(response);

Console

POST my-data-stream/_rollover

次のリクエストは、データストリームを遅延ロールオーバーします。これは、次のインデックスイベントでデータストリームがロールオーバーされることを意味します。これにより、マッピングと設定の変更が今後のデータに適用されますが、遅い取り込みのデータストリームに対して余分なバックインデックスを作成することを避けます。

Python

resp = client.indices.rollover(
   alias="my-data-stream",
   lazy=True,
)
print(resp)

Js

const response = await client.indices.rollover({
  alias: "my-data-stream",
  lazy: "true",
});
console.log(response);

Console

POST my-data-stream/_rollover?lazy

次のリクエストは、現在の書き込みインデックスが次の条件の1つ以上を満たす場合にのみデータストリームをロールオーバーします：

インデックスが7日以上前に作成されました。
インデックスに1,000以上のドキュメントが含まれています。
インデックスの最大プライマリシャードが50GB以上です。

Python

resp = client.indices.rollover(
   alias="my-data-stream",
   conditions={
   "max_age": "7d",
   "max_docs": 1000,
   "max_primary_shard_size": "50gb",
   "max_primary_shard_docs": "2000"
   },
)
print(resp)

Ruby

response = client.indices.rollover(
  alias: 'my-data-stream',
  body: {
   conditions: {
   max_age: '7d',
   max_docs: 1000,
   max_primary_shard_size: '50gb',
   max_primary_shard_docs: '2000'
   }
  }
)
puts response

Js

const response = await client.indices.rollover({
  alias: "my-data-stream",
  conditions: {
   max_age: "7d",
   max_docs: 1000,
   max_primary_shard_size: "50gb",
   max_primary_shard_docs: "2000",
  },
});
console.log(response);

Console

POST my-data-stream/_rollover
{
  "conditions": {
   "max_age": "7d",
   "max_docs": 1000,
   "max_primary_shard_size": "50gb",
   "max_primary_shard_docs": "2000"
  }
}

APIは次のように返します：

Console-Result

{
  "acknowledged": true,
  "shards_acknowledged": true,
  "old_index": ".ds-my-data-stream-2099.05.06-000001",
  "new_index": ".ds-my-data-stream-2099.05.07-000002",
  "rolled_over": true,
  "dry_run": false,
  "lazy": false,
  "conditions": {
   "[max_age: 7d]": false,
   "[max_docs: 1000]": true,
   "[max_primary_shard_size: 50gb]": false,
   "[max_primary_shard_docs: 2000]": false
  }
}

Roll over an index alias with a write index

次のリクエストは、<my-index-{now/d}-000001>を作成し、my-aliasの書き込みインデックスとして設定します。

Python

resp = client.indices.create(
   index="<my-index-{now/d}-000001>",
   aliases={
   "my-alias": {
   "is_write_index": True
   }
   },
)
print(resp)

Ruby

response = client.indices.create(
  index: '<my-index-{now/d}-000001>',
  body: {
   aliases: {
   "my-alias": {
   is_write_index: true
   }
   }
  }
)
puts response

Js

const response = await client.indices.create({
  index: "<my-index-{now/d}-000001>",
  aliases: {
   "my-alias": {
   is_write_index: true,
   },
  },
});
console.log(response);

Console


# PUT \<my-index-{now/d}-000001\>
PUT %3Cmy-index-%7Bnow%2Fd%7D-000001%3E
{
  "aliases": {
   "my-alias": {
   "is_write_index": true
   }
  }
}

次のリクエストは、現在の書き込みインデックスが次の条件の1つ以上を満たす場合にのみエイリアスをロールオーバーします：

インデックスが7日以上前に作成されました。
インデックスに1,000以上のドキュメントが含まれています。
インデックスの最大プライマリシャードが50GB以上です。

Python

resp = client.indices.rollover(
   alias="my-alias",
   conditions={
   "max_age": "7d",
   "max_docs": 1000,
   "max_primary_shard_size": "50gb",
   "max_primary_shard_docs": "2000"
   },
)
print(resp)

Ruby

response = client.indices.rollover(
  alias: 'my-alias',
  body: {
   conditions: {
   max_age: '7d',
   max_docs: 1000,
   max_primary_shard_size: '50gb',
   max_primary_shard_docs: '2000'
   }
  }
)
puts response

Js

const response = await client.indices.rollover({
  alias: "my-alias",
  conditions: {
   max_age: "7d",
   max_docs: 1000,
   max_primary_shard_size: "50gb",
   max_primary_shard_docs: "2000",
  },
});
console.log(response);

Console

POST my-alias/_rollover
{
  "conditions": {
   "max_age": "7d",
   "max_docs": 1000,
   "max_primary_shard_size": "50gb",
   "max_primary_shard_docs": "2000"
  }
}

APIは次のように返します：

Console-Result

{
  "acknowledged": true,
  "shards_acknowledged": true,
  "old_index": "my-index-2099.05.06-000001",
  "new_index": "my-index-2099.05.07-000002",
  "rolled_over": true,
  "dry_run": false,
  "lazy": false,
  "conditions": {
   "[max_age: 7d]": false,
   "[max_docs: 1000]": true,
   "[max_primary_shard_size: 50gb]": false,
   "[max_primary_shard_docs: 2000]": false
  }
}

エイリアスのインデックス名が日付数学を使用している場合、定期的にインデックスをロールオーバーすると、検索を絞り込むために日付数学を使用できます。たとえば、次の検索は、過去3日間に作成されたインデックスをターゲットにします。

Python

resp = client.search(
   index="<my-index-{now/d}-*>,<my-index-{now/d-1d}-*>,<my-index-{now/d-2d}-*>",
)
print(resp)

Ruby

response = client.search(
  index: '<my-index-{now/d}-*>,<my-index-{now/d-1d}-*>,<my-index-{now/d-2d}-*>'
)
puts response

Js

const response = await client.search({
  index: "<my-index-{now/d}-*>,<my-index-{now/d-1d}-*>,<my-index-{now/d-2d}-*>",
});
console.log(response);

Console


# GET /\u003cmy-index-{now/d}-*
GET /%3Cmy-index-%7Bnow%2Fd%7D-*%3E%2C%3Cmy-index-%7Bnow%2Fd-1d%7D-*%3E%2C%3Cmy-index-%7Bnow%2Fd-2d%7D-*%3E/_search

Roll over an index alias with one index

次のリクエストは、<my-index-{now/d}-000001>とそのエイリアスmy-write-aliasを作成します。

Python

resp = client.indices.create(
   index="<my-index-{now/d}-000001>",
   aliases={
   "my-write-alias": {}
   },
)
print(resp)

Ruby

response = client.indices.create(
  index: '<my-index-{now/d}-000001>',
  body: {
   aliases: {
   "my-write-alias": {}
   }
  }
)
puts response

Js

const response = await client.indices.create({
  index: "<my-index-{now/d}-000001>",
  aliases: {
   "my-write-alias": {},
  },
});
console.log(response);

Console


# PUT \<my-index-{now/d}-000001\>
PUT %3Cmy-index-%7Bnow%2Fd%7D-000001%3E
{
  "aliases": {
   "my-write-alias": { }
  }
}

次のリクエストは、現在のインデックスが次の条件の1つ以上を満たす場合にのみエイリアスをロールオーバーします：

インデックスが7日以上前に作成されました。
インデックスに1,000以上のドキュメントが含まれています。
インデックスの最大プライマリシャードが50GB以上です。

Python

resp = client.indices.rollover(
   alias="my-write-alias",
   conditions={
   "max_age": "7d",
   "max_docs": 1000,
   "max_primary_shard_size": "50gb",
   "max_primary_shard_docs": "2000"
   },
)
print(resp)

Ruby

response = client.indices.rollover(
  alias: 'my-write-alias',
  body: {
   conditions: {
   max_age: '7d',
   max_docs: 1000,
   max_primary_shard_size: '50gb',
   max_primary_shard_docs: '2000'
   }
  }
)
puts response

Js

const response = await client.indices.rollover({
  alias: "my-write-alias",
  conditions: {
   max_age: "7d",
   max_docs: 1000,
   max_primary_shard_size: "50gb",
   max_primary_shard_docs: "2000",
  },
});
console.log(response);

Console

POST my-write-alias/_rollover
{
  "conditions": {
   "max_age": "7d",
   "max_docs": 1000,
   "max_primary_shard_size": "50gb",
   "max_primary_shard_docs": "2000"
  }
}

APIは次のように返します：

Console-Result

{
  "acknowledged": true,
  "shards_acknowledged": true,
  "old_index": "my-index-2099.05.06-000001",
  "new_index": "my-index-2099.05.07-000002",
  "rolled_over": true,
  "dry_run": false,
  "lazy": false,
  "conditions": {
   "[max_age: 7d]": false,
   "[max_docs: 1000]": true,
   "[max_primary_shard_size: 50gb]": false,
   "[max_primary_shard_docs: 2000]": false
  }
}

Specify settings during a rollover

通常、ロールオーバー中に作成されたインデックスを自動的に構成するために、インデックステンプレートを使用します。インデックスエイリアスをロールオーバーする場合、ロールオーバーAPIを使用して追加のインデックス設定を追加したり、テンプレートの設定を上書きしたりします。データストリームはsettingsパラメータをサポートしていません。

Python

resp = client.indices.rollover(
   alias="my-alias",
   settings={
   "index.number_of_shards": 2
   },
)
print(resp)

Ruby

response = client.indices.rollover(
  alias: 'my-alias',
  body: {
   settings: {
   'index.number_of_shards' => 2
   }
  }
)
puts response

Js

const response = await client.indices.rollover({
  alias: "my-alias",
  settings: {
   "index.number_of_shards": 2,
  },
});
console.log(response);

Console

POST my-alias/_rollover
{
  "settings": {
   "index.number_of_shards": 2
  }
}