Skip to main content
A vector index enables efficient approximate nearest neighbor (ANN) search on high-dimensional columns. Use vector indexes to improve the performance of similarity searches over large datasets, such as embeddings generated by machine learning models. This page describes how to create and use vector indexes on CockroachDB.
VECTOR functionality is compatible with the pgvector extension for PostgreSQL.

​
How do vector indexes work?

CockroachDB vector indexes organize into a hierarchical structure of partitions using k-means clustering. This partition structure groups similar vectors together and enables efficient, tunable ANN searches. When a query uses a vector index, CockroachDB explores a subset of partitions based on their proximity to the query vector. It then retrieves and evaluates a candidate set of vectors using the configured distance metric and returns the top nearest results.

​
Enable vector indexes

To enable the use of vector indexes, set the feature.vector_index.enabled :
To enable the creation of vector indexes on non-empty tables, also disable the sql_safe_updates . This allows vector indexes to be backfilled on existing rows, during which table writes are blocked to ensure vector index consistency. This blocking behavior is a known limitation that is currently being tracked.
Adding a vector index to a non-empty table can temporarily disrupt workloads that perform continuous writes.

​
Create vector indexes

To create a vector index, use the statement:
You can also specify a vector index during table creation. For example:

​
Define prefix columns

You can create a vector index with one or more prefix columns to pre-filter the search space. This is especially useful for tables containing millions of vectors or more.
A vector index is only used if each prefix column is constrained to a specific value in the query. For example:
You can filter on multiple prefix values using IN:
The following example will not use the vector index:
For an example, refer to Create and query a vector index.

​
Specify an opclass

When you create a vector index, you can specify an operator class (opclass) that tells the index which VECTOR distance metric to accelerate. The following opclasses are available:
  • vector_l2_ops (default): Accelerate queries that use the L2 distance operator .
  • vector_cosine_ops: Accelerate queries that use the cosine distance operator .
  • vector_ip_ops: Accelerate queries that use the negative inner product operator .
If not specified, vector_l2_ops is used by default. To accelerate cosine or inner-product searches, specify the corresponding opclass when you create the vector index. For an example, to build a cosine-optimized index:

​
Comparisons

Vector indexes on VECTOR columns support the following comparison operators. Whether an operator is accelerated depends on the opclass that you specified upon index creation.
  • L2 distance ( ): Use when you want the true geometric distance, such as in spatial or physical models where absolute positioning matters.
  • Cosine distance ( ): Use when you only care about directional similarity, like in semantic text matching or clustering. Ideal for retrieval-augmented generation (RAG) use cases involving pretrained embedding models that either normalize vectors or are trained with a cosine similarity loss.
  • Negative inner product ( ): Use when both the magnitude and direction of vectors matter, such as in scoring or preference modeling.
Operators are used in the clause when ranking results by vector similarity. Refer to the Example.

​
Tune vector indexes

The following vector index parameters are tunable:
  • Search beam size, using vector_search_beam_size
  • Partition size, using min_partition_size and max_partition_size
  • Build beam size, using build_beam_size (not recommended)
For guidelines on how these parameters affect search accuracy and write performance, refer to Tuning considerations. Set the following storage parameters when you create a vector index:
  • min_partition_size: Minimum number of vectors in a partition before it is merged with another partition. This value must be greater than or equal to 1, up to a maximum of 1024. The default value is 16.
  • max_partition_size: Maximum number of vectors in a partition before it is split into smaller partitions. This must be at least 4 times the value of min_partition_size, up to a maximum of 4096. The default value is 128.
  • build_beam_size: Beam size for index build (how many branches of the k-means tree are explored when assigning a vector to a partition). The default value is 8. Cockroach Labs does not recommend changing this setting. It is more effective to increase vector_search_beam_size.
For example, the following statement creates a vector index with a custom partition size:
Set the to determine how many vector partitions will be considered during query execution. The default value is 32, which represents the number of partitions that are explored at each level of the k-means tree. For example:

​
Tuning considerations

Partition size and beam size interact to control both the precision of nearest neighbor search and the cost of maintaining the index. You can improve the accuracy of vector searches by increasing either the search beam size or partition size:
  • A larger search beam size improves accuracy by exploring more partitions, which increases the number of candidate vectors evaluated.
  • A larger partition size improves accuracy by placing more vectors in each partition, which increases the number of candidate vectors retrieved for a given beam size. It also improves write performance by reducing the frequency of partition splits and merges.
In both cases, read latency and CPU usage increase with size.
Changing build_beam_size offers little to no practical benefit compared to adjusting vector_search_beam_size. In most cases, tuning build_beam_size will not yield meaningful accuracy improvements and can negatively impact index construction performance.

​
Search accuracy

To explore more partitions during a search, increase vector_search_beam_size. This improves search accuracy by evaluating more of the index, but increases CPU usage and read latency because more partitions are scanned. To group more vectors into each partition, increase the partition size with min_partition_size and max_partition_size. This improves search accuracy by causing more candidate vectors to be evaluated per partition. However, it increases CPU usage and increases read latency because each partition contains more vectors. For the same reason, you can often reduce vector_search_beam_size without sacrificing accuracy. Search accuracy is highly dependent on workload factors such as partition size, the number of VECTOR dimensions, how well the embeddings reflect semantic similarity, and how vectors are distributed in the dataset. Experiment with vector_search_beam_size, min_partition_size, and max_partition_size on a representative dataset to find the optimal setting for your workload.
You can improve search accuracy for filtered queries by creating a vector index with a prefix column.

​
Write performance

Because a larger partition size leads to fewer partition splits and merges, it enables faster insert performance. To optimize writes, increase the partition size with min_partition_size and max_partition_size. A larger partition size leads to fewer partition splits and merges, resulting in faster insert performance. Large batch inserts of types can cause performance degradation. When inserting vectors, batching should be avoided. For an example, refer to .

​
Example

In the following example, a vector index with a prefix column is used to optimize searches on a VECTOR column in 512 dimensions. The example table is populated with 156,541 example rows, using a Python script to quickly insert the vectors.

​
Before you begin

  • Create a virtual python3 environment and install psycopg[binary]:
  • Download the Python script and sample data:
    Ensure that the .py and .csv files are located in the same directory.

​
Create and query a vector index

  1. Start a single-node cluster:
  2. In a separate terminal, open a SQL shell on the cluster:
  3. Enable vector indexes on the cluster:
  4. Create an items table that includes a VECTOR column called embedding, along with a vector index that uses customer_id as the prefix column:
  5. In another terminal, run the Python script to insert the clip_embeddings_with_customers.csv data into the items table:
    This process should take approximately 5-10 minutes.
  6. When the script is finished executing, verify that items is populated:
  7. Perform a vector search using the <-> L2 distance operator. Include the WHERE clause to query only the vectors associated with a given customer_id, thus narrowing the vector search space:
  8. Use EXPLAIN to show how the vector index pre-filtered the vector search space:
    In the preceding output, prefix spans: [/1 - /1] shows that the search is limited to the part of the index where customer_id = 1.

​
Known limitations

  • Large batch inserts of types can cause performance degradation. When inserting vectors, batching should be avoided. For an example, refer to .
  • IMPORT INTO is not supported on tables with vector indexes. You can import the vectors first and create the index after import is complete.
  • The distance functions vector_l1_ops, bit_hamming_ops, and bit_jaccard_ops are not implemented.
  • Index acceleration with filters is only supported if the filters match prefix columns.
  • Index recommendations are not provided for vector indexes.

​
See also