Create or update pipeline APIedit

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

response = client.ingest.put_pipeline(
  id: 'my-pipeline-id',
  body: {
    description: 'My optional pipeline description',
    processors: [
      {
        set: {
          description: 'My optional processor description',
          field: 'my-keyword-field',
          value: 'foo'
        }
      }
    ]
  }
)
puts response
PUT _ingest/pipeline/my-pipeline-id
{
  "description" : "My optional pipeline description",
  "processors" : [
    {
      "set" : {
        "description" : "My optional processor description",
        "field": "my-keyword-field",
        "value": "foo"
      }
    }
  ]
}

Requestedit

PUT /_ingest/pipeline/<pipeline>

Prerequisitesedit

  • 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 parametersedit

<pipeline>

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

To avoid naming collisions with built-in and Fleet-managed ingest pipelines, avoid using @ as part of your own ingest pipelines names. The exception of that rule are the *@custom ingest pipelines that let you safely add a custom pipeline to managed pipelines. See also Pipelines for Fleet and Elastic Agent.

Query parametersedit

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 bodyedit

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.
deprecated
(Optional, boolean) Marks this ingest pipeline as deprecated. When a deprecated ingest pipeline is referenced as the default or final pipeline when creating or updating a non-deprecated index template, Elasticsearch will emit a deprecation warning.

Examplesedit

Pipeline metadataedit

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.

response = client.ingest.put_pipeline(
  id: 'my-pipeline-id',
  body: {
    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
      }
    }
  }
)
puts response
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.