Create or update pipeline API
editCreate or update pipeline API
editCreates 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" } } ] }
Request
editPUT /_ingest/pipeline/<pipeline>
Prerequisites
edit-
If the Elasticsearch security features are enabled, you must have the
manage_pipeline
,manage_ingest_pipelines
, ormanage
cluster privilege to use this API.
Path parameters
edit-
<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 parameters
edit-
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
edit-
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 anon_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.
Examples
editPipeline metadata
editYou 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.