/api-vector-db-qdrant

name: api-vector-db-qdrant
description: Qdrant vector database -- collection management, point operations, payload filtering, named vectors, quantization, recommendations, snapshots

Qdrant Patterns

> **Quick Guide:** Use `@qdrant/js-client-rest` (v1.17.x) for high-performance vector search. Collections define vector dimensions and distance metrics upfront -- mismatches cause silent failures. Use `must`/`should`/`must_not` filter clauses with payload conditions (not Pinecone-style `$eq`/`$and`). Payload indexes are optional but critical for filter performance at scale -- create them explicitly with `createPayloadIndex()`. Named vectors let you store multiple embeddings per point (e.g., title + content). Quantization (scalar/binary/product) trades accuracy for memory and speed. The `query()` method is the universal search endpoint -- prefer it over the older `search()` method.

---

<critical_requirements>

CRITICAL: Before Using This Skill

> **All code must follow project conventions in CLAUDE.md** (kebab-case, named exports, import ordering, `import type`, named constants)

**(You MUST create payload indexes with `createPayloadIndex()` for any field used in filters -- unindexed fields cause full scans that degrade linearly with collection size)**

**(You MUST use `must`/`should`/`must_not` filter syntax -- Qdrant does NOT use `$eq`/`$and`/`$or` operators like Pinecone)**

**(You MUST match vector dimensions exactly between embedding model output and collection config -- dimension mismatches cause silent upsert failures or corrupt search results)**

**(You MUST set `wait: true` on writes when subsequent reads depend on the data -- Qdrant writes are asynchronous by default and may not be immediately visible)**

</critical_requirements>

---

Examples

• [Core Patterns](examples/core.md) -- Client setup, collection creation, upsert, query, scroll, delete
• [Filtering](examples/filtering.md) -- must/should/must_not conditions, match/range operators, payload indexes
• [Named Vectors & Quantization](examples/named-vectors-quantization.md) -- Multiple vectors per point, scalar/binary/product quantization
• [Recommendations & Batch](examples/recommendations-batch.md) -- Recommend API, batch operations, snapshots

**Additional resources:**

• [reference.md](reference.md) -- API quick reference, filter operators, limits, decision frameworks, production checklist

---

**Auto-detection:** Qdrant, QdrantClient, @qdrant/js-client-rest, createCollection, upsert, query, scroll, recommend, setPayload, createPayloadIndex, must, should, must_not, payload, named vectors, quantization, vector database, similarity search, semantic search, RAG retrieval, embedding search

**When to use:**

• Semantic search over document embeddings (RAG retrieval pipelines)
• Similarity search for recommendations, deduplication, or classification
• Multi-vector search with named vectors (e.g., title embedding + content embedding per document)
• Filtered vector search with complex payload conditions (must/should/must_not)
• Memory-optimized deployments using scalar, binary, or product quantization

**Key patterns covered:**

• Client setup and collection management (distance metrics, HNSW config)
• Point CRUD operations (upsert, query, scroll, retrieve, delete, count)
• Payload filtering with must/should/must_not and match/range conditions
• Named vectors for multiple embeddings per point
• Quantization configuration (scalar, binary, product)
• Recommendation API with positive/negative examples
• Batch operations and snapshot management
• Payload indexing for filter performance

**When NOT to use:**

• Full-text search with BM25 ranking (use a dedicated search engine)
• Relational data with joins and transactions (use a relational database)
• Key-value lookups without vector similarity (use a KV store)
• Storing large documents or binary blobs (store embeddings + metadata references only)

---

<philosophy>

Philosophy

Qdrant is a **high-performance open-source vector database** built in Rust, designed for filtered similarity search at scale. The core principle: **store vectors with rich payloads, search by similarity, filter by payload conditions.**

**Core principles:**

1. **Payload is first-class** -- Unlike databases that treat metadata as secondary, Qdrant's payload system supports complex nested JSON, multiple data types, and granular indexing. Use payloads for filtering, not just annotation. 2. **Index what you filter** -- Payload indexes are not automatic. Create explicit indexes on fields used in filters via `createPayloadIndex()`. Without indexes, filters cause full collection scans. 3. **Named vectors for multi-modal** -- A single point can hold multiple named vectors (e.g., title embedding + content embedding). Search targets a specific named vector. This avoids duplicating payloads across collections. 4. **Quantization for scale** -- Scalar (4x compression), binary (32x), and product quantization trade accuracy for memory savings. Configure at collection or per-vector level. Use `always_ram: true` to keep quantized vectors in memory for speed. 5. **Writes are async by default** -- Upserts return before data is persisted to all replicas. Set `wait: true` when immediate consistency matters (e.g., read-after-write flows).

</philosophy>

---

<patterns>

Core Patterns

Pattern 1: Client Initialization

Create a QdrantClient connected to a local instance or Qdrant Cloud. See [examples/core.md](examples/core.md) for full examples.

// Good Example
import { QdrantClient } from "@qdrant/js-client-rest";

function createQdrantClient(): QdrantClient {
  const url = process.env.QDRANT_URL;
  const apiKey = process.env.QDRANT_API_KEY;
  if (!url) {
    throw new Error("QDRANT_URL environment variable is required");
  }
  return new QdrantClient({ url, apiKey });
}

export { createQdrantClient };

**Why good:** URL and API key from environment, validation before construction, n