インデックステンプレートAPIの作成または更新

インデックステンプレートを作成または更新します。インデックステンプレートは、新しいインデックスに自動的に適用できる設定、マッピング、およびエイリアスを定義します。

Python

  1. resp = client.indices.put_index_template(
  2.    name="template_1",
  3.    index_patterns=[
  4.    "template*"
  5.    ],
  6.    priority=1,
  7.    template={
  8.    "settings": {
  9.    "number_of_shards": 2
  10.    }
  11.    },
  12. )
  13. print(resp)

Js

  1. const response = await client.indices.putIndexTemplate({
  2.   name: "template_1",
  3.   index_patterns: ["template*"],
  4.   priority: 1,
  5.   template: {
  6.    settings: {
  7.    number_of_shards: 2,
  8.    },
  9.   },
  10. });
  11. console.log(response);

コンソール

  1. PUT /_index_template/template_1
  2. {
  3.   "index_patterns" : ["template*"],
  4.   "priority" : 1,
  5.   "template": {
  6.    "settings" : {
  7.    "number_of_shards" : 2
  8.    }
  9.   }
  10. }

リクエスト

PUT /_index_template/<index-template>

前提条件

  • Elasticsearchのセキュリティ機能が有効になっている場合、このAPIを使用するには、manage_index_templatesまたはmanage クラスター権限が必要です。

説明

Elasticsearchは、インデックス名に一致するワイルドカードパターンに基づいて新しいインデックスにテンプレートを適用します。

インデックステンプレートは、データストリームまたはインデックスの作成中に適用されます。データストリームの場合、これらの設定とマッピングは、ストリームのバックインデックスが作成されるときに適用されます。

インデックス作成リクエストで指定された設定とマッピングは、インデックステンプレートで指定された設定やマッピングを上書きします。

インデックステンプレートの変更は、既存のインデックス、データストリームの既存のバックインデックスを含む、には影響しません。

インデックステンプレート内のコメント

インデックステンプレート内でCスタイルの/ /ブロックコメントを使用できます。リクエストボディのどこにでもコメントを含めることができますが、開き中括弧の前には含められません。

パスパラメータ

  • <index-template>
  • (必須、文字列) 作成するインデックステンプレートの名前。

クエリパラメータ

  • create
  • (オプション、Boolean) trueの場合、このリクエストは既存のインデックステンプレートを置き換えたり更新したりできません。デフォルトはfalseです。
  • master_timeout
  • (オプション、時間単位) マスターノードを待機する期間。タイムアウトが切れる前にマスターノードが利用できない場合、リクエストは失敗し、エラーが返されます。デフォルトは30sです。リクエストが決してタイムアウトしないことを示すために-1に設定することもできます。

