From b56b381c704ceab690689769098f5c1f61c34009 Mon Sep 17 00:00:00 2001 From: Ray Offiah Date: Fri, 1 Nov 2024 10:23:26 +0000 Subject: [PATCH 1/3] [DOC-12609]: Document the extension to vector syntax to support pre filtering: MB-62230 --- ...run-pre-filtered-vector-search-rest-api.sh | 23 +++++++ .../pages/pre-filtering-vector-search.adoc | 64 +++++++++++++++++++ modules/vector-search/partials/nav.adoc | 3 +- 3 files changed, 89 insertions(+), 1 deletion(-) create mode 100644 modules/vector-search/examples/run-pre-filtered-vector-search-rest-api.sh create mode 100644 modules/vector-search/pages/pre-filtering-vector-search.adoc 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..14fa90cff --- /dev/null +++ b/modules/vector-search/pages/pre-filtering-vector-search.adoc @@ -0,0 +1,64 @@ += 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: + +[horizontal] +Enhanced precision and relevance:: +allows searches to be narrowed down to results based on specific criteria (eg., organization, date/time ranges, geospatial locations.) + +Performance optimization:: +by reducing the search space before executing the queries, you can 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"`. +. Enter your username, password, and the Search Service endpoint on port `8094` with the name of the Vector Search index you want to query: + + +=== Example + +In the following example, you will extend a search query to employ a pre-filter to narrow the set of documents that the query will search over. + +[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[] From 0902b37dd5533491db34d001605f9026afcefb53 Mon Sep 17 00:00:00 2001 From: Ray Offiah Date: Wed, 6 Nov 2024 07:22:24 +0000 Subject: [PATCH 2/3] [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. --- .../pages/pre-filtering-vector-search.adoc | 22 +++++++++++++------ 1 file changed, 15 insertions(+), 7 deletions(-) diff --git a/modules/vector-search/pages/pre-filtering-vector-search.adoc b/modules/vector-search/pages/pre-filtering-vector-search.adoc index 14fa90cff..904593df1 100644 --- a/modules/vector-search/pages/pre-filtering-vector-search.adoc +++ b/modules/vector-search/pages/pre-filtering-vector-search.adoc @@ -10,12 +10,11 @@ Using pre-filtering as part of your vector search offers two key advantages: -[horizontal] -Enhanced precision and relevance:: -allows searches to be narrowed down to results based on specific criteria (eg., organization, date/time ranges, geospatial locations.) +. *Enhanced precision and relevance:* +Narrow your search results based on specific criteria, such as organization, date/time ranges, or geospatial locations. -Performance optimization:: -by reducing the search space before executing the queries, you can improve query execution time and reduce computational overhead. +. *Performance optimization:* +Reduce the search space before executing queries to improve query execution time and reduce computational overhead. == Prerequisites @@ -49,12 +48,21 @@ 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"`. -. Enter your username, password, and the Search Service endpoint on port `8094` with the name of the Vector Search index you want to query: +. Add your `username`, `password`, and the Search Service endpoint on port `8094`. +. Add the `index name` you wish 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 employ a pre-filter to narrow the set of documents that the query will search over. +In the following example, you will extend a search query +to find matches in `color-index`. +A pre-filter on the index will narrow the index entries searched over to those closely matching navy. [source, console] ---- From 065a208b0be6c6440533706de6e0ed2a25222067 Mon Sep 17 00:00:00 2001 From: Ray Offiah Date: Fri, 8 Nov 2024 11:54:02 +0000 Subject: [PATCH 3/3] [DOC-12609]: Document the extension to vector syntax to support pre-filtering: MB-62230 Fixups following review. --- modules/vector-search/pages/pre-filtering-vector-search.adoc | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/modules/vector-search/pages/pre-filtering-vector-search.adoc b/modules/vector-search/pages/pre-filtering-vector-search.adoc index 904593df1..0d133e918 100644 --- a/modules/vector-search/pages/pre-filtering-vector-search.adoc +++ b/modules/vector-search/pages/pre-filtering-vector-search.adoc @@ -49,7 +49,7 @@ 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 wish to query to the endpoint. +. Add the `index name` you want to query to the endpoint. [source, console] ---- @@ -62,7 +62,8 @@ curl -XPOST -H "Content-Type: application/json" \ In the following example, you will extend a search query to find matches in `color-index`. -A pre-filter on the index will narrow the index entries searched over to those closely matching navy. + 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] ----