Model Snapshots

Delete Model Snapshots

The delete model snapshot API enables you to delete an existing model snapshot.

Request

DELETE _xpack/ml/anomaly_detectors/<job_id>/model_snapshots/<snapshot_id>

Description

Important

You cannot delete the active model snapshot. To delete that snapshot, first revert to a different one.

Path Parameters

job_id (required)
(string) Identifier for the job
snapshot_id (required)
(string) Identifier for the model snapshot

Authorization

You must have manage_ml, or manage cluster privileges to use this API. For more information, see Cluster Privileges.

Examples

The following example deletes the 1491948163 snapshot:

DELETE _xpack/ml/anomaly_detectors/farequote/model_snapshots/1491948163

When the snapshot is deleted, you receive the following results:

{
  "acknowledged": true
}

Get Model Snapshots

The get model snapshots API enables you to retrieve information about model snapshots.

Request

GET _xpack/ml/anomaly_detectors/<job_id>/model_snapshots

GET _xpack/ml/anomaly_detectors/<job_id>/model_snapshots/<snapshot_id>

Path Parameters

job_id
(string) Identifier for the job.
snapshot_id
(string) Identifier for the model snapshot. If you do not specify this optional parameter, the API returns information about all model snapshots.

Request Body

desc
(boolean) If true, the results are sorted in descending order.
end
(date) Returns snapshots with timestamps earlier than this time.
from
(integer) Skips the specified number of snapshots.
size
(integer) Specifies the maximum number of snapshots to obtain.
sort
(string) Specifies the sort field for the requested snapshots. By default, the snapshots are sorted by their timestamp.
start
(string) Returns snapshots with timestamps after this time.

Results

The API returns the following information:

model_snapshots
(array) An array of model snapshot objects. For more information, see Model Snapshots.

Authorization

You must have monitor_ml, monitor, manage_ml, or manage cluster privileges to use this API. For more information, see Cluster Privileges.

Examples

The following example gets model snapshot information for the it_ops_new_logs job:

GET _xpack/ml/anomaly_detectors/farequote/model_snapshots
{
  "start": "1491852977000"
}

In this example, the API provides a single result:

{
  "count": 1,
  "model_snapshots": [
    {
      "job_id": "farequote",
      "timestamp": 1491948163000,
      "description": "State persisted due to job close at 2017-04-11T15:02:43-0700",
      "snapshot_id": "1491948163",
      "snapshot_doc_count": 1,
      "model_size_stats": {
        "job_id": "farequote",
        "result_type": "model_size_stats",
        "model_bytes": 387594,
        "total_by_field_count": 21,
        "total_over_field_count": 0,
        "total_partition_field_count": 20,
        "bucket_allocation_failures_count": 0,
        "memory_status": "ok",
        "log_time": 1491948163000,
        "timestamp": 1455234600000
      },
      "latest_record_time_stamp": 1455235196000,
      "latest_result_time_stamp": 1455234900000,
      "retain": false
    }
  ]
}

Revert Model Snapshots

The revert model snapshot API enables you to revert to a specific snapshot.

Request

POST _xpack/ml/anomaly_detectors/<job_id>/model_snapshots/<snapshot_id>/_revert

Description

The machine learning feature in X-Pack reacts quickly to anomalous input, learning new behaviors in data. Highly anomalous input increases the variance in the models whilst the system learns whether this is a new step-change in behavior or a one-off event. In the case where this anomalous input is known to be a one-off, then it might be appropriate to reset the model state to a time before this event. For example, you might consider reverting to a saved snapshot after Black Friday or a critical system failure.

Important

Before you revert to a saved snapshot, you must close the job.

Path Parameters

job_id (required)
(string) Identifier for the job
snapshot_id (required)
(string) Identifier for the model snapshot

Request Body

delete_intervening_results
(boolean) If true, deletes the results in the time period between the latest results and the time of the reverted snapshot. It also resets the model to accept records for this time period. The default value is false.
Note

If you choose not to delete intervening results when reverting a snapshot, the job will not accept input data that is older than the current time. If you want to resend data, then delete the intervening results.

Authorization

You must have manage_ml, or manage cluster privileges to use this API. For more information, see Cluster Privileges.

Examples

The following example reverts to the 1491856080 snapshot for the it_ops_new_kpi job:

POST
_xpack/ml/anomaly_detectors/it_ops_new_kpi/model_snapshots/1491856080/_revert
{
  "delete_intervening_results": true
}

When the operation is complete, you receive the following results:

{
  "acknowledged": true,
  "model": {
    "job_id": "it_ops_new_kpi",
    "timestamp": 1491856080000,
    "description": "State persisted due to job close at 2017-04-10T13:28:00-0700",
    "snapshot_id": "1491856080",
    "snapshot_doc_count": 1,
    "model_size_stats": {
      "job_id": "it_ops_new_kpi",
      "result_type": "model_size_stats",
      "model_bytes": 29518,
      "total_by_field_count": 3,
      "total_over_field_count": 0,
      "total_partition_field_count": 2,
      "bucket_allocation_failures_count": 0,
      "memory_status": "ok",
      "log_time": 1491856080000,
      "timestamp": 1455318000000
    },
    "latest_record_time_stamp": 1455318669000,
    "latest_result_time_stamp": 1455318000000,
    "retain": false
  }
}

Update Model Snapshots

The update model snapshot API enables you to update certain properties of a snapshot.

Request

POST _xpack/ml/anomaly_detectors/<job_id>/model_snapshots/<snapshot_id>/_update

Description

Updates to the configuration are only applied after the job has been closed and re-opened.

Path Parameters

job_id (required)
(string) Identifier for the job
snapshot_id (required)
(string) Identifier for the model snapshot

Request Body

The following properties can be updated after the model snapshot is created:

description
(string) An optional description of the model snapshot. For example, "Before black friday".
retain
(boolean) If true, this snapshot will not be deleted during automatic cleanup of snapshots older than model_snapshot_retention_days. Note that this snapshot will still be deleted when the job is deleted. The default value is false.

Authorization

You must have manage_ml, or manage cluster privileges to use this API. For more information, see Cluster Privileges.

Examples

The following example updates the snapshot identified as 1491852978:

POST
_xpack/ml/anomaly_detectors/it_ops_new_logs/model_snapshots/1491852978/_update
{
  "description": "Snapshot 1",
  "retain": true
}

When the snapshot is updated, you receive the following results:

{
  "acknowledged": true,
  "model": {
    "job_id": "it_ops_new_logs",
    "timestamp": 1491852978000,
    "description": "Snapshot 1",
...
    "retain": true
  }
}