Run a Vector Search with the REST API and curl/HTTP
- how-to
You can use the REST API and a curl command to run a search against a Vector Search index and return similar vectors.
For more information about how the Search Service scores documents in search results, see Scoring for Search Queries.
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 Manage Nodes and Clusters.
-
You have a bucket with scopes and collections in your database. For more information about how to create a bucket, see Create a Bucket.
-
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 List Cluster Nodes.
-
You have created a Vector Search index.
For more information about how to create a Vector Search index, see Create a Vector Search Index with the Server Web Console or Create a Vector Search Index with the REST API and curl/HTTP.
You can download a sample dataset to use with the procedure or examples on this page:
To get the best results with using the sample data with the examples in this documentation, import the sample files from the dataset into your database with the following settings:
-
Use a bucket called
vector-sample
. -
Use a scope called
color
. -
Use a collection called
rgb
forrgb.json
. -
To set your document keys, use the value of the
id
field from each JSON document.
For the best results, consider using the sample Vector Search index from Create a Vector Search Index with the Server Web Console or Create a Vector Search Index with the REST API and curl/HTTP.
-
Procedure
To run a Vector search with the REST API:
-
In your command-line tool, enter a
curl
command with theXPOST
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:curl -s -XPUT -H "Content-Type: application/json" \ -u ${CB_USERNAME}:${CB_PASSWORD} http://${CB_HOSTNAME}:8094/api/bucket/${BUCKET_NAME}/scope/${SCOPE_NAME}/index/${INDEX_NAME}/query -d \
To use SSL, use the
https
protocol in the Search Service endpoint URL and port18094
. -
Enter the JSON payload for your query.
You can copy the JSON for a Query Request from the Couchbase Server Web Console to use in your REST API call. For more information about how to perform a search with the UI, see Run A Simple Search with the Web Console.
Example
In the following example, the JSON payload uses both a query
and knn
object to run both a Vector Search and traditional Search query on an index named color-index
.
The query searches for a specified Euclidean distance color vector, but uses the query
object to search for a color with a brightness
value in the range of 70-80
:
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 ]
}
]
}'
The Search Service combines the Vector search results from the knn
object with the traditional query
object by using an OR
function.
If the same documents match the knn
and query
objects, the Search Service ranks those documents higher in search results.
For a more complex query, you can copy the query object from the example under Example: Running a Semantic Search Query with a Large Embedding Vector to use in your REST API call.
|
For more information about the available properties for a Search query JSON payload, see Search Request JSON Properties.
Next Steps
If you do not get the search results you were expecting, you can change the JSON definition for your Search index or change the parameters for your Search query.
You can also Customize a Search Index with the Web Console.