Skip to content

Latest commit

 

History

History
313 lines (270 loc) · 8.01 KB

update-transform.asciidoc

File metadata and controls

313 lines (270 loc) · 8.01 KB

Update {transform} API

Update {transform}

Updates certain properties of a {transform}.

{api-request-title}

POST _transform/<transform_id>/_update

{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.

{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

  • When {es} {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. If you provide secondary authorization headers, those credentials are used instead.

  • You must use {kib} or this API to update a {transform}. Do not update a {transform} directly via .transform-internal* indices using the {es} index API. If {es} {security-features} are enabled, do not give users any privileges on .transform-internal* indices. If you used {transforms} prior 7.5, also do not give users any privileges on .data-frame-internal* indices.

{api-path-parms-title}

<transform_id>

(Required, string) {es-repo-dir}/rest-api/common-parms.asciidoc

{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.

{api-request-body-title}

description

(Optional, string) Free text description of the {transform}.

dest

(Optional, object) {es-repo-dir}/rest-api/common-parms.asciidoc

Properties of dest
frequency

(Optional, time units) {es-repo-dir}/rest-api/common-parms.asciidoc

retention_policy

(Optional, object) {es-repo-dir}/rest-api/common-parms.asciidoc

Properties of retention_policy
settings

(Optional, object) {es-repo-dir}/rest-api/common-parms.asciidoc

Properties of settings
dates_as_epoch_millis

(Optional, boolean) {es-repo-dir}/rest-api/common-parms.asciidoc

docs_per_second

(Optional, float) {es-repo-dir}/rest-api/common-parms.asciidoc

align_checkpoints

(Optional, boolean) {es-repo-dir}/rest-api/common-parms.asciidoc

deduce_mappings

(Optional, boolean) {es-repo-dir}/rest-api/common-parms.asciidoc

max_page_search_size

(Optional, integer) {es-repo-dir}/rest-api/common-parms.asciidoc

source

(Optional, object) {es-repo-dir}/rest-api/common-parms.asciidoc

Properties of source
index

(Required, string or array) {es-repo-dir}/rest-api/common-parms.asciidoc

query

(Optional, object) {es-repo-dir}/rest-api/common-parms.asciidoc

sync

(Optional, object) {es-repo-dir}/rest-api/common-parms.asciidoc

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
time

(Required, object) {es-repo-dir}/rest-api/common-parms.asciidoc

Properties of time
delay

(Optional, time units) {es-repo-dir}/rest-api/common-parms.asciidoc

field

(Required, string) {es-repo-dir}/rest-api/common-parms.asciidoc

Tip
 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.

{api-examples-title}

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

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"
    }
  },
  "settings": { },
  "version": "7.5.0",
  "create_time": 1518808660505
}