[DOC-12609]: Document the extension to vector syntax to support pre filtering: MB-62230 (#285) (#316)

* [DOC-12609]: Document the extension to vector syntax to support pre filtering: MB-62230 (#285)

* [DOC-12609]: Document the extension to vector syntax to support pre filtering: MB-62230

* [DOC-12609]: Document the extension to vector syntax to support pre filtering: MB-62230

Fleshing out the text following review.
Tidied up the advantages list.

* [DOC-12609]: Document the extension to vector syntax to support pre-filtering: MB-62230

Fixups following review.

* [DOC-12609] Capella - Fix up the documentation for Server to apply to Capella implementation of Vector Search.

Changed filename for example since it's no longer a REST API example

Added more details to search-request-params for filter object

---------

Co-authored-by: Sarah Welton <[email protected]>

Author: simon-dew

modules/search/examples/run-search-full-request.jsonc

@@ -52,7 +52,11 @@
                 "ivf_max_codes_pct": 0.2
             },
             "field": "vector_field",
-            "vector": [ 0.707106781186548, 0, 0.707106781186548 ]
+            "vector": [ 0.707106781186548, 0, 0.707106781186548 ],
+            "filter": {
+                "min": 10000,
+                "field": "id"
+            }
         }
     ],
     // end::knn[]

modules/search/pages/search-request-params.adoc

@@ -227,7 +227,13 @@ The Search Service uses the similarity metric defined in the xref:search-index-p
 
 NOTE: The vector in your Search query must match the dimension of the vectors stored in your Search index. 
 If the dimensions do not match, your Search query does not return any results.
-For more information about the dimension value, see the xref:search-index-params.adoc#dims[dims property] or the xref:type-mapping-options.adoc#dimension[Dimension option] in the UI. 
+For more information about the dimension value, see the xref:search-index-params.adoc#dims[dims property] or the xref:type-mapping-options.adoc#dimension[Dimension option] in the UI.
+
+|[[filter]]filter |Object |No a|
+
+Add a filter object to xref:vector-search:pre-filtering-vector-search.adoc[add pre-filtering], based on an additional query, to a Vector Search query. 
+
+The `filter` object can take properties from any of the query types supported by the <<query-object,>>.
 |====
 
 [#knn-params]

modules/vector-search/examples/run-pre-filtered-vector-search-ui.json

@@ -0,0 +1,21 @@
+{
+  "fields": ["*"],
+  "query": {
+    "min": 70,
+    "max": 80,
+    "inclusive_min": false,
+    "inclusive_max": true,
+    "field": "brightness"
+  },
+  "knn": [
+    {
+      "k": 10,
+      "field": "colorvect_l2",
+      "vector": [ 176, 0, 176 ],
+      "filter": {
+        "field":  "color",
+        "match": "navy"
+      }
+    }
+  ]
+}

modules/vector-search/pages/pre-filtering-vector-search.adoc

@@ -0,0 +1,61 @@
+= Pre-filtering Vector Searches
+:page-topic-type: guide
+:page-ui-name: {ui-name}
+:description: You can specify filters as part of a Vector Search query object to restrict the documents searched in a Search index.
+
+[abstract]
+{description}
+
+== About Pre-filtering
+
+Using pre-filtering as part of your vector search offers two key advantages:
+
+. *Enhanced precision and relevance:*
+Narrow your search results based on specific criteria, such as organization, date/time ranges, or geospatial locations.
+
+. *Performance optimization:*
+Reduce the search space before executing queries to improve query execution time and reduce computational overhead.
+
+== Prerequisites
+
+* You have the Search Service enabled on a node in your operational cluster.
+For more information about how to change Services on your operational cluster, see xref:cloud:clusters:modify-database.adoc[].
+
+* You have a bucket with scopes and collections in your operational cluster. 
+For more information, see xref:cloud:clusters:data-service/manage-buckets.adoc[].
+
+* You have created a Vector Search index.
++
+For more information about how to create a Vector Search index, see xref:create-vector-search-index-ui.adoc[].
++
+[TIP]
+--
+include::partial$download-sample-partial.adoc[]
+
+For the best results, consider using the sample Vector Search index from xref:create-vector-search-index-ui.adoc#example[Create a Vector Search Index with the {page-ui-name}].
+--
+
+== Procedure
+
+To add pre-filtering to a Vector Search query: 
+
+. On the *Operational Clusters* page, select the operational cluster where you created your Search index. 
+. Go to menu:Data Tools[Search]. 
+. Next to your Vector Search index, click btn:[Search].
+. In the *Search* field, enter a search query that includes a `filter` object with your `knn` object.
++
+For more information about the `filter` object, see xref:search:search-request-params.adoc#filter[filter].
+. Press kbd:[Enter] or click btn:[Search].
+. (Optional) To view a document and its source collection, click a document name in the search results list. 
+
+=== Example: Pre-Filter A Vector Search Query For The Color "Navy"
+
+For example, the following Vector Search query tries to find matches to a color with an RGB value of `[176, 0, 176]` with a minimum brightness of `70` and a maximum of `80`.
+A pre-filter on the query will narrow the documents searched inside the Vector Search index to documents that have a `color` field value that closely matches `navy`:
+
+[source, json]
+----
+include::example$run-pre-filtered-vector-search-ui.json[]
+----
+
+

modules/vector-search/pages/run-vector-search-ui.adoc

@@ -36,7 +36,7 @@ To run a Vector Search with the {page-ui-name}:
 . Next to your Vector Search index, click btn:[Search].
 . In the *Search* field, enter a search query.
 . Press kbd:[Enter] or click btn:[Search].
-. . (Optional) To view a document and its source collection, click a document name in the search results list. 
+. (Optional) To view a document and its source collection, click a document name in the search results list. 
 
 [#similarity]
 === Example: Running a Simple Vector Similarity Query

modules/vector-search/partials/nav.adoc

@@ -1,5 +1,6 @@
 * xref:cloud:vector-search:vector-search.adoc[]
 ** xref:cloud:vector-search:create-vector-search-index-ui.adoc[]
+** xref:cloud:vector-search:pre-filtering-vector-search.adoc[]
 ** xref:cloud:vector-search:run-vector-search-ui.adoc[]
 ** xref:cloud:vector-search:run-vector-search-sdk.adoc[]
 ** xref:cloud:vector-search:fine-tune-vector-search.adoc[]