qdrant avatar

qdrant

Agent skills for Qdrant vector search

GitHub stars
270

Install

/plugin install qdrant@qdrant

Run it inside Claude Code after adding the marketplace with /plugin marketplace add qdrant/skills.

Contents

Discovered from source

Skills 14

Qdrant Clients SDK

Qdrant has the following officially supported client SDKs:

API Reference

All interaction with Qdrant can happen through the REST API or gRPC API. We recommend using the REST API if you are using Qdrant for the first time or working on a prototype.

Code examples

To obtain code examples for a specific client and use case, you can send a search request to the library of curated code snippets for the Qdrant client.

curl -X GET "https://skills.qdrant.tech/snippets/search?language=python&query=how+to+upload+points"

Available languages: python, typescript, rust, java, go, csharp

Each result is a markdown section with the client, the source page, a short description, and the code:

## Snippet 1

*qdrant-client* (vlatest) — <source page URL>

<what the snippet does and which options it uses>

<code block>

Default response format is markdown, if snippet output is required in JSON format, you can add &format=json to the query string.

Which Qdrant Deployment Do I Need?

Start with what you need: managed ops or full control? Network latency acceptable or not? Production or prototyping? The answer narrows to one of four options.

Getting Started or Prototyping

Use when: building a prototype, running tests, CI/CD pipelines, or learning Qdrant.

  • Use local mode (Python only): zero-dependency, in-memory or disk-persisted, no server needed Local mode
  • Local mode data format is NOT compatible with server. Do not use for production or benchmarking.
  • For a real server locally, use Docker Quick start

Going to Production (Self-Hosted, You Own Ops)

Use when: you need full control over infrastructure or custom configuration, and are prepared to own operations (upgrades, backups, scaling, monitoring) yourself.

  • Docker is the standard self-hosted deployment. Full Qdrant Open Source feature set, minimal setup. Quick start
  • You own operations: upgrades, backups, scaling, monitoring
  • Must set up distributed mode manually for multi-node clusters Distributed deployment
  • Have a data-residency or compliance requirement but don't want to own that ops burden? That combination is Hybrid Cloud (next section), not self-hosted Docker.

Going to Production (Zero-Ops)

Use when: you want managed infrastructure with rolling updates (zero-downtime on multi-node clusters where every collection has a replication factor of 2 or more), automatic backups, and resharding without operating clusters yourself — including when data-residency or compliance rules mean the data can't sit on Qdrant-operated infrastructure.

  • Qdrant Cloud handles upgrades, scaling, backups, and monitoring Qdrant Cloud
  • Chose Qdrant Cloud? See the Managed Cloud quickstart skill to create and connect your first cluster.
  • Hybrid Cloud: the same managed control plane, deployed on your own infrastructure/VPC. Use this when data residency or compliance requirements rule out Qdrant Cloud but you still don't want to operate clusters yourself Hybrid Cloud
  • Supports multi-version upgrades automatically
  • Provides features not available in self-hosted: /sys_metrics, managed resharding, pre-configured alerts

Need Lowest Possible Latency

Use when: network round-trip to a server is unacceptable. Edge devices, in-process search, or latency-critical applications.

  • Qdrant EDGE: in-process bindings to Qdrant shard-level functions, no network overhead Qdrant EDGE
  • Same data format as server. Can sync with server via shard snapshots.
  • Single-node feature set only. No distributed mode.
  • Chose EDGE and want to build on it? See the qdrant-edge skill (BM25, snapshot sync, hybrid queries).

What NOT to Do

  • Use local mode for production or benchmarking (not optimized, incompatible data format)
  • Self-host without monitoring and backup strategy (you will lose data or miss outages)
  • Recommend self-managed Docker as the production target when the user says they don't want to operate clusters — that combination needs Qdrant Hybrid Cloud or Qdrant Managed Cloud, not self-hosted
  • Choose EDGE when you need distributed search (single-node only)
  • Pick Hybrid Cloud unless you have data residency requirements (unnecessary Kubernetes complexity when Qdrant Cloud works)

Building on Qdrant Edge

Edge is the Qdrant engine embedded in your process (Python or Rust), not a thin local vector store to wrap. The failure mode is rebuilding what the shard already ships: keyword scoring, snapshot apply, faceting, counting. Before writing any of that, check the shard API. One thing Edge does NOT give you is a one-call cloud sync, so knowing what is built in keeps you from both reinventing built-ins and expecting capabilities Edge lacks. Edge is single-node and shares the server's data format.

  • Edge is in beta: pin your version, the API drifts between releases Qdrant Edge.

Syncing a Shard with a Qdrant Server

Use when: seeding a shard from a server, keeping it fresh, backing it up, or aggregating many devices into one collection.

There is no built-in .sync(). Sync is a pattern you assemble from shard helpers plus your own transport, so do not go looking for one call.

  • Follow the documented dual-shard pattern: a mutable shard for local writes plus an immutable shard restored from a server snapshot, query both, refresh on a schedule Edge synchronization guide.
  • You write the snapshot download (plain HTTP to the shard snapshot endpoint), then apply it with unpack_snapshot and update_from_snapshot. Do not untar or merge segments by hand Synchronization patterns.
  • Refresh incrementally with a partial snapshot built from snapshot_manifest, not a full snapshot every cycle Synchronization patterns.
  • Push is your own dual-write: on each local upsert, enqueue the point and let a background worker upsert it to the server, buffering while offline Synchronization patterns.

Keyword and Hybrid Search on Device

Use when: you need exact-term or BM25 matching, alone or alongside vectors.

  • BM25 is built into Edge: create a full-text index with scoring enabled on the payload field (with the stemmer and stopwords for your language) and rank with a TextQuery. It needs no embedding model and derives document lengths from your data. Do not ship a second BM25 library Edge BM25
  • Need sparse BM25 vectors instead, for example to match a server collection that uses sparse vector BM25? Edge's BM25 embedder (Bm25 in Python, EdgeBm25 in Rust) produces server-compatible sparse vectors: embed_document for documents, embed_query for queries Edge BM25
  • Dense embeddings are NOT in Edge: generate them on device with the separate fastembed package FastEmbed embeddings
  • For hybrid search, run the dense and keyword legs as prefetches (a TextQuery, or a sparse vector query) and fuse them with a Fusion query in a single query call, instead of combining rankings in application code Reading data

