[role="xpack"]
[testenv="basic"]
[[preview-transform]]
=== Preview {transform} API

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

Previews a {transform}.

[[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_transform` 
cluster privileges to use this API. The built-in `transform_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 
<<security-privileges>> and <<built-in-roles>>.

[[preview-transform-desc]]
==== {api-description-title}

This API generates a preview of the results that you will get when you run the
<<put-transform,create {transforms} API>> 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}


`description`::
(Optional, string) Free text description of the {transform}.

`dest`::
(Optional, object)
include::{docdir}/rest-api/common-parms.asciidoc[tag=dest]
  
`dest`.`index`:::
(Optional, string)
include::{docdir}/rest-api/common-parms.asciidoc[tag=dest-index]

`dest`.`pipeline`:::
(Optional, string)
include::{docdir}/rest-api/common-parms.asciidoc[tag=dest-pipeline]

`frequency`::
(Optional, <<time-units, time units>>)
include::{docdir}/rest-api/common-parms.asciidoc[tag=frequency]

`pivot`::
(Required, object)
include::{docdir}/rest-api/common-parms.asciidoc[tag=pivot]

`pivot`.`aggregations` or `aggs`:::
(Required, object)
include::{docdir}/rest-api/common-parms.asciidoc[tag=pivot-aggs]

`pivot`.`group_by`:::
(Required, object)
include::{docdir}/rest-api/common-parms.asciidoc[tag=pivot-group-by]

`pivot`.`max_page_search_size`:::
(Optional, integer)
include::{docdir}/rest-api/common-parms.asciidoc[tag=pivot-max-page-search-size]

`source`::
(Required, object)
include::{docdir}/rest-api/common-parms.asciidoc[tag=source-transforms]

`source`.`index`:::
(Required, string or array)
include::{docdir}/rest-api/common-parms.asciidoc[tag=source-index-transforms]

`source`.`query`:::
(Optional, object)
include::{docdir}/rest-api/common-parms.asciidoc[tag=source-query-transforms]

`sync`::
(Optional, object)
include::{docdir}/rest-api/common-parms.asciidoc[tag=sync]
  
`sync`.`time`:::
(Optional, object)
include::{docdir}/rest-api/common-parms.asciidoc[tag=sync-time]

`sync`.`time`.`delay`::::
(Optional, <<time-units, time units>>)
include::{docdir}/rest-api/common-parms.asciidoc[tag=sync-time-delay]
    
`sync`.`time`.`field`::::
(Optional, string)
include::{docdir}/rest-api/common-parms.asciidoc[tag=sync-time-field]


[[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