diff --git a/modules/vector-search/examples/run-pre-filtered-vector-search-rest-api.sh b/modules/vector-search/examples/run-pre-filtered-vector-search-rest-api.sh new file mode 100644 index 000000000..5ad973e62 --- /dev/null +++ b/modules/vector-search/examples/run-pre-filtered-vector-search-rest-api.sh @@ -0,0 +1,23 @@ +curl -XPOST -H "Content-Type: application/json" \ + -u ${CB_USERNAME}:${CB_PASSWORD} http://${CB_HOSTNAME}:8094/api/bucket/vector-sample/scope/color/index/color-index/query \ +-d '{ + "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" + } + } + ] + }' diff --git a/modules/vector-search/pages/pre-filtering-vector-search.adoc b/modules/vector-search/pages/pre-filtering-vector-search.adoc new file mode 100644 index 000000000..0d133e918 --- /dev/null +++ b/modules/vector-search/pages/pre-filtering-vector-search.adoc @@ -0,0 +1,73 @@ += Pre-filtering Vector Searches +:page-topic-type: guide +:page-ui-name: {ui-name} +:description: You can specify filters as part of a vector search statement which will restrict the documents searched during the query. + +[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 database. +For more information about how to deploy a new node and Services on your database, see xref:server:manage:manage-nodes/node-management-overview.adoc[]. + +* You have a bucket with scopes and collections in your database. +For more information about how to create a bucket, see xref:server:manage:manage-buckets/create-bucket.adoc[]. + +* Your user account has the *Search Admin* or *Search Reader* role. + +* You installed the Couchbase command-line tool (CLI). + +* You have the hostname or IP address for the node in your database where you're running the Search Service. +For more information about where to find the IP address for your node, see xref:server:manage:manage-nodes/list-cluster-nodes.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[] or xref:create-vector-search-index-rest-api.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}] or xref:create-vector-search-index-rest-api.adoc#example[Create a Vector Search Index with the REST API and curl/HTTP]. +-- + +== Procedure + +To run a pre-filtered vector search with the REST API: + +. In your command-line tool, enter a `curl` command with the `XPOST` verb. +. Set your header content to include `"Content-Type: application/json"`. +. Add your `username`, `password`, and the Search Service endpoint on port `8094`. +. Add the `index name` you want to query to the endpoint. + +[source, console] +---- +curl -XPOST -H "Content-Type: application/json" \ + -u ${CB_USERNAME}:${CB_PASSWORD} http://${CB_HOSTNAME}:8094/api/bucket/vector-sample/scope/color/index/{INDEX_NAME}/query \ +-d \ +---- + +=== Example + +In the following example, you will extend a search query +to find matches in `color-index`. + A pre-filter on the query will narrow the documents in the index searched to those with a `color` field value + that closely matches `navy`. + +[source, console] +---- +include::example$run-pre-filtered-vector-search-rest-api.sh[] +---- + + diff --git a/modules/vector-search/partials/nav.adoc b/modules/vector-search/partials/nav.adoc index 43d3ac6c0..d33a36583 100644 --- a/modules/vector-search/partials/nav.adoc +++ b/modules/vector-search/partials/nav.adoc @@ -1,6 +1,7 @@ * xref:7.6@server:vector-search:vector-search.adoc[] ** xref:7.6@server:vector-search:create-vector-search-index-ui.adoc[] ** xref:7.6@server:vector-search:create-vector-search-index-rest-api.adoc[] +** xref:7.6@server:vector-search:pre-filtering-vector-search.adoc[] ** xref:7.6@server:vector-search:run-vector-search-ui.adoc[] ** xref:7.6@server:vector-search:run-vector-search-rest-api.adoc[] -** xref:7.6@server:vector-search:run-vector-search-sdk.adoc[] \ No newline at end of file +** xref:7.6@server:vector-search:run-vector-search-sdk.adoc[]