Why a facet count may not equal a visible page
A museum catalog can combine keyword search with vector similarity so visitors find exhibits despite different phrasing. Hybrid retrieval, however, creates multiple candidate sets before ranking them together. A number displayed beside a facet such as “Textiles” may describe a broader population than the first page of visible ranked hits. Azure AI Search documents a preview setting named `countAndFacetMode` for controlling how text-side matches contribute to counts and facets when `maxTextRecallSize` limits the text candidates considered by hybrid ranking. This is an explanation problem, not proof that some records are missing or inaccessible. The examples here use hypothetical catalog rows; no Azure service was queried.
Start with the exact query and index schema
Save the query text, vector query configuration, filters, selected fields, and API version before comparing any counts. The text fields must be searchable to contribute text retrieval, while facet fields must be explicitly facetable in the index schema. A filter that excludes embargoed records changes the eligible population independently of how `countAndFacetMode` works. Keep public permissions enforced upstream and in the service architecture; do not use displayed counts as a substitute for authorization. For an audit, choose a small fixed set of test queries, including an uncommon accession term, an ordinary topic name, and a deliberately ambiguous subject query.
Understand the maxTextRecallSize window
The preview `maxTextRecallSize` control sets how many BM25-ranked results are passed from the text portion of a hybrid search into the subsequent ranking process. Microsoft’s current documentation describes a supported range from 1 to 10,000 and a default of 1,000 for the referenced preview API. Increasing the window can change which candidates compete with the vector results and can increase resource use or latency. It does not automatically make the results factual or expand a user’s permissions. Record the chosen value alongside the query and index version; otherwise two legitimate tests may appear contradictory even though they used different candidate windows.
Choose between two documented count modes
The preview API defines `countAllResults` and `countRetrievableResults`. The first includes all documents matched by the text search when calculating count and facets, whether or not those matches fall inside the text retrieval window. The second limits the text contribution to documents retrieved within `maxTextRecallSize`. Vector contributions are governed separately by the vector query and its `k` candidates. Avoid asserting that one number is universally “more correct”; the chosen number answers a different measurement question. Label the interface accordingly and verify the precise API contract in the SDK or REST version being used.
Use a transparent before-and-after comparison
An explanatory illustration might draw a large circle for all text matches, a smaller inner rectangle for the BM25 candidate window, and a joined set for the hybrid ranked results. Show separately how a filter limits the eligible records. These are conceptual shapes, not measured result counts from a live index. In a controlled test, capture both facet outputs and the returned document identifiers while holding all other parameters constant. If the number changes, check the configured mode and retrieval-window size before filing a missing-data bug. A visible page can be shorter than the underlying eligible set for ordinary paging reasons.
Do not let facet counts imply restricted access
Catalogs may include records with rights restrictions, private donor notes, or incomplete publication review. A faceted UI must not reveal sensitive categories through counts for records the visitor should never enumerate. Apply rights filtering and field security design before search results are formed, and test that count behavior respects the intended eligible population. The `countAndFacetMode` switch is not an access-control toggle. Similarly, a nonzero facet count is not a promise that the user may open each original asset. Link to an approved public record only where publication status and content rights allow it.
Check preview availability and version drift
Microsoft labels the setting as preview in its hybrid search documentation. A request that works with a newer preview REST API may not work in a stable API version or an older client library. Confirm service support, supported request shape, and the exact preview API in your environment. Do not silently drop an unsupported parameter and compare the resulting counts as if the requested mode had been applied. Surface validation errors and retain the response version in the test record. Because preview semantics can evolve, record the documentation date and require a regression check after service or SDK upgrades.
Build a meaningful validation matrix
For each sample query, compare the two modes under a fixed filter, then vary `maxTextRecallSize` deliberately and note differences. Inspect facet membership alongside identifiers from the results and check whether the public UI’s explanatory text matches the chosen scope. Use an accession lookup and a known safety-warning phrase as guard cases so relevance tuning does not mask important records. Do not fabricate a recall percentage or precision figure from schematic diagrams. If production metrics are desired, collect them in an authorized benchmark with a predefined labeled relevance set, stable index snapshot, and consistent query contract.
Publish a number with its definition
A final interface should use labels such as “matching catalog records” or “retrieved candidate records” only when those words accurately describe the underlying query mode. Document the preview dependency for maintainers, keep filters and rights decisions independent of scoring knobs, and provide a path to a fuller search when a facet is truncated. Confirm the expected behavior with current Microsoft documentation before launch. This guide does not claim any observed search speed, improved retrieval quality, or live count. The practical result is an auditable explanation for visitors and editors of what the displayed number means and what it does not measure.
How We Research
Primary official technical sources reviewed November 11, 2026: Microsoft: Hybrid search query guide; Microsoft: Search documents REST API preview; Microsoft: Relevance and ranking overview. We compared Microsoft hybrid search documentation, the preview Search Documents REST contract, and relevance guidance for the text retrieval window and facet count semantics. The comparative sets are conceptual; no index, query, measurement, or production result was obtained. All example identifiers, diagrams, comparisons, and quantities here are instructional constructs, not empirical test results, vendor screenshots, or production traces. Verify current API versions, access permissions, model support, prices, security requirements, and local policy before implementing with real data.
Frequently Asked Questions
Microsoft documents it as preview in the referenced hybrid-search API; verify the version supported by your client and service.
It counts all text matches for the relevant count and facet calculation, not just those within the BM25 retrieval window.
It limits the text-side count contribution to matches selected inside maxTextRecallSize.
No. This option is not an authorization mechanism; rights filtering must remain an independent requirement.
No. The page, retrieval candidates, vector matches, and counting scope can be different sets.