ロールアップジョブAPIの作成

8.11.0で非推奨。

ロールアップは将来のバージョンで削除されます。代わりにダウンサンプリングを使用してください。

8.15.0以降、ロールアップを使用していないクラスターでこのAPIを呼び出すと、ロールアップの非推奨と計画的な削除に関するメッセージと共に失敗します。このAPIを実行するには、クラスターにロールアップジョブまたはロールアップインデックスが含まれている必要があります。

ロールアップジョブを作成します。

リクエスト

PUT _rollup/job/<job_id>

前提条件

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

説明

ロールアップジョブの設定には、ジョブがどのように実行されるか、ドキュメントをインデックスするタイミング、将来のクエリがロールアップインデックスに対して実行できる内容に関するすべての詳細が含まれています。

ジョブ設定には、ジョブに関する物流の詳細（cronスケジュールなど）、グループ化に使用されるフィールド、および各グループのメトリクスを収集する内容の3つの主要なセクションがあります。

ジョブはSTOPPEDの状態で作成されます。ロールアップジョブの開始APIを使用して開始できます。

パスパラメータ

  • <job_id>
  • (必須、文字列) ロールアップジョブの識別子。この識別子は任意の英数字の文字列であり、ロールアップジョブに関連付けられたデータを一意に識別します。IDは永続的で、ロールアップされたデータと共に保存されます。ジョブを作成し、しばらく実行させた後にジョブを削除すると、ジョブがロールアップしたデータはこのジョブIDに関連付けられたままになります。同じIDで新しいジョブを作成することはできません。なぜなら、それはジョブ設定の不一致による問題を引き起こす可能性があるからです。