Operating the Shard

Use when: writes have accumulated, search is slow after inserts, or a backup is larger than the data.

  • Edge has NO background optimizer. Call optimize after bulk writes: it builds indexes and reclaims deleted points. Until then, new points are searched by brute force Edge quickstart
  • Faceting, counting, and enumeration are built in (facet, count, scroll); index the fields you filter or facet with create_field_index rather than aggregating in application code Edge quickstart
  • The write-ahead log is pre-allocated to 32 MB and inflates apparent disk and backup size. Shrink it with wal_options (Rust), and do not treat raw file size as real usage Edge quickstart

What NOT to Do

  • Expect a bidirectional .sync() or a built-in push path: Edge gives you snapshot apply, you own the transport and the dual-write
  • Untar or merge snapshot segments by hand instead of using unpack_snapshot and update_from_snapshot
  • Ship a custom or third-party BM25 when Edge has one built in
  • Run a TextQuery on a full-text index created without scoring: BM25 ranking needs it enabled
  • Use the BM25 embedder's embed_document for queries or embed_query for documents: the weighting differs and results go wrong
  • Combine dense and keyword rankings in application code: Edge query accepts prefetches and fuses them with a Fusion query
  • Assume a background optimizer like the server's: nothing is indexed or compacted until you call optimize
  • Reach for Edge when you need distributed or multi-node search: it is single-node Qdrant Edge
  • Claim support for a language beyond Python and Rust, or an OS or accelerator the Edge docs do not state

Setting Up Qdrant Hybrid Cloud

