IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.
« Get transform statistics API Start transform API »
Elastic Docs ›Elasticsearch Guide [7.6] ›REST APIs ›Transform APIs

Preview transform API

edit

Preview transform API

edit

Previews a transform.

This functionality is in beta and is subject to change. The design and code is less mature than official GA features and is being provided as-is with no warranties. Beta features are not subject to the support SLA of official GA features.

Request

edit

POST _transform/_preview

Prerequisites

edit
  • If the Elasticsearch 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.

Description

edit

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.

Request body

edit
description
(Optional, string) Free text description of the transform.
dest

(Optional, object) The destination for the transform.

dest.index
(Optional, string) The destination index for the transform.
dest.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 1s and the maximum is 1h. The default value is 1m.
pivot

(Required, object) The method for transforming the data. These objects define the pivot function group by fields and the aggregation to reduce the data.

pivot.aggregations or aggs

(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.

pivot.group_by

(Required, object) Defines how to group the data. More than one grouping can be defined per pivot. The following groupings are supported:

pivot.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 10 and the maximum is 10,000. The default value is 500.
source

(Required, object) The source of the data for the transform.

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-*"].
source.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.

sync.time

(Optional, object) Specifies that the transform uses a time field to synchronize the source and destination indices.

sync.time.delay
(Optional, time units) The time delay between the current time and the latest input data time. The default value is 60s.
sync.time.field
(Optional, string) The date field that is used to identify new documents in the source.

Response body

edit
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.

Examples

edit
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"
    }
    ...
  ],
  "mappings": {
    "properties": {
      "max_price": {
        "type": "double"
      },
      "customer_id": {
        "type": "keyword"
      }
    }
  }
}
« Get transform statistics API Start transform API »