Update a transform | Elasticsearch API documentation (v9)

Path parameters

transform_idstring Required
Identifier for the transform.

Query parameters

defer_validationboolean
When true, deferrable validations are not run. This behavior may be desired if the source index does not exist until after the transform is created.
timeoutstring
Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.
Values are -1 or 0.

application/json

BodyRequired

destobject
Hide dest attributes Show dest attributes object
- indexstring
- pipelinestring
  The unique identifier for an ingest pipeline.
descriptionstring
Free text description of the transform.
frequencystring
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.
_metaobject
Hide _meta attribute Show _meta attribute object
- *object Additional properties
sourceobject
Hide source attributes Show source attributes object
- indexstring | array[string] Required
- runtime_mappingsobject
  Hide runtime_mappings attribute Show runtime_mappings attribute object
  *object Additional properties
  Hide * attributes Show * attributes object
  fieldsobject
  For type composite
  Hide fields attribute Show fields attribute object
  *object Additional properties
  Hide * attribute Show * attribute object
  typestring Required
  Values are boolean, composite, date, double, geo_point, geo_shape, ip, keyword, long, or lookup.
  fetch_fieldsarray[object]
  For type lookup
  Hide fetch_fields attributes Show fetch_fields attributes object
  fieldstring Required
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  formatstring
  formatstring
  A custom format for date type runtime fields.
  input_fieldstring
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  target_fieldstring
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  target_indexstring
  scriptobject
  Hide script attributes Show script attributes object
  sourcestring | object
  One of:
  ScriptSourcestring SearchRequestBodyobject
  Hide attributes Show attributes
  aggregationsobject
  Defines the aggregations that are run as part of the search request.
  collapseobject
  explainboolean
  If true, the request returns detailed information about score computation as part of a hit.
  extobject
  Configuration of search extensions defined by Elasticsearch plugins.
  fromnumber
  The starting document offset, which must be non-negative. By default, you cannot page through more than 10,000 hits using the from and size parameters. To page through more hits, use the search_after parameter.
  highlight
  track_total_hitsboolean | number
  Number of hits matching the query to count accurately. If true, the exact number of hits is returned at the cost of some performance. If false, the response does not include the total number of hits matching the query. Defaults to 10,000 hits.
  indices_boostarray[object]
  Boost the _score of documents from specified indices. The boost value is the factor by which scores are multiplied. A boost value greater than 1.0 increases the score. A boost value between 0 and 1.0 decreases the score.
  docvalue_fieldsarray[object]
  An array of wildcard (*) field patterns. The request returns doc values for field names matching these patterns in the hits.fields property of the response.
  knn
  rankobject
  min_scorenumber
  The minimum _score for matching documents. Documents with a lower _score are not included in search results or results collected by aggregations.
  post_filterobject
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  profileboolean
  Set to true to return detailed timing information about the execution of individual components in a search request. NOTE: This is a debugging tool and adds significant overhead to search execution.
  queryobject
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  rescore
  retrieverobject
  script_fieldsobject
  Retrieve a script evaluation (based on different fields) for each hit.
  search_afterarray[number | string | boolean | null]
  A field value.
  sizenumber
  The number of hits to return, which must not be negative. By default, you cannot page through more than 10,000 hits using the from and size parameters. To page through more hits, use the search_after property.
  sliceobject
  sort
  _source
  fieldsarray[object]
  An array of wildcard (*) field patterns. The request returns values for field names matching these patterns in the hits.fields property of the response.
  suggestobject
  terminate_afternumber
  The maximum number of documents to collect for each shard. If a query reaches this limit, Elasticsearch terminates the query early. Elasticsearch collects documents before sorting.
  IMPORTANT: Use with caution. Elasticsearch applies this property to each shard handling the request. When possible, let Elasticsearch perform early termination automatically. Avoid specifying this property for requests that target data streams with backing indices across multiple data tiers.
  If set to 0 (default), the query does not terminate early.
  timeoutstring
  The period of time to wait for a response from each shard. If no response is received before the timeout expires, the request fails and returns an error. Defaults to no timeout.
  track_scoresboolean
  If true, calculate and return document scores, even if the scores are not used for sorting.
  versionboolean
  If true, the request returns the document version as part of a hit.
  seq_no_primary_termboolean
  If true, the request returns sequence number and primary term of the last modification of each hit.
  stored_fieldsstring | array[string]
  pitobject
  runtime_mappingsobject
  statsarray[string]
  The stats groups to associate with the search. Each group maintains a statistics aggregation for its associated searches. You can retrieve these stats using the indices stats API.
  idstring
  paramsobject
  Specifies any named parameters that are passed into the script as variables. Use parameters instead of hard-coded values to decrease compile time.
  Hide params attribute Show params attribute object
  *object Additional properties
  langstring
  Any of:
  ScriptLanguagestring ScriptLanguagestring
  Values are painless, expression, mustache, or java.
  optionsobject
  Hide options attribute Show options attribute object
  *string Additional properties
  typestring Required
  Values are boolean, composite, date, double, geo_point, geo_shape, ip, keyword, long, or lookup.
