cockroachdb / cockroachdb/docs

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

Ouverte
#23,456 0 commentaires 0 réactions 0 personnes assignées Voir sur GitHub
Langage dominant
HTML
Étoiles
212
Forks
476
Merge moyen
40 min
PR mergées (30 j)
3

Description

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

Guide de contribution

Aucun guide de contribution indexé pour ce dépôt

Évaluation

Cette issue n'a pas encore été évaluée.

Recevez les nouvelles issues par e-mail

Un résumé court des issues GitHub adaptées aux débutants.