Elasticsearch Elasticsearch Percolate Query

By Opster Expert Team - May 2023

Updated: Aug 29, 2023

| 3 min read

If you want to learn more about Elasticsearch Percolate Query, check out this guide.

Quick links

• Introduction
• Use cases for Elasticsearch percolate query
• Implementing Elasticsearch percolator
• Conclusion

Introduction

In this article, we will dive into the Elasticsearch percolate query, its use cases, and how to implement it.

Use Cases for Elasticsearch Percolate Query

1. Monitoring and Alerting: The percolator can be used to monitor incoming data streams and trigger alerts when specific conditions are met. For example, you can index queries that represent specific error conditions, and when a new log entry matches one of these queries, an alert can be generated.
2. Document Classification: the percolate query can be used to classify documents based on predefined criteria. By indexing queries that represent different categories, you can quickly classify new documents by finding the queries that match them.
3. Real-time Search-as-you-type Suggestions: The percolate query can be used to provide real-time search suggestions as users type their queries. By indexing common search queries, you can quickly find matching queries as users type, providing relevant suggestions to improve the search experience.

Implementing Elasticsearch Percolator

Now, let’s walk through the process step-by-step.

Step 1: Create an index with a percolator field

To use the percolate query feature, you need to create an index with a mapping that includes a field of type “percolator”. Here’s an example of how to create an index with a percolator field:

PUT /my-index
{
  "mappings": {
    "properties": {
      "query": {
        "type": "percolator"
      },
      "content": {
        "type": "text"
      }
    }
  }
}

In this example, we created an index called “my-index” with two fields: “query” of type “percolator” and “content” of type “text”.

Step 2: Index queries

Now that you have an index with a percolator field, you can start indexing queries. To index a query, you need to store it as a document in the percolator field, which in the case of our example is the “query” field. Here’s an example of how to index a query:

PUT /my-index/_doc/1
{
  "query": {
    "match": {
      "content": "elasticsearch"
    }
  }
}

In this example, we indexed a query that matches documents containing the term “elasticsearch” in the “content” field.

Step 3: Percolate documents

Once you have indexed your queries, you can use the percolate query to find the queries that match a given document. Here’s an example of how to percolate a document:

GET /my-index/_search
{
  "query": {
    "percolate": {
      "field": "query",
      "document": {
        "content": "Elasticsearch is a powerful search engine."
      }
    }
  }
}

In this example, we percolated a single document with the content “Elasticsearch is a powerful search engine.” The response will include the IDs of the indexed queries that match the document. The response should look something like this:

{
    …
  "hits": {
    "total": {
      "value": 1,
      "relation": "eq"
    },
    "max_score": 0.13076457,
    "hits": [
      {
        "_index": "percolator-index",
        "_id": "1",
        "_score": 0.13076457,
        "_source": {
          "query": {
            "match": {
              "content": "elasticsearch"
            }
          }
        },
        "fields": {
          "_percolator_document_slot": [
            0
          ]
        }
      }
    ]
  }
}

You could also provide a collection of documents to be percolated, if instead of the “document” field you use the “documents” field.

Instead of providing the documents in the query body, you could reference existing documents in an index to be used as input for the percolate query. In the example below we want the query to take the document with “id” equals to 2 in the “my-data-index”.

GET /my-index/_search
{
  "query": {
    "percolate": {
      "field": "query",
      "index": "my-data-index",
      "id": "2",
      "version": 1 
    }
  }
}

One last thing that could be useful is to highlight the query results, so you can easily see where your match occurred. Take a look at the query below:

GET /my-index/_search
{
  "query": {
    "percolate": {
      "field": "query",
      "document": {
        "content": "Elasticsearch is a powerful search engine."
      }
    }
  },
  "highlight": {
    "fields": {
      "content": {}
    }
  }
}
 
If we'd run this query we'd get this result:

{
…
  "hits": {
    "total": {
      "value": 1,
      "relation": "eq"
    },
    "max_score": 0.13076457,
    "hits": [
      {
        "_index": "percolator-index",
        "_id": "1",
        "_score": 0.13076457,
        "_source": {
          "query": {
            "match": {
              "content": "elasticsearch"
            }
          }
        },
        "fields": {
          "_percolator_document_slot": [
            0
          ]
        },
        "highlight": {
          "content": [
            "<em>Elasticsearch</em> is a powerful search engine."
          ]
        }
      }
    ]
  }
}

Notice the highlighted “Elasticsearch” term in the highlight part of the response.