elasticsearch/docs/reference/ingest/apis/simulate-pipeline.asciidoc

[[simulate-pipeline-api]]
=== Simulate pipeline API
++++
<titleabbrev>Simulate pipeline</titleabbrev>
++++

.New API reference
[sidebar]
--
For the most up-to-date API details, refer to {api-es}/group/endpoint-ingest[Ingest APIs].
--

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
}
----
////