- queryobject
  A query clause that retrieves a subset of data from the source index.
  Query DSL
settingsobject
Hide settings attributes Show settings attributes object
- align_checkpointsboolean
  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_millisboolean
  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_mappingsboolean
  Specifies whether the transform should deduce the destination index mappings from the transform configuration.
- docs_per_secondnumber
  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_sizenumber
  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.
- unattendedboolean
  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.
syncobject
Hide sync attribute Show sync attribute object
- timeobject
  Hide time attributes Show time attributes object
  delaystring
  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.
  fieldstring Required
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
retention_policyobject | string | null
Defines a retention policy for the transform. Data that meets the defined criteria is deleted from the destination index.
One of:
RetentionPolicyContainerobject string-2string | null
Hide attribute Show attribute
timeobject
Hide time attributes Show time attributes object
fieldstring Required
Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
max_agestring 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.

Responses

200 application/json
Hide response attributes Show response attributes object
- authorizationobject
  Hide authorization attributes Show authorization attributes object
  api_keyobject
  Hide api_key attributes Show api_key attributes object
  idstring Required
  The identifier for the API key.
  namestring Required
  The name of the API key.
  rolesarray[string]
  If a user ID was used for the most recent update to the transform, its roles at the time of the update are listed in the response.
  service_accountstring
  If a service account was used for the most recent update to the transform, the account name is listed in the response.
- create_timenumber Required
- descriptionstring Required
- destobject Required
  Hide dest attributes Show dest attributes object
  indexstring Required
  op_typestring
  Values are index or create.
  pipelinestring
  The name of the pipeline to use.
  routingstring
  version_typestring
  Values are internal, external, external_gte, or force.
- frequencystring
  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.
- idstring Required
- latestobject
  Hide latest attributes Show latest attributes object
  sortstring Required
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  unique_keyarray[string] Required
  Specifies an array of one or more fields that are used to group the data.
- pivotobject
  Hide pivot attributes Show pivot attributes object
  aggregationsobject
  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_byobject
  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_histogramobject
  Hide date_histogram attributes Show date_histogram attributes object
  calendar_intervalstring
  Values are second, 1s, minute, 1m, hour, 1h, day, 1d, week, 1w, month, 1M, quarter, 1q, year, or 1y.
  extended_boundsobject
  hard_boundsobject
  fieldstring
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  fixed_intervalstring
  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.
  formatstring
  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.
  intervalstring
  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_countnumber
  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.
  missing
  offsetstring
  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.
  order
  paramsobject
  scriptobject
  time_zonestring
  keyedboolean
  Set to true to associate a unique string key with each bucket and return the ranges as a hash rather than an array.
  geotile_gridobject
  Hide geotile_grid attributes Show geotile_grid attributes object
  fieldstring
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  precisionnumber
  shard_sizenumber
  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.
  sizenumber
  The maximum number of buckets to return.
  bounds
  histogramobject
  Hide histogram attributes Show histogram attributes object
  extended_boundsobject
  hard_boundsobject
  fieldstring
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  intervalnumber
  The interval for the buckets. Must be a positive decimal.
  min_doc_countnumber
  Only returns buckets that have min_doc_count number of documents. By default, the response will fill gaps in the histogram with empty buckets.
  missingnumber
  The value to apply to documents that do not have a value. By default, documents without a value are ignored.
  offsetnumber
  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.
  order
  scriptobject
  formatstring
  keyedboolean
  If true, returns buckets as a hash instead of an array, keyed by the bucket keys.
  terms
