explain-dfanalytics.asciidoc 3.4 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145
  1. [role="xpack"]
  2. [testenv="platinum"]
  3. [[explain-dfanalytics]]
  4. === Explain {dfanalytics} API
  5. [subs="attributes"]
  6. ++++
  7. <titleabbrev>Explain {dfanalytics} API</titleabbrev>
  8. ++++
  9. Explains a {dataframe-analytics-config}.
  10. experimental[]
  11. [[ml-explain-dfanalytics-request]]
  12. ==== {api-request-title}
  13. `GET _ml/data_frame/analytics/_explain` +
  14. `POST _ml/data_frame/analytics/_explain` +
  15. `GET _ml/data_frame/analytics/<data_frame_analytics_id>/_explain` +
  16. `POST _ml/data_frame/analytics/<data_frame_analytics_id>/_explain`
  17. [[ml-explain-dfanalytics-prereq]]
  18. ==== {api-prereq-title}
  19. If the {es} {security-features} are enabled, you must have the following
  20. privileges:
  21. * cluster: `monitor_ml`
  22. For more information, see <<security-privileges>> and <<built-in-roles>>.
  23. [[ml-explain-dfanalytics-desc]]
  24. ==== {api-description-title}
  25. This API provides explanations for a {dataframe-analytics-config} that either
  26. exists already or one that has not been created yet.
  27. The following explanations are provided:
  28. * which fields are included or not in the analysis and why,
  29. * how much memory is estimated to be required. The estimate can be used when
  30. deciding the appropriate value for `model_memory_limit` setting later on,
  31. about either an existing {dfanalytics-job} or one that has not been created yet.
  32. [[ml-explain-dfanalytics-path-params]]
  33. ==== {api-path-parms-title}
  34. `<data_frame_analytics_id>`::
  35. (Optional, string)
  36. include::{docdir}/ml/ml-shared.asciidoc[tag=job-id-data-frame-analytics]
  37. [[ml-explain-dfanalytics-request-body]]
  38. ==== {api-request-body-title}
  39. `data_frame_analytics_config`::
  40. (Optional, object) Intended configuration of {dfanalytics-job}. Note that `id`
  41. and `dest` don't need to be provided in the context of this API.
  42. [[ml-explain-dfanalytics-results]]
  43. ==== {api-response-body-title}
  44. The API returns a response that contains the following:
  45. `field_selection`::
  46. (array)
  47. include::{docdir}/ml/ml-shared.asciidoc[tag=field-selection]
  48. `memory_estimation`::
  49. (object)
  50. include::{docdir}/ml/ml-shared.asciidoc[tag=memory-estimation]
  51. [[ml-explain-dfanalytics-example]]
  52. ==== {api-examples-title}
  53. [source,console]
  54. --------------------------------------------------
  55. POST _ml/data_frame/analytics/_explain
  56. {
  57. "data_frame_analytics_config": {
  58. "source": {
  59. "index": "houses_sold_last_10_yrs"
  60. },
  61. "analysis": {
  62. "regression": {
  63. "dependent_variable": "price"
  64. }
  65. }
  66. }
  67. }
  68. --------------------------------------------------
  69. // TEST[skip:TBD]
  70. The API returns the following results:
  71. [source,console-result]
  72. ----
  73. {
  74. "field_selection": [
  75. {
  76. "field": "number_of_bedrooms",
  77. "mappings_types": ["integer"],
  78. "is_included": true,
  79. "is_required": false,
  80. "feature_type": "numerical"
  81. },
  82. {
  83. "field": "postcode",
  84. "mappings_types": ["text"],
  85. "is_included": false,
  86. "is_required": false,
  87. "reason": "[postcode.keyword] is preferred because it is aggregatable"
  88. },
  89. {
  90. "field": "postcode.keyword",
  91. "mappings_types": ["keyword"],
  92. "is_included": true,
  93. "is_required": false,
  94. "feature_type": "categorical"
  95. },
  96. {
  97. "field": "price",
  98. "mappings_types": ["float"],
  99. "is_included": true,
  100. "is_required": true,
  101. "feature_type": "numerical"
  102. }
  103. ],
  104. "memory_estimation": {
  105. "expected_memory_without_disk": "128MB",
  106. "expected_memory_with_disk": "32MB"
  107. }
  108. }
  109. ----