リクエストボディ

  • cron

  • (必須、文字列) ロールアップジョブが実行される間隔を定義するcron文字列。間隔がトリガーされると、インデクサーはインデックスパターン内のデータをロールアップしようとします。cronパターンは、ロールアップされるデータの時間間隔とは無関係です。たとえば、ドキュメントの時間ごとのロールアップを作成したいが、インデクサーを毎日真夜中にのみ実行したい場合、cronで定義されます。cronパターンは、Watcherのcronスケジュールと同様に定義されます。

  • groups
  • (必須、オブジェクト) このロールアップジョブに対して定義されたグループ化フィールドと集計を定義します。これらのフィールドは、後でバケットに集計するために使用可能になります。
    これらの集計とフィールドは、任意の組み合わせで使用できます。groups設定を、後で集計に使用できるツールのセットを定義するものと考えてください。生データとは異なり、どのフィールドと集計が使用されるかを事前に考える必要があります。ロールアップは十分な柔軟性を提供するため、必要なフィールドを決定するだけで済み、必要な順序を考慮する必要はありません。
    現在利用可能なグループ化のタイプは3つあります：date_histogram、histogram、terms。 
    1. -   `````date_histogram
    • (必須、オブジェクト) 日付ヒストグラムグループは、dateフィールドを時間ベースのバケットに集約します。このグループは必須です。現在、タイムスタンプとdate_histogramグループなしでドキュメントをロールアップすることはできません。date_histogramグループにはいくつかのパラメータがあります： 
      1. -   `````calendar_interval`````または`````fixed_interval
      • (必須、時間単位) ロールアップ時に生成される時間バケットの間隔。たとえば、60mは60分（時間ごと）のロールアップを生成します。これは、Elasticsearchの他の場所で使用される標準的な時間フォーマット構文に従います。間隔は、集約できる最小の間隔を定義します。時間ごとの(60m)間隔が設定されている場合、ロールアップ検索は60m以上（週ごと、月ごとなど）の間隔で集約を実行できます。したがって、後でクエリしたい最小の単位として間隔を定義してください。カレンダーと固定時間間隔の違いについての詳細は、カレンダーと固定間隔を参照してください。
        より小さく、より細かい間隔は、比例的により多くのスペースを占有します。
      • delay
      • (オプション、時間単位) 新しいドキュメントをロールアップする前に待機する時間。デフォルトでは、インデクサーは利用可能なすべてのデータをロールアップしようとします。しかし、データが順不同で到着することは珍しくなく、時には数日遅れることもあります。インデクサーは、時間範囲がロールアップされた後に到着したデータを処理できません。つまり、既存のロールアップを更新するための規定はありません。
        代わりに、順不同のデータが到着するのを期待する最長の期間に一致するdelayを指定する必要があります。たとえば、delayの1dは、インデクサーにnow - 1dまでのドキュメントをロールアップするよう指示し、順不同のドキュメントが到着するための1日のバッファ時間を提供します。
      • field
      • (必須、文字列) ロールアップされる日付フィールド。
      • time_zone
      • (オプション、文字列) ロールアップドキュメントが保存されるタイムゾーンを定義します。生データは動的にタイムゾーンを変更できますが、ロールアップされたドキュメントは特定のタイムゾーンで保存する必要があります。デフォルトでは、ロールアップドキュメントはUTCに保存されます。
    • histogram
    • (オプション、オブジェクト) ヒストグラムグループは、1つ以上の数値フィールドを数値ヒストグラム間隔に集約します。 
      1. -   `````fields
      • (必須、配列) ヒストグラムを構築したいフィールドのセット。指定されたすべてのフィールドは、何らかの数値である必要があります。順序は重要ではありません。
      • interval
      • (必須、整数) ロールアップ時に生成されるヒストグラムバケットの間隔。たとえば、5の値は、幅が5単位のバケットを作成します（0-5、5-10など）。histogramグループでは1つの間隔のみを指定できるため、ヒストグラムを介してグループ化されるすべてのフィールドは同じ間隔を共有する必要があります。
    • terms
    • (オプション、オブジェクト) 用語グループは、keywordまたは数値フィールドで使用して、後でterms集計を介してバケット化を可能にします。インデクサーは、各時間期間のフィールドのすべての値を列挙して保存します。これは、特に時間バケットが非常にまばらな場合、IPアドレスなどの高カーディナリティグループにとってコストがかかる可能性があります。
      ロールアップが生データよりも大きくなることは考えにくいですが、複数の高カーディナリティフィールドにtermsグループを定義すると、ロールアップの圧縮を大幅に減少させることができます。そのため、どの高カーディナリティフィールドを含めるかは慎重に選択する必要があります。 
      1. -   `````fields
      • (必須、文字列) 用語を収集したいフィールドのセット。この配列には、keywordおよび数値の両方のフィールドを含めることができます。順序は重要ではありません。
  • index_pattern

  • (必須、文字列) ロールアップするインデックスまたはインデックスパターン。ワイルドカードスタイルのパターンをサポートしています（logstash-*）。ジョブは、インデックスまたはインデックスパターン全体をロールアップしようとします。
    index_patternは、宛先rollup_indexにも一致するパターンであってはなりません。たとえば、パターンfoo-*はロールアップインデックスfoo-rollupに一致します。この状況は、ロールアップジョブが実行時に自分のデータをロールアップしようとするため、問題を引き起こします。rollup_indexに一致するパターンを構成しようとすると、この動作を防ぐために例外が発生します。

  • metrics
  • (オプション、オブジェクト) 各グループ化タプルのために収集するメトリクスを定義します。デフォルトでは、各グループのdoc_countsのみが収集されます。ロールアップを有用にするために、平均、最小、最大などのメトリクスを追加することがよくあります。メトリクスはフィールドごとに定義され、各フィールドに対して収集するメトリクスを構成します。 
    1. メトリクスオブジェクトのプロパティ  
    2. -   `````field
    • (必須、文字列) メトリクスを収集するフィールド。これは何らかの数値である必要があります。
    • metrics
    • (必須、配列) フィールドのために収集するメトリクスの配列。少なくとも1つのメトリクスを構成する必要があります。許可されるメトリクスはmin、max、sum、avg、およびvalue_countです。
  • page_size
  • (必須、整数) ロールアップインデクサーの各反復で処理されるバケット結果の数。大きな値は通常、実行が速くなりますが、処理中により多くのメモリを必要とします。この値は、データがどのようにロールアップされるかには影響しません。これは、インデクサーの速度やメモリコストを調整するためにのみ使用されます。
  • rollup_index
  • (必須、文字列) ロールアップ結果を含むインデックス。このインデックスは、他のロールアップジョブと共有できます。データは、無関係なジョブに干渉しないように保存されます。
  • timeout
  • (オプション、時間値) リクエストが完了するまでの待機時間。デフォルトは20s（20秒）です。

例

次の例は、sensorという名前のロールアップジョブを作成し、sensor-*インデックスパターンをターゲットにします：

Python

  1. resp = client.rollup.put_job(
  2.    id="sensor",
  3.    index_pattern="sensor-*",
  4.    rollup_index="sensor_rollup",
  5.    cron="*/30 * * * * ?",
  6.    page_size=1000,
  7.    groups={
  8.    "date_histogram": {
  9.    "field": "timestamp",
  10.    "fixed_interval": "1h",
  11.    "delay": "7d"
  12.    },
  13.    "terms": {
  14.    "fields": [
  15.    "node"
  16.    ]
  17.    }
  18.    },
  19.    metrics=[
  20.    {
  21.    "field": "temperature",
  22.    "metrics": [
  23.    "min",
  24.    "max",
  25.    "sum"
  26.    ]
  27.    },
  28.    {
  29.    "field": "voltage",
  30.    "metrics": [
  31.    "avg"
  32.    ]
  33.    }
  34.    ],
  35. )
  36. print(resp)

Js

  1. const response = await client.rollup.putJob({
  2.   id: "sensor",
  3.   index_pattern: "sensor-*",
  4.   rollup_index: "sensor_rollup",
  5.   cron: "*/30 * * * * ?",
  6.   page_size: 1000,
  7.   groups: {
  8.    date_histogram: {
  9.    field: "timestamp",
  10.    fixed_interval: "1h",
  11.    delay: "7d",
  12.    },
  13.    terms: {
  14.    fields: ["node"],
  15.    },
  16.   },
  17.   metrics: [
  18.    {
  19.    field: "temperature",
  20.    metrics: ["min", "max", "sum"],
  21.    },
  22.    {
  23.    field: "voltage",
  24.    metrics: ["avg"],
  25.    },
  26.   ],
  27. });
  28. console.log(response);

コンソール

  1. PUT _rollup/job/sensor
  2. {
  3.   "index_pattern": "sensor-*",
  4.   "rollup_index": "sensor_rollup",
  5.   "cron": "*/30 * * * * ?",
  6.   "page_size": 1000,
  7.   "groups": {
  8.    "date_histogram": {
  9.    "field": "timestamp",
  10.    "fixed_interval": "1h",
  11.    "delay": "7d"
  12.    },
  13.    "terms": {
  14.    "fields": [ "node" ]
  15.    }
  16.   },
  17.   "metrics": [
  18.    {
  19.    "field": "temperature",
  20.    "metrics": [ "min", "max", "sum" ]
  21.    },
  22.    {
  23.    "field": "voltage",
  24.    "metrics": [ "avg" ]
  25.    }
  26.   ]
  27. }
この設定により、timestamp
フィールドで日付ヒストグラムを使用し、terms集計をnodeフィールドで使用できるようになります。
この設定は、2つのフィールドにわたるメトリクスを定義します：temperatureおよびvoltage。temperatureフィールドについては、温度の最小、最大、および合計を収集しています。voltageについては、平均を収集しています。

ジョブが作成されると、次の結果が得られます：

コンソール-結果

  1. {
  2.   "acknowledged": true
  3. }