Create a Vector Search Index in Quick Mode

how-to

Use Quick Mode to create a Vector Search index in Couchbase Capella.

Quick Mode works best when you need to create a basic Search index to start testing and prototyping with the Search Service. You must use Advanced Mode to have greater control over how the Search Service returns such results, such as changing your analyzer.

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

Vector Search indexes can include all the same features and settings as a Search index. For more information about Search indexes, see the Search documentation.

You must create a Vector Search index before you can run a search that supports vector comparisons.

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 a bucket with scopes and collections in your database. For more information, see Manage Buckets.

You have documents in a keyspace inside your bucket that contain vector embeddings.

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.

You have logged in to the Couchbase Capella UI.

Procedure

To create a Vector Search index with Quick Mode in Capella:

On the Databases page, select the database where you want to create a Search index.
Go to Data Tools Search.
Click Create Search Index.

By default, Quick Mode should be on.

In the Index Name field, enter a name for the Vector Search index.

Your index name must start with an alphabetic character (a-z or A-Z). It can only contain alphanumeric characters (a-z, A-Z, or 0-9), hyphens (-), or underscores (_).

For Couchbase Server version 7.6 and later, your index name must be unique inside your selected bucket and scope. You cannot have 2 indexes with the same name inside the same bucket and scope.

Under Type Mappings, in the Bucket list, select the bucket that contains the documents you want to include in your index.
In the Scope list, select the scope that contains these documents.
Expand the collection that contains these documents.
In your document schema, select the child field that contains your vector embeddings.

Vectors must be represented as an array of floating point numbers. They appear as {field-name} [ number ] in the Capella Quick Mode editor. The Search Service also supports arrays of arrays.
Configure the options for your new child field as follows:
1. In the Dimension field, check that the value matches the total number of elements in your vector field’s array.
  
  The Search Service supports arrays up to 2048 elements. Capella automatically fills in the dimension value for your selected array field.
2. In the Similarity metric list, select the method to use to calculate the similarity between search term and Search index vectors.
  
  For more information, see Quick Field Type Mapping Options.
3. In the Optimized for list, select whether the Search Service should optimize Search queries for accuracy (recall) or speed (latency).
  
  For more information, see Quick Field Type Mapping Options.
4. Select Index.
Click Submit.
(Optional) Add additional collections or child field type mappings to your index.

For example, you could add the text field that you used to generate your vector embeddings.
Click Create Index.

Example: Creating a Vector Search Index for Vector Search Query Examples

If you want to use the sample dataset for the examples in Run a Vector Search with the Capella UI and Run a Vector Search with a Couchbase SDK, then you can import the following Search index definition into Capella UI:

{
    "name": "color-test",
    "type": "fulltext-index",
    "params": {
     "doc_config": {
      "docid_prefix_delim": "",
      "docid_regexp": "",
      "mode": "scope.collection.type_field",
      "type_field": "type"
     },
     "mapping": {
      "default_analyzer": "standard",
      "default_datetime_parser": "dateTimeOptional",
      "default_field": "_all",
      "default_mapping": {
       "dynamic": true,
       "enabled": false
      },
      "default_type": "_default",
      "docvalues_dynamic": false,
      "index_dynamic": true,
      "store_dynamic": false,
      "type_field": "_type",
      "types": {
       "color.rgb": {
        "dynamic": false,
        "enabled": true,
        "properties": {
         "description": {
          "enabled": true,
          "dynamic": false,
          "fields": [
           {
            "name": "description",
            "type": "text",
            "store": true,
            "index": true,
            "include_term_vectors": true,
            "include_in_all": false,
            "docvalues": true
           }
          ]
         },
         "brightness": {
          "enabled": true,
          "dynamic": false,
          "fields": [
           {
            "docvalues": true,
            "index": true,
            "name": "brightness",
            "store": true,
            "type": "number"
           }
          ]
         },
         "color": {
          "enabled": true,
          "dynamic": false,
          "fields": [
           {
            "docvalues": true,
            "include_term_vectors": true,
            "index": true,
            "name": "color",
            "store": true,
            "type": "text"
           }
          ]
         },
         "colorvect_l2": {
          "enabled": true,
          "dynamic": false,
          "fields": [
           {
            "dims": 3,
            "index": true,
            "name": "colorvect_l2",
            "similarity": "l2_norm",
            "type": "vector",
            "vector_index_optimized_for": "recall"
           }
          ]
         },
         "embedding_vector_dot": {
          "enabled": true,
          "dynamic": false,
          "fields": [
           {
            "dims": 1536,
            "index": true,
            "name": "embedding_vector_dot",
            "similarity": "dot_product",
            "type": "vector",
            "vector_index_optimized_for": "recall"
           }
          ]
         }
        }
       }
      }
     },
     "store": {
      "indexType": "scorch",
      "segmentVersion": 16
     }
    },
    "sourceType": "gocbcore",
    "sourceName": "vector-sample",
    "sourceParams": {},
    "planParams": {
     "maxPartitionsPerPIndex": 1024,
     "indexPartitions": 1,
     "numReplicas": 0
    },
    "uuid": "42676f35cc30b84a"
   }

Make sure you imported the sample dataset with the recommended settings.

This Vector Search index has a type mapping for a color.rgb collection and includes the following fields:

The brightness number field, which is included in search results and supports sorting and faceting.
The color string and description string fields, which are included in search results, support highlighting, phrase matching, and sorting and faceting.
The colorvect_l2 [ number ] field, which has a Dimension of 3 and uses the l2_norm Similarity Metric.
The embedding_vector_dot [ number ] field, which has a dimension of 1536 and uses the dot_product Similarity Metric.

Next Steps

A basic Vector Search index includes the vector embeddings from the child field you specified in your type mapping. If you choose to add additional child fields and enable Include in search results, the Search Service can also return data from those child fields when you run a Vector Search query.

For more information about how to add additional child fields to your index, see Create a Search Index in Quick Mode or Create a Child Field in Advanced Mode.

You can customize your Vector Search index like any other Search index to add additional data and improve search results. For more information about how to customize an index, see Search Index Features.

Some Search index features are only available in Advanced Mode. If you edit your Search index in Advanced Mode, you cannot make any additional edits in Quick Mode without losing all Advanced Mode settings.

For more information about how to run a search against a Vector Search index, see Run a Vector Search with the Capella UI.