[role="xpack"]
[testenv="basic"]
[[preview-transform]]
=== Preview {transforms} API
[subs="attributes"]
++++
Preview {transforms}
++++
Previews a {transform}.
beta[]
[[preview-transform-request]]
==== {api-request-title}
`POST _transform/_preview`
[[preview-transform-prereq]]
==== {api-prereq-title}
* If the {es} {security-features} are enabled, you must have
`manage_data_frame_transforms` cluster privileges to use this API. The built-in
`data_frame_transforms_admin` role has these privileges. You must also have
`read` and `view_index_metadata` privileges on the source index for the
{transform}. For more information,
see <> and <>.
[[preview-transform-desc]]
==== {api-description-title}
This API generates a preview of the results that you will get when you run the
<> with the same
configuration. It returns a maximum of 100 results. The calculations are based
on all the current data in the source index.
[[preview-transform-request-body]]
==== {api-request-body-title}
`source`::
(Required, object) The source configuration, which has the following
properties:
`index`:::
(Required, string or array) The _source indices_ for the
{transform}. It can be a single index, an index pattern (for
example, `"myindex*"`), or an array of indices (for example,
`["index1", "index2"]`).
`query`:::
(Optional, object) A query clause that retrieves a subset of data from the
source index. See <>.
`pivot`::
(Required, object) Defines the pivot function `group by` fields and the
aggregation to reduce the data. See <>.
[[preview-transform-response]]
==== {api-response-body-title}
`preview`::
(array) An array of documents. In particular, they are the JSON
representation of the documents that would be created in the destination index
by the {transform}.
==== {api-examples-title}
[source,console]
--------------------------------------------------
POST _transform/_preview
{
"source": {
"index": "kibana_sample_data_ecommerce"
},
"pivot": {
"group_by": {
"customer_id": {
"terms": {
"field": "customer_id"
}
}
},
"aggregations": {
"max_price": {
"max": {
"field": "taxful_total_price"
}
}
}
}
}
--------------------------------------------------
// TEST[skip:set up sample data]
The data that is returned for this example is as follows:
[source,js]
----
{
"preview" : [
{
"max_price" : 171.0,
"customer_id" : "10"
},
{
"max_price" : 233.0,
"customer_id" : "11"
},
{
"max_price" : 200.0,
"customer_id" : "12"
}
...
],
"mappings": {
"properties": {
"max_price": {
"type": "double"
},
"customer_id": {
"type": "keyword"
}
}
}
}
----
// NOTCONSOLE