Add hybrid search pre-filtering documentation

_query-dsl/compound/hybrid.md

@@ -22,7 +22,7 @@ The following table lists all top-level parameters supported by `hybrid` queries
 Parameter | Description
 :--- | :---
 `queries` | An array of one or more query clauses that are used to match documents. A document must match at least one query clause in order to be returned in the results. The documents' relevance scores from all query clauses are combined into one score by applying a [search pipeline]({{site.url}}{{site.baseurl}}/search-plugins/search-pipelines/index/). The maximum number of query clauses is 5. Required.
-`filter` | A filter to apply to all the subqueries of the hybrid query. 
+`filter` | A filter to apply to all the subqueries of the hybrid query. The filter must be a single query object. To apply multiple filter conditions, combine them in a [Boolean query]({{site.url}}{{site.baseurl}}/query-dsl/compound/bool/). For more information, see [Hybrid search with pre-filtering]({{site.url}}{{site.baseurl}}/vector-search/ai-search/hybrid-search/pre-filtering/).
 
 ### Rescoring hybrid queries
 Introduced 2.18

_vector-search/ai-search/hybrid-search/post-filtering.md

@@ -18,6 +18,8 @@ The `post_filter` clause is applied after the search results have been retrieved
 Post-filtering does not impact document relevance scores or aggregation results.
 {: .note}
 
+To filter all subqueries during query execution instead of filtering the final results, use a common filter. For more information, see [Hybrid search with pre-filtering]({{site.url}}{{site.baseurl}}/vector-search/ai-search/hybrid-search/pre-filtering/).
+
 ## Example
 
 The following example request combines two query clauses---a `term` query and a `match` query---and contains a `post_filter`:

_vector-search/ai-search/hybrid-search/pre-filtering.md

@@ -0,0 +1,145 @@
+---
+layout: default
+title: Hybrid search with pre-filtering
+parent: Hybrid search
+grand_parent: AI search
+has_children: false
+nav_order: 38
+---
+
+# Hybrid search with pre-filtering
+**Introduced 3.0**
+{: .label .label-purple }
+
+You can perform pre-filtering on hybrid search results by providing a top-level `filter` parameter in the `hybrid` query.
+
+The `filter` is applied during query execution and is pushed down to each subquery, so only documents that match the filter are scored. Pre-filtering is useful for applying the same filter to all subqueries without duplicating it in each one.
+
+The `filter` must be a single query object.
+{: .note}
+
+To filter the final results after they have been retrieved instead of filtering each subquery during execution, use a post-filter. For more information, see [Hybrid search with post-filtering]({{site.url}}{{site.baseurl}}/vector-search/ai-search/hybrid-search/post-filtering/).
+
+## Example
+
+The following example request combines a `match` query and a `knn` query and applies a common `filter` that restricts both subqueries to the `shoes` category:
+
+```json
+POST /products/_search?search_pipeline=nlp-search-pipeline
+{
+  "query": {
+    "hybrid": {
+      "filter": {
+        "term": { "category": "shoes" }
+      },
+      "queries": [
+        {
+          "match": { "description": "running shoes" }
+        },
+        {
+          "knn": {
+            "embedding": {
+              "vector": [1.23, 0.45, 0.67, ...],
+              "k": 10
+            }
+          }
+        }
+      ]
+    }
+  }
+}
+```
+{% include copy-curl.html %}
+
+OpenSearch applies the `category: shoes` filter to both the `match` and `knn` subqueries, which is equivalent to the following query that applies the filter to each subquery individually:
+
+```json
+POST /products/_search?search_pipeline=nlp-search-pipeline
+{
+  "query": {
+    "hybrid": {
+      "queries": [
+        {
+          "bool": {
+            "must": {
+              "match": { "description": "running shoes" }
+            },
+            "filter": {
+              "term": { "category": "shoes" }
+            }
+          }
+        },
+        {
+          "knn": {
+            "embedding": {
+              "vector": [1.23, 0.45, 0.67, ...],
+              "k": 10,
+              "filter": {
+                "term": { "category": "shoes" }
+              }
+            }
+          }
+        }
+      ]
+    }
+  }
+}
+```
+{% include copy-curl.html %}
+
+## Filtering on multiple conditions
+
+Because the `filter` must be a single query object, you combine multiple conditions in a [Boolean query]({{site.url}}{{site.baseurl}}/query-dsl/compound/bool/):
+
+```json
+"filter": {
+  "bool": {
+    "must": [
+      { "term": { "category": "shoes" }},
+      { "term": { "in_stock": true }}
+    ]
+  }
+}
+```
+
+## Combining a common filter with subquery filters
+
+A subquery can define its own filter in addition to the common filter. In this case, OpenSearch combines the two using a logical `AND`, further narrowing that subquery's results. Subqueries without their own filter are constrained by the common filter only.
+
+In the following example, the common filter restricts all subqueries to the `shoes` category, while the `match` subquery is additionally narrowed to the `nike` brand:
+
+```json
+POST /products/_search?search_pipeline=nlp-search-pipeline
+{
+  "query": {
+    "hybrid": {
+      "filter": {
+        "term": { "category": "shoes" }
+      },
+      "queries": [
+        {
+          "bool": {
+            "must": {
+              "match": { "description": "running shoes" }
+            },
+            "filter": {
+              "term": { "brand": "nike" }
+            }
+          }
+        },
+        {
+          "knn": {
+            "embedding": {
+              "vector": [1.23, 0.45, 0.67, ...],
+              "k": 10
+            }
+          }
+        }
+      ]
+    }
+  }
+}
+```
+{% include copy-curl.html %}
+
+As a result, the `match` subquery requires both `category: shoes` and `brand: nike`, while the `knn` subquery is constrained only to `category: shoes`.