Simulate Pipeline API

Simulate Pipeline Request

A SimulatePipelineRequest requires a source and a XContentType. The source consists of the request body. See the docs for more details on the request body.

String source =
    "{\"" +
        "pipeline\":{" +
            "\"description\":\"_description\"," +
            "\"processors\":[{\"set\":{\"field\":\"field2\",\"value\":\"_value\"}}]" +
        "}," +
        "\"docs\":[" +
            "{\"_index\":\"index\",\"_id\":\"id\",\"_source\":{\"foo\":\"bar\"}}," +
            "{\"_index\":\"index\",\"_id\":\"id\",\"_source\":{\"foo\":\"rab\"}}" +
        "]" +
    "}";
SimulatePipelineRequest request = new SimulatePipelineRequest(
    new BytesArray(source.getBytes(StandardCharsets.UTF_8)), 
    XContentType.JSON 
);

The request body as a ByteArray.

The XContentType for the request body supplied above.

Optional arguments

The following arguments can optionally be provided:

request.setId("my-pipeline-id"); 

You can either specify an existing pipeline to execute against the provided documents, or supply a pipeline definition in the body of the request. This option sets the id for an existing pipeline.

request.setVerbose(true); 

To see the intermediate results of each processor in the simulate request, you can add the verbose parameter to the request.

Synchronous Execution

SimulatePipelineResponse response = client.ingest().simulate(request, RequestOptions.DEFAULT); 

Execute the request and get back the response in a SimulatePipelineResponse object.

Asynchronous Execution

The asynchronous execution of a simulate pipeline request requires both the SimulatePipelineRequest instance and an ActionListener instance to be passed to the asynchronous method:

client.ingest().simulateAsync(request, RequestOptions.DEFAULT, listener); 

The SimulatePipelineRequest to execute and the ActionListener to use when the execution completes

The asynchronous method does not block and returns immediately. Once it is completed the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed.

A typical listener for SimulatePipelineResponse looks like:

ActionListener<SimulatePipelineResponse> listener =
    new ActionListener<SimulatePipelineResponse>() {
        @Override
        public void onResponse(SimulatePipelineResponse response) {
            
        }

        @Override
        public void onFailure(Exception e) {
            
        }
    };

Called when the execution is successfully completed. The response is provided as an argument

Called in case of failure. The raised exception is provided as an argument

Simulate Pipeline Response

The returned SimulatePipelineResponse allows to retrieve information about the executed operation as follows:

for (SimulateDocumentResult result: response.getResults()) { 
    if (request.isVerbose()) {
        assert result instanceof SimulateDocumentVerboseResult;
        SimulateDocumentVerboseResult verboseResult = (SimulateDocumentVerboseResult)result; 
        for (SimulateProcessorResult processorResult: verboseResult.getProcessorResults()) { 
            processorResult.getIngestDocument(); 
            processorResult.getFailure(); 
        }
    } else {
        assert result instanceof SimulateDocumentBaseResult;
        SimulateDocumentBaseResult baseResult = (SimulateDocumentBaseResult)result; 
        baseResult.getIngestDocument(); 
        baseResult.getFailure(); 
    }
}

Get results for each of the documents provided as instance of List<SimulateDocumentResult>.

If the request was in verbose mode cast the response to SimulateDocumentVerboseResult.

Check the result after each processor is applied.

Get the ingest document for the result obtained in 3.

Or get the failure for the result obtained in 3.

Get the result as SimulateDocumentBaseResult if the result was not verbose.

Get the ingest document for the result obtained in 6.

Or get the failure for the result obtained in 6.