apache/beam · error · ValueError

Approximate Nearest Neighbor Search (ANNS) field must be pro

Error message

Approximate Nearest Neighbor Search (ANNS) field must be provided

What it means

MilvusSearchParameters.__post_init__ validates the dataclass after construction. Milvus ANN search requires an `anns_field` naming the vector field to search against; if it is empty (the default_factory str), a ValueError is raised immediately.

Source

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

    limit: Maximum number of results to return per query. Must be positive.
      Defaults to 3 search results.
    filter: Boolean expression string for filtering search results.
      Example: 'price <= 1000 AND category == "electronics"'.
    search_params: Additional search parameters specific to the search type.
      Example: {"metric_type": VectorSearchMetrics.EUCLIDEAN_DISTANCE}.
    consistency_level: Consistency level for read operations.
      Options: "Strong", "Session", "Bounded", "Eventually". Defaults to
      "Bounded" if not specified when creating the collection.
  """
  anns_field: str
  limit: int = 3
  filter: str = field(default_factory=str)
  search_params: dict[str, Any] = field(default_factory=dict)
  consistency_level: Optional[str] = None

  def __post_init__(self):
    if not self.anns_field:
      raise ValueError(
          "Approximate Nearest Neighbor Search (ANNS) field must be provided")

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


@dataclass
class VectorSearchParameters(BaseSearchParameters):
  """Parameters for vector similarity search operations.

  Inherits all parameters from BaseSearchParameters with the same semantics.
  The anns_field should contain dense vector embeddings for this search type.

  Args:
    kwargs: Optional keyword arguments for additional vector search parameters.
      Enables forward compatibility.

  Note:

View on GitHub (pinned to 12126d8942)

Solutions

1. Pass anns_field='<name of your vector field>' when constructing MilvusSearchParameters.
2. Check the Milvus collection schema (Collection.schema / describe_collection) to find the vector field name.
3. Add a config check that asserts anns_field is non-empty before building the dataclass.

Example fix

// before
params = MilvusSearchParameters(collection_name='docs', search_params={...})
// after
params = MilvusSearchParameters(collection_name='docs', anns_field='embedding', search_params={...})

assert params.get('anns_field'), 'anns_field (Milvus vector field name) must be set'

try:
    search_params = MilvusSearchParameters(**cfg)
except ValueError as e:
    logging.error('Milvus search params invalid: %s', e)
    raise

When it happens

Trigger: Constructing MilvusSearchParameters(collection_name='x', ...) without passing anns_field, or passing anns_field='' — e.g. relying on defaults instead of naming the collection's vector column.

Common situations: Milvus collections with a vector field not named the library's default; migrating configs from other vector DBs that don't need an anns field; copying examples that omit it.

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
• Ranker must be provided for hybrid search
• 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/bfa1a8f0bf8c7ba5. Report an issue: GitHub.