Qdrant Knowledge Patch

Qdrant Knowledge Patch

Use this skill when designing, upgrading, operating, or troubleshooting Qdrant deployments whose behavior may depend on recent APIs, defaults, storage modes, query features, or compatibility changes.

How to use this skill

1. Determine the server version and deployment shape before proposing changes.
2. Read the reference file for the task; several defaults and behaviors changed after their original introduction.
3. Treat collection configuration, index creation options, and query-time parameters as different scopes. Do not move an option between them.
4. Check upgrade prerequisites before changing a cluster or single-node server.
5. Prefer the current replacement when a setting or endpoint is deprecated.
6. Validate assumptions against the running collection schema and telemetry.

Reference index

Breaking changes and deprecations

Replace the strict-mode RSS guardrail

Do not introduce strict_mode_config.max_resident_memory_percent in new configurations. Use the Global quota API for memory protection. When upgrading, find collections that still rely on the strict-mode setting and migrate their policy deliberately.

Re-evaluate ingestion back pressure

The update queue default is now much smaller than the former one-million-entry backlog. A workload that depended on deep buffering may encounter back pressure far earlier. Tune producers, monitor the queue, and decide explicitly whether a larger queue is appropriate.

Expect corrected query behavior

Regression tests should cover these compatibility-sensitive cases:

• An empty min_should with nonzero min_count no longer matches everything.
• Scalar-quantized L2 scores no longer include the former erroneous shift.
• A zero-limit batch query retains the empty-result response shape.
• Query API recommendations fail when a referenced point ID is missing.

Do not encode the superseded behavior into application logic.

Migrate from legacy search endpoints

Deprecated search endpoints are no longer present in the OpenAPI description and are marked deprecated in gRPC. Build new integrations on the points Query API and plan migrations for generated clients that depended on the old surface.

Account for storage-default changes

Single-file mmap vector storage is enabled by default for immutable segments. New deployments also use Gridstore rather than RocksDB as their embedded storage backend. Capacity and performance comparisons must name the actual backend and vector-storage configuration.

Upgrade quick reference

Advance one minor at a time

Before moving to a new minor release, bring every node to the latest patch of the immediately preceding minor. This rule applies to single-node deployments as well as clusters because skipping an intermediate minor can skip required data migrations.

Preserve availability intentionally

Zero-downtime rolling upgrades require replication factor 2 or greater for every collection and one-at-a-time node restarts. A single-node deployment, or even one collection at replication factor 1, requires a short outage.

Upgrade client SDKs before servers. SDKs are tested for backward compatibility with the latest three server minor versions, which keeps the client usable during the rollout.

With Helm, upgrading the release rolls the Qdrant StatefulSet automatically:

helm upgrade qdrant qdrant/qdrant --version <target-version> -n <namespace>

Collection and write quick reference

Evolve named-vector schemas in place

Add a new named vector to an existing collection, populate it in the background, switch consumers, and remove the old vector after migration. A full collection recreation and re-ingestion is no longer required.

Protect writes from stale callers

Attach an update filter to a point update and compare an expected version, synchronized timestamp, or monotonically increasing payload value. Qdrant rejects the write when the condition does not match. Use insert-only and update-only upsert modes when creation and mutation must not be interchangeable.

Use tiered tenant placement

Keep small tenants in a shared fallback shard and promote large tenants to user-defined dedicated shards. Continue sending the shard key selector; Qdrant routes to the dedicated shard when present and otherwise uses the fallback. Promotion uses shard transfer while reads and writes continue.

Apply guardrails at the right layer

Collection strict mode rejects operations that exceed configured limits and returns a client error naming the violated limit. It can protect against unindexed filtering, excessive query or batch parameters, and payload-index growth. Use global quotas, rather than the deprecated strict-mode RSS setting, for process-wide memory protection.

Retrieval quick reference

Choose the query-time ranking tool

Use ACORN selectively because it increases query-time work. Formula expressions can combine $score, payload conditions, numeric operations, datetime decay, geographic distance, and fallback defaults.

Filter on recent conditions

• has_vector selects points containing a named vector.
• Keyword prefix matching requires prefix support on the keyword index first.
• Slice conditions support deterministic sampling and sliced scrolling.
• text_any tokenizes several terms and matches a text field containing any one of them.

Indexing and quantization quick reference

Select a compression strategy

Use 2-bit binary quantization when explicitly representing zero helps accuracy, especially for vectors below roughly 1,000 dimensions. Use 1.5-bit for an intermediate compression/accuracy point. Asymmetric quantization can keep stored vectors binary while scalar-quantizing queries to improve precision and reduce rescoring.

TurboQuant rotates vectors before compression, so it does not depend on the centered distribution expected by binary quantization. Its 4-bit representation can serve as primary vector storage when retaining original vectors is not required.

Tune HNSW behavior deliberately

Incremental HNSW construction extends the graph for upserts, but deletes and updates can still cause a full rebuild. inline_storage: true reduces random disk reads by keeping vector data in HNSW nodes; it requires quantization and uses more storage. Payload indexes that are not used by dense-vector queries can be excluded from HNSW participation.

Text-search quick reference

Choose index features when creating the full-text payload index:

• multilingual tokenization handles languages without whitespace boundaries.
• Stop-word removal and Snowball stemming normalize language-specific text.
• Phrase matching must be enabled at index creation before match.phrase can require ordered terms.
• ASCII folding must be enabled at index creation to make cafe match café.

Index-time features require index recreation when absent; text_any is a query condition and does not replace index configuration.

Operations quick reference

Use /cluster/telemetry for a cluster-wide view, and use the collection optimizations endpoint to inspect current and historical optimization work. Collection memory data separates disk, RAM, and OS page-cache use by component. Enable per-collection metrics only when the extra Prometheus label cardinality is acceptable.

Audit protected API operations, query audit records across the cluster, and propagate a supported tracing header so entries can be correlated with client and distributed traces. Request-scoped inference credentials can travel in a request header rather than being stored as one shared server credential.

When debugging replica latency, consider delayed fan-out: a second replica is queried only after the first crosses a latency threshold, and the first response wins. Use a routing token when deterministic read routing is required.

Verification checklist

• Confirm server, client, and Helm chart versions independently.
• Inspect the live collection schema before changing vectors or indexes.
• Verify whether index options are creation-time or query-time controls.
• Exercise corrected query edge cases in application tests.
• Observe queue pressure, optimization status, and component memory after a storage, indexing, or ingestion change.
• Test rolling-upgrade availability against every collection's replication factor, not only the cluster node count.
• Check audit and metrics cardinality before enabling high-volume observability.