Qdrant Knowledge Patch

Qdrant Knowledge Patch

Use this skill when implementing, reviewing, upgrading, or operating Qdrant. Inspect the deployed server version, collection configuration, client version, and cluster topology before applying version-dependent guidance.

How to use this skill

1. For an upgrade, read the upgrade and operations reference first.
2. For an API or configuration change, load the reference for that topic.
3. Treat changed defaults, removed endpoints, and corrected result semantics as migration work, not as transparent implementation details.
4. Test retrieval quality after changing quantization, ranking, filtering, or HNSW storage because the tradeoffs are workload-dependent.
5. Test rolling upgrades against the actual replication factor and node path.

Reference index

Upgrade blockers and changed behavior

Walk every adjacent minor

Do not skip minor releases. Bring all nodes to the latest patch of the current minor, move to the immediately following minor, and repeat. Upgrade client SDKs before servers. For a rolling upgrade, restart one node at a time and verify that every collection has at least two replicas; otherwise schedule an outage.

Replace the resident-memory strict-mode guard

Do not add new uses of strict_mode_config.max_resident_memory_percent. Move memory enforcement to the Global quota API. Preserve the old field only while migrating a deployment that still accepts it.

Re-evaluate ingestion back pressure

The update-queue default is now 200 rather than one million. Explicitly size the queue when a workload depended on a large write backlog, and monitor write latency and rejection behavior during upgrades.

Remove reliance on corrected edge cases

Audit code and tests for these behavior changes:

• An empty min_should with nonzero min_count no longer matches everything.
• Scalar-quantized L2 scores no longer include the erroneous shift.
• A zero-limit batch query preserves the empty-result response shape.
• Recommend queries error when a referenced point ID is absent.
• /readyz no longer returns a false positive for a fresh peer.

Migrate from legacy search endpoints

Deprecated search endpoints are gone from the OpenAPI specification and are deprecated in gRPC. Build new retrieval flows on the Query API and update generated clients that depended on the removed OpenAPI paths.

Collection safety quick reference

Enable strict mode deliberately

New collections enable strict mode by default. Configure it to reject costly unindexed filters, oversized write or search batches, excessive filter clauses, timeouts, hnsw_ef, oversampling, too many payload indexes, and memory-heavy writes. Rejections are client errors that identify the exceeded limit.

The enabled flag is dynamic, and existing collections can be updated with PATCH. Keep the limits aligned with the indexes and request shapes used by the application.

PATCH /collections/{collection_name}
{
  "strict_mode_config": {
    "enabled": true,
    "search_max_batchsize": 64
  }
}

Protect writes from stale or wrong operation types

Use conditional point updates when a payload version, timestamp, or monotonic value must still match. Use insert-only mode for creates and update-only mode for changes so an upsert cannot silently perform the opposite operation.

Plan named-vector migrations in place

Add a new named vector to the existing schema, populate it in the background, switch reads, and then remove the old field. Use has_vector when mixed points temporarily contain different named vectors.

Choose shared and dedicated tenant shards

Keep small tenants on the fallback shard and create dedicated shard keys for large tenants. Promotion uses shard transfer while reads and writes continue; applications can keep sending the same shard-key selector.

Retrieval quick reference

Prefer Query API composition

Use prefetch plus a formula to combine $score, payload conditions, numeric expressions, datetime decay, or geographic decay. Supply defaults for absent payload inputs. Use weighted RRF when constituent rankers have unequal value, and configure the RRF k constant for the desired rank decay.

Add diversity with MMR

MMR reranks a nearest-neighbor candidate set. diversity ranges from 0.0 for relevance to 1.0 for diversity, and candidates_limit controls the initial pool. Keep the candidate pool large enough for diversification.

{
  "query": {
    "nearest": [0.01, 0.45, 0.67, 0.12],
    "mmr": {"diversity": 0.5, "candidates_limit": 100}
  },
  "limit": 10
}

Use ACORN only on affected filters

Set the query-time acorn option for filtered HNSW searches where several low-selectivity filters hide direct graph neighbors. It needs no index rebuild, but its broader traversal adds runtime overhead.

Select quantization by distribution and accuracy needs

• Binary 1-bit maximizes compression; 1.5-bit and 2-bit modes trade some space for accuracy, with 2-bit explicitly representing zero.
• Asymmetric quantization can combine binary stored vectors with scalar-quantized queries to improve precision without restoring full storage.
• TurboQuant rotates vectors before compression, avoiding binary quantization's centered-distribution assumption and supporting cosine, dot, and L2 distance.
• Four-bit TurboQuant may be primary storage when retaining original vectors is unnecessary.

Measure recall, score behavior, memory, disk, and latency with production-like queries before selecting a primary representation.

Tune HNSW storage and construction

GPU-enabled container images can build HNSW indexes on Vulkan-capable hardware, including multiple GPUs and quantized vectors; confirm detection in the logs. Incremental graph extension avoids a rebuild for new-point upserts, but deletes and updates still trigger a full rebuild.

With quantization enabled, inline_storage: true stores vectors in HNSW nodes, reducing random reads and permitting implicit rescoring at the cost of more storage. Disable per-field HNSW participation for payload indexes never used by dense-vector filtering.

Text-search quick reference

Configure text analysis when creating the payload index:

• multilingual tokenization handles languages without whitespace boundaries.
• Stop-word removal and Snowball stemming normalize language-specific input.
• phrase_matching: true is required before match.phrase can be queried.
• ascii_folding: true lets unaccented queries match accented indexed text.
• text_any replaces a client-built should list for any-token matching.
• Keyword prefix matching requires prefix support on the keyword index first.

These options change indexing or query semantics. Reindex or create the index with the required capability before relying on it.

Operations quick reference

Observe the cluster, not isolated peers

Use /cluster/telemetry for peer-wide activity, the collection optimization endpoint for current and historical optimization work, and collection memory reporting for disk, RAM, and page-cache use by vectors, payload, and indexes. Use per_collection=true on metrics only when the added collection label is acceptable for the monitoring system's cardinality.

Control read latency and routing

Delayed fan-out sends a second request only after the first replica exceeds a latency threshold and uses the first response. A routing token produces stable read routes when deterministic routing matters.

Keep audit and request correlation connected

Enable protected-operation audit logging, query entries across all nodes, and pass x-request-id, x-tracing-id, or traceparent to correlate audited calls with client and distributed traces. Pass external inference credentials in the request header when keys must be scoped per inference request.

Verification checklist

• Confirm the server and client versions before using an option or endpoint.
• Snapshot collection schemas, strict-mode settings, shard keys, and memory policies before an upgrade.
• Exercise insert-only, update-only, conditional-update, and rejection paths.
• Compare recall and score distributions after quantization or ranking changes.
• Test multilingual, phrase, folded, and prefix text behavior against the actual index configuration.
• Validate rolling availability with the real replication factors.
• Inspect telemetry, optimizations, memory, metrics, audit queries, and readiness during a staged rollout.
• Regenerate API clients after endpoint deprecations or specification changes.