mirror of
https://github.com/elastic/elasticsearch.git
synced 2025-06-30 10:23:41 -04:00
aaa712dcb0
We are adding a _meta field to many of our REST APIs so that users can attach whatever metadata they want. The data in this field will not be used by Elasticsearch. This commit add the _meta field to ingest pipelines. Relates to #75799
128 lines
3.3 KiB
Text
128 lines
3.3 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.
|
|
|
|
|
|
[[put-pipeline-api-query-params]]
|
|
==== {api-query-parms-title}
|
|
|
|
include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=master-timeout]
|
|
|
|
|
|
[[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 preform 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.
|
|
|
|
+
|
|
This parameter is intended for external systems only. {es} does not use or
|
|
validate pipeline version numbers.
|
|
|
|
`_meta`::
|
|
(Optional, object)
|
|
Optional metadata about the ingest pipeline. May have any contents. This
|
|
map is not automatically generated by {es}.
|
|
// 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.
|