lib/api/src/rest/schema.rs (1)

515-520: RRF k validation is not enforced at REST level; attribute here is ineffective without derive.

You added #[validate(range(min = 1))] on the RrfK(usize) variant, but Fusion does not derive Validate and REST validation is implemented manually in rest/validate.rs. As a result, this attribute does not enforce k ≥ 1 for REST input.

• Enforce k ≥ 1 in the manual Validate impl (see suggested fix in rest/validate.rs).
• Optionally, add a schemars constraint so OpenAPI reflects the minimum in generated docs.

Apply this diff to annotate the OpenAPI schema (purely documentation; does not enforce at runtime):

 pub enum Fusion {
     Rrf,
-    #[validate(range(min = 1))]
+    #[validate(range(min = 1))]
+    #[schemars(range(min = 1))]
     RrfK(usize),
     Dbsf,
 }

Additionally, consider updating the doc comment above to mention the object form for RRF with a custom k (e.g., "rrf_k") and an example payload to improve discoverability.

lib/api/src/grpc/proto/points.proto (3)

565-568: Clarify default vs. custom k in the Fusion enum comment.

Given the addition of rrf_custom, the comment should reflect that RRF uses the default k (2), and rrf_custom enables custom k.

Apply this diff to reword the comment:

 enum Fusion {
-    RRF = 0; // Reciprocal Rank Fusion (with k=2)
+    RRF = 0; // Reciprocal Rank Fusion (default k=2). Use `rrf_custom` to set a custom k.
     DBSF = 1; // Distribution-Based Score Fusion
 }

---

670-673: Document k’s valid range on the new message.

GRPC-side validation enforces k ≥ 1 via build.rs. Make this explicit in the proto comment for better client UX.

Apply this diff to add an explanatory comment:

 message ReciprocalRankFusion {
-    uint32 k = 1;
+    // RRF blending parameter (must be >= 1). Default (when using `Fusion = RRF`) is 2.
+    uint32 k = 1;
 }

---

674-686: Good addition; preserves backward compatibility and enables custom k.

Adding rrf_custom as a separate oneof branch keeps existing clients working with Fusion=RRF while enabling custom k for those who need it. Field number 10 is free and safe to add.

Minor doc refinement to guide users toward when to use this variant:

-    ReciprocalRankFusion rrf_custom = 10; // Reciprocal Rank Fusion with custom `k` parameter.
+    ReciprocalRankFusion rrf_custom = 10; // Reciprocal Rank Fusion with custom `k` parameter. Prefer `Fusion = RRF` for default k=2.

docs/redoc/master/openapi.json (2)

14981-14989: Clarify Fusion description to document the new object form and defaults.

Consider updating the description to explicitly document both forms and the default behavior when using the string "rrf". This reduces ambiguity for API consumers.

