[role="xpack"] [[update-transform]] = Update {transform} API [subs="attributes"] ++++ Update {transform} ++++ Updates certain properties of a {transform}. [[update-transform-request]] == {api-request-title} `POST _transform//_update` [[update-transform-prereqs]] == {api-prereq-title} Requires the following privileges: * cluster: `manage_transform` (the `transform_admin` built-in role grants this privilege) * source indices: `read`, `view_index_metadata` * destination index: `read`, `index`. If a `retention_policy` is configured, `delete` index privilege is also required. [[update-transform-desc]] == {api-description-title} This API updates an existing {transform}. The list of properties that you can update is a subset of the list that you can define when you create a {transform}. When the {transform} is updated, a series of validations occur to ensure its success. You can use the `defer_validation` parameter to skip these checks. All updated properties except description do not take effect until after the {transform} starts the next checkpoint. This is so there is data consistency in each checkpoint. [IMPORTANT] ==== * Your {transform} remembers which roles the user who updated it had at the time of update and runs with those privileges. If you provide <>, those credentials are used instead. * You must use {kib} or this API to update a {transform}. Directly updating any {transform} internal, system, or hidden indices is not supported and may cause permanent failure. ==== [[update-transform-path-parms]] == {api-path-parms-title} ``:: (Required, string) include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=transform-id] [[update-transform-query-parms]] == {api-query-parms-title} `defer_validation`:: (Optional, Boolean) When `true`, deferrable validations are not run. This behavior may be desired if the source index does not exist until after the {transform} is updated. `timeout`:: (Optional, time) Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error. Defaults to `30s`. [role="child_attributes"] [[update-transform-request-body]] == {api-request-body-title} `description`:: (Optional, string) Free text description of the {transform}. //Begin dest `dest`:: (Optional, object) include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=dest] + .Properties of `dest` [%collapsible%open] ==== `index`::: (Required, string) include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=dest-index] //Begin aliases `aliases`::: (Optional, array of objects) include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=dest-aliases] + .Properties of `aliases` [%collapsible%open] ===== `alias`:::: (Required, string) include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=dest-aliases-alias] `move_on_creation`:::: (Optional, boolean) include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=dest-aliases-move-on-creation] ===== //End aliases `pipeline`::: (Optional, string) include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=dest-pipeline] ==== //End dest `frequency`:: (Optional, <>) include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=frequency] //Begin _meta `_meta`:: (Optional, object) include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=transform-metadata] //End _meta //Begin retention policy `retention_policy`:: (Optional, object) include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=transform-retention] + .Properties of `retention_policy` [%collapsible%open] ==== `time`::: (Required, object) include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=transform-retention-time] + .Properties of `time` [%collapsible%open] ===== `field`::: (Required, string) include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=transform-retention-time-field] `max_age`::: (Required, <>) include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=transform-retention-time-max-age] ===== ==== //End retention policy //Begin settings `settings`:: (Optional, object) include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=transform-settings] + .Properties of `settings` [%collapsible%open] ==== `align_checkpoints`::: (Optional, boolean) include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=transform-settings-align-checkpoints] `dates_as_epoch_millis`::: (Optional, boolean) include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=transform-settings-dates-as-epoch-milli] `deduce_mappings`::: (Optional, boolean) include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=transform-settings-deduce-mappings] `docs_per_second`::: (Optional, float) include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=transform-settings-docs-per-second] `max_page_search_size`::: (Optional, integer) include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=transform-settings-max-page-search-size] `num_failure_retries`::: (Optional, integer) include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=transform-settings-num-failure-retries] `unattended`::: (Optional, boolean) include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=transform-settings-unattended] ==== //End settings //Begin source `source`:: (Optional, object) include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=source-transforms] + .Properties of `source` [%collapsible%open] ==== `index`::: (Required, string or array) include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=source-index-transforms] `query`::: (Optional, object) include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=source-query-transforms] ==== //End source //Begin sync `sync`:: (Optional, object) include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=sync] + -- NOTE: You can update these properties only if it is a continuous {transform}. You cannot change a batch {transform} into a continuous {transform} or vice versa. Instead, clone the {transform} in {kib} and add or remove the `sync` property. -- + .Properties of `sync` [%collapsible%open] ==== //Begin sync.time `time`::: (Required, object) include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=sync-time] + .Properties of `time` [%collapsible%open] ===== `delay`:::: (Optional, <>) include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=sync-time-delay] `field`:::: (Required, string) include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=sync-time-field] + -- TIP: In general, it’s a good idea to use a field that contains the <>. If you use a different field, you might need to set the `delay` such that it accounts for data transmission delays. -- ===== //End sync.time ==== //End sync [[update-transform-example]] == {api-examples-title} [source,console] -------------------------------------------------- POST _transform/simple-kibana-ecomm-pivot/_update { "source": { "index": "kibana_sample_data_ecommerce", "query": { "term": { "geoip.continent_name": { "value": "Asia" } } } }, "description": "Maximum priced ecommerce data by customer_id in Asia", "dest": { "index": "kibana_sample_data_ecommerce_transform_v2", "pipeline": "add_timestamp_pipeline" }, "frequency": "15m", "sync": { "time": { "field": "order_date", "delay": "120s" } } } -------------------------------------------------- // TEST[setup:simple_kibana_continuous_pivot] When the {transform} is updated, you receive the updated configuration: [source,console-result] ---- { "id" : "simple-kibana-ecomm-pivot", "authorization" : { "roles" : [ "superuser" ] }, "version" : "8.4.0", "create_time" : 1656113450613, "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" } } }, "aggregations" : { "max_price" : { "max" : { "field" : "taxful_total_price" } } } }, "description" : "Maximum priced ecommerce data by customer_id in Asia", "settings" : { } } ---- // TESTRESPONSE[s/"version" : "8.4.0"/"version" : $body.version/] // TESTRESPONSE[s/"create_time" : 1656113450613/"create_time" : $body.create_time/] // TESTRESPONSE[s/"authorization" : \{[^}]*\},//]