[role="xpack"] [testenv="platinum"] [[ml-put-job]] === Create {anomaly-jobs} API ++++ Create jobs ++++ Instantiates an {anomaly-job}. [[ml-put-job-request]] ==== {api-request-title} `PUT _ml/anomaly_detectors/` [[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 <>. [[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} ``:: (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`::: (<>) 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] [[put-customrules]]`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] If you specify a value for this property, it is ignored. -- `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`::: (<>) 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, <>) 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} [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" : "7.5.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" : "7.5.0"/"job_version" : $body.job_version/] // TESTRESPONSE[s/1562352500629/$body.$_path/]