Preview a transform Added in 7.2.0

POST /_transform/_preview
Api key auth Basic auth Bearer auth

Generates a preview of the results that you will get when you create a transform 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. These values are determined based on the field types of the source index and the transform aggregations.

Query parameters

  • timeout string

    Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.

application/json

Body

  • dest object
    Hide dest attributes Show dest attributes object
  • description string

    Free text description of the transform.

  • frequency string

    A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.

  • pivot object
    Hide pivot attributes Show pivot attributes object
    • aggregations object

      Defines how to aggregate the grouped data. The following aggregations are currently supported: average, bucket script, bucket selector, cardinality, filter, geo bounds, geo centroid, geo line, max, median absolute deviation, min, missing, percentiles, rare terms, scripted metric, stats, sum, terms, top metrics, value count, weighted average.

    • group_by object

      Defines how to group the data. More than one grouping can be defined per pivot. The following groupings are currently supported: date histogram, geotile grid, histogram, terms.

      Hide group_by attribute Show group_by attribute object
      • * object Additional properties
        Hide * attributes Show * attributes object
        • date_histogram object
          Hide date_histogram attributes Show date_histogram attributes object
          • calendar_interval string

            Values are second, 1s, minute, 1m, hour, 1h, day, 1d, week, 1w, month, 1M, quarter, 1q, year, or 1y.

          • extended_bounds object
            Hide extended_bounds attributes Show extended_bounds attributes object
          • hard_bounds object
            Hide hard_bounds attributes Show hard_bounds attributes object
          • field string

            Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

          • fixed_interval string

            A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.

          • format string

            The date format used to format key_as_string in the response. If no format is specified, the first date format specified in the field mapping is used.

          • interval string

            A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.

          • min_doc_count number

            Only returns buckets that have min_doc_count number of documents. By default, all buckets between the first bucket that matches documents and the last one are returned.

          • offset string

            A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.

          • params object
            Hide params attribute Show params attribute object
            • * object Additional properties
          • script object
            Hide script attributes Show script attributes object
            • source string

              The script source.

            • id string
            • params object

              Specifies any named parameters that are passed into the script as variables. Use parameters instead of hard-coded values to decrease compile time.

            • lang
            • options object
          • time_zone string
          • keyed boolean

            Set to true to associate a unique string key with each bucket and return the ranges as a hash rather than an array.

        • geotile_grid object
          Hide geotile_grid attributes Show geotile_grid attributes object
          • field string

            Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

          • precision number
          • shard_size number

            Allows for more accurate counting of the top cells returned in the final result the aggregation. Defaults to returning max(10,(size x number-of-shards)) buckets from each shard.

          • size number

            The maximum number of buckets to return.

        • histogram object
          Hide histogram attributes Show histogram attributes object
          • extended_bounds object
            Hide extended_bounds attributes Show extended_bounds attributes object
            • max number

              Maximum value for the bound.

            • min number

              Minimum value for the bound.

          • hard_bounds object
            Hide hard_bounds attributes Show hard_bounds attributes object
            • max number

              Maximum value for the bound.

            • min number

              Minimum value for the bound.

          • field string

            Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

          • interval number

            The interval for the buckets. Must be a positive decimal.

          • min_doc_count number

            Only returns buckets that have min_doc_count number of documents. By default, the response will fill gaps in the histogram with empty buckets.

          • missing number

            The value to apply to documents that do not have a value. By default, documents without a value are ignored.

          • offset number

            By default, the bucket keys start with 0 and then continue in even spaced steps of interval. The bucket boundaries can be shifted by using the offset option.

          • script object
            Hide script attributes Show script attributes object
            • source string

              The script source.

            • id string
            • params object

              Specifies any named parameters that are passed into the script as variables. Use parameters instead of hard-coded values to decrease compile time.

            • lang
            • options object
          • format string
          • keyed boolean

            If true, returns buckets as a hash instead of an array, keyed by the bucket keys.

        • terms
  • source object
    Hide source attributes Show source attributes object
    • index string | array[string] Required
    • runtime_mappings object
      Hide runtime_mappings attribute Show runtime_mappings attribute object
      • * object Additional properties
        Hide * attributes Show * attributes object
        • fields object

          For type composite

          Hide fields attribute Show fields attribute object
          • * object Additional properties
            Hide * attribute Show * attribute object
            • type string Required

              Values are boolean, composite, date, double, geo_point, geo_shape, ip, keyword, long, or lookup.

        • fetch_fields array[object]

          For type lookup

          Hide fetch_fields attributes Show fetch_fields attributes object
          • field string Required

            Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

          • format string
        • format string

          A custom format for date type runtime fields.

        • input_field string

          Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

        • target_field string

          Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

        • target_index string
        • script object
          Hide script attributes Show script attributes object
        • type string Required

          Values are boolean, composite, date, double, geo_point, geo_shape, ip, keyword, long, or lookup.

    • query object

      A query clause that retrieves a subset of data from the source index.

      Query DSL
  • settings object
    Hide settings attributes Show settings attributes object
    • align_checkpoints boolean

      Specifies whether the transform checkpoint ranges should be optimized for performance. Such optimization can align checkpoint ranges with the date histogram interval when date histogram is specified as a group source in the transform config. As a result, less document updates in the destination index will be performed thus improving overall performance.

    • dates_as_epoch_millis boolean

      Defines if dates in the ouput should be written as ISO formatted string or as millis since epoch. epoch_millis was the default for transforms created before version 7.11. For compatible output set this value to true.

    • deduce_mappings boolean

      Specifies whether the transform should deduce the destination index mappings from the transform configuration.

    • docs_per_second number

      Specifies a limit on the number of input documents per second. This setting throttles the transform by adding a wait time between search requests. The default value is null, which disables throttling.

    • max_page_search_size number

      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 65,536.

    • unattended boolean

      If true, the transform runs in unattended mode. In unattended mode, the transform retries indefinitely in case of an error which means the transform never fails. Setting the number of retries other than infinite fails in validation.

  • sync object
    Hide sync attribute Show sync attribute object
    • time object
      Hide time attributes Show time attributes object
      • delay string

        A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.

      • field string Required

        Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

  • retention_policy object
    Hide retention_policy attribute Show retention_policy attribute object
    • time object
      Hide time attributes Show time attributes object
      • field string Required

        Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

      • max_age string Required

        A duration. Units can be nanos, micros, ms (milliseconds), s (seconds), m (minutes), h (hours) and d (days). Also accepts "0" without a unit and "-1" to indicate an unspecified value.

  • latest object
    Hide latest attributes Show latest attributes object
    • sort string Required

      Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.

    • unique_key array[string] Required

      Specifies an array of one or more fields that are used to group the data.

