Run a Vector Search with the Capella UI

how-to

Run a Vector Search query from the Couchbase Capella UI 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 change Services on your database, see Modify a Database.

You have created a Vector Search index.

For more information about how to create a Vector Search index, see Create a Vector Search Index in Quick Mode.

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 in Quick Mode.

You have logged in to the Couchbase Capella UI.

Procedure

To run a Vector Search with the Capella UI:

On the Databases page, select the database where you created your Search index.
Go to Data Tools Search.
Next to your Vector Search index, click Search.
In the Search field, enter a search query.
Press Enter or click Search.
. (Optional) To view a document and its source collection, click a document name in the search results list.

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 add additional features to your Search index.