This version of the OpenSearch documentation is no longer maintained. For the latest version, see the current documentation. For information about OpenSearch version maintenance, see Release Schedule and Maintenance Policy.

Percolator field type

A percolator field type specifies to treat this field as a query. Any JSON object field can be marked as a percolator field. Normally, documents are indexed and searches are run against them. When you use a percolator field, you store a search, and later the percolate query matches documents to that search.

Example

A customer is searching for a table priced at $400 or less and wants to create an alert for this search.

Create a mapping assigning a percolator field type to the query field:

  1. PUT testindex1
  2. {
  3.   "mappings": {
  4.     "properties": {
  5.       "search": {
  6.         "properties": {
  7.           "query": { 
  8.             "type": "percolator" 
  9.           }
  10.         }
  11.       },
  12.       "price": { 
  13.         "type": "float" 
  14.       },
  15.       "item": { 
  16.         "type": "text" 
  17.       }
  18.     }
  19.   }
  20. }

copy

Index a query:

  1. PUT testindex1/_doc/1
  2. {
  3.   "search": {
  4.     "query": {
  5.       "bool": {
  6.         "filter": [
  7.           { 
  8.             "match": { 
  9.               "item": { 
  10.                 "query": "table" 
  11.               }
  12.             }
  13.           },
  14.           { 
  15.             "range": { 
  16.               "price": { 
  17.                 "lte": 400.00 
  18.               } 
  19.             } 
  20.           }
  21.         ]
  22.       }
  23.     }
  24.   }
  25. }

copy

Fields referenced in the query must already exist in the mapping.

Run a percolate query to search for matching documents:

  1. GET testindex1/_search
  2. {
  3.   "query" : {
  4.     "bool" : {
  5.       "filter" : 
  6.         {
  7.           "percolate" : {
  8.             "field" : "search.query",
  9.             "document" : {
  10.               "item" : "Mahogany table",
  11.               "price": 399.99
  12.             }
  13.           }
  14.         }
  15.     }
  16.   }
  17. }

copy

The response contains the originally indexed query:

  1. {
  2.   "took" : 30,
  3.   "timed_out" : false,
  4.   "_shards" : {
  5.     "total" : 1,
  6.     "successful" : 1,
  7.     "skipped" : 0,
  8.     "failed" : 0
  9.   },
  10.   "hits" : {
  11.     "total" : {
  12.       "value" : 1,
  13.       "relation" : "eq"
  14.     },
  15.     "max_score" : 0.0,
  16.     "hits" : [
  17.       {
  18.         "_index" : "testindex1",
  19.         "_type" : "_doc",
  20.         "_id" : "1",
  21.         "_score" : 0.0,
  22.         "_source" : {
  23.           "search" : {
  24.             "query" : {
  25.               "bool" : {
  26.                 "filter" : [
  27.                   {
  28.                     "match" : {
  29.                       "item" : {
  30.                         "query" : "table"
  31.                       }
  32.                     }
  33.                   },
  34.                   {
  35.                     "range" : {
  36.                       "price" : {
  37.                         "lte" : 400.0
  38.                       }
  39.                     }
  40.                   }
  41.                 ]
  42.               }
  43.             }
  44.           }
  45.         },
  46.         "fields" : {
  47.           "_percolator_document_slot" : [
  48.             0
  49.           ]
  50.         }
  51.       }
  52.     ]
  53.   }
  54. }