Update transforms API
editUpdate transforms API
editUpdates an existing transform.
This functionality is in beta and is subject to change. The design and code is less mature than official GA features and is being provided as-is with no warranties. Beta features are not subject to the support SLA of official GA features.
Request
editPOST _data_frame/transforms/<transform_id>/_update
Prerequisites
edit-
If the Elasticsearch security features are enabled, you must have
manage_data_frame_transforms
cluster privileges to use this API. The built-indata_frame_transforms_admin
role has these privileges. You must also haveread
andview_index_metadata
privileges on the source index andread
,create_index
, andindex
privileges on the destination index. For more information, see Security privileges and Built-in roles.
Description
editThis API updates an existing transform. All settings except description do not take effect until after the transform starts the next checkpoint. This is so there is consistency with the pivoted data in each checkpoint.
When Elasticsearch security features are enabled, your transform remembers which roles the user who updated it had at the time of update and runs with those privileges.
You must use Kibana or this API to update a transform.
Do not update a transform directly via
.data-frame-internal*
indices using the Elasticsearch index API.
If Elasticsearch security features are enabled, do not give users any
privileges on .data-frame-internal*
indices.
Path parameters
edit-
<transform_id>
- (Required, string) Identifier for the transform. This identifier can contain lowercase alphanumeric characters (a-z and 0-9), hyphens, and underscores. It must start and end with alphanumeric characters.
Query parameters
edit-
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.
Request body
edit-
description
- (Optional, string) Free text description of the transform.
-
dest
-
(Optional, object) The destination configuration, which has the following properties:
-
index
- (Required, string) The destination index for the transform.
-
pipeline
- (Optional, string) The unique identifier for a pipeline.
-
-
frequency
-
(Optional, time units) 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 is1h
. The default value is1m
. -
source
-
(Optional, object) The source configuration, which has the following properties:
-
index
-
(Required, string or array) The source indices for the
transform. It can be a single index, an index pattern (for
example,
"myindex*"
), or an array of indices (for example,["index1", "index2"]
). -
query
- (Optional, object) A query clause that retrieves a subset of data from the source index. See Query DSL.
-
-
sync
-
(Optional, object) Defines the properties required to run continuously.
-
time
-
(Required, object) Specifies that the transform uses a time field to synchronize the source and destination indices.
-
field
-
(Required, string) The date field that is used to identify new documents in the source.
In general, it’s a good idea to use a field that contains the ingest timestamp. If you use a different field, you might need to set the
delay
such that it accounts for data transmission delays. -
delay
-
(Optional, time units) The time delay between the current
time and the latest input data time. The default value is
60s
.
-
-
Examples
editPOST _data_frame/transforms/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" } } }
When the transform is updated, you receive the updated configuration:
{ "id": "simple-kibana-ecomm-pivot", "source": { "index": ["kibana_sample_data_ecommerce"], "query": { "term": { "geoip.continent_name": { "value": "Asia" } } } }, "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", "dest": { "index": "kibana_sample_data_ecommerce_transform_v2", "pipeline": "add_timestamp_pipeline" }, "frequency": "15m", "sync": { "time": { "field": "order_date", "delay": "120s" } }, "version": "7.4.0", "create_time": 1518808660505 }