|
| 1 | +--- |
| 2 | +layout: default |
| 3 | +title: Filter query processor |
| 4 | +nav_order: 10 |
| 5 | +has_children: false |
| 6 | +parent: Search pipelines |
| 7 | +grand_parent: Search |
| 8 | +--- |
| 9 | + |
| 10 | +# Filter query processor |
| 11 | + |
| 12 | +This is an experimental feature and is not recommended for use in a production environment. For updates on the progress of the feature or if you want to leave feedback, see the associated [GitHub issue](https://forum.opensearch.org/t/rfc-search-pipelines/12099). |
| 13 | +{: .warning} |
| 14 | + |
| 15 | +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. |
| 16 | + |
| 17 | +## Request fields |
| 18 | + |
| 19 | +The following table lists all available request fields. |
| 20 | + |
| 21 | +Field | Data type | Description |
| 22 | +:--- | :--- | :--- |
| 23 | +`query` | Object | A query in query domain-specific language (DSL). For a list of OpenSearch query types, see [Query DSL]({{site.url}}{{site.baseurl}}/opensearch/query-dsl/). Required. |
| 24 | +`tag` | String | The processor's identifier. Optional. |
| 25 | +`description` | String | A description of the processor. Optional. |
| 26 | + |
| 27 | +## Example |
| 28 | + |
| 29 | +The following example demonstrates using a search pipeline with a `filter_query` processor. |
| 30 | + |
| 31 | +### Setup |
| 32 | + |
| 33 | +Create an index named `my_index` and index two documents, one public and one private: |
| 34 | + |
| 35 | +```json |
| 36 | +POST /my_index/_doc/1 |
| 37 | +{ |
| 38 | + "message": "This is a public message", |
| 39 | + "visibility":"public" |
| 40 | +} |
| 41 | +``` |
| 42 | +{% include copy-curl.html %} |
| 43 | + |
| 44 | +```json |
| 45 | +POST /my_index/_doc/2 |
| 46 | +{ |
| 47 | + "message": "This is a private message", |
| 48 | + "visibility": "private" |
| 49 | +} |
| 50 | +``` |
| 51 | +{% include copy-curl.html %} |
| 52 | + |
| 53 | +### Creating a search pipeline |
| 54 | + |
| 55 | +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: |
| 56 | + |
| 57 | +```json |
| 58 | +PUT /_search/pipeline/my_pipeline |
| 59 | +{ |
| 60 | + "request_processors": [ |
| 61 | + { |
| 62 | + "filter_query" : { |
| 63 | + "tag" : "tag1", |
| 64 | + "description" : "This processor is going to restrict to publicly visible documents", |
| 65 | + "query" : { |
| 66 | + "term": { |
| 67 | + "visibility": "public" |
| 68 | + } |
| 69 | + } |
| 70 | + } |
| 71 | + } |
| 72 | + ] |
| 73 | +} |
| 74 | +``` |
| 75 | +{% include copy-curl.html %} |
| 76 | + |
| 77 | +### Using a search pipeline |
| 78 | + |
| 79 | +Search for documents in `my_index` without a search pipeline: |
| 80 | + |
| 81 | +```json |
| 82 | +GET /my_index/_search |
| 83 | +``` |
| 84 | +{% include copy-curl.html %} |
| 85 | + |
| 86 | +The response contains both documents: |
| 87 | + |
| 88 | +<details open markdown="block"> |
| 89 | + <summary> |
| 90 | + Response |
| 91 | + </summary> |
| 92 | + {: .text-delta} |
| 93 | +```json |
| 94 | +{ |
| 95 | + "took" : 47, |
| 96 | + "timed_out" : false, |
| 97 | + "_shards" : { |
| 98 | + "total" : 1, |
| 99 | + "successful" : 1, |
| 100 | + "skipped" : 0, |
| 101 | + "failed" : 0 |
| 102 | + }, |
| 103 | + "hits" : { |
| 104 | + "total" : { |
| 105 | + "value" : 2, |
| 106 | + "relation" : "eq" |
| 107 | + }, |
| 108 | + "max_score" : 1.0, |
| 109 | + "hits" : [ |
| 110 | + { |
| 111 | + "_index" : "my_index", |
| 112 | + "_id" : "1", |
| 113 | + "_score" : 1.0, |
| 114 | + "_source" : { |
| 115 | + "message" : "This is a public message", |
| 116 | + "visibility" : "public" |
| 117 | + } |
| 118 | + }, |
| 119 | + { |
| 120 | + "_index" : "my_index", |
| 121 | + "_id" : "2", |
| 122 | + "_score" : 1.0, |
| 123 | + "_source" : { |
| 124 | + "message" : "This is a private message", |
| 125 | + "visibility" : "private" |
| 126 | + } |
| 127 | + } |
| 128 | + ] |
| 129 | + } |
| 130 | +} |
| 131 | +``` |
| 132 | +</details> |
| 133 | + |
| 134 | +To search with a pipeline, specify the pipeline name in the `search_pipeline` query parameter: |
| 135 | + |
| 136 | +```json |
| 137 | +GET /my_index/_search?search_pipeline=my_pipeline |
| 138 | +``` |
| 139 | +{% include copy-curl.html %} |
| 140 | + |
| 141 | +The response contains only the document with `public` visibility: |
| 142 | + |
| 143 | +<details open markdown="block"> |
| 144 | + <summary> |
| 145 | + Response |
| 146 | + </summary> |
| 147 | + {: .text-delta} |
| 148 | +```json |
| 149 | +{ |
| 150 | + "took" : 19, |
| 151 | + "timed_out" : false, |
| 152 | + "_shards" : { |
| 153 | + "total" : 1, |
| 154 | + "successful" : 1, |
| 155 | + "skipped" : 0, |
| 156 | + "failed" : 0 |
| 157 | + }, |
| 158 | + "hits" : { |
| 159 | + "total" : { |
| 160 | + "value" : 1, |
| 161 | + "relation" : "eq" |
| 162 | + }, |
| 163 | + "max_score" : 0.0, |
| 164 | + "hits" : [ |
| 165 | + { |
| 166 | + "_index" : "my_index", |
| 167 | + "_id" : "1", |
| 168 | + "_score" : 0.0, |
| 169 | + "_source" : { |
| 170 | + "message" : "This is a public message", |
| 171 | + "visibility" : "public" |
| 172 | + } |
| 173 | + } |
| 174 | + ] |
| 175 | + } |
| 176 | +} |
| 177 | +``` |
| 178 | +</details> |
0 commit comments