Filter query processor

Introduced 2.8

The filter_query search request processor intercepts a search request and applies an additional query to the request, filtering the results. This is useful when you don’t want to rewrite existing queries in your application but need additional filtering of the results.

Request body fields

The following table lists all available request fields.

FieldData typeDescription
queryObjectA query in query domain-specific language (DSL). For a list of OpenSearch query types, see Query DSL. Required.
tagStringThe processor’s identifier. Optional.
descriptionStringA description of the processor. Optional.
ignore_failureBooleanIf true, OpenSearch ignores any failure of this processor and continues to run the remaining processors in the search pipeline. Optional. Default is false.

Example

The following example demonstrates using a search pipeline with a filter_query processor.

Setup

Create an index named my_index and index two documents, one public and one private:

  1. POST /my_index/_doc/1
  2. {
  3.   "message": "This is a public message", 
  4.   "visibility":"public"
  5. }

copy

  1. POST /my_index/_doc/2
  2. {
  3.   "message": "This is a private message", 
  4.   "visibility": "private"
  5. }

copy

Creating a search pipeline

The following request creates a search pipeline called my_pipeline with a filter_query request processor that uses a term query to return only public messages:

  1. PUT /_search/pipeline/my_pipeline 
  2. {
  3.   "request_processors": [
  4.     {
  5.       "filter_query" : {
  6.         "tag" : "tag1",
  7.         "description" : "This processor is going to restrict to publicly visible documents",
  8.         "query" : {
  9.           "term": {
  10.             "visibility": "public"
  11.           }
  12.         }
  13.       }
  14.     }
  15.   ]
  16. }

copy

Using a search pipeline

Search for documents in my_index without a search pipeline:

  1. GET /my_index/_search

copy

The response contains both documents:

Response

  1. {
  2.   "took" : 47,
  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" : 2,
  13.       "relation" : "eq"
  14.     },
  15.     "max_score" : 1.0,
  16.     "hits" : [
  17.       {
  18.         "_index" : "my_index",
  19.         "_id" : "1",
  20.         "_score" : 1.0,
  21.         "_source" : {
  22.           "message" : "This is a public message",
  23.           "visibility" : "public"
  24.         }
  25.       },
  26.       {
  27.         "_index" : "my_index",
  28.         "_id" : "2",
  29.         "_score" : 1.0,
  30.         "_source" : {
  31.           "message" : "This is a private message",
  32.           "visibility" : "private"
  33.         }
  34.       }
  35.     ]
  36.   }
  37. }

To search with a pipeline, specify the pipeline name in the search_pipeline query parameter:

  1. GET /my_index/_search?search_pipeline=my_pipeline

copy

The response contains only the document with public visibility:

Response

  1. {
  2.   "took" : 19,
  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" : "my_index",
  19.         "_id" : "1",
  20.         "_score" : 0.0,
  21.         "_source" : {
  22.           "message" : "This is a public message",
  23.           "visibility" : "public"
  24.         }
  25.       }
  26.     ]
  27.   }
  28. }