[role="xpack"]
[testenv="basic"]
[[upgrade-transforms]]
= Upgrade {transforms} API

[subs="attributes"]
++++
<titleabbrev>Upgrade {transforms}</titleabbrev>
++++

Upgrades all {transforms}.

[[upgrade-transforms-request]]
== {api-request-title}

`POST _transform/_upgrade`

[[upgrade-transforms-prereqs]]
== {api-prereq-title}

Requires the following privileges:

* cluster: `manage_transform` (the `transform_admin` built-in role grants this
  privilege)


[[upgrade-transforms-desc]]
== {api-description-title}

{transforms-cap} are compatible across minor versions and between supported 
major versions. However, over time, the format of {transform} configuration 
information may change. This API identifies {transforms} which have a legacy 
configuration format and upgrades them to the latest version; including clean up 
of the internal data structures that store {transform} state and checkpoints. 
{transform-cap} upgrade does not affect the source and destination indices.

If a {transform} upgrade step fails, the upgrade stops, and an error is returned 
about the underlying issue. Resolve the issue then re-run the process again. A 
summary is returned when the upgrade is finished.

To ensure {ctransforms} remain running during a major version upgrade of the 
cluster – for example, from 7.16 to 8.0 – it is recommended to upgrade 
{transforms} before upgrading the cluster. You may want to perform a recent 
cluster backup prior to the upgrade.


[IMPORTANT]
====

* When {es} {security-features} are enabled, your {transform} remembers the 
roles of the user who created or updated it last. In contrast to 
<<update-transform,update transform>>, a {transform} upgrade does not change the 
stored roles, therefore the role used to read source data and write to the 
destination index remains unchanged.

====


[[upgrade-transforms-query-parms]]
== {api-query-parms-title}

`dry_run`::
  (Optional, Boolean) When `true`, only checks for updates but does not execute 
  them. Defaults to `false`.


[[upgrade-transforms-response-body]]
== {api-response-body-title}

`needs_update`::
  (integer) The number of {transforms} that need to be upgraded.

`no_action`::
  (integer) The number of {transforms} that don't require upgrading.

`updated`:: 
  (integer) The number of {transforms} that have been upgraded.



[[upgrade-transforms-example]]
== {api-examples-title}

To upgrade the legacy {transforms} to the latest configuration format, perform 
the following API call:

[source,console]
--------------------------------------------------
POST _transform/_upgrade
--------------------------------------------------
// TEST[setup:simple_kibana_continuous_pivot]

When all {transforms} are upgraded, you receive a summary:

[source,console-result]
----
{
  "needs_update": 0,
  "updated": 2,
  "no_action": 1
}
----
// TESTRESPONSE[skip:TBD]