mirror of
https://github.com/elastic/elasticsearch.git
synced 2025-04-25 15:47:23 -04:00
d42211c431
Changes the type of the version parameter in `IngestDocument` from `Long` to `long` and moves it to the third argument, so all required values occur before nullable arguments. The `IngestService` expects a non-null version for a document and will throw an `NullPointerException` if one is not provided. Related: #87309
447 lines
9.1 KiB
Text
447 lines
9.1 KiB
Text
|
|
[[simulate-pipeline-api]]
|
|
=== Simulate pipeline API
|
|
++++
|
|
<titleabbrev>Simulate pipeline</titleabbrev>
|
|
++++
|
|
|
|
Executes an ingest pipeline against
|
|
a set of provided documents.
|
|
|
|
////
|
|
[source,console]
|
|
----
|
|
PUT /_ingest/pipeline/my-pipeline-id
|
|
{
|
|
"description" : "example pipeline to simulate",
|
|
"processors": [
|
|
{
|
|
"set" : {
|
|
"field" : "field2",
|
|
"value" : "_value"
|
|
}
|
|
}
|
|
]
|
|
}
|
|
----
|
|
// TESTSETUP
|
|
////
|
|
|
|
[source,console]
|
|
----
|
|
POST /_ingest/pipeline/my-pipeline-id/_simulate
|
|
{
|
|
"docs": [
|
|
{
|
|
"_index": "index",
|
|
"_id": "id",
|
|
"_source": {
|
|
"foo": "bar"
|
|
}
|
|
},
|
|
{
|
|
"_index": "index",
|
|
"_id": "id",
|
|
"_source": {
|
|
"foo": "rab"
|
|
}
|
|
}
|
|
]
|
|
}
|
|
----
|
|
|
|
|
|
[[simulate-pipeline-api-request]]
|
|
==== {api-request-title}
|
|
|
|
`POST /_ingest/pipeline/<pipeline>/_simulate`
|
|
|
|
`GET /_ingest/pipeline/<pipeline>/_simulate`
|
|
|
|
`POST /_ingest/pipeline/_simulate`
|
|
|
|
`GET /_ingest/pipeline/_simulate`
|
|
|
|
[[simulate-pipeline-api-prereqs]]
|
|
==== {api-prereq-title}
|
|
|
|
* If the {es} {security-features} are enabled, you must have the
|
|
`read_pipeline`, `manage_pipeline`, `manage_ingest_pipelines`, or `manage`
|
|
<<privileges-list-cluster,cluster privilege>> to use this API.
|
|
|
|
[[simulate-pipeline-api-desc]]
|
|
==== {api-description-title}
|
|
|
|
The simulate pipeline API executes a specific pipeline
|
|
against a set of documents provided in the body of the request.
|
|
|
|
You can either specify an existing pipeline
|
|
to execute against the provided documents
|
|
or supply a pipeline definition in the body of the request.
|
|
|
|
|
|
[[simulate-pipeline-api-path-params]]
|
|
==== {api-path-parms-title}
|
|
|
|
`<pipeline>`::
|
|
(Required*, string)
|
|
Pipeline to test. If you don't specify a `pipeline` in the request body, this
|
|
parameter is required.
|
|
|
|
[[simulate-pipeline-api-query-params]]
|
|
==== {api-query-parms-title}
|
|
|
|
`verbose`::
|
|
(Optional, Boolean)
|
|
If `true`,
|
|
the response includes output data
|
|
for each processor in the executed pipeline.
|
|
|
|
|
|
[role="child_attributes"]
|
|
[[simulate-pipeline-api-request-body]]
|
|
==== {api-request-body-title}
|
|
|
|
`pipeline`::
|
|
(Required*, object)
|
|
Pipeline to test. If you don't specify the `<pipeline>` request path parameter,
|
|
this parameter is required. If you specify both this and the request path
|
|
parameter, the API only uses the request path parameter.
|
|
+
|
|
.Properties of `pipeline`
|
|
[%collapsible%open]
|
|
====
|
|
include::put-pipeline.asciidoc[tag=pipeline-object]
|
|
====
|
|
|
|
`docs`::
|
|
(Required, array of objects)
|
|
Sample documents to test in the pipeline.
|
|
+
|
|
.Properties of `docs` objects
|
|
[%collapsible%open]
|
|
====
|
|
`_id`::
|
|
(Optional, string)
|
|
Unique identifier for the document. This ID must be unique within the `_index`.
|
|
|
|
`_index`::
|
|
(Optional, string)
|
|
Name of the index containing the document.
|
|
|
|
`_routing`::
|
|
(Optional, string)
|
|
Value used to send the document to a specific primary shard. See the
|
|
<<mapping-routing-field,`_routing`>> field.
|
|
|
|
`_source`::
|
|
(Required, object)
|
|
JSON body for the document.
|
|
====
|
|
|
|
[[simulate-pipeline-api-example]]
|
|
==== {api-examples-title}
|
|
|
|
|
|
[[simulate-pipeline-api-path-parm-ex]]
|
|
===== Specify a pipeline as a path parameter
|
|
|
|
[source,console]
|
|
----
|
|
POST /_ingest/pipeline/my-pipeline-id/_simulate
|
|
{
|
|
"docs": [
|
|
{
|
|
"_index": "index",
|
|
"_id": "id",
|
|
"_source": {
|
|
"foo": "bar"
|
|
}
|
|
},
|
|
{
|
|
"_index": "index",
|
|
"_id": "id",
|
|
"_source": {
|
|
"foo": "rab"
|
|
}
|
|
}
|
|
]
|
|
}
|
|
----
|
|
|
|
The API returns the following response:
|
|
|
|
[source,console-result]
|
|
----
|
|
{
|
|
"docs": [
|
|
{
|
|
"doc": {
|
|
"_id": "id",
|
|
"_index": "index",
|
|
"_version": "-3",
|
|
"_source": {
|
|
"field2": "_value",
|
|
"foo": "bar"
|
|
},
|
|
"_ingest": {
|
|
"timestamp": "2017-05-04T22:30:03.187Z"
|
|
}
|
|
}
|
|
},
|
|
{
|
|
"doc": {
|
|
"_id": "id",
|
|
"_index": "index",
|
|
"_version": "-3",
|
|
"_source": {
|
|
"field2": "_value",
|
|
"foo": "rab"
|
|
},
|
|
"_ingest": {
|
|
"timestamp": "2017-05-04T22:30:03.188Z"
|
|
}
|
|
}
|
|
}
|
|
]
|
|
}
|
|
----
|
|
// TESTRESPONSE[s/"2017-05-04T22:30:03.187Z"/$body.docs.0.doc._ingest.timestamp/]
|
|
// TESTRESPONSE[s/"2017-05-04T22:30:03.188Z"/$body.docs.1.doc._ingest.timestamp/]
|
|
|
|
|
|
[[simulate-pipeline-api-request-body-ex]]
|
|
===== Specify a pipeline in the request body
|
|
|
|
[source,console]
|
|
----
|
|
POST /_ingest/pipeline/_simulate
|
|
{
|
|
"pipeline" :
|
|
{
|
|
"description": "_description",
|
|
"processors": [
|
|
{
|
|
"set" : {
|
|
"field" : "field2",
|
|
"value" : "_value"
|
|
}
|
|
}
|
|
]
|
|
},
|
|
"docs": [
|
|
{
|
|
"_index": "index",
|
|
"_id": "id",
|
|
"_source": {
|
|
"foo": "bar"
|
|
}
|
|
},
|
|
{
|
|
"_index": "index",
|
|
"_id": "id",
|
|
"_source": {
|
|
"foo": "rab"
|
|
}
|
|
}
|
|
]
|
|
}
|
|
----
|
|
|
|
The API returns the following response:
|
|
|
|
[source,console-result]
|
|
----
|
|
{
|
|
"docs": [
|
|
{
|
|
"doc": {
|
|
"_id": "id",
|
|
"_index": "index",
|
|
"_version": "-3",
|
|
"_source": {
|
|
"field2": "_value",
|
|
"foo": "bar"
|
|
},
|
|
"_ingest": {
|
|
"timestamp": "2017-05-04T22:30:03.187Z"
|
|
}
|
|
}
|
|
},
|
|
{
|
|
"doc": {
|
|
"_id": "id",
|
|
"_index": "index",
|
|
"_version": "-3",
|
|
"_source": {
|
|
"field2": "_value",
|
|
"foo": "rab"
|
|
},
|
|
"_ingest": {
|
|
"timestamp": "2017-05-04T22:30:03.188Z"
|
|
}
|
|
}
|
|
}
|
|
]
|
|
}
|
|
----
|
|
// TESTRESPONSE[s/"2017-05-04T22:30:03.187Z"/$body.docs.0.doc._ingest.timestamp/]
|
|
// TESTRESPONSE[s/"2017-05-04T22:30:03.188Z"/$body.docs.1.doc._ingest.timestamp/]
|
|
|
|
|
|
[[ingest-verbose-param]]
|
|
===== View verbose results
|
|
|
|
You can use the simulate pipeline API
|
|
to see how each processor affects the ingest document
|
|
as it passes through the pipeline.
|
|
To see the intermediate results
|
|
of each processor in the simulate request,
|
|
you can add the `verbose` parameter to the request.
|
|
|
|
[source,console]
|
|
----
|
|
POST /_ingest/pipeline/_simulate?verbose=true
|
|
{
|
|
"pipeline" :
|
|
{
|
|
"description": "_description",
|
|
"processors": [
|
|
{
|
|
"set" : {
|
|
"field" : "field2",
|
|
"value" : "_value2"
|
|
}
|
|
},
|
|
{
|
|
"set" : {
|
|
"field" : "field3",
|
|
"value" : "_value3"
|
|
}
|
|
}
|
|
]
|
|
},
|
|
"docs": [
|
|
{
|
|
"_index": "index",
|
|
"_id": "id",
|
|
"_source": {
|
|
"foo": "bar"
|
|
}
|
|
},
|
|
{
|
|
"_index": "index",
|
|
"_id": "id",
|
|
"_source": {
|
|
"foo": "rab"
|
|
}
|
|
}
|
|
]
|
|
}
|
|
----
|
|
|
|
The API returns the following response:
|
|
|
|
[source,console-result]
|
|
----
|
|
{
|
|
"docs" : [
|
|
{
|
|
"processor_results" : [
|
|
{
|
|
"processor_type" : "set",
|
|
"status" : "success",
|
|
"doc" : {
|
|
"_index" : "index",
|
|
"_id" : "id",
|
|
"_version": "-3",
|
|
"_source" : {
|
|
"field2" : "_value2",
|
|
"foo" : "bar"
|
|
},
|
|
"_ingest" : {
|
|
"pipeline" : "_simulate_pipeline",
|
|
"timestamp" : "2020-07-30T01:21:24.251836Z"
|
|
}
|
|
}
|
|
},
|
|
{
|
|
"processor_type" : "set",
|
|
"status" : "success",
|
|
"doc" : {
|
|
"_index" : "index",
|
|
"_id" : "id",
|
|
"_version": "-3",
|
|
"_source" : {
|
|
"field3" : "_value3",
|
|
"field2" : "_value2",
|
|
"foo" : "bar"
|
|
},
|
|
"_ingest" : {
|
|
"pipeline" : "_simulate_pipeline",
|
|
"timestamp" : "2020-07-30T01:21:24.251836Z"
|
|
}
|
|
}
|
|
}
|
|
]
|
|
},
|
|
{
|
|
"processor_results" : [
|
|
{
|
|
"processor_type" : "set",
|
|
"status" : "success",
|
|
"doc" : {
|
|
"_index" : "index",
|
|
"_id" : "id",
|
|
"_version": "-3",
|
|
"_source" : {
|
|
"field2" : "_value2",
|
|
"foo" : "rab"
|
|
},
|
|
"_ingest" : {
|
|
"pipeline" : "_simulate_pipeline",
|
|
"timestamp" : "2020-07-30T01:21:24.251863Z"
|
|
}
|
|
}
|
|
},
|
|
{
|
|
"processor_type" : "set",
|
|
"status" : "success",
|
|
"doc" : {
|
|
"_index" : "index",
|
|
"_id" : "id",
|
|
"_version": "-3",
|
|
"_source" : {
|
|
"field3" : "_value3",
|
|
"field2" : "_value2",
|
|
"foo" : "rab"
|
|
},
|
|
"_ingest" : {
|
|
"pipeline" : "_simulate_pipeline",
|
|
"timestamp" : "2020-07-30T01:21:24.251863Z"
|
|
}
|
|
}
|
|
}
|
|
]
|
|
}
|
|
]
|
|
}
|
|
----
|
|
// TESTRESPONSE[s/"2020-07-30T01:21:24.251836Z"/$body.docs.0.processor_results.0.doc._ingest.timestamp/]
|
|
// TESTRESPONSE[s/"2020-07-30T01:21:24.251836Z"/$body.docs.0.processor_results.1.doc._ingest.timestamp/]
|
|
// TESTRESPONSE[s/"2020-07-30T01:21:24.251863Z"/$body.docs.1.processor_results.0.doc._ingest.timestamp/]
|
|
// TESTRESPONSE[s/"2020-07-30T01:21:24.251863Z"/$body.docs.1.processor_results.1.doc._ingest.timestamp/]
|
|
|
|
////
|
|
[source,console]
|
|
----
|
|
DELETE /_ingest/pipeline/*
|
|
----
|
|
|
|
[source,console-result]
|
|
----
|
|
{
|
|
"acknowledged": true
|
|
}
|
|
----
|
|
////
|