elasticsearch/docs/reference/ml/anomaly-detection/apis/put-job.asciidoc

[role="xpack"]
[testenv="platinum"]
[[ml-put-job]]
=== Create {anomaly-jobs} API
++++
<titleabbrev>Create jobs</titleabbrev>
++++

Instantiates an {anomaly-job}.

[[ml-put-job-request]]
==== {api-request-title}

`PUT _ml/anomaly_detectors/<job_id>`

[[ml-put-job-prereqs]]
==== {api-prereq-title}

* If the {es} {security-features} are enabled, you must have `manage_ml` or
`manage` cluster privileges to use this API. See
<<security-privileges>>.

[[ml-put-job-desc]]
==== {api-description-title}

IMPORTANT: You must use {kib} or this API to create an {anomaly-job}. Do not put
a job directly to the `.ml-config` index using the {es} index API. If {es}
{security-features} are enabled, do not give users `write` privileges on the
`.ml-config` index.

[[ml-put-job-path-parms]]
==== {api-path-parms-title}

`<job_id>`::
(Required, string)
include::{docdir}/ml/ml-shared.asciidoc[tag=job-id-anomaly-detection-define]

[[ml-put-job-request-body]]
==== {api-request-body-title}

`allow_lazy_open`::
(Optional, boolean)
include::{docdir}/ml/ml-shared.asciidoc[tag=allow-lazy-open]

[[put-analysisconfig]]`analysis_config`::
(Required, object)
include::{docdir}/ml/ml-shared.asciidoc[tag=analysis-config]

`analysis_config`.`bucket_span`:::
(<<time-units,time units>>)
include::{docdir}/ml/ml-shared.asciidoc[tag=bucket-span]

`analysis_config`.`categorization_field_name`:::
(string)
include::{docdir}/ml/ml-shared.asciidoc[tag=categorization-field-name]

`analysis_config`.`categorization_filters`:::
(array of strings)
include::{docdir}/ml/ml-shared.asciidoc[tag=categorization-filters]

`analysis_config`.`categorization_analyzer`:::
(object or string)
include::{docdir}/ml/ml-shared.asciidoc[tag=categorization-analyzer]

`analysis_config`.`detectors`:::
(array) An array of detector configuration objects. Detector configuration
objects specify which data fields a job analyzes. They also specify which
analytical functions are used. You can specify multiple detectors for a job. 
+
--
NOTE: If the `detectors` array does not contain at least one detector,
no analysis can occur and an error is returned.

A detector has the following properties:
--

`analysis_config`.`detectors`.`by_field_name`::::
(string)
include::{docdir}/ml/ml-shared.asciidoc[tag=by-field-name]

`analysis_config`.`detectors`.`custom_rules`::::
+
--
(array)
include::{docdir}/ml/ml-shared.asciidoc[tag=custom-rules]

`analysis_config`.`detectors`.`custom_rules`.`actions`:::
(array)
include::{docdir}/ml/ml-shared.asciidoc[tag=custom-rules-actions]

`analysis_config`.`detectors`.`custom_rules`.`scope`:::
(object)
include::{docdir}/ml/ml-shared.asciidoc[tag=custom-rules-scope]

`analysis_config`.`detectors`.`custom_rules`.`scope`.`filter_id`::::
(string)
include::{docdir}/ml/ml-shared.asciidoc[tag=custom-rules-scope-filter-id]

`analysis_config`.`detectors`.`custom_rules`.`scope`.`filter_type`::::
(string)
include::{docdir}/ml/ml-shared.asciidoc[tag=custom-rules-scope-filter-type]

`analysis_config`.`detectors`.`custom_rules`.`conditions`:::
(array)
include::{docdir}/ml/ml-shared.asciidoc[tag=custom-rules-conditions]

`analysis_config`.`detectors`.`custom_rules`.`conditions`.`applies_to`::::
(string)
include::{docdir}/ml/ml-shared.asciidoc[tag=custom-rules-conditions-applies-to]

`analysis_config`.`detectors`.`custom_rules`.`conditions`.`operator`::::
(string)
include::{docdir}/ml/ml-shared.asciidoc[tag=custom-rules-conditions-operator]

`analysis_config`.`detectors`.`custom_rules`.`conditions`.`value`::::
(double)
include::{docdir}/ml/ml-shared.asciidoc[tag=custom-rules-conditions-value]
--

`analysis_config`.`detectors`.`detector_description`::::
(string)
include::{docdir}/ml/ml-shared.asciidoc[tag=detector-description]

`analysis_config`.`detectors`.`detector_index`::::
(integer)
include::{docdir}/ml/ml-shared.asciidoc[tag=detector-index]

`analysis_config`.`detectors`.`exclude_frequent`::::
(string)
include::{docdir}/ml/ml-shared.asciidoc[tag=exclude-frequent]

`analysis_config`.`detectors`.`field_name`::::
(string)
include::{docdir}/ml/ml-shared.asciidoc[tag=detector-field-name]

