OpenSearch/docs/java-api/query-dsl/percolate-query.asciidoc

[[java-query-percolate-query]]
==== Percolate query

See: {ref}/query-dsl-percolate-query.html[Percolate Query]

In order to use the `percolate` query from the Java API your
the percolator module dependency should be on the classpath and
the transport client should be loaded with the percolator plugin:

[source,java]
--------------------------------------------------
TransportClient transportClient = TransportClient.builder()
        .settings(Settings.builder().put("node.name", "node"))
        .addPlugin(PercolatorPlugin.class)
        .build();
transportClient.addTransportAddress(
        new InetSocketTransportAddress(new InetSocketAddress(InetAddresses.forString("127.0.0.1"), 9300))
);
--------------------------------------------------

Before the `percolate` query can be used an `percolator` mapping should be added and
a document containing a percolator query should be indexed:

[source,java]
--------------------------------------------------
// create an index with a percolator field with the name 'query':
client.admin().indices().prepareCreate("myIndexName")
                        .addMapping("query", "query", "type=percolator")
                        .get();

//This is the query we're registering in the percolator
QueryBuilder qb = termQuery("content", "amazing");

//Index the query = register it in the percolator
client.prepareIndex("myIndexName", "query", "myDesignatedQueryName")
    .setSource(jsonBuilder()
        .startObject()
            .field("query", qb) // Register the query
        .endObject())
    .setRefresh(true) // Needed when the query shall be available immediately
    .get();
--------------------------------------------------

This indexes the above term query under the name
*myDesignatedQueryName*.

In order to check a document against the registered queries, use this
code:

[source,java]
--------------------------------------------------
//Build a document to check against the percolator
XContentBuilder docBuilder = XContentFactory.jsonBuilder().startObject();
docBuilder.field("doc").startObject(); //This is needed to designate the document
docBuilder.field("content", "This is amazing!");
docBuilder.endObject(); //End of the doc field
docBuilder.endObject(); //End of the JSON root object
// Percolate, by executing the percolator query in the query dsl:
SearchResponse response = client().prepareSearch("myIndexName")
        .setQuery(QueryBuilders.percolateQuery("query", ""myDocumentType", docBuilder.bytes()))
        .get();
//Iterate over the results
for(SearchHit hit : response.getHits()) {
    // Percolator queries as hit
}
--------------------------------------------------