Update a transform

POST /_transform/{transform_id}/_update

Updates certain properties of a transform.

All updated properties except description do not take effect until after the transform starts the next checkpoint, thus there is data consistency in each checkpoint. To use this API, you must have read and view_index_metadata privileges for the source indices. You must also have index and read privileges for the destination index. When Elasticsearch security features are enabled, the transform remembers which roles the user who updated it had at the time of update and runs with those privileges.

Required authorization

Authentication

Api key

Authorization: <value>

Elasticsearch APIs support key-based authentication. You must create an API key and use the encoded value in the request header. For example:

		curl -X GET "${ES_URL}/_cat/indices?v=true" \
  -H "Authorization: ApiKey ${API_KEY}"

To get API keys, use the /_security/api_key APIs.

Basic

Authorization: Basic <credentials>

Bearer

Authorization: Bearer <token>

Elasticsearch APIs support the use of bearer tokens in the Authorization HTTP header to authenticate with the API. For examples, refer to Token-based authentication services

dest object: The destination for the transform.
description string: Free text description of the transform.
frequency string · default: 1m: 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.
_meta object: Defines optional transform metadata.
source object: The source of the data for the transform.
settings object: Defines optional transform settings.
sync object: Defines the properties transforms require to run continuously.
retention_policy union oneOf nullable: Defines a retention policy for the transform. Data that meets the defined criteria is deleted from the destination index.; One of:

Response

application/json

authorization object
create_time number required
description string required
dest object required
frequency string
id string required
latest object
pivot object
retention_policy object
settings object required
source object required
sync object
version string required
_meta object

Examples

Request Console 1 / 8 languages

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

Console Kibana Dev Tools

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"
    }
  }
}

JavaScript Elasticsearch JavaScript Client

const response = await client.transform.updateTransform({
  transform_id: "simple-kibana-ecomm-pivot",
  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",
    },
  },
});

Python Elasticsearch Python Client

resp = client.transform.update_transform(
    transform_id="simple-kibana-ecomm-pivot",
    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"
        }
    },
)

curl Shell

curl -X POST "$ELASTICSEARCH_URL/_transform/simple-kibana-ecomm-pivot/_update" \
  -H "Authorization: ApiKey $ELASTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "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"
      }
    }
  }'

Java Elasticsearch Java Client

client.transform().updateTransform(u -> u
    .description("Maximum priced ecommerce data by customer_id in Asia")
    .dest(d -> d
        .index("kibana_sample_data_ecommerce_transform1")
        .pipeline("add_timestamp_pipeline")
    )
    .frequency(f -> f
        .time("5m")
    )
    .retentionPolicy(r -> r
        .time(t -> t
            .field("order_date")
            .maxAge(m -> m
                .time("30d")
            )
        )
    )
    .source(s -> s
        .index("kibana_sample_data_ecommerce")
        .query(q -> q
            .term(te -> te
                .field("geoip.continent_name")
                .value(FieldValue.of("Asia"))
            )
        )
    )
    .sync(sy -> sy
        .time(ti -> ti
            .delay(d -> d
                .time("60s")
            )
            .field("order_date")
        )
    )
    .transformId("simple-kibana-ecomm-pivot")
);

C# Elasticsearch .NET Client

var response = await client.TransformManagement
    .UpdateTransformAsync(transformId: "simple-kibana-ecomm-pivot", d1 => d1
        .Description("Maximum priced ecommerce data by customer_id in Asia")
        .Dest(d2 => d2
            .Index("kibana_sample_data_ecommerce_transform_v2")
            .Pipeline("add_timestamp_pipeline")
        )
        .Frequency("15m")
        .Source(d2 => d2
            .Indices(new[] { "kibana_sample_data_ecommerce" })
            .Query(d3 => d3
                .Term(d4 => d4
                    .Field(x => x.Geoip.ContinentName)
                    .Value("Asia")
                )
            )
        )
        .Sync(d2 => d2
            .Time(d3 => d3
                .Delay("120s")
                .Field(x => x.OrderDate)
            )
        )
    );

PHP Elasticsearch PHP Client

$resp = $client->transform()->updateTransform([
    "transform_id" => "simple-kibana-ecomm-pivot",
    "body" => [
        "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",
            ],
        ],
    ],
]);

Ruby Elasticsearch Ruby Client

response = client.transform.update_transform(
  transform_id: "simple-kibana-ecomm-pivot",
  body: {
    "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"
      }
    }
  }
)

Response

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"
    }
  }
}

Update a transform

Required authorization

Authentication

Path parameters

Query parameters

Request body

Response

Required authorization

Authentication

Path parameters

Query parameters

Request body { }

Response

Request body