elasticsearch/docs/reference/ml/df-analytics/apis/preview-dfanalytics.asciidoc

[role="xpack"]
[testenv="platinum"]
[[preview-dfanalytics]]
= Preview {dfanalytics} API

[subs="attributes"]
++++
<titleabbrev>Preview {dfanalytics}</titleabbrev>
++++

Previews the features used by a {dataframe-analytics-config}.


[[ml-preview-dfanalytics-request]]
== {api-request-title}

`GET _ml/data_frame/analytics/_preview` +

`POST _ml/data_frame/analytics/_preview` +

`GET _ml/data_frame/analytics/<data_frame_analytics_id>/_preview` +

`POST _ml/data_frame/analytics/<data_frame_analytics_id>/_preview`


[[ml-preview-dfanalytics-prereq]]
== {api-prereq-title}

Requires the `monitor_ml` cluster privilege. This privilege is included in the 
`machine_learning_user` built-in role.


[[ml-preview-dfanalytics-desc]]
== {api-description-title}

This API provides preview of the extracted features for a {dataframe-analytics-config}
that either exists already or one that has not been created yet.


[[ml-preview-dfanalytics-path-params]]
== {api-path-parms-title}

`<data_frame_analytics_id>`::
(Optional, string)
include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=job-id-data-frame-analytics]

[[ml-preview-dfanalytics-request-body]]
== {api-request-body-title}

`config`::
(Optional, object)
A {dataframe-analytics-config} as described in <<put-dfanalytics>>.
Note that `id` and `dest` don't need to be provided in the context of this API.

[role="child_attributes"]
[[ml-preview-dfanalytics-results]]
== {api-response-body-title}

The API returns a response that contains the following:

`feature_values`::
(array)
An array of objects that contain feature name and value pairs. The features have
been processed and indicate what will be sent to the model for training.

[[ml-preview-dfanalytics-example]]
== {api-examples-title}

[source,console]
--------------------------------------------------
POST _ml/data_frame/analytics/_preview
{
  "config": {
    "source": {
      "index": "houses_sold_last_10_yrs"
    },
    "analysis": {
      "regression": {
        "dependent_variable": "price"
      }
    }
  }
}
--------------------------------------------------
// TEST[skip:TBD]

The API returns the following results:

[source,console-result]
----
{
  "feature_values": [
    {
      "number_of_bedrooms": "1",
      "postcode": "29655",
      "price": "140.4"
    },
    ...
  ]
}
----