cockroachdb / cockroachdb/docs
docs: clarify default operator class for vector indexing (CREATE VECTOR INDEX defaults to vector_l2_ops)
- 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.