- retention_policyobject
  Hide retention_policy attribute Show retention_policy attribute object
  timeobject
  Hide time attributes Show time attributes object
  fieldstring Required
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  max_agestring 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.
- settingsobject Required
  Hide settings attributes Show settings attributes object
  align_checkpointsboolean
  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_millisboolean
  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_mappingsboolean
  Specifies whether the transform should deduce the destination index mappings from the transform configuration.
  docs_per_secondnumber
  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_sizenumber
  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.
  unattendedboolean
  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.
- sourceobject Required
  Hide source attributes Show source attributes object
  indexstring | array[string] Required
  queryobject
  An Elasticsearch Query DSL (Domain Specific Language) object that defines a query.
  External documentation
  remoteobject
  Hide remote attributes Show remote attributes object
  connect_timeoutstring
  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.
  headersobject
  An object containing the headers of the request.
  Hide headers attribute Show headers attribute object
  hoststring Required
  usernamestring
  passwordstring
  socket_timeoutstring
  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.
  sizenumber
  The number of documents to index per batch. Use it when you are indexing from remote to ensure that the batches fit within the on-heap buffer, which defaults to a maximum size of 100 MB.
  sliceobject
  Hide slice attributes Show slice attributes object
  fieldstring
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  idstring Required
  maxnumber Required
  sortstring | object | array[string | object]
  One of:
  Fieldstring SortOptionsobject Sortarray[string | object]
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  Hide attributes Show attributes
  _scoreobject
  Hide _score attribute Show _score attribute object
  orderstring
  Values are asc or desc.
  _docobject
  Hide _doc attribute Show _doc attribute object
  orderstring
  Values are asc or desc.
  _geo_distanceobject
  Hide _geo_distance attributes Show _geo_distance attributes object
  modestring
  Values are min, max, sum, avg, or median.
  distance_typestring
  Values are arc or plane.
  ignore_unmappedboolean
  orderstring
  Values are asc or desc.
  unitstring
  Values are in, ft, yd, mi, nmi, km, m, cm, or mm.
  nestedobject
  _scriptobject
  Hide _script attributes Show _script attributes object
  orderstring
  Values are asc or desc.
  scriptobject Required
  typestring
  Values are string, number, or version.
  modestring
  Values are min, max, sum, avg, or median.
  nestedobject
  One of:
  Fieldstring SortOptionsobject
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  _sourcestring | array[string]
  runtime_mappingsobject
  Hide runtime_mappings attribute Show runtime_mappings attribute object
  *object Additional properties
  Hide * attributes Show * attributes object
  fieldsobject
  For type composite
  Hide fields attribute Show fields attribute object
  *object Additional properties
  Hide * attribute Show * attribute object
  typestring Required
  Values are boolean, composite, date, double, geo_point, geo_shape, ip, keyword, long, or lookup.
  fetch_fieldsarray[object]
  For type lookup
  Hide fetch_fields attributes Show fetch_fields attributes object
  fieldstring Required
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  formatstring
  formatstring
  A custom format for date type runtime fields.
  input_fieldstring
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  target_fieldstring
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
  target_indexstring
  scriptobject
  Hide script attributes Show script attributes object
  sourcestring | object
  One of:
  ScriptSourcestring SearchRequestBodyobject
  idstring
  paramsobject
  Specifies any named parameters that are passed into the script as variables. Use parameters instead of hard-coded values to decrease compile time.
  Hide params attribute Show params attribute object
  *object Additional properties
  langstring
  Any of:
  ScriptLanguagestring ScriptLanguagestring
  Values are painless, expression, mustache, or java.
  optionsobject
  Hide options attribute Show options attribute object
  *string Additional properties
  typestring Required
  Values are boolean, composite, date, double, geo_point, geo_shape, ip, keyword, long, or lookup.
- syncobject
  Hide sync attribute Show sync attribute object
  timeobject
  Hide time attributes Show time attributes object
  delaystring
  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.
  fieldstring Required
  Path to field or array of paths. Some API's support wildcards in the path to select multiple fields.
- versionstring Required
- _metaobject
  Hide _meta attribute Show _meta attribute object
  *object Additional properties

POST /_transform/{transform_id}/_update

