Share via

Timeline for Hierarchical Facets GA in Azure AI Search and risks of using Preview feature

Arunkumar B 0 Reputation points
2026-03-04T05:42:48.4533333+00:00

We noticed that Hierarchical Facets are currently available in preview in Azure AI Search. This feature is very useful for our scenario where we need multi-level facets (for example: Region → Country) similar to nested aggregations in Elasticsearch.

Before adopting this feature, we would like clarification on the following:

  1. Is there an estimated timeline for when Hierarchical Facets will reach GA (stable release)?
  2. What are the implications of using the preview feature in production, such as possible breaking changes, SLA limitations, or performance considerations?
  3. If we implement queries using the preview API now, is it likely that query structure or response format may change when the feature becomes GA?

Any guidance from the Azure AI Search team on the roadmap and recommended approach would be helpful for our implementation planning.

Azure AI Search
Azure AI Search

An Azure search service with built-in artificial intelligence capabilities that enrich information to help identify and explore relevant content at scale.

0 comments

1 answer

Sort by: Most helpful
Most helpful Newest Oldest
  1. Q&A Assist
    2026-03-04T05:43:04.68+00:00
    AI generated content. This question contains an answer created with AI from Q&A Assist. Learn more
    1. There is no published or committed timeline in the documentation for when hierarchical facets will reach GA. The feature is currently documented as a preview capability exposed via the Search Documents (2025-03-01-preview) API version and is listed under “Facet hierarchies, aggregations, and facet filters (preview).” GA and retirement announcements are communicated via the Azure AI Search “What’s new” and “Service Updates” pages, not as specific dates in the feature docs.
    2. Implications of using the preview feature in production:
      • Preview contractual terms and support:
        • Preview features are provided under separate Supplemental Terms of Use and are not covered by a service level agreement.
        • Preview features are not meant for production use and are not supported by Microsoft Support for production scenarios; support is best-effort and focused on feedback.
        • Functionality can be limited or restricted and may not be available in all regions.
      • Stability and breaking changes:
        • Preview features might undergo breaking changes if redesign is required.
        • Some preview features may never ship as GA.
      • API-version dependency:
        • Hierarchical facets, facet filters, and facet aggregations are only available through preview data-plane APIs (currently 2025-03-01-preview for search). Preview API versions are cumulative and roll up to the next preview; using them in production couples the application to a non-stable API surface.
      • General performance considerations:
        • The documentation does not call out specific performance penalties for hierarchical facets, but as with any preview feature, behavior and performance characteristics may evolve across preview versions.
    3. Likelihood of query/response changes when moving from preview to GA:
      • The documentation explicitly states that preview features might undergo breaking changes and that code written against preview APIs should be prepared for upgrades to newer API versions.
      • An “Upgrade REST APIs” guide is maintained specifically to help migrate from one API version to another, which implies that request/response shapes, parameters, or behavior can change between preview and later versions.
      • Because hierarchical facets are only documented on preview APIs, both the query structure (facet parameters, new query options) and response format (facet structures, aggregations, filters) should be treated as subject to change until the feature is GA.

    Recommended planning approach based on the docs:

    • Use the latest preview search API version (currently Search Documents (2025-03-01-preview)) to access hierarchical facets and related capabilities.
    • Architect the application so that facet query construction and response parsing are isolated behind an internal abstraction, making it easier to adapt to breaking changes in preview or GA.
    • Track the Azure AI Search “What’s new” page and Service Updates for GA or behavior-change announcements, and plan to follow the “Upgrade REST APIs” guidance when moving from preview to GA.
    • Avoid hard production dependencies on preview behavior where possible, or plan explicit test and migration windows when new preview or GA versions are released.

    References:

    0 comments

Your answer

Answers can be marked as 'Accepted' by the question author and 'Recommended' by moderators, which helps users know the answer solved the author's problem.