Responses

POST /_transform/_preview 
curl \
 --request POST http://api.example.com/_transform/_preview \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '"{\n  \"source\": {\n    \"index\": \"kibana_sample_data_ecommerce\"\n  },\n  \"pivot\": {\n    \"group_by\": {\n      \"customer_id\": {\n        \"terms\": {\n          \"field\": \"customer_id\",\n          \"missing_bucket\": true\n        }\n      }\n    },\n    \"aggregations\": {\n      \"max_price\": {\n        \"max\": {\n          \"field\": \"taxful_total_price\"\n        }\n      }\n    }\n  }\n}"'
Request example
Run `POST _transform/_preview` to preview a transform that uses the pivot method. 
{
  "source": {
    "index": "kibana_sample_data_ecommerce"
  },
  "pivot": {
    "group_by": {
      "customer_id": {
        "terms": {
          "field": "customer_id",
          "missing_bucket": true
        }
      }
    },
    "aggregations": {
      "max_price": {
        "max": {
          "field": "taxful_total_price"
        }
      }
    }
  }
}
Response examples (200)
An abbreviated response from `POST _transform/_preview` that contains a preview a transform that uses the pivot method. 
{
  "preview": [
    {
      "max_price": 171,
      "customer_id": "10"
    },
    {
      "max_price": 233,
      "customer_id": "11"
    },
    {
      "max_price": 200,
      "customer_id": "12"
    },
    {
      "max_price": 301,
      "customer_id": "13"
    },
    {
      "max_price": 176,
      "customer_id": "14"
    },
    {
      "max_price": 2250,
      "customer_id": "15"
    },
    {
      "max_price": 170,
      "customer_id": "16"
    },
    {
      "max_price": 243,
      "customer_id": "17"
    },
    {
      "max_price": 154,
      "customer_id": "18"
    },
    {
      "max_price": 393,
      "customer_id": "19"
    },
    {
      "max_price": 165,
      "customer_id": "20"
    },
    {
      "max_price": 115,
      "customer_id": "21"
    },
    {
      "max_price": 192,
      "customer_id": "22"
    },
    {
      "max_price": 169,
      "customer_id": "23"
    },
    {
      "max_price": 230,
      "customer_id": "24"
    },
    {
      "max_price": 278,
      "customer_id": "25"
    },
    {
      "max_price": 200,
      "customer_id": "26"
    },
    {
      "max_price": 344,
      "customer_id": "27"
    },
    {
      "max_price": 175,
      "customer_id": "28"
    },
    {
      "max_price": 177,
      "customer_id": "29"
    },
    {
      "max_price": 190,
      "customer_id": "30"
    },
    {
      "max_price": 190,
      "customer_id": "31"
    },
    {
      "max_price": 205,
      "customer_id": "32"
    },
    {
      "max_price": 215,
      "customer_id": "33"
    },
    {
      "max_price": 270,
      "customer_id": "34"
    },
    {
      "max_price": 184,
      "customer_id": "36"
    },
    {
      "max_price": 222,
      "customer_id": "37"
    },
    {
      "max_price": 370,
      "customer_id": "38"
    },
    {
      "max_price": 240,
      "customer_id": "39"
    },
    {
      "max_price": 230,
      "customer_id": "4"
    },
    {
      "max_price": 229,
      "customer_id": "41"
    },
    {
      "max_price": 190,
      "customer_id": "42"
    },
    {
      "max_price": 150,
      "customer_id": "43"
    },
    {
      "max_price": 175,
      "customer_id": "44"
    },
    {
      "max_price": 190,
      "customer_id": "45"
    },
    {
      "max_price": 150,
      "customer_id": "46"
    },
    {
      "max_price": 310,
      "customer_id": "48"
    },
    {
      "max_price": 223,
      "customer_id": "49"
    },
    {
      "max_price": 283,
      "customer_id": "5"
    },
    {
      "max_price": 185,
      "customer_id": "50"
    },
    {
      "max_price": 190,
      "customer_id": "51"
    },
    {
      "max_price": 333,
      "customer_id": "52"
    },
    {
      "max_price": 165,
      "customer_id": "6"
    },
    {
      "max_price": 144,
      "customer_id": "7"
    },
    {
      "max_price": 198,
      "customer_id": "8"
    },
    {
      "max_price": 210,
      "customer_id": "9"
    }
  ],
  "generated_dest_index": {
    "mappings": {
      "_meta": {
        "_transform": {
          "transform": "transform-preview",
          "version": {
            "created": "10.0.0"
          },
          "creation_date_in_millis": 1712948905889
        },
        "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": {}
  }
}