リクエストボディ

  • composed_of

  • (オプション、文字列の配列) コンポーネントテンプレート名の順序付きリスト。コンポーネントテンプレートは指定された順序でマージされ、最後に指定されたコンポーネントテンプレートが最も優先されます。例については、複数のコンポーネントテンプレートの構成を参照してください。

  • data_stream

  • (オプション、オブジェクト) このオブジェクトが含まれている場合、テンプレートはデータストリームとそのバックインデックスを作成するために使用されます。空のオブジェクトをサポートします。
    データストリームには、data_streamオブジェクトを持つ一致するインデックステンプレートが必要です。インデックステンプレートの作成を参照してください。 
    1. -   `````allow_custom_routing
    • (オプション、Boolean) trueの場合、データストリームはカスタムルーティングをサポートします。デフォルトはfalseです。
    • hidden
    • (オプション、Boolean) trueの場合、データストリームは非表示です。デフォルトはfalseです。
    • index_mode
    • (オプション、文字列) 作成するデータストリームのタイプ。有効な値はnull（通常のデータストリーム）とtime_series（時系列データストリーム）です。
      time_seriesの場合、各バックインデックスにはindex.modeインデックス設定がtime_seriesになります。
  • index_patterns
  • (必須、文字列の配列) 作成中にデータストリームとインデックスの名前に一致するワイルドカード(*)式の配列。
    Elasticsearchには、いくつかの組み込みインデックステンプレートが含まれています。これらのテンプレートとの名前の衝突を避けるために、インデックスパターンの衝突を避けるを参照してください。
  • _meta
  • (オプション、オブジェクト) インデックステンプレートに関するオプションのユーザーメタデータ。任意の内容を持つことができます。このマップはElasticsearchによって自動的に生成されません。
  • priority
  • (オプション、整数) 新しいデータストリームまたはインデックスが作成されるときのインデックステンプレートの優先順位を決定します。最も優先度の高いインデックステンプレートが選択されます。優先順位が指定されていない場合、テンプレートは優先度0（最低優先度）のものとして扱われます。この数値はElasticsearchによって自動的に生成されません。
  • template
  • (オプション、オブジェクト) 適用されるテンプレート。aliases、mappings、またはsettingsの構成を含めることができます。 
    1. -   `````aliases
    • (オプション、オブジェクトのオブジェクト) 追加するエイリアス。
      インデックステンプレートにdata_streamオブジェクトが含まれている場合、これらはデータストリームエイリアスです。それ以外の場合、これらはインデックスエイリアスです。データストリームエイリアスは、index_routing、routing、およびsearch_routingオプションを無視します。 
      1. -   `````<alias>
      • (必須、オブジェクト) キーはエイリアス名です。インデックスエイリアス名は日付数学をサポートします。
        オブジェクト本体にはエイリアスのオプションが含まれます。空のオブジェクトをサポートします。
        <alias>のプロパティ
      • filter
      • (オプション、クエリDSLオブジェクト) エイリアスがアクセスできるドキュメントを制限するために使用されるクエリ。
      • index_routing
      • (オプション、文字列) インデックス操作を特定のシャードにルーティングするために使用される値。指定された場合、これはインデックス操作のrouting値を上書きします。
      • is_hidden
      • (オプション、Boolean) trueの場合、エイリアスは非表示です。デフォルトはfalseです。エイリアスのすべてのインデックスは同じis_hidden値を持つ必要があります。
      • is_write_index
      • (オプション、Boolean) trueの場合、インデックスはエイリアスの書き込みインデックスです。デフォルトはfalseです。
      • routing
      • (オプション、文字列) インデックス操作と検索操作を特定のシャードにルーティングするために使用される値。
      • search_routing
      • (オプション、文字列) 検索操作を特定のシャードにルーティングするために使用される値。指定された場合、これは検索操作のrouting値を上書きします。
    • mappings
    • (オプション、マッピングオブジェクト) インデックス内のフィールドのマッピング。指定された場合、このマッピングには次のものが含まれる可能性があります：
    • settings
    • (オプション、インデックス設定オブジェクト) インデックスの構成オプション。 インデックス設定を参照してください。
  • version
  • (オプション、整数) インデックステンプレートを外部で管理するために使用されるバージョン番号。この数値はElasticsearchによって自動的に生成されません。
  • deprecated
  • (オプション、boolean) このインデックステンプレートを非推奨としてマークします。非推奨のコンポーネントを使用する非推奨でないインデックステンプレートを作成または更新する際、Elasticsearchは非推奨警告を発します。

例

インデックスエイリアスを持つインデックステンプレート

インデックステンプレートにindex aliasesを含めることができます。

Python

  1. resp = client.indices.put_index_template(
  2.    name="template_1",
  3.    index_patterns=[
  4.    "template*"
  5.    ],
  6.    template={
  7.    "settings": {
  8.    "number_of_shards": 1
  9.    },
  10.    "aliases": {
  11.    "alias1": {},
  12.    "alias2": {
  13.    "filter": {
  14.    "term": {
  15.    "user.id": "kimchy"
  16.    }
  17.    },
  18.    "routing": "shard-1"
  19.    },
  20.    "{index}-alias": {}
  21.    }
  22.    },
  23. )
  24. print(resp)

Js

  1. const response = await client.indices.putIndexTemplate({
  2.   name: "template_1",
  3.   index_patterns: ["template*"],
  4.   template: {
  5.    settings: {
  6.    number_of_shards: 1,
  7.    },
  8.    aliases: {
  9.    alias1: {},
  10.    alias2: {
  11.    filter: {
  12.    term: {
  13.    "user.id": "kimchy",
  14.    },
  15.    },
  16.    routing: "shard-1",
  17.    },
  18.    "{index}-alias": {},
  19.    },
  20.   },
  21. });
  22. console.log(response);

コンソール

  1. PUT _index_template/template_1
  2. {
  3.   "index_patterns" : ["template*"],
  4.   "template": {
  5.    "settings" : {
  6.    "number_of_shards" : 1
  7.    },
  8.    "aliases" : {
  9.    "alias1" : {},
  10.    "alias2" : {
  11.    "filter" : {
  12.    "term" : {"user.id" : "kimchy" }
  13.    },
  14.    "routing" : "shard-1"
  15.    },
  16.    "{index}-alias" : {}
  17.    }
  18.   }
  19. }
エイリアス名の{index}プレースホルダーは、インデックス作成中にテンプレートが適用される実際のインデックス名に置き換えられます。

複数の一致するテンプレート

新しいインデックスまたはデータストリームの名前に一致する複数のインデックステンプレートがある場合、最も優先度の高いテンプレートが使用されます。例えば：

Python

  1. resp = client.indices.put_index_template(
  2.    name="template_1",
  3.    index_patterns=[
  4.    "temp*"
  5.    ],
  6.    priority=0,
  7.    template={
  8.    "settings": {
  9.    "number_of_shards": 1,
  10.    "number_of_replicas": 0
  11.    },
  12.    "mappings": {
  13.    "_source": {
  14.    "enabled": False
  15.    }
  16.    }
  17.    },
  18. )
  19. print(resp)
  21. resp1 = client.indices.put_index_template(
  22.    name="template_2",
  23.    index_patterns=[
  24.    "template*"
  25.    ],
  26.    priority=1,
  27.    template={
  28.    "settings": {
  29.    "number_of_shards": 2
  30.    },
  31.    "mappings": {
  32.    "_source": {
  33.    "enabled": True
  34.    }
  35.    }
  36.    },
  37. )
  38. print(resp1)

Js

  1. const response = await client.indices.putIndexTemplate({
  2.   name: "template_1",
  3.   index_patterns: ["temp*"],
  4.   priority: 0,
  5.   template: {
  6.    settings: {
  7.    number_of_shards: 1,
  8.    number_of_replicas: 0,
  9.    },
  10.    mappings: {
  11.    _source: {
  12.    enabled: false,
  13.    },
  14.    },
  15.   },
  16. });
  17. console.log(response);
  19. const response1 = await client.indices.putIndexTemplate({
  20.   name: "template_2",
  21.   index_patterns: ["template*"],
  22.   priority: 1,
  23.   template: {
  24.    settings: {
  25.    number_of_shards: 2,
  26.    },
  27.    mappings: {
  28.    _source: {
  29.    enabled: true,
  30.    },
  31.    },
  32.   },
  33. });
  34. console.log(response1);

コンソール

  1. PUT /_index_template/template_1
  2. {
  3.   "index_patterns" : ["temp*"],
  4.   "priority" : 0,
  5.   "template": {
  6.    "settings" : {
  7.    "number_of_shards" : 1,
  8.    "number_of_replicas": 0
  9.    },
  10.    "mappings" : {
  11.    "_source" : { "enabled" : false }
  12.    }
  13.   }
  14. }
  16. PUT /_index_template/template_2
  17. {
  18.   "index_patterns" : ["template*"],
  19.   "priority" : 1,
  20.   "template": {
  21.    "settings" : {
  22.    "number_of_shards" : 2
  23.    },
  24.    "mappings" : {
  25.    "_source" : { "enabled" : true }
  26.    }
  27.   }
  28. }
  2. 同じ優先度で重複するインデックスパターンを持つ複数のテンプレートは許可されず、同じ優先度で既存のインデックステンプレートに一致するテンプレートを作成しようとするとエラーが発生します。
  5. ### テンプレートのバージョン管理
  7. `````version`````パラメータを使用してインデックステンプレートにバージョン番号を追加できます。外部システムはこれらのバージョン番号を使用してテンプレート管理を簡素化できます。  
  9. `````version`````パラメータはオプションであり、Elasticsearchによって自動的に生成または使用されることはありません。  
  11. `````version`````を解除するには、テンプレートを指定せずに置き換えます。
  14. #### Python
  16. ``````python
  17. resp = client.indices.put_index_template(
  18.    name="template_1",
  19.    index_patterns=[
  20.    "foo",
  21.    "bar"
  22.    ],
  23.    priority=0,
  24.    template={
  25.    "settings": {
  26.    "number_of_shards": 1
  27.    }
  28.    },
  29.    version=123,
  30. )
  31. print(resp)
  32. `