POST _transform/simple-kibana-ecomm-pivot/_update
{
  "source": {
    "index": "kibana_sample_data_ecommerce",
    "query": {
      "term": {
        "geoip.continent_name": {
          "value": "Asia"
        }
      }
    }
  },
  "pivot": {
    "group_by": {
      "customer_id": {
        "terms": {
          "field": "customer_id",
          "missing_bucket": true
        }
      }
    },
    "aggregations": {
      "max_price": {
        "max": {
          "field": "taxful_total_price"
        }
      }
    }
  },
  "description": "Maximum priced ecommerce data by customer_id in Asia",
  "dest": {
    "index": "kibana_sample_data_ecommerce_transform1",
    "pipeline": "add_timestamp_pipeline"
  },
  "frequency": "5m",
  "sync": {
    "time": {
      "field": "order_date",
      "delay": "60s"
    }
  },
  "retention_policy": {
    "time": {
      "field": "order_date",
      "max_age": "30d"
    }
  }
}

curl \
 --request POST 'http://api.example.com/_transform/{transform_id}/_update' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '"{\n  \"source\": {\n    \"index\": \"kibana_sample_data_ecommerce\",\n    \"query\": {\n      \"term\": {\n        \"geoip.continent_name\": {\n          \"value\": \"Asia\"\n        }\n      }\n    }\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  \"description\": \"Maximum priced ecommerce data by customer_id in Asia\",\n  \"dest\": {\n    \"index\": \"kibana_sample_data_ecommerce_transform1\",\n    \"pipeline\": \"add_timestamp_pipeline\"\n  },\n  \"frequency\": \"5m\",\n  \"sync\": {\n    \"time\": {\n      \"field\": \"order_date\",\n      \"delay\": \"60s\"\n    }\n  },\n  \"retention_policy\": {\n    \"time\": {\n      \"field\": \"order_date\",\n      \"max_age\": \"30d\"\n    }\n  }\n}"'

Request example

Run `POST _transform/simple-kibana-ecomm-pivot/_update` to update a transform that uses the pivot method.

{
  "source": {
    "index": "kibana_sample_data_ecommerce",
    "query": {
      "term": {
        "geoip.continent_name": {
          "value": "Asia"
        }
      }
    }
  },
  "pivot": {
    "group_by": {
      "customer_id": {
        "terms": {
          "field": "customer_id",
          "missing_bucket": true
        }
      }
    },
    "aggregations": {
      "max_price": {
        "max": {
          "field": "taxful_total_price"
        }
      }
    }
  },
  "description": "Maximum priced ecommerce data by customer_id in Asia",
  "dest": {
    "index": "kibana_sample_data_ecommerce_transform1",
    "pipeline": "add_timestamp_pipeline"
  },
  "frequency": "5m",
  "sync": {
    "time": {
      "field": "order_date",
      "delay": "60s"
    }
  },
  "retention_policy": {
    "time": {
      "field": "order_date",
      "max_age": "30d"
    }
  }
}

Response examples (200)

A successful response when creating a transform.

{
  "id": "simple-kibana-ecomm-pivot",
  "authorization": {
    "roles": [
      "superuser"
    ]
  },
  "version": "10.0.0",
  "create_time": 1712951576767,
  "source": {
    "index": [
      "kibana_sample_data_ecommerce"
    ],
    "query": {
      "term": {
        "geoip.continent_name": {
          "value": "Asia"
        }
      }
    }
  },
  "dest": {
    "index": "kibana_sample_data_ecommerce_transform_v2",
    "pipeline": "add_timestamp_pipeline"
  },
  "frequency": "15m",
  "sync": {
    "time": {
      "field": "order_date",
      "delay": "120s"
    }
  },
  "pivot": {
    "group_by": {
      "customer_id": {
        "terms": {
          "field": "customer_id",
          "missing_bucket": true
        }
      }
    },
    "aggregations": {
      "max_price": {
        "max": {
          "field": "taxful_total_price"
        }
      }
    }
  },
  "description": "Maximum priced ecommerce data by customer_id in Asia",
  "settings": {},
  "retention_policy": {
    "time": {
      "field": "order_date",
      "max_age": "30d"
    }
  }
}

Path parameters

Query parameters

BodyRequired

sourcestring | object

langstring

retention_policyobject | string | null

Responses

sortstring | object | array[string | object]

sourcestring | object

langstring