get-record.asciidoc 7.3 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237
  1. [role="xpack"]
  2. [testenv="platinum"]
  3. [[ml-get-record]]
  4. = Get records API
  5. ++++
  6. <titleabbrev>Get records</titleabbrev>
  7. ++++
  8. Retrieves anomaly records for an {anomaly-job}.
  9. [[ml-get-record-request]]
  10. == {api-request-title}
  11. `GET _ml/anomaly_detectors/<job_id>/results/records`
  12. [[ml-get-record-prereqs]]
  13. == {api-prereq-title}
  14. Requires the `monitor_ml` cluster privilege. This privilege is included in the
  15. `machine_learning_user` built-in role.
  16. [[ml-get-record-desc]]
  17. == {api-description-title}
  18. Records contain the detailed analytical results. They describe the anomalous
  19. activity that has been identified in the input data based on the detector
  20. configuration.
  21. There can be many anomaly records depending on the characteristics and size of
  22. the input data. In practice, there are often too many to be able to manually
  23. process them. The {ml-features} therefore perform a sophisticated aggregation of
  24. the anomaly records into buckets.
  25. The number of record results depends on the number of anomalies found in each
  26. bucket, which relates to the number of time series being modeled and the number
  27. of detectors.
  28. [[ml-get-record-path-parms]]
  29. == {api-path-parms-title}
  30. `<job_id>`::
  31. (Required, string)
  32. include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=job-id-anomaly-detection]
  33. [[ml-get-record-request-body]]
  34. == {api-request-body-title}
  35. `desc`::
  36. (Optional, Boolean)
  37. include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=desc-results]
  38. `end`::
  39. (Optional, string) Returns records with timestamps earlier than this time.
  40. `exclude_interim`::
  41. (Optional, Boolean)
  42. include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=exclude-interim-results]
  43. `page`.`from`::
  44. (Optional, integer) Skips the specified number of records.
  45. `page`.`size`::
  46. (Optional, integer) Specifies the maximum number of records to obtain.
  47. `record_score`::
  48. (Optional, double) Returns records with anomaly scores greater or equal than
  49. this value.
  50. `sort`::
  51. (Optional, string) Specifies the sort field for the requested records. By
  52. default, the records are sorted by the `anomaly_score` value.
  53. `start`::
  54. (Optional, string) Returns records with timestamps after this time.
  55. [[ml-get-record-results]]
  56. == {api-response-body-title}
  57. The API returns an array of record objects, which have the following properties:
  58. `actual`::
  59. (array) The actual value for the bucket.
  60. `bucket_span`::
  61. (number)
  62. include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=bucket-span-results]
  63. `by_field_name`::
  64. (string)
  65. include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=by-field-name]
  66. `by_field_value`::
  67. (string) The value of `by_field_name`.
  68. `causes`::
  69. (array) For population analysis, an over field must be specified in the detector.
  70. This property contains an array of anomaly records that are the causes for the
  71. anomaly that has been identified for the over field. If no over fields exist,
  72. this field is not present. This sub-resource contains the most anomalous records
  73. for the `over_field_name`. For scalability reasons, a maximum of the 10 most
  74. significant causes of the anomaly are returned. As part of the core analytical modeling, these low-level anomaly records are aggregated for their parent over
  75. field record. The causes resource contains similar elements to the record
  76. resource, namely `actual`, `typical`, `geo_results.actual_point`,
  77. `geo_results.typical_point`, `*_field_name` and `*_field_value`. Probability and
  78. scores are not applicable to causes.
  79. `detector_index`::
  80. (number) A unique identifier for the detector.
  81. `field_name`::
  82. (string) Certain functions require a field to operate on, for example, `sum()`.
  83. For those functions, this value is the name of the field to be analyzed.
  84. `function`::
  85. (string) The function in which the anomaly occurs, as specified in the detector
  86. configuration. For example, `max`.
  87. `function_description`::
  88. (string) The description of the function in which the anomaly occurs, as
  89. specified in the detector configuration.
  90. `geo_results.actual_point`::
  91. (string) The actual value for the bucket formatted as a `geo_point`. If the
  92. detector function is `lat_long`, this is a comma delimited string of the
  93. latitude and longitude.
  94. `geo_results.typical_point`::
  95. (string) The typical value for the bucket formatted as a `geo_point`. If the
  96. detector function is `lat_long`, this is a comma delimited string of the
  97. latitude and longitude.
  98. `influencers`::
  99. (array) If `influencers` was specified in the detector configuration, this array
  100. contains influencers that contributed to or were to blame for an anomaly.
  101. `initial_record_score`::
  102. (number) A normalized score between 0-100, which is based on the probability of
  103. the anomalousness of this record. This is the initial value that was calculated
  104. at the time the bucket was processed.
  105. `is_interim`::
  106. (Boolean)
  107. include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=is-interim]
  108. `job_id`::
  109. (string)
  110. include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=job-id-anomaly-detection]
  111. `over_field_name`::
  112. (string)
  113. include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=over-field-name]
  114. `over_field_value`::
  115. (string) The value of `over_field_name`.
  116. `partition_field_name`::
  117. (string)
  118. include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=partition-field-name]
  119. `partition_field_value`::
  120. (string) The value of `partition_field_name`.
  121. `probability`::
  122. (number) The probability of the individual anomaly occurring, in the range
  123. 0 to 1. For example, 0.0000772031. This value can be held to a high precision
  124. of over 300 decimal places, so the `record_score` is provided as a
  125. human-readable and friendly interpretation of this.
  126. `multi_bucket_impact`::
  127. (number) An indication of how strongly an anomaly is multi bucket or single
  128. bucket. The value is on a scale of `-5.0` to `+5.0` where `-5.0` means the
  129. anomaly is purely single bucket and `+5.0` means the anomaly is purely multi
  130. bucket.
  131. `record_score`::
  132. (number) A normalized score between 0-100, which is based on the probability of
  133. the anomalousness of this record. Unlike `initial_record_score`, this value will
  134. be updated by a re-normalization process as new data is analyzed.
  135. `result_type`::
  136. (string) Internal. This is always set to `record`.
  137. `timestamp`::
  138. (date)
  139. include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=timestamp-results]
  140. `typical`::
  141. (array) The typical value for the bucket, according to analytical modeling.
  142. NOTE: Additional record properties are added, depending on the fields being
  143. analyzed. For example, if it's analyzing `hostname` as a _by field_, then a field
  144. `hostname` is added to the result document. This information enables you to
  145. filter the anomaly results more easily.
  146. [[ml-get-record-example]]
  147. == {api-examples-title}
  148. [source,console]
  149. --------------------------------------------------
  150. GET _ml/anomaly_detectors/low_request_rate/results/records
  151. {
  152. "sort": "record_score",
  153. "desc": true,
  154. "start": "1454944100000"
  155. }
  156. --------------------------------------------------
  157. // TEST[skip:Kibana sample data]
  158. [source,js]
  159. ----
  160. {
  161. "count" : 4,
  162. "records" : [
  163. {
  164. "job_id" : "low_request_rate",
  165. "result_type" : "record",
  166. "probability" : 1.3882308899968812E-4,
  167. "multi_bucket_impact" : -5.0,
  168. "record_score" : 94.98554565630553,
  169. "initial_record_score" : 94.98554565630553,
  170. "bucket_span" : 3600,
  171. "detector_index" : 0,
  172. "is_interim" : false,
  173. "timestamp" : 1577793600000,
  174. "function" : "low_count",
  175. "function_description" : "count",
  176. "typical" : [
  177. 28.254208230188834
  178. ],
  179. "actual" : [
  180. 0.0
  181. ]
  182. },
  183. ...
  184. ]
  185. }
  186. ----