Ruby

  1. response = client.indices.put_index_template(
  2.   name: 'template_1',
  3.   body: {
  4.    index_patterns: [
  5.    'foo',
  6.    'bar'
  7.    ],
  8.    priority: 0,
  9.    template: {
  10.    settings: {
  11.    number_of_shards: 1
  12.    }
  13.    },
  14.    version: 123
  15.   }
  16. )
  17. puts response

Js

  1. const response = await client.indices.putIndexTemplate({
  2.   name: "template_1",
  3.   index_patterns: ["foo", "bar"],
  4.   priority: 0,
  5.   template: {
  6.    settings: {
  7.    number_of_shards: 1,
  8.    },
  9.   },
  10.   version: 123,
  11. });
  12. console.log(response);

コンソール

  1. PUT /_index_template/template_1
  2. {
  3.   "index_patterns" : ["foo", "bar"],
  4.   "priority" : 0,
  5.   "template": {
  6.    "settings" : {
  7.    "number_of_shards" : 1
  8.    }
  9.   },
  10.   "version": 123
  11. }
  3. ### テンプレートメタデータ
  5. `````_meta`````パラメータを使用してインデックステンプレートに任意のメタデータを追加できます。このユーザー定義オブジェクトはクラスター状態に保存されるため、短く保つことが望ましいです。  
  7. `````_meta`````パラメータはオプションであり、Elasticsearchによって自動的に生成または使用されることはありません。  
  9. `````_meta`````を解除するには、テンプレートを指定せずに置き換えます。
  12. #### Python
  14. ``````python
  15. resp = client.indices.put_index_template(
  16.    name="template_1",
  17.    index_patterns=[
  18.    "foo",
  19.    "bar"
  20.    ],
  21.    template={
  22.    "settings": {
  23.    "number_of_shards": 3
  24.    }
  25.    },
  26.    meta={
  27.    "description": "set number of shards to three",
  28.    "serialization": {
  29.    "class": "MyIndexTemplate",
  30.    "id": 17
  31.    }
  32.    },
  33. )
  34. print(resp)
  35. `

Ruby

  1. response = client.indices.put_index_template(
  2.   name: 'template_1',
  3.   body: {
  4.    index_patterns: [
  5.    'foo',
  6.    'bar'
  7.    ],
  8.    template: {
  9.    settings: {
  10.    number_of_shards: 3
  11.    }
  12.    },
  13.    _meta: {
  14.    description: 'set number of shards to three',
  15.    serialization: {
  16.    class: 'MyIndexTemplate',
  17.    id: 17
  18.    }
  19.    }
  20.   }
  21. )
  22. puts response

Js

  1. const response = await client.indices.putIndexTemplate({
  2.   name: "template_1",
  3.   index_patterns: ["foo", "bar"],
  4.   template: {
  5.    settings: {
  6.    number_of_shards: 3,
  7.    },
  8.   },
  9.   _meta: {
  10.    description: "set number of shards to three",
  11.    serialization: {
  12.    class: "MyIndexTemplate",
  13.    id: 17,
  14.    },
  15.   },
  16. });
  17. console.log(response);

コンソール

  1. PUT /_index_template/template_1
  2. {
  3.   "index_patterns": ["foo", "bar"],
  4.   "template": {
  5.    "settings" : {
  6.    "number_of_shards" : 3
  7.    }
  8.   },
  9.   "_meta": {
  10.    "description": "set number of shards to three",
  11.    "serialization": {
  12.    "class": "MyIndexTemplate",
  13.    "id": 17
  14.    }
  15.   }
  16. }
  3. ### データストリーム定義
  5. データストリーム用のインデックステンプレートを使用するには、テンプレートに`````data_stream`````オブジェクトを含める必要があります。[インデックステンプレートの作成](beb5bf4d08d7f40c.md#create-index-template)を参照してください。
  8. #### Python
  10. ``````python
  11. resp = client.indices.put_index_template(
  12.    name="template_1",
  13.    index_patterns=[
  14.    "logs-*"
  15.    ],
  16.    data_stream={},
  17. )
  18. print(resp)
  19. `

