Merge doc-examples branch (#2759)

* Add machine learning API examples (#2452)

* Add examples for transform APIs (#2505)

* [DOCS] Adds ML API examples (DELETE ops) (#2518)

* [DOCS] Adds anomaly detection API examples.

* [DOCS] Adds more ML examples.

* [DOCS] Further edits.

* [DOCS] Fixes style.

* [DOCS] Adds example requests and responses to ML APIs (C-E) (#2521)

Co-authored-by: Quentin Pradet <[email protected]>

---------

Co-authored-by: Lisa Cawley <[email protected]>
Co-authored-by: István Zoltán Szabó <[email protected]>

specification/ml/clear_trained_model_deployment_cache/examples/200_response/MlClearTrainedModelDeploymentCacheResponseExample1.json

@@ -0,0 +1,6 @@
+{
+  "summary": "A successful response when clearing the inference cache.",
+  "value": {
+    "cleared": true
+  }
+}

specification/ml/close_job/examples/200_response/MlCloseJobResponseExample1.json

@@ -0,0 +1,6 @@
+{
+  "summary": "A successful response when closing anomaly detection jobs.",
+  "value": {
+    "closed": true
+  }
+}

specification/ml/delete_calendar/examples/200_response/MlDeleteCalendarResponseExample1.json

@@ -0,0 +1,6 @@
+{
+  "summary": "A successful response when deleting a calendar.",
+  "value": {
+    "acknowledged": true
+  }
+}

specification/ml/delete_calendar_event/examples/200_response/MlDeleteCalendarEventResponseExample1.json

@@ -0,0 +1,6 @@
+{
+  "summary": "A successful response when deleting a calendar event.",
+  "value": {
+    "acknowledged": true
+  }
+}

specification/ml/delete_calendar_job/examples/200_response/MlDeleteCalendarJobResponseExample1.json

@@ -0,0 +1,7 @@
+{
+  "summary": "A successful response when deleting an anomaly detection job from a calendar.",
+  "value": {
+    "calendar_id": "planned-outages",
+    "job_ids": []
+  }
+}

specification/ml/delete_data_frame_analytics/examples/200_response/MlDeleteDataFrameAnalyticsResponseExample1.json

@@ -0,0 +1,6 @@
+{
+  "summary": "A successful response when deleting a data frame analytics job.",
+  "value": {
+    "acknowledged": true
+  }
+}

specification/ml/delete_datafeed/examples/200_response/MlDeleteDatafeedResponseExample1.json

@@ -0,0 +1,6 @@
+{
+  "summary": "A successful response when deleting a datafeed.",
+  "value": {
+    "acknowledged": true
+  }
+}

specification/ml/delete_expired_data/examples/200_response/MlDeleteExpiredDataResponseExample1.json

@@ -0,0 +1,6 @@
+{
+  "summary": "A successful response when deleting expired and unused anomaly detection data.",
+  "value": {
+    "deleted": true
+  }
+}

specification/ml/delete_filter/examples/200_response/MlDeleteFilterResponseExample1.json

@@ -0,0 +1,6 @@
+{
+  "summary": "A successful response when deleting a filter.",
+  "value": {
+    "acknowledged": true
+  }
+}

specification/ml/delete_forecast/examples/200_response/MlDeleteForecastResponseExample1.json

@@ -0,0 +1,6 @@
+{
+  "summary": "A successful response when deleting a forecast from an anomaly detection job.",
+  "value": {
+    "acknowledged": true
+  }
+}

specification/ml/delete_job/examples/200_response/MlDeleteJobResponseExample1.json

@@ -0,0 +1,6 @@
+{
+  "summary": "A successful response when deleting an anomaly detection job.",
+  "value": {
+    "acknowledged": true
+  }
+}

specification/ml/delete_job/examples/200_response/MlDeleteJobResponseExample2.json

@@ -0,0 +1,7 @@
+{
+  "summary": "A successful response when deleting an anomaly detection job asynchronously.",
+  "description": "When the `wait_for_completion` query parameter is set to `false`, the response contains an identifier for the job deletion task.",
+  "value": {
+    "task": "oTUltX4IQMOUUVeiohTt8A:39"
+  }
+}

specification/ml/delete_model_snapshot/examples/200_responses/MlDeleteModelSnapshotResponseExample1.json

@@ -0,0 +1,6 @@
+{
+  "summary": "A successful response when deleting an existing model snapshot.",
+  "value": {
+    "acknowledged": true
+  }
+}

specification/ml/delete_trained_model/examples/200_response/MlDeleteTrainedModelResponseExample1.json

@@ -0,0 +1,6 @@
+{
+  "summary": "A successful response when deleting an existing trained inference model.",
+  "value": {
+    "acknowledged": true
+  }
+}

specification/ml/delete_trained_model_alias/examples/MlDeleteTrainedModelAliasResponseExample1.json

@@ -0,0 +1,6 @@
+{
+  "summary": "A successful response when deleting a trained model alias.",
+  "value": {
+    "acknowledged": true
+  }
+}

specification/ml/estimate_model_memory/examples/200_response/MlEstimateModelMemoryResponseExample1.json

@@ -0,0 +1,6 @@
+{
+  "summary": "A successful response when estimating sufficent memory for a model.",
+  "value": {
+    "model_memory_estimate": "21mb"
+  }
+}

specification/ml/estimate_model_memory/examples/request/MlEstimateModelMemoryRequestExample1.json

@@ -0,0 +1,25 @@
+{
+  "summary": "A request of estimating model memory limit based on the analysis configuration details provided in the body.",
+  "value": {
+    "analysis_config": {
+      "bucket_span": "5m",
+      "detectors": [
+        {
+          "function": "sum",
+          "field_name": "bytes",
+          "by_field_name": "status",
+          "partition_field_name": "app"
+        }
+      ],
+      "influencers": ["source_ip", "dest_ip"]
+    },
+    "overall_cardinality": {
+      "status": 10,
+      "app": 50
+    },
+    "max_bucket_cardinality": {
+      "source_ip": 300,
+      "dest_ip": 30
+    }
+  }
+}

specification/ml/evaluate_data_frame/examples/200_response/MlEvaluateDataFrameResponseClassificationExample1.json

@@ -0,0 +1,43 @@
+{
+  "summary": "A succesful response for evaluating a classification analysis job for an annotated index.",
+  "description": "The `actual_class` contains the name of the class the analysis tried to predict. The `actual_class_doc_count` is the number of documents in the index belonging to the `actual_class`. The `predicted_classes` object contains the list of the predicted classes and the number of predictions associated with the class.",
+  "value": {
+    "classification": {
+      "multiclass_confusion_matrix": {
+        "confusion_matrix": [
+          {
+            "actual_class": "cat",
+            "actual_class_doc_count": 12,
+            "predicted_classes": [
+              {
+                "predicted_class": "cat",
+                "count": 12
+              },
+              {
+                "predicted_class": "dog",
+                "count": 0
+              }
+            ],
+            "other_predicted_class_doc_count": 0
+          },
+          {
+            "actual_class": "dog",
+            "actual_class_doc_count": 11,
+            "predicted_classes": [
+              {
+                "predicted_class": "dog",
+                "count": 7
+              },
+              {
+                "predicted_class": "cat",
+                "count": 4
+              }
+            ],
+            "other_predicted_class_doc_count": 0
+          }
+        ],
+        "other_actual_class_count": 0
+      }
+    }
+  }
+}

specification/ml/evaluate_data_frame/examples/200_response/MlEvaluateDataFrameResponseClassificationExample2.json

@@ -0,0 +1,10 @@
+{
+  "summary": "A succesful response for evaluating a classification analysis job with the AUC ROC metrics for an annotated index.",
+  "value": {
+    "classification": {
+      "auc_roc": {
+        "value": 0.8941788639536681
+      }
+    }
+  }
+}

specification/ml/evaluate_data_frame/examples/200_response/MlEvaluateDataFrameResponseOutlierExample.json

@@ -0,0 +1,40 @@
+{
+  "summary": "A successful response when evaluating an outlier detection job.",
+  "value": {
+    "outlier_detection": {
+      "auc_roc": {
+        "value": 0.92584757746414444
+      },
+      "confusion_matrix": {
+        "0.25": {
+          "tp": 5,
+          "fp": 9,
+          "tn": 204,
+          "fn": 5
+        },
+        "0.5": {
+          "tp": 1,
+          "fp": 5,
+          "tn": 208,
+          "fn": 9
+        },
+        "0.75": {
+          "tp": 0,
+          "fp": 4,
+          "tn": 209,
+          "fn": 10
+        }
+      },
+      "precision": {
+        "0.25": 0.35714285714285715,
+        "0.5": 0.16666666666666666,
+        "0.75": 0
+      },
+      "recall": {
+        "0.25": 0.5,
+        "0.5": 0.1,
+        "0.75": 0
+      }
+    }
+  }
+}

specification/ml/evaluate_data_frame/examples/request/MlEvaluateDataFrameRequestClassificationExample1.json

@@ -0,0 +1,16 @@
+{
+  "summary": "A request for evaluating a classification job for an annotated index.",
+  "description": "The `actual_field` contains the ground truth for classification. The `predicted_field` contains the predicted value calculated by the classification analysis.",
+  "value": {
+    "index": "animal_classification",
+    "evaluation": {
+      "classification": {
+        "actual_field": "animal_class",
+        "predicted_field": "ml.animal_class_prediction",
+        "metrics": {
+          "multiclass_confusion_matrix": {}
+        }
+      }
+    }
+  }
+}

specification/ml/evaluate_data_frame/examples/request/MlEvaluateDataFrameRequestClassificationExample2.json

@@ -0,0 +1,17 @@
+{
+  "summary": "A request for evaluating a classification job with AUC ROC metrics for an annotated index.",
+  "description": "The `class_name` specifies the class name that is treated as positive during the evaluation, all the other classes are treated as negative.",
+  "value": {
+    "index": "animal_classification",
+    "evaluation": {
+      "classification": {
+        "actual_field": "animal_class",
+        "metrics": {
+          "auc_roc": {
+            "class_name": "dog"
+          }
+        }
+      }
+    }
+  }
+}

specification/ml/evaluate_data_frame/examples/request/MlEvaluateDataFrameRequestOutlierExample.json

@@ -0,0 +1,12 @@
+{
+  "summary": "A request for evaluating an outlier detection job for an annotated index.",
+  "value": {
+    "index": "my_analytics_dest_index",
+    "evaluation": {
+      "outlier_detection": {
+        "actual_field": "is_outlier",
+        "predicted_probability_field": "ml.outlier_score"
+      }
+    }
+  }
+}

specification/ml/evaluate_data_frame/examples/request/MlEvaluateDataFrameRequestRegressionExample1.json

@@ -0,0 +1,34 @@
+{
+  "summary": "A request for evaluating the testing error of a regression job for an annotated index.",
+  "description": "The term query in the body limits evaluation to be performed on the test split only. The `actual_field` contains the ground truth for house prices. The `predicted_field` contains the house price calculated by the regression analysis.",
+  "value": {
+    "index": "house_price_predictions",
+    "query": {
+      "bool": {
+        "filter": [
+          {
+            "term": {
+              "ml.is_training": false
+            }
+          }
+        ]
+      }
+    },
+    "evaluation": {
+      "regression": {
+        "actual_field": "price",
+        "predicted_field": "ml.price_prediction",
+        "metrics": {
+          "r_squared": {},
+          "mse": {},
+          "msle": {
+            "offset": 10
+          },
+          "huber": {
+            "delta": 1.5
+          }
+        }
+      }
+    }
+  }
+}

specification/ml/evaluate_data_frame/examples/request/MlEvaluateDataFrameRequestRegressionExample2.json

@@ -0,0 +1,26 @@
+{
+  "summary": "A request for evaluating the training error of a regression job for an annotated index.",
+  "description": "The term query in the body limits evaluation to be performed on the training split only. The `actual_field` contains the ground truth for house prices. The `predicted_field` contains the house price calculated by the regression analysis.",
+  "value": {
+    "index": "house_price_predictions",
+    "query": {
+      "term": {
+        "ml.is_training": {
+          "value": true
+        }
+      }
+    },
+    "evaluation": {
+      "regression": {
+        "actual_field": "price",
+        "predicted_field": "ml.price_prediction",
+        "metrics": {
+          "r_squared": {},
+          "mse": {},
+          "msle": {},
+          "huber": {}
+        }
+      }
+    }
+  }
+}

specification/ml/explain_data_frame_analytics/examples/200_response/MlExplainDataFrameAnalyticsResponseExample1.json

@@ -0,0 +1,39 @@
+{
+  "summary": "A succesful response for explaining a data frame analytics job configuration.",
+  "value": {
+    "field_selection": [
+      {
+        "field": "number_of_bedrooms",
+        "mappings_types": ["integer"],
+        "is_included": true,
+        "is_required": false,
+        "feature_type": "numerical"
+      },
+      {
+        "field": "postcode",
+        "mappings_types": ["text"],
+        "is_included": false,
+        "is_required": false,
+        "reason": "[postcode.keyword] is preferred because it is aggregatable"
+      },
+      {
+        "field": "postcode.keyword",
+        "mappings_types": ["keyword"],
+        "is_included": true,
+        "is_required": false,
+        "feature_type": "categorical"
+      },
+      {
+        "field": "price",
+        "mappings_types": ["float"],
+        "is_included": true,
+        "is_required": true,
+        "feature_type": "numerical"
+      }
+    ],
+    "memory_estimation": {
+      "expected_memory_without_disk": "128MB",
+      "expected_memory_with_disk": "32MB"
+    }
+  }
+}

specification/ml/explain_data_frame_analytics/examples/request/MlExplainDataFrameAnalyticsRequestExample1.json

@@ -0,0 +1,13 @@
+{
+  "summary": "A request for explaining a data frame analytics job configuration.",
+  "value": {
+    "source": {
+      "index": "houses_sold_last_10_yrs"
+    },
+    "analysis": {
+      "regression": {
+        "dependent_variable": "price"
+      }
+    }
+  }
+}