Preview transform APIedit
Previews a transform.
Requestedit
POST _transform/_preview
Prerequisitesedit
If the Elasticsearch security features are enabled, you must have the following privileges:
-
manage_transform -
source index:
read,view_index_metadata
The built-in transform_admin role has the manage_transform privilege.
For more information, see Security privileges and Built-in roles.
Descriptionedit
This API generates a preview of the results that you will get when you run the 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.
It also generates a list of mappings and settings for the destination index. If the destination index does not exist when you start a transform, these are the mappings and settings that are used. These values are determined based on the field types of the source index and the transform aggregations.
There are some limitations that might result in poor mappings. As a work-around, create the destination index or an index template with your preferred mappings before you start the transform.
Request bodyedit
-
description - (Optional, string) Free text description of the transform.
-
dest -
(Optional, object) The destination for the transform.
Properties of
dest-
index - (Optional, string) The destination index for the transform.
-
pipeline - (Optional, string) The unique identifier for a pipeline.
-
-
frequency -
(Optional, time units)
The interval between checks for changes in the source indices when the
transform is running continuously. Also determines the retry interval in the
event of transient failures while the transform is searching or indexing. The
minimum value is
1sand the maximum is1h. The default value is1m.
-
pivot -
(Required, object) The method for transforming the data. These objects define the pivot function
group byfields and the aggregation to reduce the data.Properties of
pivot-
aggregationsoraggs -
(Required, object) Defines how to aggregate the grouped data. The following composite aggregations are supported:
Transforms support a subset of the functionality in composite aggregations. See Limitations.
-
group_by -
(Required, object) Defines how to group the data. More than one grouping can be defined per pivot. The following groupings are supported:
-
max_page_search_size -
(Optional, integer)
Defines the initial page size to use for the composite aggregation for each
checkpoint. If circuit breaker exceptions occur, the page size is dynamically
adjusted to a lower value. The minimum value is
10and the maximum is10,000. The default value is500.
-
-
source -
(Required, object) The source of the data for the transform.
Properties of
source-
index -
(Required, string or array)
The source indices for the transform. It can be a single index, an index
pattern (for example,
"myindex*"), an array of indices (for example,["index1", "index2"]), or an array of index patterns (for example,["myindex1-*", "myindex2-*"]. -
query - (Optional, object) A query clause that retrieves a subset of data from the source index. See Query DSL.
-
-
sync -
(Optional, object) Defines the properties transforms require to run continuously.
Properties of
sync-
time -
(Optional, object) Specifies that the transform uses a time field to synchronize the source and destination indices.
Properties of
analysis_config-
delay -
(Optional, time units)
The time delay between the current time and the latest input data time. The
default value is
60s. -
field - (Optional, string) The date field that is used to identify new documents in the source.
-
-
Response bodyedit
-
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.
-
generated_dest_index -
(object) Contains details about the destination index.
Properties of
generated_dest_index-
aliases - (object) The aliases for the destination index.
-
mappings - (object) The mappings for each document in the destination index.
-
settings - (object) The index settings for the destination index.
-
Examplesedit
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"
}
}
}
}
}
The data that is returned for this example is as follows:
{
"preview" : [
{
"max_price" : 171.0,
"customer_id" : "10"
},
{
"max_price" : 233.0,
"customer_id" : "11"
},
{
"max_price" : 200.0,
"customer_id" : "12"
}
...
],
"generated_dest_index" : {
"mappings" : {
"_meta" : {
"_transform" : {
"transform" : "transform-preview",
"version" : {
"created" : "7.7.0"
},
"creation_date_in_millis" : 1584738236757
},
"created_by" : "transform"
},
"properties" : {
"max_price" : {
"type" : "half_float"
},
"customer_id" : {
"type" : "keyword"
}
}
},
"settings" : {
"index" : {
"number_of_shards" : "1",
"auto_expand_replicas" : "0-1"
}
},
"aliases" : { }
}
}