apache/beam · error · ValueError

Ranker must be provided for hybrid search

Error message

Ranker must be provided for hybrid search

What it means

Hybrid search must know how to fuse vector and keyword result lists, so HybridSearchParameters requires a `ranker` (e.g. RRFRanker or WeightedRanker). __post_init__ raises ValueError when the ranker field is falsy (None or not provided).

Source

Thrown at sdks/python/apache_beam/ml/rag/enrichment/milvus_search.py:204

    limit: Maximum number of results to return per query. Defaults to 3 search
      results.
    kwargs: Optional keyword arguments for additional hybrid search parameters.
      Enables forward compatibility.
  """
  vector: VectorSearchParameters
  keyword: KeywordSearchParameters
  ranker: MilvusBaseRanker
  limit: int = 3
  kwargs: dict[str, Any] = field(default_factory=dict)

  def __post_init__(self):
    if not self.vector or not self.keyword:
      raise ValueError(
          "Vector and keyword search parameters must be provided for "
          "hybrid search")

    if not self.ranker:
      raise ValueError("Ranker must be provided for hybrid search")

    if self.limit <= 0:
      raise ValueError(f"Search limit must be positive, got {self.limit}")


SearchStrategyType = Union[VectorSearchParameters,
                           KeywordSearchParameters,
                           HybridSearchParameters]


@dataclass
class MilvusSearchParameters:
  """Parameters configuring Milvus search operations.

  This class encapsulates all parameters needed to execute searches against
  Milvus collections, supporting vector, keyword, and hybrid search strategies.

  Args:

View on GitHub (pinned to 12126d8942)

Solutions

1. Pass a ranker instance, e.g. ranker=RRFRanker() or WeightedRanker(0.7, 0.3).
2. Import the ranker from pymilvus (pymilvus.model.reranker or milvus hybrid-search API) and instantiate it.
3. Ensure you pass an instance, not the class (RRFRanker, not RRFRanker).

Example fix

// before
params = HybridSearchParameters(vector=v, keyword=k)  # ranker missing
// after
params = HybridSearchParameters(vector=v, keyword=k, ranker=RRFRanker())

from pymilvus.model.reranker import RRFRanker
assert ranker is not None, 'Hybrid search requires a ranker instance'

try:
    params = HybridSearchParameters(vector=v, keyword=k, ranker=ranker)
except ValueError as e:
    logging.error('Hybrid search params invalid: %s', e)
    raise

When it happens

Trigger: HybridSearchParameters(vector=..., keyword=...) constructed without passing a ranker instance, or ranker=None explicitly.

Common situations: Following older Milvus API examples where the ranker was optional; forgetting to import pymilvus ranker classes; passing the ranker class instead of an instance.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• Vector and keyword search parameters must be provided for hy
• Approximate Nearest Neighbor Search (ANNS) field must be pro
• Collection name must be provided
• Search limit must be positive, got {self.limit}
• Search strategy must be provided

AI-assisted analysis of apache/beam@12126d8942 (2026-09-13). Data as JSON: /api/errors/b7644a6a70dcb55f. Report an issue: GitHub.