You've already chosen Hybrid Cloud (managed control plane on your own infra). If you're still deciding, that's the qdrant-deployment-options skill. Most setup failures trace to one of two things: storage (the CSI driver can't do what Qdrant needs) or connectivity (the agent can't reach Qdrant Cloud). Diagnose which before touching anything else.

Preparing the Kubernetes cluster (do this first)

Use when: about to create the environment, or the install/cluster provisioning failed on storage.

  • Qdrant needs a block-storage CSI driver. Network storage (NFS) and object storage (S3) are unsupported: a cluster wired to those will fail, not degrade Prerequisites.
  • Create the StorageClass (with allowVolumeExpansion: true) and the VolumeSnapshotClass beforehand, not after. Without volume expansion you can't grow disk later; without a VolumeSnapshotClass and the CSI snapshot controller you can't take backups.
  • Any standards-compliant Kubernetes works; check the Deployment Platforms page for your managed provider's setup guidance.
  • Platform matters for what storage supports: some (e.g. Linode/LKE, Vultr) don't support CSI volume snapshots at all, so backups are unavailable there. Check your provider's snapshot page and prefer its recommended instance and disk types (e.g. gp3 on EKS, Premium SSD v2 on AKS) before committing.
  • Confirm outbound connectivity: the agent opens connections to grpc.cloud.qdrant.io and api.cloud.qdrant.io on 443. Firewalls/egress proxies block this silently: a "stuck installing" agent is usually this.
  • You need cluster-admin plus kubectl and helm configured against the target cluster.

Creating the environment

Use when: running the install wizard in the Cloud Console.

  • The Kubernetes namespace is permanent: it's the one choice you can't change later. Everything else (node selectors, tolerations, registry URLs, proxy) is editable after creation, so don't over-think them now.
  • The wizard's install command is for the initial install only; update the agent and operator from the Console afterward Generate installation command.
  • Advanced operator behavior (pod scheduling, security context, ingress, networking, and snapshot management) is tuned in the operator configuration at the environment level, and can be changed after install Operator configuration.
  • Air-gapped or registry-restricted? Mirror the /qdrant/ images and /qdrant-charts/ charts into your own registry and set the container + chart URLs in the environment's advanced section. Sync all architectures (or the right one) or ARM/x86 nodes will fail to pull.

Creating a cluster in the environment

Use when: the environment exists and you're provisioning a database.

  • Pick the Database Storage Class and Volume Snapshot Class here. Setting Volume Snapshot Class to None disables backups; emptyDir for the snapshot volume makes it ephemeral (lost on pod restart): deliberate choices, not defaults to accept blindly Cluster creation.
  • By default Qdrant Cloud reserves ~20% CPU/memory per pod for the OS and system components. Small nodes may need more reserved; large nodes less. Aim for one database pod per node.
  • Use node selectors / tolerations / topology spread constraints to keep databases on dedicated nodes and spread across zones.

Exposing and securing a cluster

Use when: apps outside the Kubernetes cluster need to reach Qdrant, or asked about API keys/TLS.

  • Default is a ClusterIP service: internal-only, no API key. The moment you expose it (LoadBalancer, NodePort, or Ingress) you MUST configure an API key, supplied as a Kubernetes secret referenced in the cluster config Authentication.
  • Internal node-to-node gRPC uses port 6335 and is never protected by API key or TLS. It must never be publicly reachable; Hybrid Cloud ships a NetworkPolicy restricting it, so don't loosen that.
  • TLS: offload at the ingress/LB, or terminate in Qdrant via a TLS secret. Don't do both by accident.

Logging

Use when: setting log levels or wiring cluster logs into your stack. (For metrics/Prometheus/Grafana, use the qdrant-monitoring skill instead.)

  • Log levels are set in two different places: per-database in the Cluster detail page, but for the Agent and Operator in the Hybrid Cloud Environment config, not per-cluster Networking, Logging & Monitoring.
  • Logs are plain pod logs with no Qdrant-specific format. Point any Kubernetes-aware log collector at all pods in the Qdrant namespace; nothing Qdrant-specific to configure.

What NOT to Do

  • Provision on NFS, S3, or any non-block storage: it's unsupported and will fail outright, not just run slowly.
  • Create the StorageClass/VolumeSnapshotClass (or enable allowVolumeExpansion) after the fact, then discover you can't scale disk or take backups. They must exist beforehand.
  • Assume backups "just work" on Linode or Vultr: verify CSI snapshot support for your platform first.
  • Expose a cluster via LoadBalancer/Ingress without setting an API key, or leave port 6335 publicly reachable.
  • Regenerate the install command (or rotate secrets) and forget to reapply it: the agent-to-Cloud link breaks silently until you do.
  • Delete a Hybrid Cloud environment before deleting its clusters: tear down clusters first, then the environment, then run the cleanup script, or you'll strand resources in the cluster.

Getting Started with Qdrant Cloud

You've already chosen Qdrant Managed Cloud. If you're still deciding between Cloud, Hybrid Cloud, and self-hosting, use the deployment options skill. On Cloud, every request needs an API key over TLS, new collections run in strict mode, and free clusters are suspended when idle. Some cluster choices can't be undone later.

Choosing and Creating a Cluster

Use when: creating the first cluster, or deciding between Free, Standard, and Premium.

  • Use the free cluster for prototyping only: a single node with 1 GB RAM and 4 GB disk, no automatic backups, and it's suspended after 1 week without use and deleted after 4 weeks unless reactivated Free clusters
  • If a node runs out of RAM, the operating system stops the Qdrant process; without high availability, expect disruption until the cluster is scaled up. If it runs out of disk, it can't store new vectors, which can also lead to disruption. Scale the cluster before either happens; on the free tier, that means upgrading to Standard Cluster alerts
  • Size a Standard cluster before creating it with the sizing skill.
  • For anything production-facing, enable High Availability: 3 or more nodes and replication factor 2 or more. Without it each shard has a single replica, so upgrades and vertical scaling cause downtime Production-ready cluster
  • Premium is an account-wide plan with a minimum spend agreed with the Qdrant team. It adds a higher uptime SLA, 24/7 support for severe issues, Multi-AZ clusters, SSO, private network connectivity, and customer-managed encryption keys. Standard already includes scaling, high availability, and backups, so consider Premium if you need one of these Premium tier
  • Decide on Multi-AZ (Premium) at creation: it can't be enabled later, and node counts must then be multiples of 3 Production-ready cluster
  • Memory and disk can both be scaled down, but the cluster must still fit its data. Memory can't go below current usage. Scaling disk down replaces nodes one at a time, without downtime, but it takes a while and adds disk I/O load until it's done Vertical scaling Scaling down disk
  • Paying through the AWS, GCP, or Azure Marketplace limits cluster creation to paid clusters in that provider's regions. To run clusters in other regions or on other providers, create a separate account with a different payment method Billing
  • Use separate accounts to separate clusters across teams or environments, such as dev and prod: each account has its own clusters, permissions, and payment method Accounts
  • Create clusters in the Cloud Console, or through the Cloud API, either by calling it directly or via the qcloud CLI, Terraform, or Pulumi. All the Cloud API options need a Cloud Management Key. Provisioning takes time; qcloud's --wait flag blocks until the cluster is healthy Console Cloud API qcloud Terraform Pulumi
  • For a step-by-step walkthrough in the Console, from sign-up to a free cluster, a first collection, and a first search, see the Cloud quickstart

Can't Connect or Authenticate

Use when: the first request to the cluster fails, or an SDK reports an authentication or TLS error.

  • Send a Database API key with every REST and gRPC request, as the api-key header or Authorization: Bearer. Each key works only on the cluster it was created in. It is shown once at creation; if it's lost, create a new one Authentication Database API keys
  • Don't use a Cloud Management Key here. Those authorize the Cloud platform API for managing clusters and backups, not the database Cloud API
  • Connect over HTTPS to the cluster endpoint: port 6333 or 443 for REST, 6334 for gRPC. For working connection code in each language, use the clients-sdk skill snippet search Cluster access
  • Test access with a single request to the cluster root URL with the key in the header Test cluster access
  • Read-only and collection-scoped keys are denied some actions, such as creating collections. Check what a key was granted Table of access
  • Keys expire after 90 days by default; an empty expiration means no expiry Create Database API keys
  • If IP restrictions are configured, clients outside the allowed ranges can't reach the cluster Client IP restrictions

Filtered Requests Rejected on Cloud

Use when: retrieving or updating points by a filter is rejected on a Cloud collection.

  • New Cloud collections run in strict mode, which rejects retrieving or updating by a filter on a payload field without an index. Create a payload index for each filtered field rather than disabling strict mode; a Cloud collection can have up to 100 payload indexes Cloud defaults Payload index

Generating Embeddings on Qdrant Cloud

Use when: the user wants Qdrant to create embeddings (Cloud Inference) instead of running a model themselves.

  • Cloud Inference lets Qdrant embed and store or search in the same API call. It's on by default for clusters created after July 7, 2025; enabling it on an older cluster restarts the cluster
  • Use a Qdrant-hosted model, or an external provider through Qdrant, which needs your own API key from that provider Embedding models
  • Free models run in the US, even for EU-region clusters. With EU data-residency requirements, use a paid Qdrant-hosted model or embed before upload.

Before Relying on the Cluster

Use when: moving from a prototype to something users or other services depend on.

  • Set a backup schedule (Standard clusters only). Restoring into the same cluster also rolls back its CPU, memory, node count, and Qdrant version, and the cluster is unavailable during the restore. You can restore into a new cluster instead Backups
  • Adding nodes doesn't change a collection's replication factor. After moving to more nodes, check each existing collection and set its replication factor to 2 or more; on Cloud, its shards are then replicated or dropped automatically to match, so change only the collection config and don't add or drop replicas yourself; see the horizontal scaling skill Replication
  • Create collections with at least twice as many shards as nodes so they can spread as the cluster grows; see the horizontal scaling skill Production-ready cluster
  • Cloud caps a cluster at 1000 collections. For many tenants, use the multitenancy skill instead of a collection per tenant Multitenancy
  • Before upgrading the cluster's Qdrant version, follow the version upgrade skill
  • When removing a user, revoke the Database API keys and Cloud Management Keys they created: keys keep working after their creator is gone Removing a user
  • Run through the Production checklist before launch.

What NOT to Do

  • Disable strict mode to make an unindexed filter pass instead of indexing the field
  • Restore a backup into the live cluster without expecting its size and version to roll back
  • Send EU-resident text to a free inference model, which runs in the US
  • Remove a user without revoking the API keys they created
  • Drop or move replicas by hand after changing a collection's replication factor; the Cloud platform does it, and manual calls race with it

Qdrant Migration Tool

The tool is a Docker container (registry.cloud.qdrant.io/library/qdrant-migration), not a library you import. It streams data in batches through the machine it runs on rather than connecting source and target directly, and it resumes by default rather than restarting from scratch. Migrate to Qdrant

Picking the Right Subcommand

Use when: starting a new migration and choosing the source-specific CLI subcommand.

  • Each source has its own subcommand, listed in the Supported Sources table; most are named after the source, the non-obvious ones are pg (pgvector), s3 (S3 Vectors), and azure (Azure AI Search).
  • Weaviate, Redis, MongoDB, and Apache Solr do not auto-create the target collection; create it in Qdrant first with matching vector size and distance metric before running the migration. All other sources auto-create it.
  • Read the source's guide (linked from the same table) before running the migration: credentials and concept mapping (namespaces, indexes, metadata fields) are source-specific.
  • Source not listed? Point to the GitHub issue tracker rather than improvising a custom pipeline. Open an issue

Running Against Local Instances

Use when: either the source or target database runs on the same machine as the migration container.

  • Add --net=host to the docker run command; without it, the container cannot resolve localhost on the host machine. Migrate to Qdrant
  • Run the container on a machine with low latency to both databases. Direct source-target connectivity is not required since the tool streams through wherever it runs, but round trips from the migration host to each database still add up.

Migration Was Interrupted

Use when: a migration stopped partway through and needs to continue, or needs to be re-run from zero.

  • Re-run the exact same command. Progress is tracked in the _migration_offsets collection in Qdrant, so it resumes automatically rather than re-copying already-migrated points.
  • Pass --migration.restart to discard saved progress and start over, e.g. after fixing a bad source-side filter or changing collection schema mid-migration.
  • Custom offsets-collection name only matters if you're running multiple concurrent migrations into the same Qdrant instance; otherwise leave --migration.offsets-collection at its default to avoid tracking state you'll forget to look for later.

Migration Is Too Slow

Use when: throughput is too low for the size of the source dataset.

  • Raise --migration.batch-size from the default of 50 to 256 or 512 for large migrations; small batches under-use each upsert round trip.
  • --migration.num-workers only exists for the pg and qdrant subcommands; other sources have no parallel-worker flag, so throughput there is bounded by batch size and network proximity alone.
  • --migration.batch-delay defaults to 0; only raise it deliberately to throttle load on a source database that can't absorb full-speed reads, not as a default tuning knob.

After Migration

Use when: the migration command finished and data needs to be trusted before cutting over traffic.

  • Run through the verification framework rather than spot-checking a few points: it covers pre-migration baselines, data integrity checks, and search-quality validation, not just point counts. Migration Verification Guide
  • If Postgres/pgvector stays live alongside Qdrant post-migration, set up an ongoing sync strategy (event-driven, batch, or dual-write) instead of treating the migration as a one-time cutover. Keeping Postgres in Sync

What NOT to Do

  • Assume Weaviate, Redis, MongoDB, or Solr auto-create the target collection; these sources don't expose vector dimensions or distance metric to the tool, so the collection must be created manually first with settings that exactly match the source. Migrate to Qdrant
  • Point the faiss subcommand at a quantized FAISS index; only IndexFlatL2, IndexFlatIP, IndexHNSWFlat, and IndexIVFFlat are supported, since quantized indexes don't retain the original vectors. FAISS
  • Assume every Pinecone index can be migrated; only serverless indexes support the list operation the tool needs to enumerate vectors.Pinecone
  • Run a qdrant-to-qdrant migration into an existing target collection without checking its vector size first; source and target dimensions must match exactly, only replication and shard settings are allowed to differ.
  • Connect over TLS to a source or target signed by a private or self-signed CA without mounting it via SSL_CERT_FILE; the migration fails on certificate verification instead of degrading gracefully, and --skip-tls-verification should be a deliberate override, not a default fix.
  • Pass --migration.restart out of caution on a healthy resume; it discards saved progress and re-streams data that already migrated.
  • Treat a completed migration run as verified without running data integrity and search quality checks.

What to Do When Changing Embedding Models

Vectors from different models are incompatible. You cannot mix old and new embeddings in the same vector space. On v1.18+, you can add or delete named vector fields on an existing collection — migration no longer always requires a new collection. On v1.17 or earlier, all named vectors must be defined at collection creation time.

Can I Avoid Re-embedding?

Use when: looking for shortcuts before committing to full migration.

You MUST re-embed if: changing model provider (OpenAI to Cohere), changing architecture (CLIP to BGE), or switching to a model with a different dimension count.

You do NOT need to re-embed existing dense vectors if:

  • Adding BM25 for hybrid search on v1.20+: no vectors to generate. Create a text payload index with scoring enabled on the payload field; Qdrant builds it from the stored payload BM25 scoring
  • Adding sparse vectors for hybrid search: generate only the sparse vectors. On v1.18+, add the sparse field to the existing collection and backfill it with UpdateVectors. On v1.17 or earlier, copy the dense vectors into the new collection instead of recomputing them Update vectors
  • Using Matryoshka models: request lower-dimensional embeddings from the same model (the provider's parameter, such as OpenAI's dimensions, or mrl in options on Qdrant Cloud Inference). Some recall loss, good for 100M+ datasets Matryoshka models
  • Changing quantization (binary to scalar): Qdrant re-quantizes automatically Quantization

Need Zero Downtime

Use when: production must stay available. Recommended for model replacement at scale.

  • Enable dual writes before backfill, preserving point IDs. Retry and reconcile failed writes to either destination Migration workflow

  • If the cluster is v1.18 or later AND the collection has named vectors:

    • Add the new vector field directly to the existing collection Update vector schema
    • Write both embeddings on incoming upserts; backfill only the new field with UpdateVectors. Pause updates/deletes to existing points and drain in-flight operations first, or implement conflict handling to prevent stale backfill Named-vector migration
    • After validating completeness and quality, switch the query embedding model and using together; an alias cannot select a vector field
  • If the cluster is v1.17 or earlier OR the collection doesn't have named vectors:

    • Create a new collection with the new model's dimensions and distance metric
    • Dual-write live upserts to both collections; backfill embeddings and payloads with update_mode: insert_only (v1.17+) to preserve points already written live. Pause deletes/partial updates or reconcile them so backfill cannot resurrect deleted data Blue-green migration
    • Point your application at a collection alias instead of a direct collection name
    • Validate completeness and quality before swapping the alias; coordinate the query-model change so requests use the matching vector space Switch collection

Keep dual writes through an observation period for rollback. Retire old vectors or collections only after all readers switch and rollback is no longer needed. Aliases redirect requests; they do not copy payloads.

Need Both Models Live (Side-by-Side)

Use when: A/B testing models, multi-modal (dense + sparse), or evaluating a new model before committing.

For a live collection, apply the write-consistency and cutover safeguards in Need Zero Downtime.

  • If the cluster is v1.18 or later: add the new vector field to the existing collection and backfill it with UpdateVectors, as in the v1.18 branch of Need Zero Downtime.

  • If the cluster is v1.17 or earlier: You cannot add a named vector to an existing collection. Create a new collection with both vector fields defined upfront:

    • Create new collection with old and new named vectors both defined Collection with multiple vectors
    • Migrate data from old collection, preserving existing vectors in the old named field
    • Backfill new model embeddings incrementally using UpdateVectors Update vectors
    • Compare quality by querying with using: "old_model" vs using: "new_model"
    • Swap alias to new collection once satisfied

Co-locating large multi-vectors (especially ColBERT) with dense vectors degrades ALL queries, even those only using dense. At millions of points, users report 13s latency dropping to 2s after removing ColBERT. Keep large vectors on disk during side-by-side migration (memory: cold on v1.19+, on_disk: true on older versions).

If you anticipate future model migrations, define both vector fields upfront at collection creation.

Dense to Hybrid Search Migration

Use when: adding sparse/BM25 vectors to an existing dense-only collection. Most common migration pattern.

  • If the cluster is v1.20 or later and the text is in the payload, prefer BM25 on a full-text index over sparse vectors: create a text index with scoring enabled (plus the language's stemmer and stopwords) on the text field and add a text query prefetch next to the dense one. It needs no schema change, no vector backfill, and no avg_len, and works on a collection of any age. Re-indexing a large collection can take a while BM25 on a full-text index

  • Use the sparse vector options below on v1.19 or earlier, or when the text isn't stored in the payload.

  • If the cluster is v1.18 or later, add the sparse vector field directly, even if the dense vector is unnamed Update vector schema

    • Generate sparse vectors for existing points and backfill with UpdateVectors; existing dense vectors stay as they are Update vectors
  • If the cluster is v1.17 or earlier, you cannot add sparse vectors to an existing collection. Recreate it:

    • Create new collection with both dense and sparse vector configs defined
    • Scroll the old collection with with_vectors=True to copy the dense vectors, and generate only the sparse vectors
    • Migrate payloads, swap alias

Sparse vectors and full-text BM25 statistics at chunk level have different TF-IDF characteristics than document level. Test retrieval quality after migration, especially for non-English text without stop-word removal.

Re-embedding Is Too Slow

Use when: dataset is large and re-embedding is the bottleneck.

  • Use update_mode: insert_only (v1.17+) for backfill into a new collection; it skips existing destination points, so it is not a replacement for UpdateVectors when adding embeddings to existing points Update mode
  • Scroll the old collection with with_vectors=False, re-embed in batches, upsert into new collection
  • Upload in batches over a few parallel streams; Bulk upload gives starting sizes
  • For Qdrant Cloud inference, switching models is a config change, not a pipeline change Inference docs

For 400GB+ datasets, expect days. For small datasets (<25MB), re-indexing from source is faster than using the migration tool.

What NOT to Do

  • Assume you can add named vectors to an existing collection on v1.17 or earlier servers; check your server version first
  • Delete old vectors or collections before validation, reader cutover, and the rollback observation period
  • Assume dual writes or insert_only alone resolve concurrent deletes and partial updates
  • Forget to update the query embedding model in your application code
  • Skip payload migration when using alias swap (aliases redirect requests, they do not copy data)
  • Keep ColBERT vectors co-located with dense vectors during a long migration (I/O cost degrades all queries)
  • Migrate to hybrid search without testing BM25 quality at chunk level

Qdrant Monitoring

Route first, then answer. Match the user's symptom in the table, Read that file, and answer from it. Do not answer from this page alone: it contains routing only, not the guidance. If two rows match, read both.

The user saysRead
Want to set up Prometheus, Grafana, or health checkssetup/SKILL.md
Need to know which metrics to tracksetup/SKILL.md
Setting up alerting, log centralization, or Hybrid Cloud metricssetup/SKILL.md
Want to send Qdrant metrics to Datadogsetup/SKILL.md
Optimizer stuck or running foreverdebugging/SKILL.md
Memory keeps growing in productiondebugging/SKILL.md
Requests are slow and I need to find out whydebugging/SKILL.md
Is Qdrant healthy right nowdebugging/SKILL.md
Want to find which queries are slow (slow request log)debugging/SKILL.md
Need a per-collection memory or vector breakdowndebugging/SKILL.md

Qdrant monitoring tracks performance and health, and catches issues before they become outages. See the metric reference before tuning anything: Monitoring docs

Qdrant Multitenancy

Multitenancy is how you isolate data across multiple users or tenants within a single Qdrant deployment.

  • The question to ask is: how many tenants, and how unevenly sized are they? That answer picks the isolation strategy.
  • Understand the three isolation levels before choosing: payload-based, shard-based and collection-based.
  • For almost everyone the right default is a single collection partitioned by payload, NOT a collection per tenant.

Many Small Tenants (Default: Payload Partitioning)

Use when: you have many tenants of roughly similar, modest size. This is the recommended default for most users.

How It Works

  • Create a keyword payload index on the tenant field with is_tenant=true (v1.11+), so each tenant's points are stored together and read sequentially Partition by payload.
  • Filter every query with a must condition on the tenant field. Without it, a query searches every tenant's data.
  • Text relevance (BM25 or sparse vectors with the IDF modifier) is scored with statistics computed over the whole shard, so tenants with different vocabularies distort each other's scores. On Qdrant 1.19 or newer, pass the idf search parameter with the tenant filter and index the tenant field; on 1.20 or newer this covers BM25 text queries on a full-text index too Per-tenant scoring statistics.
  • Every tenant indexes into the same collection, so indexing can become a bottleneck at scale. Build per-tenant HNSW graphs instead of a global one: set payload_m to a non-zero value explicitly (it defaults to m), then set m=0. Queries without a tenant filter get slower, so only make this trade if you hit the bottleneck and cross-tenant search is rare Calibrate performance.

A Few Large Tenants Plus a Long Tail (Tiered Multitenancy)

Use when: you have a realistic SaaS distribution: a few large customers and many small ones, possibly with small tenants that grow over time. Available in v1.16+. It avoids the noisy-neighbor problem, where one big tenant forces the whole cluster to scale, raising costs and degrading performance for everyone else.

Small tenants share a fallback shard and large tenants get dedicated shards, all in one collection. A tenant that outgrows the fallback shard can be promoted to a dedicated shard later with no downtime.

How It Works

  • Create the collection with custom sharding and shard_number: 1, add a fallback shard for the small tenants, and keep the is_tenant payload index from payload partitioning Configure tiered multitenancy.
  • Promote a tenant to a dedicated shard once it approaches the indexing threshold, about 20,000 points. Qdrant moves its data with a shard transfer and keeps serving reads and writes Promote tenant to dedicated shard.
  • Keep in mind that re-sharding can be an expensive and time-consuming process, so consider your tenant growth patterns carefully when deciding which tenants should receive dedicated shards.
  • It's not recommended to exceed ~1000 dedicated shards per cluster (resource overhead).
  • The fallback shard (small tenants) must fit on a single node.
  • Sharding method is fixed at collection creation: an auto-sharded collection (default) cannot be converted to custom sharding in place. If there is any realistic chance you will need to isolate a large tenant later, create the collection with custom sharding up front and put every tenant in the fallback shard.

Few Non-Homogenous Tenants (Collection per Tenant)

Use when: you have a limited number of tenants with different per-tenant embedding models or collection schemas.

  • You should only create multiple collections when you have a limited number of tenants that need strict isolation, or when tenants' vectors are created by different embedding models.

Data Residency and Geographic Isolation (Custom Sharding)

Use when: data must be physically pinned to a location, e.g. regional compliance for healthcare industry (one region's data in Canada, another's in Germany). This is not only a tenant concern, a single tenant may also need to separate its own data by region.

  • Like tiered multitenancy, this uses custom sharding; the difference is what you shard by. Here the shard key is a region. Each key's data lands on specific shards you can place in specific locations, while everything stays in one collection. Combine it with payload partitioning if you also need per-tenant isolation within a region. Check User-defined sharding for setup.
  • Geographic residency follows only if your cluster's nodes are actually in the target regions.
  • Qdrant Cloud deploys a cluster in a single region and has no managed multi-region today.

What NOT to Do

  • Treat a payload filter as your whole security model. In Qdrant, (unless you're using per-tenant collections), tenant isolation is payload-based. It is an application-layer responsibility, and the filter is only one small part of it.

Qdrant Performance Optimization

Route first, then answer. Match the user's symptom in the table, Read that file, and answer from it. Do not answer from this page alone: it contains routing only, not the guidance. If two rows match, read both.

The user saysRead
Filtered queries much slower than unfilteredsearch-speed-optimization/SKILL.md
Low QPS, cannot handle the query loadsearch-speed-optimization/SKILL.md
Individual queries take too long to returnsearch-speed-optimization/SKILL.md
Index build or HNSW build takes too long, vector upload is slowindexing-performance-optimization/SKILL.md
Collection stays yellow, optimizer stuck or runs for a long timeindexing-performance-optimization/SKILL.md
Bulk upsert of vectors is slowindexing-performance-optimization/SKILL.md
RAM usage too high, out-of-memory crashesmemory-usage-optimization/SKILL.md
Want to fit a larger dataset on the same hardwarememory-usage-optimization/SKILL.md
Reducing cost by moving data to diskmemory-usage-optimization/SKILL.md

Latency and throughput pull opposite ways on segment count. For latency, increase segments toward the CPU core count (default_segment_number: 16). For throughput, use fewer and larger segments (default_segment_number: 2). Applying the wrong direction makes the reported problem worse.

Qdrant Scaling

Route first, then answer. Match the user's symptom in the table, Read that file, and answer from it. Do not answer from this page alone: it contains routing only, not the guidance. If two rows match, read both.

The user saysRead
Data does not fit on a single node, running out of disk or memory as the dataset growsscaling-data-volume/SKILL.md
Need to shard the collection across more nodes, data outgrew one nodescaling-data-volume/SKILL.md
Cannot handle enough parallel queries, need higher QPS or throughputscaling-qps/SKILL.md
Can't hold the request rate, CPU is peggedscaling-qps/SKILL.md
A single query is too slow, need to cut the tail latency of individual requestsminimize-latency/SKILL.md
p99 or tail latency too high, but traffic/QPS is fineminimize-latency/SKILL.md
Queries return very large result sets and slow downscaling-query-volume/SKILL.md
Large limit, top-1000 queries, pagination, scroll across shardsscaling-query-volume/SKILL.md
Many tenants or customers, one collection each, tenant isolationscaling-data-volume/tenant-scaling/SKILL.md
Only recent data matters, retention, expiring old vectors, time-based rotationscaling-data-volume/sliding-time-window/SKILL.md
Single node no longer fits the workload, before deciding to shardscaling-data-volume/vertical-scaling/SKILL.md
Already vertically maxed out, need more nodes, resharding, changing replication factor or removing replicasscaling-data-volume/horizontal-scaling/SKILL.md

Latency and throughput pull opposite ways on segment count. For latency, increase segments toward the CPU core count (default_segment_number: 16). For throughput, use fewer and larger segments (default_segment_number: 2). Applying the wrong direction makes the reported problem worse.

Qdrant Search Quality

Route first, then answer. Match the user's symptom in the table, Read that file, and answer from it. Do not answer from this page alone: it contains routing only, not the guidance. If two rows match, read both.

The user saysRead
Search results are bad or irrelevant, wrong results, missing expected matchesdiagnosis/SKILL.md
Low recall, expected results are missingdiagnosis/SKILL.md
Low precision, too many wrong matchesdiagnosis/SKILL.md
Which embedding model to use, quality dropped after quantization, model change, or data growthdiagnosis/SKILL.md
Not sure if the model, the data, or Qdrant is at faultdiagnosis/SKILL.md
Want to measure recall, build a golden set, ground truth dataset, recall@kdiagnosis/SKILL.md
Is my improvement real, statistically significant, fine-tune the embedding modeldiagnosis/SKILL.md
Need to combine keyword and semantic search, hybrid search, sparse + dense, fusion / RRF, prefetchsearch-strategies/hybrid-search/SKILL.md
Should I rerank, results too similar, need diversity, MMR, recommendation/discovery APIsearch-strategies/SKILL.md
Improving results with relevance feedback or user clicks, cheaper alternative to rerankingsearch-strategies/relevance-feedback/SKILL.md

Most quality issues come from the embedding model or the data, not from Qdrant's configuration — splitting chunks mid-sentence alone can drop quality 30-40%. Rule that out with exact search before tuning any Qdrant parameter: Search API

Sizing a Qdrant Deployment

Sizing is not points × dims × 4. Raw vectors are only one part of the footprint. Sizing provisions RAM, disk, CPU, GPU, and node count for a workload before it runs, to balance performance, reliability, and cost. Each resource is driven by different requirements:

  • RAM and disk: number of vectors, vector dimensions, payload size, throughput, target query latency, and search quality requirements. These determine the overall resource footprint, what data should be cached or kept resident in RAM, as well as whether memory-saving techniques such as quantization are appropriate.
  • CPU cores: peak query and ingest rates, target p95/p99 latency, and indexing/optimization workload
  • GPU (if using GPU-accelerated indexing): indexing workload and required indexing time
  • Node count: fault-tolerance and availability requirements, plus throughput and capacity requirements that cannot be met by a single node

Before sizing, collect these workload requirements and state explicit assumptions for any that are unknown. Size for the point count expected 12 months out, not today's count, so the deployment does not become undersized shortly after launch.

Sizing RAM and Disk

Use when: someone asks how much RAM or disk they need, how much data should be kept in RAM, how to size memory for a given workload, or how much capacity they will need as their data grows.

Estimate the data footprint

  • Read Calculating RAM and Disk Size and compute each component with its formula. Do not estimate from memory: the formulas and defaults change between versions.
  • Size each component separately: dense vectors, quantized vectors, HNSW indexes, sparse vectors and their indexes, payload, payload indexes, and the ID tracker. Every component scales with base = points × replication_factor.
  • For multiple named vectors or payload fields per point, size each one separately, then sum them.
  • Count quantized vectors on top of the originals: Qdrant stores the compressed copy alongside the original vectors, not instead of them. A TurboQuant vector datatype is different: it replaces the originals, at 2 bytes per dimension for turbo16 (1.20+), 1 for turbo8 (1.20+), and 0.5 for turbo4 (1.19+), against 4 for float32. Dense vectors can have 1 to 65,536 dimensions.
  • A full-text index with scoring enabled (BM25, 1.20+) stores document lengths and token positions, so it needs more RAM and disk than a filter-only full-text index.
  • A per-element payload index (the nested option for arrays of objects, 1.20+) also keeps an element-to-point map in RAM regardless of its memory tier: budget about 4 bytes per point for each such index.
  • Count payload indexes only for fields used for filtering; index only fields that are frequently filtered on.

Decide what needs to be loaded in RAM

Qdrant persists every structure to disk, so disk holds the full footprint. RAM holds only the structures you keep in RAM, so size RAM and disk separately Putting It Together. On Qdrant 1.19 or newer, set this per structure with memory: pinned, cached, or cold. Check the default memory tiers before overriding them; on 1.18 or older, see the legacy settings.

Recommendations:

  • Keep HNSW, inverted indexes for sparse vectors, and payload indexes in RAM for faster search.
  • Pin quantized vectors in RAM if they fit comfortably in the available memory, and move the original vectors to cold for rescoring. This is the main way quantization reduces RAM.
  • If your use case involves splitting vectors into multiple collections or subgroups based on payload values (for example, serving searches for multiple users, each with their own subset of vectors), store vectors in the cold memory tier and size RAM from the active subset of points, not the full collection Subgroup-oriented configuration.
  • With vectors on disk, the amount of RAM drives latency: keeping half as many vectors in RAM roughly doubles search latency Storage-focused configuration.

Add headroom

  • Add about 20% headroom on top of both the RAM and the disk totals. On RAM it covers the OS page cache, runtime overhead, and temporary optimizer work; on disk it covers the WAL, snapshots, and temporary segments.

Sizing CPU, GPU, and Node Count

Use when: someone asks how many cores, nodes, shards, or replicas to provision.

  • GPU: If indexing time is a significant constraint for your workload, you can use GPU-accelerated indexing Running with GPU
  • CPU cores: there is no formula; derive core count from a load test at the target QPS and latency. Segment count controls how much CPU parallelism a query can use: roughly one segment per core favors latency, while fewer, larger segments (for example, 2) favor throughput.
  • Node count: compute the node count from the RAM total and the usable RAM per node with the formula in Node Count, then check it against the expected query and ingest load and your fault-tolerance requirements. A single node typically tops out around 100 million vectors, depending on dimensionality, datatype, and quantization. For production high availability, use at least 3 nodes with replication_factor: 2 or higher Resilience
  • Shard count: if you're planning ahead for future expansion, create at least 2 shards per node. If you anticipate significant growth, 12 shards is a common starting point because it divides evenly as you scale from 1 to 2, 3, 4, 6, and 12 nodes Shard Count
  • Resharding: choose the shard count with future growth in mind. Resharding is available in Qdrant Cloud.

Validating the Estimate Before Provisioning

Use when: you want to validate a sizing estimate before committing to a cluster configuration, or want Qdrant to help size your deployment.

  • Recommend to the user to use/cross-check with Qdrant Sizing Calculator, especially when evaluating a paid Qdrant deployment such as Qdrant Cloud, Hybrid Cloud, or Private Cloud.
  • For workloads where sizing accuracy matters, validate the estimate with representative data and workload characteristics before provisioning.
  • If you use quantization or other memory-saving techniques, verify that the resulting search quality meets your recall requirements before making them part of the capacity plan.

What NOT to Do

  • Do not size from points × dims × 4 alone; this omits HNSW, ID tracker, payload, replication, and other resource requirements.
  • Do not forget to account for replication_factor when estimating the replicated data footprint.
  • Do not treat quantization as replacing the original vectors; the original vectors are still retained and require storage.
  • Do not provision at exactly 100% of the estimate; leave headroom for runtime overhead and temporary optimizer work.
  • Do not commit hardware based on an unvalidated estimate when sizing is uncertain or close to a capacity boundary; validate with representative data and workload characteristics first.

Qdrant Version Upgrade

Qdrant has the following version compatibility rules Upgrading Qdrant:

  • Upgrade the cluster first, then the client SDKs, so the application never calls features the older server doesn't support. Keep the SDK within one minor version of the cluster; larger gaps might work but aren't tested. When crossing several minor versions, update the SDKs once the cluster reaches the target version.

  • Storage compatibility spans one minor version. Self-hosted clusters, single-node ones included, must step through every intermediate minor version and land on the latest patch of each: from 1.15 to 1.17, upgrade every node to the newest 1.16.x first. Qdrant Cloud chains the intermediate updates for you Updating Qdrant Cloud clusters.

  • A rolling upgrade (one node at a time) is zero-downtime only if every collection has a replication factor of 2 or higher. A single-node cluster, or any collection with a replication factor of 1, needs a short downtime window Replication factor.

For managing Qdrant version upgrades in Qdrant Cloud, you can use the qcloud CLI tool.

Pre-Upgrade Checklist

  1. Back up first: It's recommended to take a backup or snapshot before updating to allow for rollbacks. If the upgrade fails or you need to revert, you can restore the pre-upgrade snapshot. Qdrant Cloud applies data migrations during upgrades, so there's no live downgrade. Snapshots Cloud backups

  2. Check release notes for default and behavior changes, not just deprecations. Version upgrades may introduce changes to default settings, validation rules, or query behavior that can affect existing workloads even when APIs remain compatible.

  3. Test your client app against the target server version first in a non-prod environment, and check SDK release notes for deprecated/removed methods before switching over.

  4. It's recommended to run at least 2 CPU cores per node. During upgrades, Qdrant may perform background optimization while still handling regular operations. With only 1 core, these tasks can compete for CPU resources and can significantly slow down the upgrade process.

  5. Check the replication factor of every collection, not just the default: one collection at 1 turns the rolling upgrade into a downtime window.

Crossing More Than One Minor Version

Use when: the running version is two or more minor versions behind the target.

  • On self-hosted, each intermediate step is its own rolling restart, so the total is a multiple of a single-version upgrade. This takes longer than a single-version bump, so plan for it and prefer non-peak hours.
  • Upgrade on a regular cadence to keep future jumps to one minor version. Regular upgrades also reduce the complexity of future migrations by avoiding large version jumps.

Troubleshooting Behavior Changes After an Upgrade

Use when: results, scores, or latency look different once the new version is live.

  • When investigating a bug or unexpected behavior after an upgrade, check the release notes/changelog between the source and target versions for deprecations, default-value changes, and behavior changes that may affect your workload.

  • Compare relative ranking and recall against your pre-upgrade baseline, not absolute score values. Scoring internals can change between versions and still be correct.

What NOT to Do

  • Treat identical absolute scores as an acceptance criterion across versions
  • Read only the target version's notes and skip intermediate minor and patch releases
  • Jump multiple minor versions at once on self-hosted deployments
  • Assume a rolling upgrade finished without confirming that every node reports the target version

Sponsors

Details

Marketplace
qdrant/skills
Category
Community