Ruby

  1. response = client.indices.put_index_template(
  2.   name: 'template_1',
  3.   body: {
  4.    index_patterns: [
  5.    'logs-*'
  6.    ],
  7.    data_stream: {}
  8.   }
  9. )
  10. puts response

Js

  1. const response = await client.indices.putIndexTemplate({
  2.   name: "template_1",
  3.   index_patterns: ["logs-*"],
  4.   data_stream: {},
  5. });
  6. console.log(response);

コンソール

  1. PUT /_index_template/template_1
  2. {
  3.   "index_patterns": ["logs-*"],
  4.   "data_stream": { }
  5. }

エイリアス、マッピング、および設定の構成

インデックステンプレートのcomposed_ofフィールドに複数のコンポーネントテンプレートが指定されている場合、それらは指定された順序でマージされ、後のコンポーネントテンプレートが前のコンポーネントテンプレートを上書きします。親インデックステンプレートからのマッピング、設定、またはエイリアスは次にマージされます。最後に、インデックスリクエスト自体の設定がマージされます。

この例では、2つのコンポーネントテンプレートの順序がインデックスのシャード数を変更します：

Python

  1. resp = client.cluster.put_component_template(
  2.    name="template_with_2_shards",
  3.    template={
  4.    "settings": {
  5.    "index.number_of_shards": 2
  6.    }
  7.    },
  8. )
  9. print(resp)
  11. resp1 = client.cluster.put_component_template(
  12.    name="template_with_3_shards",
  13.    template={
  14.    "settings": {
  15.    "index.number_of_shards": 3
  16.    }
  17.    },
  18. )
  19. print(resp1)
  21. resp2 = client.indices.put_index_template(
  22.    name="template_1",
  23.    index_patterns=[
  24.    "t*"
  25.    ],
  26.    composed_of=[
  27.    "template_with_2_shards",
  28.    "template_with_3_shards"
  29.    ],
  30. )
  31. print(resp2)