-      "Fusion": {
-        "description": "Fusion algorithm allows to combine results of multiple prefetches.\n\nAvailable fusion algorithms:\n\n* `rrf` - Reciprocal Rank Fusion * `dbsf` - Distribution-Based Score Fusion",
+      "Fusion": {
+        "description": "Fusion algorithm allows combining results of multiple prefetches.\n\nAvailable fusion algorithms:\n\n* `rrf` - Reciprocal Rank Fusion. You can also configure its `k` parameter by using an object form: `{ \"rrf_k\": <uint, min 1> }`. If the plain string `\"rrf\"` is used, the default `k` is applied by the server.\n* `dbsf` - Distribution-Based Score Fusion",

---

14990-15003: Add example for the parameterized RRF object form.

Providing an inline example improves discoverability in Swagger/ReDoc and for SDK generators.

           {
             "type": "object",
             "required": [
               "rrf_k"
             ],
             "properties": {
               "rrf_k": {
                 "type": "integer",
                 "format": "uint",
-                "minimum": 0
+                "minimum": 1
               }
             },
+            "example": {
+              "rrf_k": 60
+            },
             "additionalProperties": false
           }

lib/segment/src/common/reciprocal_rank_fusion.rs (3)

15-17: Defensive check: guard against k == 0 to avoid division-by-zero

Even though upstream validation enforces k ≥ 1, this low-level helper should defensively assert to prevent accidental misuse and hard-to-debug NaNs/Infs if validation is bypassed in the future.

Apply this diff to add a debug assertion:

 fn position_score(position: usize, k: usize) -> f32 {
+    debug_assert!(k > 0, "RRF k must be >= 1 to avoid division by zero");
     1.0 / (position as f32 + k as f32)
 }

---

25-28: Document the k parameter contract (k ≥ 1, default = DEFAULT_RRF_K)

The signature change is correct. Please add a short doc note on the k constraints and recommended default to make the API self-explanatory for callers who don’t see upstream validators.

---

75-125: Float assertions are brittle; prefer approximate comparisons

Hard-coding f32 literals (e.g., 1.0833334) makes tests fragile across platforms/optimizations. Consider approximate comparisons with a small epsilon to reduce flakiness.

For example:

fn approx_eq(a: f32, b: f32, eps: f32) -> bool { (a - b).abs() <= eps }

assert!(approx_eq(scored_points[0].score, 0.5, 1e-6));
assert!(approx_eq(scored_points[0].score, 1.0833334, 1e-6));

docs/grpc/docs.md (2)

239-239: Fix markdown list indentation (MD007)

markdownlint flagged this newly added TOC entry. Align it with the expected 2-space indent.

Apply this diff:

-    - [ReciprocalRankFusion](#qdrant-ReciprocalRankFusion)
+  - [ReciprocalRankFusion](#qdrant-ReciprocalRankFusion)

If this file is generated, please adjust the generator to emit the correct indentation.

---

4183-4192: Enrich the ReciprocalRankFusion docs with constraints and defaults

Please add a short description noting:

• k must be ≥ 1 (validation constraint)
• default k is 2 when using Fusion = RRF (enum)
• formula reference: score contribution = 1 / (k + rank_index), where rank_index starts at 0

If this page is generated from proto comments, adding the notes to the proto will propagate here.

I can propose proto comment text to include these nuances if helpful.

lib/collection/src/shards/local_shard/query.rs (1)

408-411: Pass-through of k to rrf_scoring is correct; assert invariant to guard accidental k=0

Given upstream validation enforces k ≥ 1, this match arm is functionally correct. Add a debug assertion to catch any accidental bypass of validation.

Apply this diff:

-        let fused = match fusion {
-            FusionInternal::RrfK(k) => rrf_scoring(sources, k),
+        let fused = match fusion {
+            FusionInternal::RrfK(k) => {
+                debug_assert!(k > 0, "RRF k must be >= 1");
+                rrf_scoring(sources, k)
+            },
             FusionInternal::Dbsf => score_fusion(sources, ScoreFusion::dbsf()),
         };

lib/collection/src/collection/query.rs (1)

363-365: Correct: use RrfK(k) and forward k to rrf_scoring

This aligns the collection-level fusion with the parameterized RRF behavior. Keep this consistent with the shard-level fusion_rescore to avoid drift in semantics.

Consider extracting a small helper that applies the common “rrf_scoring + optional score_threshold + limit/offset” pipeline so both code paths share identical logic.

lib/api/src/grpc/qdrant.rs (1)

7107-7111: Doc tweak suggestion: clarify default vs. custom RRF usage.

The comment “Reciprocal Rank Fusion (with k=2)” is good for the enum variant. Consider explicitly referencing that this is the default when using Fusion::Rrf, while Query::RrfCustom allows specifying k ≥ 1. This reduces ambiguity when users scan the generated docs.

If you prefer, I can propose an update in the source .proto docs so it’s reflected across all generated artifacts.

lib/collection/src/operations/universal_query/shard_query.rs (2)

60-60: Consider modeling k as NonZeroU32 (or at least u32) at the type level

k is constrained by the gRPC schema to uint32 and by validation to k ≥ 1. Representing it as NonZeroU32 (or u32) in FusionInternal would:

• encode the ≥ 1 invariant at the type level, and
• avoid lossy usize→u32 casts elsewhere.

This is optional but would reduce conversion hazards and improve API consistency across layers.

---

545-549: Nit: avoid importing Query in a scope where it names the impl target

Within impl From for api::grpc::qdrant::Query, importing Query can be confusing. Either fully qualify or omit the import to avoid shadowing the impl target type name.

Optional readability tweak:

-        use api::grpc::qdrant::{Fusion, Query, ReciprocalRankFusion};
+        use api::grpc::qdrant::{Fusion, ReciprocalRankFusion};

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

💡 Knowledge Base configuration:

• MCP integration is disabled by default for public repositories
• Jira integration is disabled by default for public repositories
• Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

Learnt from: generall
PR: qdrant/qdrant#7006
File: lib/collection/src/operations/verification/update.rs:158-174
Timestamp: 2025-08-10T18:30:02.986Z
Learning: In Qdrant's strict mode verification code (lib/collection/src/operations/verification/update.rs), exhaustive pattern matching without `..` is intentionally used for structs like PointsBatch and PointsList. This design pattern ensures compilation fails when new fields are added, forcing developers to explicitly consider how new fields should be handled in the indexed_filter_write method. This provides visibility and compile-time safety for struct evolution.

lib/api/src/rest/schema.rs (1)

533-542: Allow omitting type and accept rrf_k as an alias for k

Right now, RrfParams requires the type field at deserialization time, despite having a default enum variant. Also, some examples/comments have used rrf_k as a key. To make the request shape more forgiving and self-explanatory:

• Default the type field to Rrf when omitted.
• Accept "rrf_k" as an alias for "k".

This will support both {"fusion": {"type":"rrf","k":60}} and {"fusion": {"k":60}} and be lenient if users follow older examples.

 #[derive(Debug, Default, Serialize, Deserialize, JsonSchema, Validate)]
 #[serde(rename_all = "snake_case")]
 pub struct RrfParams {
-    pub r#type: RrfType,
+    #[serde(default)]
+    pub r#type: RrfType,
 
     /// K parameter for reciprocal rank fusion
     #[validate(range(min = 1))]
-    #[serde(default)]
-    pub k: Option<usize>,
+    #[serde(default, alias = "rrf_k")]
+    pub k: Option<usize>,
 }

lib/api/src/grpc/validate.rs (1)

349-350: Validate nested FusionParams to enforce k ≥ 1 (don’t short-circuit validation)

Currently FusionParams is accepted without validating its payload, allowing k=0 to pass through despite the documented min=1 constraint. Validate the nested message so field-level constraints apply. This aligns with earlier feedback for the old RrfCustom route.

Apply this diff:

-            grpc::query::Variant::Sample(_)
-            | grpc::query::Variant::Fusion(_)
-            | grpc::query::Variant::FusionParams(_)
-            | grpc::query::Variant::OrderBy(_) => Ok(()),
+            grpc::query::Variant::Sample(_)
+            | grpc::query::Variant::Fusion(_)
+            | grpc::query::Variant::OrderBy(_) => Ok(()),
+            grpc::query::Variant::FusionParams(params) => params.validate(),

If FusionParams or its inner RrfParams doesn’t derive Validate, add it and ensure k has range(min = 1). Also consider a negative unit test asserting that a Query with FusionParams { rrf: { k: 0 } } fails validation.

Use this to confirm the build script or derives inject range(min = 1) for RrfParams.k:

#!/bin/bash
# Check for RrfParams.k constraints and Validate derive
rg -n -C3 'message\s+RrfParams\b' lib/api/src/grpc/proto
rg -n -C5 'RrfParams\.k|range\s*\(\s*min\s*=\s*1\s*\)' lib/api

lib/collection/src/operations/universal_query/shard_query.rs (2)

569-579: Avoid usize -> u32 truncation when emitting Query (custom k path)

k is usize internally but serialized as u32. Using as may silently truncate on 64-bit platforms for very large k.

Apply a fallible conversion with clamping to avoid truncation:

-            FusionInternal::RrfK(k) => Query {
+            FusionInternal::RrfK(k) => Query {
                 variant: Some(QueryVariant::FusionParams(FusionParams {
-                    variant: Some(FusionParamsVariant::Rrf(RrfParams { k: Some(k as u32) })),
+                    variant: Some(FusionParamsVariant::Rrf(RrfParams {
+                        k: Some(u32::try_from(k).unwrap_or(u32::MAX)),
+                    })),
                 })),
             },

Optionally, instead of clamping, return an error earlier or change FusionInternal to hold u32/NonZeroU32 (see earlier refactor suggestion).

---

593-604: Avoid usize -> u32 truncation when emitting query_shard_points::Query (custom k path)

Same truncation risk here when serializing k.

Apply the same fix:

-            FusionInternal::RrfK(k) => Query {
+            FusionInternal::RrfK(k) => Query {
                 score: Some(Score::FusionParams(FusionParams {
-                    variant: Some(FusionParamsVariant::Rrf(RrfParams { k: Some(k as u32) })),
+                    variant: Some(FusionParamsVariant::Rrf(RrfParams {
+                        k: Some(u32::try_from(k).unwrap_or(u32::MAX)),
+                    })),
                 })),
             },

lib/api/src/grpc/proto/points.proto (2)

568-570: Clarify RRF enum doc to reflect default vs parameterized K

The comment “with k=2” is fine as a shorthand, but now that parameterized RRF exists, consider clarifying that RRF (enum) uses the default k=2, while FusionParams.rrf allows overriding k.

-    RRF = 0; // Reciprocal Rank Fusion (with k=2)
+    RRF = 0; // Reciprocal Rank Fusion (default k=2). Use FusionParams.rrf to override k.

---

695-696: Adding Query.fusion_params is backward compatible; verify precedence rules

Introducing fusion_params alongside the legacy Fusion enum in the same oneof is backwards compatible. Please ensure server-side validation clarifies behavior if clients mistakenly set both (oneof last-write-wins at decode time). If not already handled, consider rejecting requests that provide both in REST to avoid ambiguity.

lib/api/src/rest/schema.rs (1)

706-709: FusionQuery switches to FusionInterface — LGTM; doc follow-up

This enables both legacy string fusion and parameterized object forms. Consider updating any user-facing docs/snippets to show both shapes:

• "fusion": "rrf" (default k=2)
• "fusion": { "type": "rrf", "k": 60 }

lib/api/src/grpc/qdrant.rs (2)

5631-5641: RrfParams looks correct; suggest documenting the default.

The optional k with validation is good. Consider documenting that omission defaults to the legacy behavior (k=2) to avoid ambiguity in client usage.

 pub struct RrfParams {
-    /// K parameter for reciprocal rank fusion
+    /// K parameter for reciprocal rank fusion
+    /// If omitted, defaults to 2 (legacy behavior).
     #[prost(uint32, optional, tag = "1")]
     #[validate(range(min = 1))]
     pub k: ::core::option::Option<u32>,
 }

---

7142-7143: Clarify the legacy k=2 semantics in the Fusion enum doc.

The comment “with k=2” is accurate for the legacy enum-based fusion. Consider making “default k=2” explicit to reduce confusion alongside the new parameterized FusionParams.

-    /// Reciprocal Rank Fusion (with k=2)
+    /// Reciprocal Rank Fusion (default k=2). For custom k use `FusionParams::Rrf`.

lib/collection/benches/batch_query_bench.rs (1)

262-262: Switch to FusionInternal::RrfK(DEFAULT_RRF_K) is correct

Bench inputs now reflect the new internal enum shape. Optional: consider running the bench with a few k values (e.g., [1, 2, DEFAULT_RRF_K, 120]) to observe sensitivity of fusion latency/throughput to k.

lib/collection/src/tests/shard_query.rs (1)

5-5: Add a targeted test to exercise non-default k

Optional but useful: add a case that uses a small k (e.g., k=1) vs a large k to verify that fusion ordering/weights change as expected. This will catch regressions in parameter pluming and scoring sensitivity.

Also applies to: 62-62, 97-97, 144-144, 188-188

docs/grpc/docs.md (5)

170-170: Fix markdown list indentation (MD007).

markdownlint flags these list items for using 4 spaces. Align with 2-space indentation to satisfy MD007, unless this file is auto-generated and lint is intentionally ignored for it.

Also applies to: 251-251

---

2994-3007: Clarify FusionParams usage and defaults.

Document that FusionParams is the parameterized alternative to Fusion and that RRF’s k defaults to 2 when omitted.

-### FusionParams
-Parameterized fusion of multiple prefetches.
+### FusionParams
+Parameterized fusion of multiple prefetches. Use this to pass algorithm-specific parameters.
+If omitted, defaults are applied (for RRF, k defaults to 2).

 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| rrf | [RrfParams](#qdrant-RrfParams) |  | Reciprocal Rank Fusion |
+| rrf | [RrfParams](#qdrant-RrfParams) |  | Reciprocal Rank Fusion (set k to override the default; k ≥ 1) |

---

4031-4031: State mutual exclusivity for fusion vs fusion_params.

Add a short note that Query.fusion and Query.fusion_params are mutually exclusive (they occupy the same oneof).

-| fusion_params | [FusionParams](#qdrant-FusionParams) |  | Parameterized fusion of multiple prefetches. |
+| fusion_params | [FusionParams](#qdrant-FusionParams) |  | Parameterized fusion of multiple prefetches. Mutually exclusive with `fusion`. |

---

4419-4427: Document default and constraints for RrfParams.k.

Spell out default and minimum accepted value for k.

-### RrfParams
-Parameterized reciprocal rank fusion
+### RrfParams
+Parameterized reciprocal rank fusion. When omitted, `k` defaults to 2 (DEFAULT_RRF_K).

 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| k | [uint32](#uint32) | optional | K parameter for reciprocal rank fusion |
+| k | [uint32](#uint32) | optional | K parameter for reciprocal rank fusion (k ≥ 1; default 2) |

---

5252-5252: Cross-reference FusionParams for non-default k.

Help users discover how to customize k.

-| RRF | 0 | Reciprocal Rank Fusion (with k=2) |
+| RRF | 0 | Reciprocal Rank Fusion (with k=2). Use `FusionParams` → `RrfParams` to override `k`. |

docs/redoc/master/openapi.json (3)

15007-15010: Use of FusionInterface is correct; consider adding an inline example for clarity.

This change enables both legacy string and new object forms. Adding an example here will help users and codegen see the intended shapes immediately.

           "fusion": {
-            "$ref": "#/components/schemas/FusionInterface"
+            "$ref": "#/components/schemas/FusionInterface",
+            "example": { "type": "rrf", "k": 60 }
           }

---

15030-15036: Add a discriminator to FusionParams to improve SDK codegen and validation.

Declaring a discriminator on the tagged union helps generators produce sealed types and improves error messages.

       "FusionParams": {
-        "anyOf": [
+        "anyOf": [
           {
             "$ref": "#/components/schemas/RrfParams"
           }
-        ]
+        ],
+        "discriminator": {
+          "propertyName": "type",
+          "mapping": {
+            "rrf": "#/components/schemas/RrfParams"
+          }
+        }
       },

---

15037-15055: RrfParams.k: document the default (2) and add an example.

Server uses DEFAULT_RRF_K = 2 when k is unset. Make this explicit in the schema description and provide an example value.

       "RrfParams": {
         "type": "object",
         "required": [
           "type"
         ],
         "properties": {
           "type": {
             "$ref": "#/components/schemas/RrfType"
           },
           "k": {
-            "description": "K parameter for reciprocal rank fusion",
+            "description": "K parameter for reciprocal rank fusion. Defaults to 2 if omitted.",
             "default": null,
             "type": "integer",
             "format": "uint",
+            "example": 60,
             "minimum": 1,
             "nullable": true
           }
         }
       },

lib/collection/src/operations/universal_query/shard_query.rs (2)

60-60: Consider storing k as NonZeroU32 (or u32) to match API surface and invariants

Internal RrfK(usize) forces lossy casts to u32 at the API boundary and allows 0, which the proto forbids. Using NonZeroU32 (or plain u32) would remove casts and encode the invariant in the type.

Example enum pivot (requires touch-ups at call sites):

-    RrfK(usize),
+    RrfK(std::num::NonZeroU32),

Benefits: fewer casts, no silent truncation risk, and k ≥ 1 guaranteed by type.

---

563-584: Optional: Deduplicate Fusion→gRPC encoding between Query and query_shard_points::Query

Both impls are nearly identical. Consider extracting a small helper to DRY up the construction of Fusion/FusionParams with the k==DEFAULT_RRF_K fast-path. This reduces maintenance overhead.

If you want, I can sketch a small internal helper API to unify these two impls.

Also applies to: 586-608

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

💡 Knowledge Base configuration:

• MCP integration is disabled by default for public repositories
• Jira integration is disabled by default for public repositories
• Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

Learnt from: coszio
PR: qdrant/qdrant#7065
File: lib/collection/src/operations/universal_query/shard_query.rs:0-0
Timestamp: 2025-08-15T15:56:36.821Z
Learning: Internal gRPC APIs in Qdrant don't require additional runtime validation when proto-level validation is already configured via build.rs range constraints.

Learnt from: generall
PR: qdrant/qdrant#7006
File: lib/collection/src/operations/point_ops.rs:501-528
Timestamp: 2025-08-10T18:31:56.855Z
Learning: In Qdrant, batch operations validate that `ids`, `vectors`, and `payloads` (if present) have matching lengths at the REST API level in `lib/api/src/rest/validate.rs` through the `Validate` trait implementation for `Batch`. This validation happens before data is converted to internal structures like `PointInsertOperationsInternal`, so methods operating on these internal structures can safely assume the lengths match.

Learnt from: generall
PR: qdrant/qdrant#7006
File: docs/redoc/master/openapi.json:13645-13652
Timestamp: 2025-08-10T18:26:12.443Z
Learning: In qdrant, docs/redoc/master/openapi.json is auto-generated from the REST schemas. To change field docs, edit lib/api/src/rest/schema.rs (e.g., add doc comments or #[schemars(description = ...)]). Specifically, UpdateVectors.update_filter lacked a description and should state: "If specified, only update vectors for points that match this filter; points not matching the filter are left unchanged."

Learnt from: generall
PR: qdrant/qdrant#7006
File: docs/redoc/master/openapi.json:10393-10401
Timestamp: 2025-08-10T18:26:33.017Z
Learning: In qdrant, docs/redoc/master/openapi.json is auto-generated. Any description changes must be made in the source (e.g., lib/api/src/rest/schema.rs and/or lib/api/src/grpc/proto/points.proto), not edited directly in the JSON.

Learnt from: generall
PR: qdrant/qdrant#7006
File: docs/redoc/master/openapi.json:10626-10634
Timestamp: 2025-08-10T18:25:16.206Z
Learning: In Qdrant, docs/redoc/master/openapi.json is autogenerated from the Rust REST schema definitions (e.g., lib/api/src/rest/schema.rs). To change OpenAPI descriptions, update the Rust struct field doc comments/attributes rather than editing the JSON directly.

Learnt from: generall
PR: qdrant/qdrant#6854
File: lib/segment/src/index/query_estimator.rs:320-327
Timestamp: 2025-07-11T11:35:21.549Z
Learning: In test code for Qdrant's query estimator (lib/segment/src/index/query_estimator.rs), simplified ID resolution logic using `id.to_string().parse().unwrap()` is acceptable for testing purposes and doesn't need to match production code's `id_tracker.internal_id()` approach. Test code can use mock implementations that serve the testing goals.

lib/collection/src/operations/universal_query/shard_query.rs (1)

556-574: Avoid usize → u32 truncation when serializing k to gRPC

Current code uses k as u32 which will silently truncate large usize values. Clamp into the u32 domain to preserve correctness.

Apply this diff in both conversions:

-            FusionInternal::RrfK(k) => Query {
-                variant: Some(QueryVariant::Rrf(Rrf { k: Some(k as u32) })),
+            FusionInternal::RrfK(k) => Query {
+                variant: Some(QueryVariant::Rrf(Rrf {
+                    k: Some(k.min(u32::MAX as usize) as u32),
+                })),
             },

-            FusionInternal::RrfK(k) => Query {
-                score: Some(Score::Rrf(Rrf { k: Some(k as u32) })),
+            FusionInternal::RrfK(k) => Query {
+                score: Some(Score::Rrf(Rrf {
+                    k: Some(k.min(u32::MAX as usize) as u32),
+                })),
             },

Notes:

• From can’t fail; clamping is preferable to silent truncation.
• Longer-term, making k a u32/NonZeroU32 internally would remove this edge entirely.

Also applies to: 576-595

lib/api/src/grpc/proto/points.proto (2)

568-569: Clarify the “default parameters” note for RRF

Since a parameterized RRF is now available via Query.rrf, consider clarifying here that Fusion::RRF implies RRF with the default k (e.g., k=2). This will help clients choose between Fusion::RRF and the object form Query.rrf.

-    RRF = 0; // Reciprocal Rank Fusion (with default parameters)
+    RRF = 0; // Reciprocal Rank Fusion (uses default parameters, e.g. k=2)

---

672-676: Document k’s constraints and default

The field is optional and validated elsewhere; documenting the expected constraints here improves discoverability for SDK consumers.

-message Rrf {
-    optional uint32 k = 1; // K parameter for reciprocal rank fusion
-}
+message Rrf {
+    // K parameter for reciprocal rank fusion
+    // Must be >= 1. If not provided, the server uses a default (e.g., k=2).
+    optional uint32 k = 1;
+}

lib/collection/src/operations/universal_query/collection_query.rs (1)

726-731: Map REST RRF object to internal, but consider clamping/validating k

The REST layer validates k ≥ 1, but adding a small guard here would protect against accidental misuse if a future path bypassed REST validation.

-            FusionInternal::RrfK(k.unwrap_or(DEFAULT_RRF_K))
+            FusionInternal::RrfK(k.filter(|k| *k >= 1).unwrap_or(DEFAULT_RRF_K))

lib/api/src/rest/schema.rs (3)

519-524: Nit: consider documenting that this tag always deserializes to “rrf”

RrfType only has one variant, so requiring the field in JSON is a bit redundant unless you plan multiple RRF subtypes later.

Add a short doc comment, or make its presence optional (see next comment).

---

526-535: Make type optional and improve ergonomics; accept rrf_k as an alias

Requiring "type":"rrf" inside the object is redundant given the dedicated RRF wrapper. Also consider accepting rrf_k as an alias to ease migration from earlier examples.

 #[derive(Debug, Default, Serialize, Deserialize, JsonSchema, Validate)]
 #[serde(rename_all = "snake_case")]
 pub struct Rrf {
-    pub r#type: RrfType,
+    #[serde(default)]
+    pub r#type: RrfType,
 
     /// K parameter for reciprocal rank fusion
     #[validate(range(min = 1))]
-    #[serde(default)]
+    #[serde(default, alias = "rrf_k")]
     pub k: Option<usize>,
 }

---

537-542: Consider accepting both object shapes: { "type": "rrf", "k": ... } and { "rrf": { "k": ... } }

If you intend to support the nested/tagged shape discussed in the PR comments, you can accept both without breaking the existing object form.

 #[derive(Debug, Serialize, Deserialize, JsonSchema)]
 #[serde(untagged)]
 pub enum FusionInterface {
     Fusion(Fusion),
-    RRF(Rrf),
+    RRF(Rrf),
+    // Also accept the nested/tagged shape: { "rrf": { "k": ... } }
+    RrfTagged(RrfTagged),
 }

Add this helper outside of the changed hunk (for maintainers to apply):

#[derive(Debug, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub struct RrfTagged {
    pub rrf: Rrf,
}

Documentation: update examples to show both

• "fusion": "rrf"
• "fusion": { "type": "rrf", "k": 60 }
• "fusion": { "rrf": { "k": 60 } }

lib/api/src/grpc/qdrant.rs (2)

5631-5641: Consider documenting the default k in the proto comment

Nit: The doc says “K parameter for reciprocal rank fusion” but doesn’t mention the default (2). Adding that in the proto comment (not here, since this file is generated) will help SDK users.

---

7123-7126: Clarify Fusion::Rrf docs — nice touch

The note “with default parameters” makes it clear when to use the enum vs. the parameterized message. Consider also mentioning the default k value in the proto docs for extra clarity.

lib/collection/src/operations/universal_query/shard_query.rs (2)

60-60: Consider encoding k’s invariants in the type (NonZeroU32/u32) instead of usize

Storing k as usize forces repeated lossy casts to u32 at the gRPC boundary. Using u32 or NonZeroU32 internally would:

• Eliminate truncation risk at serialization time.
• Encode the k ≥ 1 invariant at the type level (if NonZeroU32), aligning with proto validation.

---

363-372: LGTM: Robust conversion from gRPC Rrf, defaulting to DEFAULT_RRF_K

Mapping Option -> usize with a default is fine here. Style nit: usize::from(k) avoids an as cast, but current code is clear enough.

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

💡 Knowledge Base configuration:

• MCP integration is disabled by default for public repositories
• Jira integration is disabled by default for public repositories
• Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

Learnt from: generall
PR: qdrant/qdrant#7006
File: lib/collection/src/operations/point_ops.rs:501-528
Timestamp: 2025-08-10T18:31:56.855Z
Learning: In Qdrant, batch operations validate that `ids`, `vectors`, and `payloads` (if present) have matching lengths at the REST API level in `lib/api/src/rest/validate.rs` through the `Validate` trait implementation for `Batch`. This validation happens before data is converted to internal structures like `PointInsertOperationsInternal`, so methods operating on these internal structures can safely assume the lengths match.

Learnt from: generall
PR: qdrant/qdrant#7006
File: docs/redoc/master/openapi.json:13645-13652
Timestamp: 2025-08-10T18:26:12.443Z
Learning: In qdrant, docs/redoc/master/openapi.json is auto-generated from the REST schemas. To change field docs, edit lib/api/src/rest/schema.rs (e.g., add doc comments or #[schemars(description = ...)]). Specifically, UpdateVectors.update_filter lacked a description and should state: "If specified, only update vectors for points that match this filter; points not matching the filter are left unchanged."

Learnt from: generall
PR: qdrant/qdrant#7006
File: docs/redoc/master/openapi.json:10393-10401
Timestamp: 2025-08-10T18:26:33.017Z
Learning: In qdrant, docs/redoc/master/openapi.json is auto-generated. Any description changes must be made in the source (e.g., lib/api/src/rest/schema.rs and/or lib/api/src/grpc/proto/points.proto), not edited directly in the JSON.

Learnt from: generall
PR: qdrant/qdrant#7006
File: docs/redoc/master/openapi.json:10626-10634
Timestamp: 2025-08-10T18:25:16.206Z
Learning: In Qdrant, docs/redoc/master/openapi.json is autogenerated from the Rust REST schema definitions (e.g., lib/api/src/rest/schema.rs). To change OpenAPI descriptions, update the Rust struct field doc comments/attributes rather than editing the JSON directly.

Learnt from: coszio
PR: qdrant/qdrant#7065
File: lib/collection/src/operations/universal_query/shard_query.rs:0-0
Timestamp: 2025-08-15T15:56:36.821Z
Learning: Internal gRPC APIs in Qdrant don't require additional runtime validation when proto-level validation is already configured via build.rs range constraints.

docs/grpc/docs.md (3)

250-250: Add Rrf to TOC — looks correct; watch markdownlint MD007 on this line

The anchor and placement are correct. markdownlint flagged ul-indent (expected 2 spaces, found 4). Since this file appears generated from proto docs, prefer ignoring markdownlint for generated docs or disabling MD007 for this path rather than hand-tweaking a single line which would make the TOC inconsistent with the rest.

If you want to silence the linter globally for generated gRPC docs, add docs/grpc/docs.md to the linter ignore, or disable MD007 for this path in your markdownlint config.

---

4015-4016: Clarify the purpose and defaults for the new rrf field on Query

Consider documenting that this field enables configurable RRF, its default when k is omitted, and the valid range for k.

Apply this diff to improve clarity (ideally via proto comments and re-generating this file):

-| rrf | [Rrf](#qdrant-Rrf) |  | Parameterized RRF fusion |
+| rrf | [Rrf](#qdrant-Rrf) |  | Reciprocal Rank Fusion with configurable k (defaults to 2; k must be ≥ 1) |

Note: If this file is generated, update the comment on the rrf field in points.proto and re-generate docs.

---

4402-4411: Document default and validation for Rrf.k

The new Rrf message is useful. Please surface the default (2) and the validation bound (k ≥ 1) to prevent guesswork by API consumers.

Apply this diff (preferably by changing proto comments and re-generating):

-### Rrf
-Parameterized reciprocal rank fusion
+### Rrf
+Reciprocal Rank Fusion (RRF) with configurable smoothing parameter.
@@
-| k | [uint32](#uint32) | optional | K parameter for reciprocal rank fusion |
+| k | [uint32](#uint32) | optional | Smoothing parameter k for RRF. Optional; defaults to 2 if unset. Must be ≥ 1. |

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

💡 Knowledge Base configuration:

• MCP integration is disabled by default for public repositories
• Jira integration is disabled by default for public repositories
• Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

lib/api/src/grpc/qdrant.rs (3)

5631-5641: Add RRF message with validation: good shape and semantics

Optional k with min ≥ 1 is appropriate and keeps backward compatibility by allowing omission (use default). One nit: consider documenting the default value for k here (e.g., “If omitted, defaults to 2”) so it propagates into generated docs for clients. That doc should be added in the .proto, not this generated file.

---

7123-7127: Doc tweak clarifies legacy Fusion enum usage

Updating the Fusion enum doc to “Reciprocal Rank Fusion (with default parameters)” is correct given the new parameterized path. Consider adding a short cross-reference in the .proto docs (not here) indicating “for parameterized RRF use the Query::Rrf message.”

---

5637-5641: Optional cap for k (non-blocking suggestion)

If you want guardrails against extreme values (e.g., accidental k=0 already blocked, but very large k could flatten weights), consider adding an upper bound in the validator (e.g., max = 65535). This is optional; the current type is correct.

docs/redoc/master/openapi.json (3)

15012-15021: Use oneOf instead of anyOf for FusionInterface to improve validation and codegen.

Only one of the two shapes can ever match (string enum vs object), so oneOf is a better semantic fit and yields clearer SDK types.

Apply this diff:

-      "FusionInterface": {
-        "anyOf": [
+      "FusionInterface": {
+        "oneOf": [
           {
             "$ref": "#/components/schemas/Fusion"
           },
           {
             "$ref": "#/components/schemas/Rrf"
           }
-        ]
+        ]
       },

---

15030-15048: Document and surface the default K (2) for RRF in the schema; add example for clarity.

Server defaults to K=2 if omitted. Reflecting this in OpenAPI avoids ambiguity and improves SDK DX. Keep nullable: true to preserve the ability to explicitly send null while code-generated clients still know the default when omitted.

Apply this diff:

       "Rrf": {
         "type": "object",
         "required": [
           "type"
         ],
         "properties": {
           "type": {
             "$ref": "#/components/schemas/RrfType"
           },
           "k": {
-            "description": "K parameter for reciprocal rank fusion",
-            "default": null,
+            "description": "K parameter for Reciprocal Rank Fusion. If omitted, defaults to 2.",
+            "default": 2,
             "type": "integer",
             "format": "uint",
             "minimum": 1,
             "nullable": true
           }
         }
+        ,
+        "example": {
+          "type": "rrf",
+          "k": 60
+        }
       },

---

15049-15054: Optional: Inline RrfType to reduce schema surface area.

RrfType is a single-value enum used only here. Consider inlining to cut indirection. Fine to keep as-is if it matches your schema style.

Example inline alternative (no change required if you prefer the current style):

-          "type": {
-            "$ref": "#/components/schemas/RrfType"
-          },
+          "type": {
+            "type": "string",
+            "enum": ["rrf"]
+          },

docs/grpc/docs.md (4)

250-250: TOC entry for Rrf looks correct; consider silencing markdownlint MD007 for generated docs

The anchor resolves to the new Rrf section. markdownlint flagged list indentation here (MD007), but indentation matches surrounding generated entries. Prefer excluding generated gRPC docs from lint or configuring MD007 rather than hand-editing this file.

If you want to silence the linter for generated files, add an ignore to your markdownlint config (example for markdownlint-cli2):

# .markdownlint-cli2.yaml
+globsIgnore:
+  - "docs/grpc/**"

---

4015-4016: Clarify precedence between Query.fusion (RRF) and Query.rrf

There are now two ways to request RRF: the Fusion enum with default parameters and the parameterized Rrf field. Please document precedence/mutual exclusivity (e.g., if rrf is set, it overrides Fusion=RRF, or they are mutually exclusive).

Since this file is generated from .proto comments, update the proto doc comments and regenerate. For example, adjust the field description:

-| rrf | [Rrf](#qdrant-Rrf) |  | Parameterized RRF fusion |
+| rrf | [Rrf](#qdrant-Rrf) |  | Parameterized RRF fusion. If provided, it takes precedence over `fusion = RRF` (default-parameter RRF). |

Would you like me to propose concrete .proto comment changes once you confirm the intended precedence?

---

5236-5236: Enum description tweak: cross-reference the parameterized Rrf

The “with default parameters” note is good. Consider adding a short pointer to the new Rrf message so users discover how to customize k.

Apply via proto comments (regenerate docs):

-| RRF | 0 | Reciprocal Rank Fusion (with default parameters) |
+| RRF | 0 | Reciprocal Rank Fusion (with default parameters). See [Rrf](#qdrant-Rrf) to customize `k`. |

---

4402-4411: Document k constraints and default in Rrf proto

To surface validation and default behavior in the generated docs, update the .proto comment for k in lib/api/src/grpc/proto/points.proto:

• File: lib/api/src/grpc/proto/points.proto

   message Rrf {

• optional uint32 k = 1; // K parameter for reciprocal rank fusion

• optional uint32 k = 1; // K parameter for reciprocal rank fusion (must be ≥ 1, defaults to 2)
  }

This change ensures the docs show:
- “k must be ≥ 1” (enforced by `build.rs`/validators), and  
- “default = 2” (from `DEFAULT_RRF_K`)  

After updating this comment, regenerate the gRPC docs to apply.

</blockquote></details>

</blockquote></details>

<details>
<summary>📜 Review details</summary>

**Configuration used: CodeRabbit UI**
**Review profile: CHILL**
**Plan: Pro**

**💡 Knowledge Base configuration:**

- MCP integration is disabled by default for public repositories
- Jira integration is disabled by default for public repositories
- Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

<details>
<summary>📥 Commits</summary>

Reviewing files that changed from the base of the PR and between 5986c0fdca6de1b02619066b753a0a4e66f2abd3 and a018d669ced233d13119bb314351849c1fc85141.

</details>

<details>
<summary>📒 Files selected for processing (19)</summary>

* `docs/grpc/docs.md` (4 hunks)
* `docs/redoc/master/openapi.json` (2 hunks)
* `lib/api/build.rs` (1 hunks)
* `lib/api/src/grpc/proto/points.proto` (3 hunks)
* `lib/api/src/grpc/proto/points_internal_service.proto` (1 hunks)
* `lib/api/src/grpc/qdrant.rs` (5 hunks)
* `lib/api/src/grpc/validate.rs` (1 hunks)
* `lib/api/src/rest/schema.rs` (2 hunks)
* `lib/api/src/rest/validate.rs` (2 hunks)
* `lib/collection/benches/batch_query_bench.rs` (2 hunks)
* `lib/collection/src/collection/query.rs` (1 hunks)
* `lib/collection/src/operations/universal_query/collection_query.rs` (1 hunks)
* `lib/collection/src/operations/universal_query/planned_query.rs` (6 hunks)
* `lib/collection/src/operations/universal_query/shard_query.rs` (8 hunks)
* `lib/collection/src/shards/local_shard/query.rs` (1 hunks)
* `lib/collection/src/tests/shard_query.rs` (5 hunks)
* `lib/segment/src/common/reciprocal_rank_fusion.rs` (4 hunks)
* `src/common/inference/batch_processing_grpc.rs` (1 hunks)
* `src/common/inference/query_requests_grpc.rs` (1 hunks)

</details>

<details>
<summary>🚧 Files skipped from review as they are similar to previous changes (16)</summary>

* lib/api/src/grpc/proto/points_internal_service.proto
* lib/collection/src/collection/query.rs
* lib/api/src/grpc/validate.rs
* src/common/inference/query_requests_grpc.rs
* lib/collection/benches/batch_query_bench.rs
* lib/api/src/grpc/proto/points.proto
* lib/api/build.rs
* lib/collection/src/operations/universal_query/planned_query.rs
* src/common/inference/batch_processing_grpc.rs
* lib/collection/src/operations/universal_query/collection_query.rs
* lib/collection/src/tests/shard_query.rs
* lib/api/src/rest/validate.rs
* lib/collection/src/shards/local_shard/query.rs
* lib/segment/src/common/reciprocal_rank_fusion.rs
* lib/api/src/rest/schema.rs
* lib/collection/src/operations/universal_query/shard_query.rs

</details>

<details>
<summary>🧰 Additional context used</summary>

<details>
<summary>🪛 markdownlint-cli2 (0.17.2)</summary>

<details>
<summary>docs/grpc/docs.md</summary>

250-250: Unordered list indentation
Expected: 2; Actual: 4

(MD007, ul-indent)

</details>

</details>

</details>

<details>
<summary>🔇 Additional comments (3)</summary><blockquote>

<details>
<summary>lib/api/src/grpc/qdrant.rs (2)</summary>

`10177-10180`: **Extend QueryShardPoints::Query.Score tags to include 7: OK**

Tag addition looks correct and maintains existing tags. No collisions observed.

---

`5647-5649`: **Validation for Rrf is wired, conversions need manual confirmation**

- lib/api/src/grpc/validate.rs includes  
`grpc::query::Variant::Rrf(q) => q.validate()`  
so inbound validation is in place.

I couldn’t locate the gRPC↔internal conversion implementations for the new Rrf variant. Please verify (or add) in your conversion modules that:

• Inbound (gRPC→internal):  
  grpc::query::Variant::Rrf(q)  
    → `FusionInternal::RrfK(q.k.unwrap_or(DEFAULT_RRF_K))`

• Outbound (internal→gRPC), for both Query and QueryShardPoints:  
  – `FusionInternal::RrfK(k) if k == DEFAULT_RRF_K`  
     → `grpc::query::Variant::Rrf`  
  – `FusionInternal::RrfK(k) if k != DEFAULT_RRF_K`  
     → `grpc::query::Variant::Fusion(Rrf(k as i32))`

Ensure these mappings live alongside your other `TryFrom`/`From` impls (e.g. in lib/api/src/grpc/convert_*.rs).

</details>
<details>
<summary>docs/redoc/master/openapi.json (1)</summary>

`15007-15010`: **LGTM: FusionQuery now references FusionInterface (backward compatible).**

This cleanly enables both the legacy string enum and the new object form without breaking existing clients.

</details>

</blockquote></details>

</details>

<!-- This is an auto-generated comment by CodeRabbit for review status -->

lib/api/src/grpc/qdrant.rs (1)

5631-5641: RRF message + k validation added: looks good; confirm upstream defaulting and guardrails

Introducing Rrf { k: Option<u32> } with #[validate(range(min = 1))] is correct for payload validation. Please ensure:

• None is resolved to DEFAULT_RRF_K.
• Some(0) (or any non-positive) is rejected in the internal conversion path as previously discussed.

This was raised earlier for TryFrom<grpc::Rrf> for FusionInternal and still applies here.

#!/bin/bash
set -euo pipefail

# 1) Validate that gRPC validators call q.validate() for the new Query::Rrf path (top-level)
rg -n -C3 'query::Variant::Rrf\(' lib/api/src/grpc/validate.rs || true

# 2) Validate that gRPC validators call q.validate() for the shard scoring path
rg -n -C3 'query::Score::Rrf\(' lib/api/src/grpc/validate.rs || true

# 3) Check TryFrom<grpc::Rrf> mapping validates k > 0,
#    defaults to DEFAULT_RRF_K when None, and maps to FusionInternal::RrfK
rg -n -C5 'impl\s+TryFrom<.*grpc::Rrf.*>\s+for\s+.*' lib -g '!**/target/**' || true
rg -n -C5 'FusionInternal::RrfK' lib/collection/src/operations/universal_query/shard_query.rs || true
rg -n -C5 'DEFAULT_RRF_K' lib/collection/src/operations/universal_query/shard_query.rs || true

# 4) Ensure rrf_scoring takes k and is fed properly
rg -n -C3 'rrf_scoring\s*\(' lib -g '!**/target/**' || true

lib/api/src/grpc/qdrant.rs (1)

7123-7123: Doc nit: consider stating the actual default k (2) explicitly

The comment “with default parameters” could be made more explicit to reduce ambiguity, e.g., “with default k=2”.

docs/grpc/docs.md (4)

250-250: ToC entry for Rrf looks good; watch markdownlint MD007 (indent).

The new entry links to the correct anchor. However, markdownlint flagged unordered list indentation at this position (Expected: 2; Actual: 4). If this file is generated, consider excluding docs/grpc from linting or adjusting the rule; otherwise, re-indent to satisfy MD007.

---

4015-4016: Clarify how Query.rrf interacts with Query.fusion (precedence and defaults).

Having both a Fusion enum and an Rrf message can confuse users about which one to set and what happens if both are provided. Recommend stating that rrf enables RRF with an optional k, that the default is used when unspecified, and which takes precedence when both are set.

Apply this diff to expand the description inline:

-| rrf | [Rrf](#qdrant-Rrf) |  | Parameterized reciprocal rank fusion |
+| rrf | [Rrf](#qdrant-Rrf) |  | Parameterized reciprocal rank fusion. When set, enables RRF with optional k. If omitted and `fusion` = RRF is set, the default k is used. If both are set, `rrf.k` takes precedence. |

---

4404-4411: Document validation and default for Rrf.k (min and default).

The docs should state constraints and defaults to prevent misuse and align with the implementation (k ≥ 1, default k = 2).

Apply this diff:

 ### Rrf
-Parameterized reciprocal rank fusion
+Parameterized reciprocal rank fusion
+
+Default: k = 2. Validation: k must be >= 1.

 | Field | Type | Label | Description |
 | ----- | ---- | ----- | ----------- |
-| k | [uint32](#uint32) | optional | K parameter for reciprocal rank fusion |
+| k | [uint32](#uint32) | optional | K parameter for reciprocal rank fusion (min: 1, default: 2) |

---

5236-5236: Make Fusion enum doc explicit about the default k.

Since RRF now has a configurable k, calling out the default value in the enum description improves clarity.

Apply this diff:

-| RRF | 0 | Reciprocal Rank Fusion (with default parameters) |
+| RRF | 0 | Reciprocal Rank Fusion (default k = 2) |

docs/redoc/master/openapi.json (4)

14813-14815: Query shape for parameterized RRF diverges from PR examples—confirm intended UX and update docs accordingly

The schema adds RrfQuery as a top-level query variant ({ "rrf": { "k": ... } }). The PR text and discussion also mention shapes under fusion, e.g.:

• {"query":{"fusion":{"type":"rrf","k":60}}} (tagged)
• or nested {"query":{"fusion":{"rrf":{"k":123}}}}.

As modeled, the valid payloads per this OpenAPI are:

• Shorthand: {"query":{"fusion":"rrf"}}
• Parameterized: {"query":{"rrf":{"k":60}}}

If this is the finalized shape, please align the PR description and docs with the top-level rrf variant. If instead the goal is to nest RRF under fusion, the schema should be refactored to model a tagged/nested union under fusion rather than a separate RrfQuery variant.

---

15016-15021: Update Fusion description to reflect configurable RRF k (default 2), not fixed k=2

The current description still says “rrf — ... (with k=2)”, which can mislead users now that k is configurable.

Apply this diff to adjust the description:

-        "description": "Fusion algorithm allows to combine results of multiple prefetches.\n\nAvailable fusion algorithms:\n\n* `rrf` - Reciprocal Rank Fusion (with k=2) * `dbsf` - Distribution-Based Score Fusion",
+        "description": "Fusion algorithm allows combining results of multiple prefetches.\n\nAvailable fusion algorithms:\n\n* `rrf` - Reciprocal Rank Fusion (k configurable, default 2)\n* `dbsf` - Distribution-Based Score Fusion",

---

15023-15033: Add a short description to RrfQuery for clarity in generated docs/SDKs

Adding a description helps generated clients and documentation.

       "RrfQuery": {
+        "description": "Perform Reciprocal Rank Fusion with optional parameters.",
         "type": "object",
         "required": [
           "rrf"
         ],
         "properties": {
           "rrf": {
             "$ref": "#/components/schemas/Rrf"
           }
         }
       },

---

15035-15047: Consider documenting the default k=2 on the Rrf schema (and optionally set default to 2)

Server-side defaults to k=2 when omitted. Reflecting that here improves client UX and codegen. Option A only updates description; Option B also sets a default.

Option A (description only):

       "Rrf": {
         "description": "Parameters for Reciprocal Rank Fusion",
         "type": "object",
         "properties": {
           "k": {
-            "description": "K parameter for reciprocal rank fusion",
+            "description": "K parameter for reciprocal rank fusion. Default is 2.",
             "default": null,
             "type": "integer",
             "format": "uint",
             "minimum": 1,
             "nullable": true
           }
         }
       },

Option B (set default, keep nullable if server accepts explicit null):

           "k": {
-            "description": "K parameter for reciprocal rank fusion",
-            "default": null,
+            "description": "K parameter for reciprocal rank fusion. Default is 2.",
+            "default": 2,
             "type": "integer",
             "format": "uint",
             "minimum": 1,
             "nullable": true
           }

If the server treats explicit null the same as omission (i.e., use default), Option B is safe; otherwise prefer Option A.

src/common/inference/query_requests_rest.rs (1)

269-270: Add conversion tests for RRF (custom k and default parity)

To lock in the behavior of both payload shapes and ensure defaulting remains consistent, please append the following tests to the bottom of the tests module in src/common/inference/query_requests_rest.rs:

#[test]
fn test_convert_query_with_inferred_rrf_custom_k() {
    let inferred = create_test_inferred_batch();
    let query = rest::QueryInterface::Query(rest::Query::Rrf(rest::RrfQuery {
        rrf: rest::Rrf { k: Some(60) },
    }));

    let result = super::convert_query_with_inferred(query, &inferred).unwrap();
    match result {
        Query::Fusion(FusionInternal::RrfK(k)) => assert_eq!(k, 60),
        other => panic!("Expected Fusion::RrfK(60), got {:?}", other),
    }
}

#[test]
fn test_convert_query_with_inferred_rrf_default_matches_shorthand() {
    let inferred = create_test_inferred_batch();

    // Nested RRF with no k (should use default)
    let nested = rest::QueryInterface::Query(rest::Query::Rrf(rest::RrfQuery {
        rrf: rest::Rrf { k: None },
    }));

    // Shorthand "fusion": "rrf" (should use the same default)
    let shorthand = rest::QueryInterface::Query(rest::Query::Fusion(rest::FusionQuery {
        fusion: rest::Fusion::Rrf,
    }));

    let nested_res = super::convert_query_with_inferred(nested, &inferred).unwrap();
    let shorthand_res = super::convert_query_with_inferred(shorthand, &inferred).unwrap();

    let k_nested = match nested_res {
        Query::Fusion(FusionInternal::RrfK(k)) => k,
        other => panic!("Expected Fusion::RrfK(_), got {:?}", other),
    };
    let k_short = match shorthand_res {
        Query::Fusion(FusionInternal::RrfK(k)) => k,
        other => panic!("Expected Fusion::RrfK(_), got {:?}", other),
    };

    assert_eq!(k_nested, k_short, "Default k must be equal across both shapes");
}

These tests will ensure:

• A custom k is passed through correctly.
• The default k used in nested RRF matches the default when using the Fusion shorthand.

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

💡 Knowledge Base configuration:

• MCP integration is disabled by default for public repositories
• Jira integration is disabled by default for public repositories
• Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

Learnt from: generall
PR: qdrant/qdrant#7006
File: lib/collection/src/operations/point_ops.rs:501-528
Timestamp: 2025-08-10T18:31:56.855Z
Learning: In Qdrant, batch operations validate that `ids`, `vectors`, and `payloads` (if present) have matching lengths at the REST API level in `lib/api/src/rest/validate.rs` through the `Validate` trait implementation for `Batch`. This validation happens before data is converted to internal structures like `PointInsertOperationsInternal`, so methods operating on these internal structures can safely assume the lengths match.

docs/redoc/master/openapi.json (2)

15016-15022: Clarify Fusion doc to point users to RrfQuery for custom k

The description says “rrf … with default parameters”, but doesn’t tell users how to pass custom parameters. Add a one-liner to steer them to the new RrfQuery shape to reduce ambiguity.

Proposed diff:

       "Fusion": {
-        "description": "Fusion algorithm allows to combine results of multiple prefetches.\n\nAvailable fusion algorithms:\n\n* `rrf` - Reciprocal Rank Fusion (with default parameters) * `dbsf` - Distribution-Based Score Fusion",
+        "description": "Fusion algorithm allows to combine results of multiple prefetches.\n\nAvailable fusion algorithms:\n\n* `rrf` - Reciprocal Rank Fusion (with default parameters)\n* `dbsf` - Distribution-Based Score Fusion\n\nNote:\n- Use the shorthand string form `\"fusion\": \"rrf\"` to apply defaults (k=2).\n- To customize RRF parameters, use the dedicated RrfQuery variant: `{ \"rrf\": { \"k\": <uint>=2 } }`.",
         "type": "string",
         "enum": [
           "rrf",
           "dbsf"
         ]
       },

---

15023-15047: RrfQuery/Rrf schema looks good; consider documenting default and adding examples

• k uses unsigned integer with minimum 1 and nullable for “use default” – aligns with server validation and defaulting behavior. Nice.
• Minor doc polish: explicitly state the default (2) and add examples to improve SDK codegen docs and UX.

Proposed diff:

       "RrfQuery": {
         "type": "object",
         "required": [
           "rrf"
         ],
         "properties": {
           "rrf": {
             "$ref": "#/components/schemas/Rrf"
           }
-        }
+        },
+        "example": { "rrf": { "k": 60 } }
       },
       "Rrf": {
-        "description": "Parameters for Reciprocal Rank Fusion",
+        "description": "Parameters for Reciprocal Rank Fusion. If `k` is omitted or null, the server uses the default k=2.",
         "type": "object",
         "properties": {
           "k": {
             "description": "K parameter for reciprocal rank fusion",
             "default": null,
             "type": "integer",
             "format": "uint",
             "minimum": 1,
-            "nullable": true
+            "nullable": true,
+            "example": 60
           }
         }
       },

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

💡 Knowledge Base configuration:

• MCP integration is disabled by default for public repositories
• Jira integration is disabled by default for public repositories
• Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.