microsoft/semantic-kernel · error · VectorStoreModelException

Hybrid search requires 'keyword_field_name' in options.

Error message

Hybrid search requires 'keyword_field_name' in options.

What it means

Raised by the Azure Cosmos DB NoSQL vector store when a KEYWORD_HYBRID search is requested but no keyword/text field is configured. The hybrid path builds an RRF() clause combining VectorDistance and FullTextScore(c.<text_field>, @keywords); FullTextScore needs a concrete text column to score against. Without a configured keyword field the SQL cannot be generated, so the store aborts before issuing the query. This is a VectorStoreModelException, signaling a misconfigured data model / options, not a transient runtime fault.

Source

Thrown at python/semantic_kernel/connectors/azure_cosmos_db.py:838

                else f"WHERE ({' AND '.join(rendered_clauses)}) "
            )
        vector_field_name = vector_field.storage_name or vector_field.name
        select_clause = self._build_select_clause(options.include_vectors)
        params.append({"name": "@vector", "value": vector})
        if vector_field.distance_function not in DISTANCE_FUNCTION_MAP_NOSQL:
            raise VectorStoreModelException(
                f"Distance function '{vector_field.distance_function}' is not supported by Azure Cosmos DB NoSQL."
            )
        # Cosmos DB VectorDistance function only accepts 2 parameters: field and vector
        # Distance function is configured in the vector index, not in the query
        if search_type == SearchType.VECTOR:
            distance_clause = f"VectorDistance(c.{vector_field_name}, @vector)"
        elif search_type == SearchType.KEYWORD_HYBRID:
            # Hybrid search: requires both a vector and keywords
            params.append({"name": "@keywords", "value": values})
            text_field = options.additional_property_name
            if not text_field:
                raise VectorStoreModelException("Hybrid search requires 'keyword_field_name' in options.")
            distance_clause = (
                f"RRF(VectorDistance(c.{vector_field_name}, @vector), FullTextScore(c.{text_field}, @keywords))"
            )
        else:
            raise VectorStoreModelException(f"Search type '{search_type}' is not supported.")
        query = (
            f"SELECT TOP @top {select_clause}, "  # nosec: B608
            f"{distance_clause} as {NOSQL_SCORE_PROPERTY_NAME} "  # nosec: B608
            "FROM c "
            f"{where_clauses}"  # nosec: B608
            f"ORDER BY {distance_clause}"  # nosec: B608
        )

        container_proxy = await self._get_container_proxy(self.collection_name, **kwargs)
        try:
            results = container_proxy.query_items(query, parameters=params)
        except Exception as exc:
            raise VectorSearchExecutionException("Failed to search items.") from exc

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Set the keyword field when building options: VectorSearchOptions(additional_property_name="description") (or keyword_field_name alias), pointing at a text property that exists in your data model and is covered by a full-text policy/index.
2. Ensure that text field is declared in the record data model and that the container's indexing policy enables full-text search on it before issuing hybrid queries.
3. If you only need pure vector similarity, call search with SearchType.VECTOR instead of KEYWORD_HYBRID so the keyword field is not required.

Example fix

// before
results = await store.search(vector, VectorSearchOptions(top=5))  # search_type defaults but hybrid keyword field missing
// after
results = await store.search(
    vector,
    VectorSearchOptions(top=5, additional_property_name="description"),
)

opts = VectorSearchOptions(top=5, additional_property_name="description")
assert opts.additional_property_name, "Hybrid search requires a keyword field"
# only then:
results = await store.search(vector, options=opts)

def is_hybrid_ready(store, options: VectorSearchOptions) -> bool:
    return (
        options.additional_property_name is not None
        and options.additional_property_name in store.definition.storage_names
    )

When it happens

Trigger: Calling _inner_search (via the public search API) with search_type=SearchType.KEYWORD_HYBRID while VectorSearchOptions.additional_property_name is None or unset. This field (aliased as keyword_field_name) selects which string property FullTextScore runs against; if it is missing the check at azure_cosmos_db.py:836-838 fires.

Common situations: You added hybrid search to an existing vector-only collection but forgot to designate a text field for full-text indexing, or you reuse a VectorSearchOptions object that was built for a pure vector query. Also happens when the data model has no full-text-searchable text field defined, or after upgrading where the option key changed naming.

Related errors

• Search type '{search_type}' is not supported.
• Distance function '{field.distance_function}' is not support
• The collection name is required, can be passed directly or t
• Failed to create Azure CosmosDB for MongoDB settings.
• The name of the Azure Cosmos DB NoSQL database is missing.

AI-assisted analysis of microsoft/semantic-kernel@c028a0c7dc (2026-08-13). Data as JSON: /api/errors/845d16ab070d9ac4. Report an issue: GitHub.