Js

  1. const response = await client.cluster.putComponentTemplate({
  2.   name: "template_with_2_shards",
  3.   template: {
  4.    settings: {
  5.    "index.number_of_shards": 2,
  6.    },
  7.   },
  8. });
  9. console.log(response);
  11. const response1 = await client.cluster.putComponentTemplate({
  12.   name: "template_with_3_shards",
  13.   template: {
  14.    settings: {
  15.    "index.number_of_shards": 3,
  16.    },
  17.   },
  18. });
  19. console.log(response1);
  21. const response2 = await client.indices.putIndexTemplate({
  22.   name: "template_1",
  23.   index_patterns: ["t*"],
  24.   composed_of: ["template_with_2_shards", "template_with_3_shards"],
  25. });
  26. console.log(response2);

コンソール

  1. PUT /_component_template/template_with_2_shards
  2. {
  3.   "template": {
  4.    "settings": {
  5.    "index.number_of_shards": 2
  6.    }
  7.   }
  8. }
  10. PUT /_component_template/template_with_3_shards
  11. {
  12.   "template": {
  13.    "settings": {
  14.    "index.number_of_shards": 3
  15.    }
  16.   }
  17. }
  19. PUT /_index_template/template_1
  20. {
  21.   "index_patterns": ["t*"],
  22.   "composed_of": ["template_with_2_shards", "template_with_3_shards"]
  23. }

この場合、t*に一致するインデックスは3つのプライマリシャードを持ちます。構成されたテンプレートの順序が逆になった場合、インデックスは2つのプライマリシャードを持つことになります。

マッピング定義は再帰的にマージされるため、後のマッピングコンポーネントは新しいフィールドマッピングを導入し、マッピング構成を更新できます。フィールドマッピングがすでに前のコンポーネントに含まれている場合、その定義は後のものによって完全に上書きされます。

この再帰的マージ戦略は、フィールドマッピングだけでなく、dynamic_templatesやmetaのようなルートオプションにも適用されます。前のコンポーネントにdynamic_templatesブロックが含まれている場合、デフォルトでは新しいdynamic_templatesエントリが末尾に追加されます。同じキーを持つエントリがすでに存在する場合、それは新しい定義によって上書きされます。