Simulate pipeline API

edit

Executes an ingest pipeline against a set of provided documents.

POST /_ingest/pipeline/my-pipeline-id/_simulate
{
  "docs": [
    {
      "_index": "index",
      "_id": "id",
      "_source": {
        "foo": "bar"
      }
    },
    {
      "_index": "index",
      "_id": "id",
      "_source": {
        "foo": "rab"
      }
    }
  ]
}

Request

edit

POST /_ingest/pipeline/<pipeline>/_simulate

GET /_ingest/pipeline/<pipeline>/_simulate

POST /_ingest/pipeline/_simulate

GET /_ingest/pipeline/_simulate

Prerequisites

edit
  • If the Elasticsearch security features are enabled, you must have the manage_pipeline, manage_ingest_pipelines, or manage cluster privilege to use this API.

Description

edit

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.

Path parameters

edit
<pipeline>
(Optional, string) Pipeline ID used to simulate an ingest.

Query parameters

edit
verbose
(Optional, Boolean) If true, the response includes output data for each processor in the executed pipeline.

Request body

edit
description
(Optional, string) Description of the ingest pipeline.
processors

(Optional, array of processor objects) Array of processors used to pre-process documents during ingest.

Processors are executed in the order provided.

See Processors for processor object definitions and a list of built-in processors.

docs

(Required, array) Array of documents ingested by the pipeline.

Document object parameters include:

_index
(Optional, string) Name of the index containing the document.
_id
(Optional, string) Unique identifier for the document. This ID is only unique within the index.
_source
(Required, object) JSON body for the document.

Examples

edit

Specify a pipeline as a path parameter

edit
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:

{
   "docs": [
      {
         "doc": {
            "_id": "id",
            "_index": "index",
            "_type": "_doc",
            "_source": {
               "field2": "_value",
               "foo": "bar"
            },
            "_ingest": {
               "timestamp": "2017-05-04T22:30:03.187Z"
            }
         }
      },
      {
         "doc": {
            "_id": "id",
            "_index": "index",
            "_type": "_doc",
            "_source": {
               "field2": "_value",
               "foo": "rab"
            },
            "_ingest": {
               "timestamp": "2017-05-04T22:30:03.188Z"
            }
         }
      }
   ]
}

Specify a pipeline in the request body

edit
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:

{
   "docs": [
      {
         "doc": {
            "_id": "id",
            "_index": "index",
            "_type": "_doc",
            "_source": {
               "field2": "_value",
               "foo": "bar"
            },
            "_ingest": {
               "timestamp": "2017-05-04T22:30:03.187Z"
            }
         }
      },
      {
         "doc": {
            "_id": "id",
            "_index": "index",
            "_type": "_doc",
            "_source": {
               "field2": "_value",
               "foo": "rab"
            },
            "_ingest": {
               "timestamp": "2017-05-04T22:30:03.188Z"
            }
         }
      }
   ]
}

View verbose results

edit

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.

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:

{
  "docs": [
    {
      "processor_results": [
        {
          "processor_type": "set",
          "status": "success",
          "doc": {
            "_index": "index",
            "_type": "_doc",
            "_id": "id",
            "_source": {
              "field2": "_value2",
              "foo": "bar"
            },
            "_ingest": {
              "pipeline": "_simulate_pipeline",
              "timestamp": "2020-07-30T01:21:24.251836Z"
            }
          }
        },
        {
          "processor_type": "set",
          "status": "success",
          "doc": {
            "_index": "index",
            "_type": "_doc",
            "_id": "id",
            "_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",
            "_type": "_doc",
            "_id": "id",
            "_source": {
              "field2": "_value2",
              "foo": "rab"
            },
            "_ingest": {
              "pipeline": "_simulate_pipeline",
              "timestamp": "2020-07-30T01:21:24.251863Z"
            }
          }
        },
        {
          "processor_type": "set",
          "status": "success",
          "doc": {
            "_index": "index",
            "_type": "_doc",
            "_id": "id",
            "_source": {
              "field3": "_value3",
              "field2": "_value2",
              "foo": "rab"
            },
            "_ingest": {
              "pipeline": "_simulate_pipeline",
              "timestamp": "2020-07-30T01:21:24.251863Z"
            }
          }
        }
      ]
    }
  ]
}