[DOCS] Move anomaly detection job resource definitions into APIs (#49700)

Co-Authored-By: István Zoltán Szabó <[email protected]>

Author: lcawl

client/rest-high-level/src/main/java/org/elasticsearch/client/ml/job/config/Detector.java

@@ -34,9 +34,9 @@
 /**
  * Defines the fields and functions used in the analysis. A combination of <code>field_name</code>,
  * <code>by_field_name</code> and <code>over_field_name</code> can be used depending on the specific
- * function chosen. For more information see
- * <a href="https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-job-resource.html#ml-detectorconfig">configuring
- * detectors</a> and <a href="https://www.elastic.co/guide/en/elastic-stack-overview/current/ml-functions.html">detector functions</a>.
+ * function chosen. For more information see the
+ * <a href="https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-put-job.html">create anomaly detection
+ * jobs API</a> and <a href="https://www.elastic.co/guide/en/elastic-stack-overview/current/ml-functions.html">detector functions</a>.
  */
 public class Detector implements ToXContentObject {
 

docs/build.gradle

@@ -29,6 +29,7 @@ buildRestTests.expectedUnconvertedCandidates = [
   'reference/ml/anomaly-detection/apis/get-category.asciidoc',
   'reference/ml/anomaly-detection/apis/get-influencer.asciidoc',
   'reference/ml/anomaly-detection/apis/get-job-stats.asciidoc',
+  'reference/ml/anomaly-detection/apis/get-job.asciidoc',
   'reference/ml/anomaly-detection/apis/get-overall-buckets.asciidoc',
   'reference/ml/anomaly-detection/apis/get-record.asciidoc',
   'reference/ml/anomaly-detection/apis/get-snapshot.asciidoc',

docs/reference/ml/anomaly-detection/apis/close-job.asciidoc

@@ -60,25 +60,15 @@ results the job might have recently produced or might produce in the future.
 ==== {api-path-parms-title}
 
 `<job_id>`::
-  (Required, string) Identifier for the {anomaly-job}. It can be a job
-  identifier, a group name, or a wildcard expression.
+(Required, string)
+include::{docdir}/ml/ml-shared.asciidoc[tag=job-id-anomaly-detection-wildcard]
 
 [[ml-close-job-query-parms]]
 ==== {api-query-parms-title}
 
 `allow_no_jobs`::
-  (Optional, boolean) Specifies what to do when the request:
-+
---
-* Contains wildcard expressions and there are no jobs that match.
-* Contains the `_all` string or no identifiers and there are no matches.
-* Contains wildcard expressions and there are only partial matches.
-
-The default value is `true`, which returns an empty `jobs` array 
-when there are no matches and the subset of results when there are partial 
-matches. If this parameter is `false`, the request returns a `404` status code
-when there are no matches or only partial matches.
---
+(Optional, boolean)
+include::{docdir}/ml/ml-shared.asciidoc[tag=allow-no-jobs]
 
 `force`::
   (Optional, boolean) Use to close a failed job, or to forcefully close a job

docs/reference/ml/anomaly-detection/apis/datafeedresource.asciidoc

@@ -50,7 +50,7 @@ A {dfeed} resource has the following properties:
 `script_fields`::
   (object) Specifies scripts that evaluate custom expressions and returns
   script fields to the {dfeed}.
-  The <<ml-detectorconfig,detector configuration objects>> in a job can contain
+  The detector configuration objects in a job can contain
   functions that use these script fields.
   For more information, see
   {stack-ov}/ml-configuring-transform.html[Transforming Data With Script Fields].

docs/reference/ml/anomaly-detection/apis/delete-job.asciidoc

@@ -39,7 +39,8 @@ separated list.
 ==== {api-path-parms-title}
 
 `<job_id>`::
-  (Required, string) Identifier for the {anomaly-job}.
+(Required, string)
+include::{docdir}/ml/ml-shared.asciidoc[tag=job-id-anomaly-detection]
 
 [[ml-delete-job-query-parms]]
 ==== {api-query-parms-title}

docs/reference/ml/anomaly-detection/apis/flush-job.asciidoc

@@ -37,7 +37,8 @@ opened again before analyzing further data.
 ==== {api-path-parms-title}
 
 `<job_id>`::
-(string) Required. Identifier for the job.
+(Required, string)
+include::{docdir}/ml/ml-shared.asciidoc[tag=job-id-anomaly-detection]
 
 [[ml-flush-job-query-parms]]
 ==== {api-query-parms-title}

docs/reference/ml/anomaly-detection/apis/forecast.asciidoc

@@ -29,15 +29,16 @@ See {stack-ov}/ml-overview.html#ml-forecasting[Forecasting the future].
 ===============================
 
 * If you use an `over_field_name` property in your job, you cannot create a
-forecast. For more information about this property, see <<ml-job-resource>>.
+forecast. For more information about this property, see <<ml-put-job>>.
 * The job must be open when you create a forecast. Otherwise, an error occurs.
 ===============================
 
 [[ml-forecast-path-parms]]
 ==== {api-path-parms-title}
 
 `<job_id>`::
-  (Required, string) Identifier for the job.
+(Required, string)
+include::{docdir}/ml/ml-shared.asciidoc[tag=job-id-anomaly-detection]
 
 [[ml-forecast-request-body]]
 ==== {api-request-body-title}

docs/reference/ml/anomaly-detection/apis/get-bucket.asciidoc

@@ -36,7 +36,8 @@ bucket.
 ==== {api-path-parms-title}
 
 `<job_id>`::
-  (Required, string) Identifier for the {anomaly-job}.
+(Required, string)
+include::{docdir}/ml/ml-shared.asciidoc[tag=job-id-anomaly-detection]
 
 `<timestamp>`::
   (Optional, string) The timestamp of a single bucket result. If you do not

docs/reference/ml/anomaly-detection/apis/get-category.asciidoc

@@ -35,7 +35,8 @@ For more information about categories, see
 ==== {api-path-parms-title}
 
 `<job_id>`::
-  (Required, string) Identifier for the {anomaly-job}.
+(Required, string)
+include::{docdir}/ml/ml-shared.asciidoc[tag=job-id-anomaly-detection]
 
 `<category_id>`::
   (Optional, long) Identifier for the category. If you do not specify this

docs/reference/ml/anomaly-detection/apis/get-influencer.asciidoc

@@ -27,7 +27,8 @@ privileges. See <<security-privileges>> and
 ==== {api-path-parms-title}
 
 `<job_id>`::
-  (Required, string) Identifier for the {anomaly-job}.
+(Required, string)
+include::{docdir}/ml/ml-shared.asciidoc[tag=job-id-anomaly-detection]
 
 [[ml-get-influencer-request-body]]
 ==== {api-request-body-title}

docs/reference/ml/anomaly-detection/apis/get-job-stats.asciidoc

@@ -40,35 +40,24 @@ IMPORTANT: This API returns a maximum of 10,000 jobs.
 ==== {api-path-parms-title}
 
 `<job_id>`::
-  (Optional, string) An identifier for the {anomaly-job}. It can be a
-  job identifier, a group name, or a wildcard expression. If you do not specify
-  one of these options, the API returns statistics for all {anomaly-jobs}.
+(Optional, string)
+include::{docdir}/ml/ml-shared.asciidoc[tag=job-id-anomaly-detection-default]
 
 [[ml-get-job-stats-query-parms]]
 ==== {api-query-parms-title}
 
 `allow_no_jobs`::
-  (Optional, boolean) Specifies what to do when the request:
-+
---
-* Contains wildcard expressions and there are no jobs that match.
-* Contains the `_all` string or no identifiers and there are no matches.
-* Contains wildcard expressions and there are only partial matches.
-
-The default value is `true`, which returns an empty `jobs` array 
-when there are no matches and the subset of results when there are partial 
-matches. If this parameter is `false`, the request returns a `404` status code
-when there are no matches or only partial matches.
---
+(Optional, boolean)
+include::{docdir}/ml/ml-shared.asciidoc[tag=allow-no-jobs]
 
 [[ml-get-job-stats-results]]
 ==== {api-response-body-title}
 
 The API returns the following information:
 
 `jobs`::
-  (array) An array of {anomaly-job} statistics objects.
-  For more information, see <<ml-jobstats>>.
+(array) 
+include::{docdir}/ml/ml-shared.asciidoc[tag=jobs-stats-anomaly-detection]
 
 [[ml-get-job-stats-response-codes]]
 ==== {api-response-codes-title}

docs/reference/ml/anomaly-detection/apis/get-job.asciidoc

@@ -40,35 +40,101 @@ IMPORTANT: This API returns a maximum of 10,000 jobs.
 ==== {api-path-parms-title}
 
 `<job_id>`::
-  (Optional, string) Identifier for the {anomaly-job}. It can be a job
-  identifier, a group name, or a wildcard expression. If you do not specify one
-  of these options, the API returns information for all {anomaly-jobs}.
+(Optional, string)
+include::{docdir}/ml/ml-shared.asciidoc[tag=job-id-anomaly-detection-default]
 
 [[ml-get-job-query-parms]]
 ==== {api-query-parms-title}
 
 `allow_no_jobs`::
-  (Optional, boolean) Specifies what to do when the request:
+(Optional, boolean)
+include::{docdir}/ml/ml-shared.asciidoc[tag=allow-no-jobs]
+
+
+[[ml-get-job-results]]
+==== {api-response-body-title}
+
+The API returns an array of {anomaly-job} resources, which have the following
+properties:
+
+`allow_lazy_open`::
+(boolean)
+include::{docdir}/ml/ml-shared.asciidoc[tag=allow-lazy-open]
+
+[[get-analysisconfig]]`analysis_config`::
+(object)
+include::{docdir}/ml/ml-shared.asciidoc[tag=analysis-config]
+
+[[get-analysislimits]]`analysis_limits`::
+(object)
+include::{docdir}/ml/ml-shared.asciidoc[tag=analysis-limits]
+
+`background_persist_interval`::
+(time units)
+include::{docdir}/ml/ml-shared.asciidoc[tag=background-persist-interval]
+
+`create_time`::
+(string) The time the job was created. For example, `1491007356077`. This
+property is informational; you cannot change its value.
+
+[[get-customsettings]]`custom_settings`::
+(object)
+include::{docdir}/ml/ml-shared.asciidoc[tag=custom-settings]
+
+[[get-datadescription]]`data_description`:: 
+(object)
+include::{docdir}/ml/ml-shared.asciidoc[tag=data-description]
+
+`description`::
+(string) An optional description of the job.
+  
+`finished_time`::
+(string) If the job closed or failed, this is the time the job finished,
+otherwise it is `null`. This property is informational; you cannot change its
+value.
+
+`groups`::
+(array of strings)
+include::{docdir}/ml/ml-shared.asciidoc[tag=groups]
+
+`job_id`::
+(string)
+include::{docdir}/ml/ml-shared.asciidoc[tag=job-id-anomaly-detection-define]
 +
 --
-* Contains wildcard expressions and there are no jobs that match.
-* Contains the `_all` string or no identifiers and there are no matches.
-* Contains wildcard expressions and there are only partial matches.
-
-The default value is `true`, which returns an empty `jobs` array 
-when there are no matches and the subset of results when there are partial 
-matches. If this parameter is `false`, the request returns a `404` status code
-when there are no matches or only partial matches.
+This property is informational; you cannot change the identifier for existing
+jobs.
 --
 
-[[ml-get-job-results]]
-==== {api-response-body-title}
+`job_type`::
+(string) Reserved for future use, currently set to `anomaly_detector`.
 
-The API returns the following information:
+`job_version`::
+(string) The version of {es} that existed on the node when the job was created.
 
-`jobs`::
-  (array) An array of {anomaly-job} resources.
-  For more information, see <<ml-job-resource>>.
+[[get-modelplotconfig]]`model_plot_config`::
+(object)
+include::{docdir}/ml/ml-shared.asciidoc[tag=model-plot-config]
+
+`model_snapshot_id`::
+(string)
+include::{docdir}/ml/ml-shared.asciidoc[tag=model-snapshot-id]
++
+--
+This property is informational; you cannot change its value. 
+--
+
+`model_snapshot_retention_days`::
+(long)
+include::{docdir}/ml/ml-shared.asciidoc[tag=model-snapshot-retention-days]
+
+`renormalization_window_days`::
+(long)
+include::{docdir}/ml/ml-shared.asciidoc[tag=renormalization-window-days]
+
+`results_index_name`::
+(string)
+include::{docdir}/ml/ml-shared.asciidoc[tag=results-index-name]
 
 [[ml-get-job-response-codes]]
 ==== {api-response-codes-title}
@@ -80,53 +146,68 @@ The API returns the following information:
 [[ml-get-job-example]]
 ==== {api-examples-title}
 
-The following example gets configuration information for the `total-requests` job:
+//The following example gets configuration information for the `total-requests` job:
 
 [source,console]
 --------------------------------------------------
-GET _ml/anomaly_detectors/total-requests
+GET _ml/anomaly_detectors/high_sum_total_sales
 --------------------------------------------------
-// TEST[skip:setup:server_metrics_job]
+// TEST[skip:Kibana sample data]
 
 The API returns the following results:
 
-[source,console-result]
+[source,js]
 ----
 {
   "count": 1,
   "jobs": [
     {
-      "job_id": "total-requests",
-      "job_type": "anomaly_detector",
-      "job_version": "7.0.0-alpha1",
-      "description": "Total sum of requests",
-      "create_time": 1517011406091,
-      "analysis_config": {
-        "bucket_span": "10m",
-        "detectors": [
+      "job_id" : "high_sum_total_sales",
+      "job_type" : "anomaly_detector",
+      "job_version" : "8.0.0",
+      "groups" : [
+        "kibana_sample_data",
+        "kibana_sample_ecommerce"
+      ],
+      "description" : "Find customers spending an unusually high amount in an hour",
+      "create_time" : 1575402224732,
+      "finished_time" : 1575402238311,
+      "analysis_config" : {
+        "bucket_span" : "1h",
+        "detectors" : [
           {
-            "detector_description": "Sum of total",
-            "function": "sum",
-            "field_name": "total",
-            "detector_index": 0
+            "detector_description" : "High total sales",
+            "function" : "high_sum",
+            "field_name" : "taxful_total_price",
+            "over_field_name" : "customer_full_name.keyword",
+            "detector_index" : 0
           }
         ],
-        "influencers": [ ]
+        "influencers" : [
+          "customer_full_name.keyword",
+          "category.keyword"
+        ]
+      },
+      "analysis_limits" : {
+        "model_memory_limit" : "10mb",
+        "categorization_examples_limit" : 4
+      },
+      "data_description" : {
+        "time_field" : "order_date",
+        "time_format" : "epoch_ms"
       },
-      "analysis_limits": {
-        "model_memory_limit": "1024mb",
-        "categorization_examples_limit": 4
+      "model_plot_config" : {
+        "enabled" : true
       },
-      "data_description": {
-        "time_field": "timestamp",
-        "time_format": "epoch_ms"
+      "model_snapshot_retention_days" : 1,
+      "custom_settings" : {
+        "created_by" : "ml-module-sample",
+        ...
       },
-      "model_snapshot_retention_days": 1,
-      "results_index_name": "shared",
-      "allow_lazy_open": false
+      "model_snapshot_id" : "1575402237",
+      "results_index_name" : "shared",
+      "allow_lazy_open" : false
     }
   ]
 }
 ----
-// TESTRESPONSE[s/"7.0.0-alpha1"/$body.$_path/]
-// TESTRESPONSE[s/1517011406091/$body.$_path/]