Skip to content

docs: clarify default operator class for vector indexing (CREATE VECTOR INDEX defaults to vector_l2_ops) #23456

Description

@dj-Majelanx

Documentation Clarification: Vector Index Operator Class Defaults

Summary

When creating vector indexes in CockroachDB (v26.2+ pgvector compatibility), \CREATE VECTOR INDEX\ without an explicit operator class defaults to \�ector_l2_ops\ (Euclidean distance). Queries using cosine distance (<=>), which is the standard distance metric for normalized text embeddings (e.g., OpenAI, Amazon Titan, Cohere), bypass index acceleration and fall back to sequential scans unless \�ector_cosine_ops\ is explicitly specified at index creation time.

Observed Behavior & Query Plan

\\sql
-- 1. Table and vector index created without explicit opclass:
CREATE TABLE document_embeddings (
doc_id STRING PRIMARY KEY,
embedding VECTOR(1024)
);
CREATE VECTOR INDEX idx_doc_embeddings ON document_embeddings (embedding);

-- 2. Query using cosine distance (<=>)
EXPLAIN SELECT doc_id FROM document_embeddings ORDER BY embedding <=> ::VECTOR LIMIT 4;
-- Query plan: sequential table scan + top-k sort (index bypassed).

-- 3. Correct index declaration:
DROP INDEX idx_doc_embeddings;
CREATE VECTOR INDEX idx_doc_embeddings_cosine ON document_embeddings (embedding vector_cosine_ops);

EXPLAIN SELECT doc_id FROM document_embeddings ORDER BY embedding <=> ::VECTOR LIMIT 4;
-- Query plan: IVFFlat / vector index scan.
\\

Suggested Documentation Update

On the Vector Search and Index documentation pages, explicitly advise users that:

  • Default operator class is \�ector_l2_ops\ (L2 / Euclidean distance <->).
  • If querying with cosine distance (<=>), \�ector_cosine_ops\ must be declared: \CREATE VECTOR INDEX idx_name ON table (col vector_cosine_ops);.
  • If querying with inner product (<#>), \�ector_ip_ops\ must be declared.

Jira issue: DOC-18578

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions