Docs
Elasticsearch Guide [8.1] » REST APIs » Ingest APIs » Create or update pipeline API
« Ingest APIs Delete pipeline API »

Create or update pipeline API

Creates or updates an ingest pipeline. Changes made using this API take effect immediately.

PUT _ingest/pipeline/my-pipeline-id
{
  "description" : "My optional pipeline description",
  "processors" : [
    {
      "set" : {
        "description" : "My optional processor description",
        "field": "my-keyword-field",
        "value": "foo"
      }
    }
  ]
}

Request

PUT /_ingest/pipeline/<pipeline>

Prerequisites

  • If the Elasticsearch security features are enabled, you must have the manage_pipeline, manage_ingest_pipelines, or manage cluster privilege to use this API.

Path parameters

<pipeline>
(Required, string) ID of the ingest pipeline to create or update.

Query parameters

if_version
(Optional, integer) Perform the operation only if the pipeline has this version. If specified and the update is successful, the pipeline’s version is incremented.
master_timeout
(Optional, time units) Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error. Defaults to 30s.
timeout
(Optional, time units) 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.

Request body

description
(Optional, string) Description of the ingest pipeline.
on_failure

(Optional, array of processor objects) Processors to run immediately after a processor failure.

Each processor supports a processor-level on_failure value. If a processor without an on_failure value fails, Elasticsearch uses this pipeline-level parameter as a fallback. The processors in this parameter run sequentially in the order specified. Elasticsearch will not attempt to run the pipeline’s remaining processors.

processors
(Required, array of processor objects) Processors used to perform transformations on documents before indexing. Processors run sequentially in the order specified.
version

(Optional, integer) Version number used by external systems to track ingest pipelines.

See the if_version parameter above for how the version attribute is used.

_meta
(Optional, object) Optional metadata about the ingest pipeline. May have any contents. This map is not automatically generated by Elasticsearch.

Examples

Pipeline metadata

You can use the _meta parameter to add arbitrary metadata to a pipeline. This user-defined object is stored in the cluster state, so keeping it short is preferable.

The _meta parameter is optional and not automatically generated or used by Elasticsearch.

To unset _meta, replace the pipeline without specifying one.

PUT /_ingest/pipeline/my-pipeline-id
{
  "description" : "My optional pipeline description",
  "processors" : [
    {
      "set" : {
        "description" : "My optional processor description",
        "field": "my-keyword-field",
        "value": "foo"
      }
    }
  ],
  "_meta": {
    "reason": "set my-keyword-field to foo",
    "serialization": {
      "class": "MyPipeline",
      "id": 10
    }
  }
}

To check the _meta, use the get pipeline API.

« Ingest APIs Delete pipeline API »