データフィード API の更新

データフィードの特定のプロパティを更新します。

リクエスト

POST _ml/datafeeds/<feed_id>/_update

前提条件

manage_ml クラスター権限が必要です。この権限は machine_learning_admin ビルトインロールに含まれています。

説明

データフィードが停止している間のみ、データフィードのプロパティを更新できます。ただし、データフィードを停止し、そのプロパティの1つを更新し、関連するジョブを閉じることなく再起動することが可能です。

Elasticsearch のセキュリティ機能が有効になっている場合、データフィードは更新時にユーザーが持っていたロールを記憶し、それらのロールを使用してクエリを実行します。 二次認証ヘッダーを提供した場合、それらの資格情報が代わりに使用されます。

パスパラメータ

  • <feed_id>
  • (必須、文字列) データフィードを一意に識別する数値文字列。この識別子は、小文字の英数字 (a-z および 0-9)、ハイフン、アンダースコアを含むことができます。英数字で始まり、英数字で終わる必要があります。

クエリパラメータ

  • allow_no_indices
  • (オプション、Boolean) true の場合、具体的なインデックスに解決されないワイルドカードインデックス式は無視されます。これには _all 文字列や、インデックスが指定されていない場合が含まれます。デフォルトは true です。
  • expand_wildcards
  • (オプション、文字列) ワイルドカードパターンが一致できるインデックスのタイプ。リクエストがデータストリームをターゲットにできる場合、この引数はワイルドカード式が隠れたデータストリームに一致するかどうかを決定します。カンマ区切りの値をサポートし、open,hidden などが含まれます。有効な値は次のとおりです:
    • all
    • すべてのデータストリームまたはインデックスに一致します。 隠れたものも含まれます。
    • open
    • 開いている非隠れインデックスに一致します。また、非隠れデータストリームにも一致します。
    • closed
    • 閉じた非隠れインデックスに一致します。また、非隠れデータストリームにも一致します。データストリームは閉じることができません。
    • hidden
    • 隠れたデータストリームと隠れたインデックスに一致します。 open、closed、またはその両方と組み合わせる必要があります。
    • none
    • ワイルドカードパターンは受け入れられません。
      デフォルトは open です。
  • ignore_throttled
  • (オプション、Boolean) true の場合、具体的、拡張された、またはエイリアスされたインデックスは凍結時に無視されます。デフォルトは true です。
    [7.16.0] 7.16.0 で非推奨。
  • ignore_unavailable
  • (オプション、Boolean) true の場合、利用できないインデックス (欠落または閉じた) は無視されます。デフォルトは false です。

リクエストボディ

