Run A Vector Search with the Server Web Console

how-to

Run a Vector Search query from the Couchbase Server Web Console to preview and test the search results from a Vector Search index.

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 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.

You can download a sample dataset to use with the procedure or examples on this page:

Download color_data_2vectors.zip

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 for rgb.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.

You have logged in to the Couchbase Server Web Console.

Procedure

To run a Vector Search with the Couchbase Server Web Console:

Go to Search.
Click the index where you want to run a search.
In the Search this index field, enter a search query.
Press Enter or click Search.

Example: Running a Simple Vector Similarity Query

For example, the following query searches for the top 2 vectors similar to the vector [ 0, 0, 128 ] in the colorvect_l2 field:

{
    "fields": ["*"], 
    "query": { 
      "match_none": ""
    }, 
    "knn": [
      {
        "k": 2, 
        "field": "colorvect_l2", 
        "vector": [ 0, 0, 128 ]
      }
    ]
}

By using the special match_none query in the query field, the Search query is only a Vector Search query. It only returns the k number of similar vectors.

The Search Service combines the Vector search results from a 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.

The document for the color navy should be the first result, followed by a similar color.

Example: Running a Simple Hybrid Search Query

The following hybrid Search query searches for the top vector similar to the vector [ 0, 0, 128 ] in the colorvect_l2 field. It also runs a Numeric Range Query on the brightness field to only return colors that have a brightness value between 70 and 80:

{
    "fields": ["*"], 
    "query": { 
      "min": 70,
      "max": 80,
      "inclusive_min": false,
      "inclusive_max": true,
      "field": "brightness"
    }, 
    "knn": [
      {
        "k": 1, 
        "field": "colorvect_l2", 
        "vector": [ 0, 0, 128 ]
      }
    ]
}

The document for the color navy should be the first result, followed by colors that are similar and match the brightness field query.

Example: Running a Semantic Search Query with a Large Embedding Vector

The following query searches for matches to a large embedding vector, generated by the OpenAI embedding model, text-embedding-ada-002-v2.

You can find generated embedding vectors for each color’s description field in rgb.json.

This query should return the document for the color navy, based on a generated embedding vector for:

What is a classic, refined hue that exudes elegance and is often linked to power and stability?

The following shows part of the sample Search query:

{
    "fields": ["*"],
    "knn": [
      {
        "field": "embedding_vector_dot",
        "k": 3,
        "vector": [
          0.024032991379499435,
          -0.009131478145718575,
          0.013961897231638432,
          -0.024734394624829292,
          -0.020605377852916718,
          0.006739427801221609,
          -0.012539239600300789,
          0.0063192471861839294,
          0.000004374724539957242,
          -0.030252983793616295,
          -0.010944539681077003,
          -0.0012845275923609734,
          0.0059850881807506084,
          -0.006388725712895393,
          -0.016304319724440575,
          0.03046472743153572,
          0.029988301917910576,
          -0.013121536932885647,
          0.01815708354115486,
          -0.011096730828285217,
          -0.0423753522336483,
          -0.0023523480631411076,
          -0.00022332418302539736,
          -0.0024681459181010723,
          -0.02911485731601715,

Due to the size of the embedding vector, only part of the full query is being displayed in the documentation.

Click View on GitHub to view and copy the entire Vector Search query payload. Make sure you remove the lines for // tag::partial[] and // end::partial[].

Next Steps

If you do not get the search results you were expecting, you can change the JSON payload for your Search query.

You can also customize your Search index with additional features.

Either of the example queries on this page can also be used with the REST API to run a search.