`analysis_config`.`detectors`.`function`::::
(string)
include::{docdir}/ml/ml-shared.asciidoc[tag=function]

`analysis_config`.`detectors`.`over_field_name`::::
(string)
include::{docdir}/ml/ml-shared.asciidoc[tag=over-field-name]

`analysis_config`.`detectors`.`partition_field_name`::::
(string)
include::{docdir}/ml/ml-shared.asciidoc[tag=partition-field-name]

`analysis_config`.`detectors`.`use_null`::::
(boolean)
include::{docdir}/ml/ml-shared.asciidoc[tag=use-null]

`analysis_config`.`influencers`:::
(array of strings)
include::{docdir}/ml/ml-shared.asciidoc[tag=influencers]

`analysis_config`.`latency`:::
(time units)
include::{docdir}/ml/ml-shared.asciidoc[tag=latency]

`analysis_config`.`multivariate_by_fields`:::
(boolean)
include::{docdir}/ml/ml-shared.asciidoc[tag=multivariate-by-fields]

`analysis_config`.`summary_count_field_name`:::
(string)
include::{docdir}/ml/ml-shared.asciidoc[tag=summary-count-field-name]

[[put-analysislimits]]`analysis_limits`::
(Optional, object)
include::{docdir}/ml/ml-shared.asciidoc[tag=analysis-limits]
+
--
The `analysis_limits` object has the following properties:
--

`analysis_limits`.`categorization_examples_limit`:::
(long)
include::{docdir}/ml/ml-shared.asciidoc[tag=categorization-examples-limit]

`analysis_limits`.`model_memory_limit`:::
(long or string) 
include::{docdir}/ml/ml-shared.asciidoc[tag=model-memory-limit]

`background_persist_interval`::
(Optional, <<time-units, time units>>)
include::{docdir}/ml/ml-shared.asciidoc[tag=background-persist-interval]

[[put-customsettings]]`custom_settings`::
(Optional, object)
include::{docdir}/ml/ml-shared.asciidoc[tag=custom-settings]

[[put-datadescription]]`data_description`::
(Required, object)
include::{docdir}/ml/ml-shared.asciidoc[tag=data-description]

`description`::
  (Optional, string) A description of the job.

`groups`::
(Optional, array of strings)
include::{docdir}/ml/ml-shared.asciidoc[tag=groups]

`model_plot_config`::
(Optional, object)
include::{docdir}/ml/ml-shared.asciidoc[tag=model-plot-config]

`model_plot_config`.`enabled`:::
(boolean)
include::{docdir}/ml/ml-shared.asciidoc[tag=model-plot-config-enabled]

`model_plot_config`.`terms`:::
experimental[] (string)
include::{docdir}/ml/ml-shared.asciidoc[tag=model-plot-config-terms]

`model_snapshot_retention_days`::
(Optional, long)
include::{docdir}/ml/ml-shared.asciidoc[tag=model-snapshot-retention-days]

`renormalization_window_days`::
(Optional, long)
include::{docdir}/ml/ml-shared.asciidoc[tag=renormalization-window-days]

`results_index_name`::
(Optional, string)
include::{docdir}/ml/ml-shared.asciidoc[tag=results-index-name]

`results_retention_days`::
(Optional, long)
include::{docdir}/ml/ml-shared.asciidoc[tag=results-retention-days]

[[ml-put-job-example]]
==== {api-examples-title}

The following example creates the `total-requests` job:

[source,console]
--------------------------------------------------
PUT _ml/anomaly_detectors/total-requests
{
  "description" : "Total sum of requests",
  "analysis_config" : {
    "bucket_span":"10m",
    "detectors": [
      {
        "detector_description": "Sum of total",
        "function": "sum",
        "field_name": "total"
      }
    ]
  },
  "data_description" : {
    "time_field":"timestamp",
    "time_format": "epoch_ms"
  }
}
--------------------------------------------------

When the job is created, you receive the following results:

[source,console-result]
----
{
  "job_id" : "total-requests",
  "job_type" : "anomaly_detector",
  "job_version" : "8.0.0",
  "description" : "Total sum of requests",
  "create_time" : 1562352500629,
  "analysis_config" : {
    "bucket_span" : "10m",
    "detectors" : [
      {
        "detector_description" : "Sum of total",
        "function" : "sum",
        "field_name" : "total",
        "detector_index" : 0
      }
    ],
    "influencers" : [ ]
  },
  "analysis_limits" : {
    "model_memory_limit" : "1024mb",
    "categorization_examples_limit" : 4
  },
  "data_description" : {
    "time_field" : "timestamp",
    "time_format" : "epoch_ms"
  },
  "model_snapshot_retention_days" : 1,
  "results_index_name" : "shared",
  "allow_lazy_open" : false
}
----
// TESTRESPONSE[s/"job_version" : "8.0.0"/"job_version" : $body.job_version/]
// TESTRESPONSE[s/1562352500629/$body.$_path/]