Claude Skill

api-vector-db-qdrant

Qdrant vector database -- collection management, point operations, payload filtering, named vectors, quantization, recommendations, snapshots

LLM Mart · 0 points · 1 views 0 listing impressions 0 install-command copies
Download agents-inc-skills-dist_plugins_api-vector-db-qdrant_skills_api-vector-db-qdrant-707467a.zip · 20 KB

Install

skills CLI npx skills add https://github.com/agents-inc/skills/tree/main/dist/plugins/api-vector-db-qdrant/skills/api-vector-db-qdrant
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install agents-inc-skills@llmmart
Git git clone https://github.com/agents-inc/skills.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole agents-inc/skills collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

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

(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

Additional resources:

  • 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)



<decision_framework>

Decision Framework

Which Distance Metric?

Which distance metric should I use?
|-- Using normalized embeddings (OpenAI, Cohere)? -> Cosine (most common, safe default)
|-- Pre-normalized embeddings and need speed? -> Dot (faster, same results as Cosine for unit vectors)
|-- Raw feature vectors where magnitude matters? -> Euclid (L2 distance)
|-- City-block distance needed? -> Manhattan
'-- Unsure? -> Cosine (works with any embedding model)

Single Vector vs Named Vectors?

How many embeddings per point?
|-- One embedding model? -> Single vector (simpler config)
|-- Multiple embedding models (title + content)? -> Named vectors
|-- Same model, different text segments? -> Named vectors
|-- Multi-modal (text + image)? -> Named vectors with different dimensions
'-- Want to avoid duplicating payloads across collections? -> Named vectors

Which Quantization Method?

How should I optimize memory?
|-- Good default, balanced accuracy/speed? -> Scalar (int8, 4x compression)
|-- Maximum speed, can tolerate accuracy loss? -> Binary (32x compression)
|   '-- Best with high-dimensional models (>= 1024 dims)
|-- Maximum compression, speed not critical? -> Product (up to 64x compression)
|   '-- Slowest quantization, most accuracy loss
'-- No memory pressure? -> Skip quantization (full float32 precision)

Payload Index Strategy?

Should I create a payload index?
|-- Field used in filter conditions? -> YES, always index
|-- Field used in order_by for scroll? -> YES, index for sort performance
|-- Field only read after search (display only)? -> NO, skip index
|-- High-cardinality field (UUIDs, timestamps)? -> YES, but evaluate index type
'-- Low-cardinality field (enum-like)? -> YES, keyword index is very efficient

</decision_framework>


<red_flags>

RED FLAGS

High Priority Issues:

  • Using Pinecone-style filter syntax ($eq, $and, $or) -- Qdrant uses must/should/must_not with match/range conditions
  • Vector dimension mismatch between embedding model and collection config -- causes silent failures or garbage results
  • Missing payload indexes on filtered fields -- causes full collection scans that degrade linearly with size
  • Not setting wait: true when read-after-write consistency is needed -- writes are async by default

Medium Priority Issues:

  • Using deprecated search() method instead of query() -- query() is the universal endpoint with prefetch and fusion support
  • Forgetting with_payload: true in queries -- payload is NOT included by default
  • Creating payload indexes after bulk upsert instead of before -- retroactive indexing is slower than indexing during upsert
  • Using offset for deep pagination in scroll -- performance degrades; use offset as cursor (point ID), not page number

Common Mistakes:

  • Passing filter at the wrong nesting level -- filter goes at the top level of the query args, not nested inside another object
  • Using id: 0 as a point ID -- Qdrant requires positive integers or UUID strings; 0 is invalid
  • Confusing setPayload (merge) with overwritePayload (replace) -- setPayload merges fields, overwritePayload replaces the entire payload
  • Calling deletePayload with field names but no point selector -- you must specify which points to update via points array or filter

Gotchas & Edge Cases:

  • Point IDs must be positive integers or UUID strings -- negative numbers, zero, and non-UUID strings are rejected
  • scroll() with order_by requires a payload index on the sort field -- without it, the request fails
  • count() with exact: true is slow on large collections -- use exact: false (default) for approximate counts
  • Snapshot recovery requires matching Qdrant minor versions -- a v1.14.x snapshot cannot be restored to a v1.15.x cluster
  • Binary quantization works best with high-dimensional vectors (>= 1024 dims) -- for smaller vectors, scalar quantization is more accurate
  • query() with prefetch enables multi-stage retrieval (retrieve 1000, then re-rank to top 10) -- but requires understanding the prefetch pipeline
  • Named vector search requires the using parameter -- omitting it searches the default (unnamed) vector, which may not exist
  • deletePayload removes specific keys, clearPayload removes ALL keys -- they are different operations

</red_flags>


<critical_reminders>

CRITICAL REMINDERS

(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)

Failure to follow these rules will cause empty search results, degraded filter performance, data consistency issues, and hard-to-debug dimension mismatch errors.

</critical_reminders>

