Filter search results

Filter search results

You can use two methods to filter search results:

  • Use a boolean query with a filter clause. Search requests apply boolean filters to both search hits and aggregations.

  • Use the search API’s post_filter parameter. Search requests apply post filters only to search hits, not aggregations. You can use a post filter to calculate aggregations based on a broader result set, and then further narrow the results.

    You can also rescore hits after the post filter to improve relevance and reorder results.

Post filter

When you use the post_filter parameter to filter search results, the search hits are filtered after the aggregations are calculated. A post filter has no impact on the aggregation results.

For example, you are selling shirts that have the following properties:

  1. PUT /shirts
  2. {
  3.   "mappings": {
  4.     "properties": {
  5.       "brand": { "type": "keyword"},
  6.       "color": { "type": "keyword"},
  7.       "model": { "type": "keyword"}
  8.     }
  9.   }
  10. }
  12. PUT /shirts/_doc/1?refresh
  13. {
  14.   "brand": "gucci",
  15.   "color": "red",
  16.   "model": "slim"
  17. }

Imagine a user has specified two filters:

color:red and brand:gucci. You only want to show them red shirts made by Gucci in the search results. Normally you would do this with a bool query:

  1. GET /shirts/_search
  2. {
  3.   "query": {
  4.     "bool": {
  5.       "filter": [
  6.         { "term": { "color": "red"   }},
  7.         { "term": { "brand": "gucci" }}
  8.       ]
  9.     }
  10.   }
  11. }

However, you would also like to use faceted navigation to display a list of other options that the user could click on. Perhaps you have a model field that would allow the user to limit their search results to red Gucci t-shirts or dress-shirts.

This can be done with a terms aggregation:

  1. GET /shirts/_search
  2. {
  3.   "query": {
  4.     "bool": {
  5.       "filter": [
  6.         { "term": { "color": "red"   }},
  7.         { "term": { "brand": "gucci" }}
  8.       ]
  9.     }
  10.   },
  11.   "aggs": {
  12.     "models": {
  13.       "terms": { "field": "model" } 
  14.     }
  15.   }
  16. }

Returns the most popular models of red shirts by Gucci.

But perhaps you would also like to tell the user how many Gucci shirts are available in other colors. If you just add a terms aggregation on the color field, you will only get back the color red, because your query returns only red shirts by Gucci.

Instead, you want to include shirts of all colors during aggregation, then apply the colors filter only to the search results. This is the purpose of the post_filter:

  1. GET /shirts/_search
  2. {
  3.   "query": {
  4.     "bool": {
  5.       "filter": {
  6.         "term": { "brand": "gucci" } 
  7.       }
  8.     }
  9.   },
  10.   "aggs": {
  11.     "colors": {
  12.       "terms": { "field": "color" } 
  13.     },
  14.     "color_red": {
  15.       "filter": {
  16.         "term": { "color": "red" } 
  17.       },
  18.       "aggs": {
  19.         "models": {
  20.           "terms": { "field": "model" } 
  21.         }
  22.       }
  23.     }
  24.   },
  25.   "post_filter": { 
  26.     "term": { "color": "red" }
  27.   }
  28. }

The main query now finds all shirts by Gucci, regardless of color.

The colors agg returns popular colors for shirts by Gucci.

The color_red agg limits the models sub-aggregation to red Gucci shirts.

Finally, the post_filter removes colors other than red from the search hits.

Rescore filtered search results

Rescoring can help to improve precision by reordering just the top (eg 100 - 500) documents returned by the query and post_filter phases, using a secondary (usually more costly) algorithm, instead of applying the costly algorithm to all documents in the index.

A rescore request is executed on each shard before it returns its results to be sorted by the node handling the overall search request.

Currently the rescore API has only one implementation: the query rescorer, which uses a query to tweak the scoring. In the future, alternative rescorers may be made available, for example, a pair-wise rescorer.

An error will be thrown if an explicit sort (other than _score in descending order) is provided with a rescore query.

when exposing pagination to your users, you should not change window_size as you step through each page (by passing different from values) since that can alter the top hits causing results to confusingly shift as the user steps through pages.

Query rescorer

The query rescorer executes a second query only on the Top-K results returned by the query and post_filter phases. The number of docs which will be examined on each shard can be controlled by the window_size parameter, which defaults to 10.

By default the scores from the original query and the rescore query are combined linearly to produce the final _score for each document. The relative importance of the original query and of the rescore query can be controlled with the query_weight and rescore_query_weight respectively. Both default to 1.

For example:

  1. POST /_search
  2. {
  3.    "query" : {
  4.       "match" : {
  5.          "message" : {
  6.             "operator" : "or",
  7.             "query" : "the quick brown"
  8.          }
  9.       }
  10.    },
  11.    "rescore" : {
  12.       "window_size" : 50,
  13.       "query" : {
  14.          "rescore_query" : {
  15.             "match_phrase" : {
  16.                "message" : {
  17.                   "query" : "the quick brown",
  18.                   "slop" : 2
  19.                }
  20.             }
  21.          },
  22.          "query_weight" : 0.7,
  23.          "rescore_query_weight" : 1.2
  24.       }
  25.    }
  26. }

The way the scores are combined can be controlled with the score_mode:

Score ModeDescription

total

Add the original score and the rescore query score. The default.

multiply

Multiply the original score by the rescore query score. Useful for function query rescores.

avg

Average the original score and the rescore query score.

max

Take the max of original score and the rescore query score.

min

Take the min of the original score and the rescore query score.

Multiple rescores

It is also possible to execute multiple rescores in sequence:

  1. POST /_search
  2. {
  3.    "query" : {
  4.       "match" : {
  5.          "message" : {
  6.             "operator" : "or",
  7.             "query" : "the quick brown"
  8.          }
  9.       }
  10.    },
  11.    "rescore" : [ {
  12.       "window_size" : 100,
  13.       "query" : {
  14.          "rescore_query" : {
  15.             "match_phrase" : {
  16.                "message" : {
  17.                   "query" : "the quick brown",
  18.                   "slop" : 2
  19.                }
  20.             }
  21.          },
  22.          "query_weight" : 0.7,
  23.          "rescore_query_weight" : 1.2
  24.       }
  25.    }, {
  26.       "window_size" : 10,
  27.       "query" : {
  28.          "score_mode": "multiply",
  29.          "rescore_query" : {
  30.             "function_score" : {
  31.                "script_score": {
  32.                   "script": {
  33.                     "source": "Math.log10(doc.count.value + 2)"
  34.                   }
  35.                }
  36.             }
  37.          }
  38.       }
  39.    } ]
  40. }

The first one gets the results of the query then the second one gets the results of the first, etc. The second rescore will “see” the sorting done by the first rescore so it is possible to use a large window on the first rescore to pull documents into a smaller window for the second rescore.