mirror of
https://github.com/elastic/elasticsearch.git
synced 2025-04-25 07:37:19 -04:00
143 lines
4 KiB
Text
143 lines
4 KiB
Text
[[put-pipeline-api]]
|
|
=== Create or update pipeline API
|
|
++++
|
|
<titleabbrev>Create or update pipeline</titleabbrev>
|
|
++++
|
|
|
|
Creates or updates an <<ingest,ingest pipeline>>. Changes made using this API
|
|
take effect immediately.
|
|
|
|
[source,console]
|
|
----
|
|
PUT _ingest/pipeline/my-pipeline-id
|
|
{
|
|
"description" : "My optional pipeline description",
|
|
"processors" : [
|
|
{
|
|
"set" : {
|
|
"description" : "My optional processor description",
|
|
"field": "my-keyword-field",
|
|
"value": "foo"
|
|
}
|
|
}
|
|
]
|
|
}
|
|
----
|
|
|
|
|
|
[[put-pipeline-api-request]]
|
|
==== {api-request-title}
|
|
|
|
`PUT /_ingest/pipeline/<pipeline>`
|
|
|
|
[[put-pipeline-api-prereqs]]
|
|
==== {api-prereq-title}
|
|
|
|
* If the {es} {security-features} are enabled, you must have the
|
|
`manage_pipeline`, `manage_ingest_pipelines`, or `manage`
|
|
<<privileges-list-cluster,cluster privilege>> to use this API.
|
|
|
|
|
|
[[put-pipeline-api-path-params]]
|
|
==== {api-path-parms-title}
|
|
|
|
`<pipeline>`::
|
|
(Required, string) ID of the ingest pipeline to create or update.
|
|
+
|
|
[IMPORTANT]
|
|
====
|
|
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-elastic-agent>>.
|
|
====
|
|
|
|
[[put-pipeline-api-query-params]]
|
|
==== {api-query-parms-title}
|
|
|
|
`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.
|
|
|
|
include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=timeoutparms]
|
|
|
|
[[put-pipeline-api-request-body]]
|
|
==== {api-request-body-title}
|
|
|
|
// tag::pipeline-object[]
|
|
`description`::
|
|
(Optional, string)
|
|
Description of the ingest pipeline.
|
|
|
|
`on_failure`::
|
|
(Optional, array of <<processors,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, {es} uses this pipeline-level parameter as
|
|
a fallback. The processors in this parameter run sequentially in the order
|
|
specified. {es} will not attempt to run the pipeline's remaining processors.
|
|
|
|
`processors`::
|
|
(Required, array of <<processors,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 <<put-pipeline-api-query-params,`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 {es}.
|
|
|
|
`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,
|
|
{es} will emit a deprecation warning.
|
|
// end::pipeline-object[]
|
|
|
|
[[put-pipeline-api-example]]
|
|
==== {api-examples-title}
|
|
|
|
[[pipeline-metadata]]
|
|
===== 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 {es}.
|
|
|
|
To unset `_meta`, replace the pipeline without specifying one.
|
|
|
|
[source,console]
|
|
--------------------------------------------------
|
|
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,get pipeline>> API.
|