Files (skills)
  • examples
    • core.md 10.4 KB
      Loading…
    • filtering.md 8.7 KB
      Loading…
    • named-vectors-quantization.md 8.7 KB
      Loading…
    • recommendations-batch.md 10.3 KB
      Loading…
  • reference.md 12.8 KB
    Loading…
  • SKILL.md 15.2 KB
    ---
    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
    
    **(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.
    
    ```typescript
    // 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, named export
    
    ```typescript
    // Bad Example
    import { QdrantClient } from "@qdrant/js-client-rest";
    const client = new QdrantClient({
      host: "my-cluster.cloud.qdrant.io",
      apiKey: "sk-abc123...",
    });
    // Hardcoded credentials leak in version control
    ```
    
    **Why bad:** Hardcoded API key, host without HTTPS (use `url` with full protocol for cloud)
    
    ---
    
    ### Pattern 2: Collection Creation
    
    Define vector dimensions and distance metric. Dimension must exactly match your embedding model output. See [examples/core.md](examples/core.md).
    
    ```typescript
    // Good Example
    const EMBEDDING_DIMENSION = 1536;
    
    await client.createCollection("documents", {
      vectors: {
        size: EMBEDDING_DIMENSION,
        distance: "Cosine",
      },
    });
    
    export { EMBEDDING_DIMENSION };
    ```
    
    **Why good:** Named constant for dimension, explicit distance metric, clean config
    
    ```typescript
    // Bad Example
    await client.createCollection("documents", {
      vectors: { size: 768, distance: "Cosine" },
      // Dimension mismatch if using a 1536-dim model -- upserts may silently fail or produce garbage search results
    });
    ```
    
    **Why bad:** Hardcoded dimension that may not match embedding model, no named constant
    
    ---
    
    ### Pattern 3: Upsert Points with Payload
    
    Upsert vectors with payload (Qdrant's term for metadata). See [examples/core.md](examples/core.md).
    
    ```typescript
    // Good Example
    interface DocumentPayload {
      title: string;
      category: string;
      createdAt: number;
      tags: string[];
    }
    
    await client.upsert("documents", {
      wait: true,
      points: [
        {
          id: "doc-1",
          vector: embedding,
          payload: {
            title: "Guide",
            category: "tutorial",
            createdAt: 1710000000,
            tags: ["ai", "search"],
          },
        },
      ],
    });
    ```
    
    **Why good:** Typed payload interface, `wait: true` for immediate consistency, structured payload
    
    ---
    
    ### Pattern 4: Query with Payload Filter
    
    Use `must`/`should`/`must_not` filter clauses -- NOT Pinecone-style `$eq`/`$and`. See [examples/filtering.md](examples/filtering.md).
    
    ```typescript
    // Good Example
    const TOP_K = 10;
    
    const results = await client.query("documents", {
      query: queryEmbedding,
      filter: {
        must: [
          { key: "category", match: { value: "tutorial" } },
          { key: "createdAt", range: { gte: 1700000000 } },
        ],
      },
      with_payload: true,
      limit: TOP_K,
    });
    
    for (const point of results.points) {
      console.log(point.id, point.score, point.payload);
    }
    ```
    
    **Why good:** Named constant for limit, Qdrant filter syntax (must + match/range), `with_payload` included
    
    ```typescript
    // Bad Example -- Pinecone syntax does NOT work in Qdrant
    const results = await client.query("documents", {
      query: embedding,
      filter: {
        $and: [{ category: { $eq: "tutorial" } }],
      },
      limit: 100,
    });
    ```
    
    **Why bad:** Pinecone-style `$and`/`$eq` operators are invalid in Qdrant, magic number for limit
    
    ---
    
    ### Pattern 5: Named Vectors
    
    Store multiple embeddings per point. See [examples/named-vectors-quantization.md](examples/named-vectors-quantization.md).
    
    ```typescript
    // Good Example
    const TITLE_DIM = 384;
    const CONTENT_DIM = 1536;
    
    await client.createCollection("articles", {
      vectors: {
        title: { size: TITLE_DIM, distance: "Cosine" },
        content: { size: CONTENT_DIM, distance: "Cosine" },
      },
    });
    
    // Upsert with named vectors
    await client.upsert("articles", {
      wait: true,
      points: [
        {
          id: "article-1",
          vector: { title: titleEmbedding, content: contentEmbedding },
          payload: { title: "Intro to Vectors" },
        },
      ],
    });
    
    // Search by specific named vector
    const results = await client.query("articles", {
      query: queryEmbedding,
      using: "content",
      limit: TOP_K,
    });
    ```
    
    **Why good:** Different dimensions per named vector, `using` specifies which vector to search, avoids duplicating payloads across collections
    
    ---
    
    ### Pattern 6: Recommendation API
    
    Find similar points using positive/negative examples. See [examples/recommendations-batch.md](examples/recommendations-batch.md).
    
    ```typescript
    // Good Example
    const results = await client.query("documents", {
      query: {
        recommend: {
          positive: [1, 42],
          negative: [7],
          strategy: "best_score",
        },
      },
      limit: TOP_K,
      with_payload: true,
    });
    ```
    
    **Why good:** Uses point IDs as positive/negative examples, `best_score` strategy handles negatives better than default `average_vector`
    
    </patterns>
    
    ---
    
    <decision_framework>
    
    ## Decision Framework
    
    ### Which Distance Metric?
    
    ```
    Which distance metric should I use?
    |-- Using normalized embeddings (OpenAI, Cohere)? -> Cosine (most common, safe default)
    |-- Pre-normalized embeddings and need speed? -> Dot (faster, same results as Cosine for unit vectors)
    |-- Raw feature vectors where magnitude matters? -> Euclid (L2 distance)
    |-- City-block distance needed? -> Manhattan
    '-- Unsure? -> Cosine (works with any embedding model)
    ```
    
    ### Single Vector vs Named Vectors?
    
    ```
    How many embeddings per point?
    |-- One embedding model? -> Single vector (simpler config)
    |-- Multiple embedding models (title + content)? -> Named vectors
    |-- Same model, different text segments? -> Named vectors
    |-- Multi-modal (text + image)? -> Named vectors with different dimensions
    '-- Want to avoid duplicating payloads across collections? -> Named vectors
    ```
    
    ### Which Quantization Method?
    
    ```
    How should I optimize memory?
    |-- Good default, balanced accuracy/speed? -> Scalar (int8, 4x compression)
    |-- Maximum speed, can tolerate accuracy loss? -> Binary (32x compression)
    |   '-- Best with high-dimensional models (>= 1024 dims)
    |-- Maximum compression, speed not critical? -> Product (up to 64x compression)
    |   '-- Slowest quantization, most accuracy loss
    '-- No memory pressure? -> Skip quantization (full float32 precision)
    ```
    
    ### Payload Index Strategy?
    
    ```
    Should I create a payload index?
    |-- Field used in filter conditions? -> YES, always index
    |-- Field used in order_by for scroll? -> YES, index for sort performance
    |-- Field only read after search (display only)? -> NO, skip index
    |-- High-cardinality field (UUIDs, timestamps)? -> YES, but evaluate index type
    '-- Low-cardinality field (enum-like)? -> YES, keyword index is very efficient
    ```
    
    </decision_framework>
    
    ---
    
    <red_flags>
    
    ## RED FLAGS
    
    **High Priority Issues:**
    
    - Using Pinecone-style filter syntax (`$eq`, `$and`, `$or`) -- Qdrant uses `must`/`should`/`must_not` with `match`/`range` conditions
    - Vector dimension mismatch between embedding model and collection config -- causes silent failures or garbage results
    - Missing payload indexes on filtered fields -- causes full collection scans that degrade linearly with size
    - Not setting `wait: true` when read-after-write consistency is needed -- writes are async by default
    
    **Medium Priority Issues:**
    
    - Using deprecated `search()` method instead of `query()` -- `query()` is the universal endpoint with prefetch and fusion support
    - Forgetting `with_payload: true` in queries -- payload is NOT included by default
    - Creating payload indexes after bulk upsert instead of before -- retroactive indexing is slower than indexing during upsert
    - Using `offset` for deep pagination in scroll -- performance degrades; use `offset` as cursor (point ID), not page number
    
    **Common Mistakes:**
    
    - Passing `filter` at the wrong nesting level -- filter goes at the top level of the query args, not nested inside another object
    - Using `id: 0` as a point ID -- Qdrant requires positive integers or UUID strings; 0 is invalid
    - Confusing `setPayload` (merge) with `overwritePayload` (replace) -- `setPayload` merges fields, `overwritePayload` replaces the entire payload
    - Calling `deletePayload` with field names but no point selector -- you must specify which points to update via `points` array or `filter`
    
    **Gotchas & Edge Cases:**
    
    - Point IDs must be positive integers or UUID strings -- negative numbers, zero, and non-UUID strings are rejected
    - `scroll()` with `order_by` requires a payload index on the sort field -- without it, the request fails
    - `count()` with `exact: true` is slow on large collections -- use `exact: false` (default) for approximate counts
    - Snapshot recovery requires matching Qdrant minor versions -- a v1.14.x snapshot cannot be restored to a v1.15.x cluster
    - Binary quantization works best with high-dimensional vectors (>= 1024 dims) -- for smaller vectors, scalar quantization is more accurate
    - `query()` with `prefetch` enables multi-stage retrieval (retrieve 1000, then re-rank to top 10) -- but requires understanding the prefetch pipeline
    - Named vector search requires the `using` parameter -- omitting it searches the default (unnamed) vector, which may not exist
    - `deletePayload` removes specific keys, `clearPayload` removes ALL keys -- they are different operations
    
    </red_flags>
    
    ---
    
    <critical_reminders>
    
    ## CRITICAL REMINDERS
    
    **(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)**
    
    **Failure to follow these rules will cause empty search results, degraded filter performance, data consistency issues, and hard-to-debug dimension mismatch errors.**
    
    </critical_reminders>
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.