データフィードが作成された後に更新できるプロパティは次のとおりです:

  • aggregations
  • (オプション、オブジェクト) 設定されている場合、データフィードは集約検索を実行します。集約のサポートは制限されており、低いカーディナリティデータでのみ使用する必要があります。詳細については、パフォーマンス向上のためのデータの集約を参照してください。
  • chunking_config
  • (オプション、オブジェクト) データフィードは、数ヶ月または数年にわたって長期間にわたって検索する必要がある場合があります。この検索は、Elasticsearch の負荷を管理するために、時間のチャンクに分割されます。チャンク設定は、これらの時間チャンクのサイズがどのように計算されるかを制御し、高度な設定オプションです。
    chunking_config のプロパティ
    • mode
    • (文字列) 利用可能なモードは3つあります:
      • auto: チャンクサイズが動的に計算されます。これは、データフィードが集約を使用しない場合のデフォルトで推奨される値です。
      • manual: 指定された time_span に従ってチャンク処理が適用されます。このモードは、データフィードが集約を使用する場合に使用します。
      • off: チャンク処理は適用されません。
    • time_span
    • (時間単位) 各検索がクエリを実行する時間範囲。この設定は、モードが manual に設定されている場合にのみ適用されます。例えば: 3h。
  • delayed_data_check_config
  • (オプション、オブジェクト) データフィードが欠落データをチェックするかどうかとウィンドウのサイズを指定します。例えば: {"enabled": true, "check_window": "1h"}。
    データフィードは、インデックスにその後追加されたデータがあるかどうかを判断するために、すでに読み取られたインデックスをオプションで検索できます。欠落データが見つかった場合、これは query_delay オプションが低すぎて、データがデータフィードがその時点を過ぎた後にインデックスされていることを示す良い指標です。遅延データの処理を参照してください。
    このチェックは、リアルタイムデータフィードでのみ実行されます。
    delayed_data_check_config のプロパティ
    • check_window
    • (時間単位) 遅延データを検索するための時間ウィンドウ。この時間ウィンドウは、最新の確定バケットで終了します。デフォルトは null で、リアルタイムデータフィードが実行されるときに適切な check_window が計算されます。特に、デフォルトの check_window スパン計算は、2h または 8 * bucket_span の最大値に基づいています。
    • enabled
    • (Boolean) データフィードが遅延データを定期的にチェックするかどうかを指定します。デフォルトは true です。
  • frequency
  • (オプション、時間単位) データフィードがリアルタイムで実行されている間に、スケジュールされたクエリが行われる間隔。デフォルト値は、短いバケットスパンの場合はバケットスパン、長いバケットスパンの場合はバケットスパンの適切な分数です。例えば: 150s。 frequency がバケットスパンより短い場合、最後の (部分的な) バケットの中間結果が書き込まれ、その後最終的に完全なバケット結果によって上書きされます。データフィードが集約を使用する場合、この値は日付ヒストグラム集約の間隔で割り切れる必要があります。
  • indices
  • (オプション、配列) インデックス名の配列。ワイルドカードがサポートされています。例えば: ["it_ops_metrics", "server*"]。
    リモートクラスターにインデックスがある場合、機械学習ノードは remote_cluster_client 権限を持っている必要があります。
  • indices_options
  • (オプション、オブジェクト) 検索中に使用されるインデックス拡張オプションを指定します。
    例えば:
    1. {
    2. "expand_wildcards": ["all"],
    3. "ignore_unavailable": true,
    4. "allow_no_indices": "false",
    5. "ignore_throttled": true
    6. }
    これらのオプションの詳細については、マルチターゲット構文を参照してください。
  • max_empty_searches
  • (オプション、整数) リアルタイムデータフィードがデータを一度も見たことがない場合 (初期トレーニング期間中を含む)、この数のリアルタイム検索がドキュメントを返さないと、自動的に停止し、関連するジョブを閉じます。言い換えれば、リアルタイム操作の frequency 回数の後に停止します。設定されていない場合、終了時間がなくデータが見られないデータフィードは、明示的に停止されるまで開始されたままになります。デフォルトでは、この設定は設定されていません。
    特別な値 -1 はこの設定を解除します。
  • query
  • (オプション、オブジェクト) Elasticsearch クエリドメイン固有言語 (DSL)。この値は、Elasticsearch 検索 POST ボディのクエリオブジェクトに対応します。Elasticsearch によってサポートされるすべてのオプションを使用できます。このオブジェクトはそのまま Elasticsearch に渡されます。デフォルトでは、このプロパティは次の値を持ちます: {"match_all": {"boost": 1}}。
    クエリを変更すると、分析されたデータも変更されます。したがって、学習に必要な時間が長くなる可能性があり、結果の理解可能性は予測できません。ソースデータに大きな変更を加えたい場合は、それをクローンして修正を含む2番目のジョブを作成することをお勧めします。両方を並行して実行し、他のジョブの結果に満足したら1つを閉じます。
  • query_delay
  • (オプション、時間単位) データがクエリされるリアルタイムからの秒数。例えば、午前10時4分のデータは午前10時6分までElasticsearchで検索できない場合、このプロパティを120秒に設定します。デフォルト値は 60s と 120s の間でランダムに選択されます。このランダム性は、同じノードで複数のジョブが実行されているときのクエリパフォーマンスを向上させます。詳細については、遅延データの処理を参照してください。
  • runtime_mappings
  • (オプション、オブジェクト) データフィード検索のランタイムフィールドを指定します。
    例えば:
    1. {
    2. "day_of_week": {
    3. "type": "keyword",
    4. "script": {
    5. "source": "emit(doc['@timestamp'].value.dayOfWeekEnum.getDisplayName(TextStyle.FULL, Locale.ENGLISH))"
    6. }
    7. }
    8. }
  • script_fields
  • (オプション、オブジェクト) カスタム式を評価し、データフィードにスクリプトフィールドを返すスクリプトを指定します。ジョブ内の検出器設定オブジェクトには、これらのスクリプトフィールドを使用する関数が含まれる場合があります。詳細については、スクリプトフィールドを使用したデータの変換およびスクリプトフィールドを参照してください。
  • scroll_size
  • (オプション、符号なし整数) データフィードが集約を使用しない場合にElasticsearch検索で使用される size パラメータ。デフォルト値は 1000 です。最大値は index.max_result_window の値で、デフォルトは10,000です。

例

Python

  1. resp = client.ml.update_datafeed(
  2.    datafeed_id="datafeed-test-job",
  3.    query={
  4.    "term": {
  5.    "geo.src": "US"
  6.    }
  7.    },
  8. )
  9. print(resp)

Ruby

  1. response = client.ml.update_datafeed(
  2.   datafeed_id: 'datafeed-test-job',
  3.   body: {
  4.    query: {
  5.    term: {
  6.    'geo.src' => 'US'
  7.    }
  8.    }
  9.   }
  10. )
  11. puts response

Js

  1. const response = await client.ml.updateDatafeed({
  2.   datafeed_id: "datafeed-test-job",
  3.   query: {
  4.    term: {
  5.    "geo.src": "US",
  6.    },
  7.   },
  8. });
  9. console.log(response);

コンソール

  1. POST _ml/datafeeds/datafeed-test-job/_update
  2. {
  3.   "query": {
  4.    "term": {
  5.    "geo.src": "US"
  6.    }
  7.   }
  8. }

データフィードが更新されると、更新された値を持つ完全なデータフィード構成が受信されます:

コンソール-結果

  1. {
  2.   "datafeed_id" : "datafeed-test-job",
  3.   "job_id" : "test-job",
  4.   "authorization" : {
  5.    "roles" : [
  6.    "superuser"
  7.    ]
  8.   },
  9.   "query_delay" : "64489ms",
  10.   "chunking_config" : {
  11.    "mode" : "auto"
  12.   },
  13.   "indices_options" : {
  14.    "expand_wildcards" : [
  15.    "open"
  16.    ],
  17.    "ignore_unavailable" : false,
  18.    "allow_no_indices" : true,
  19.    "ignore_throttled" : true
  20.   },
  21.   "query" : {
  22.    "term" : {
  23.    "geo.src" : "US"
  24.    }
  25.   },
  26.   "indices" : [
  27.    "kibana_sample_data_logs"
  28.   ],
  29.   "scroll_size" : 1000,
  30.   "delayed_data_check_config" : {
  31.    "enabled" : true
  32.   }
  33. }