Explain the search result cache under Azure AI Search in V2 admin

[Paul Lizer (paullizer)]

Summary

• Why: V2 Admin Settings showed enable_search_result_caching under Knowledge > Web & Research > Web Search, as a bare switch labelled with its key. It had no declared field, so the enable_* fallback scan placed it by word stems. "search" ties Web Search and Azure AI Search, and Web Search wins because it comes first in navigation order. The setting actually caches workspace document searches against Azure AI Search, not web search. Nothing on the page told an admin what it did or whether to leave it on.
• What: It is now declared in a new Search result cache group in Knowledge > Search Index > Azure AI Search, directly after the Connection group. The help text explains what is cached and what forces a fresh search. It also says each cached hit is re-checked against the requesting user's access, and when to turn caching off. The group also exposes search_cache_ttl_seconds as Cache lifetime (seconds): 60 to 3,600, default 300, shown only while caching is on. The runtime already read this value, but no interface could edit it.
• Default stays On, with no migration. It already defaults to on in functions_settings.py and in the utils_cache.get_cache_settings() fallback. A cache hit skips the query embedding and one semantic-ranked hybrid query per in-scope index, and it returns the same sources for the same question. Reuse is safe because the cache key includes a fingerprint of every in-scope document (id, version, content screening state). If an admin has already saved it as Off, that value is kept.
• Docs:
  • docs/admin/knowledge.md explains the cache, lists both settings, and adds a troubleshooting row.
  • The misfiled row is removed from docs/admin/scale.md.
  • Adds a fix doc, a feature doc note, and a v0.261.262 release note.

After: rendered by the new Playwright test from the built SPA, using the real field schema and synthetic fixture settings.

Notes for reviewers

• Both keys are V2-only and recorded in V2_ONLY_FIELDS. The classic Azure AI Search card briefly had a control in late 2025, but the classic save handler never stored it and the control was removed. The classic page is unchanged, and the new functional test fails if a classic form starts submitting either key.
• The lifetime's unit is in its label because number controls do not render suffix; only range controls do.
• This branch merged the latest V2 (Fix V2 admin Web Search test failing for saved Foundry connections #1662, Hide always-on tabular preflight switches from V2 Admin Settings #1663) and moved from 0.261.260 to 0.261.262, following the usual merge-and-renumber pattern. Both upstream release note sections are kept, with this one on top.

Linked issue

N/A, there is no associated issue. The investigation found two existing search cache problems. This PR doesn't change them, but each is worth its own issue:

• invalidate_group_search_cache and invalidate_public_workspace_search_cache filter on CONTAINS(c.doc_scope, <id>), but doc_scope stores only the scope name. So they delete nothing, unless the group call passes document_id. Document fingerprints still keep results correct. The cache lifetime is what bounds staleness for changes that do not alter a document's version.
• The search_cache container has no Cosmos TTL: config.py sets none, and the Bicep and Terraform templates set it to null. An expired entry is deleted only when the same search is read again or an invalidation happens to match it. Entries for searches that are never repeated accumulate.

Release Notes & Latest Features

• New Feature
• Bug Fix
• UI Enhancement
• Breaking Change
• Internal only

Is this visible to end users?

• Yes
• No

Is this admin-facing (Admin Settings, governance, deployment, config)?

• Yes
• No

Should this become a Latest Feature card?

• Yes
• No
• Already added

Screenshot needed for the card?

• Yes
• No
• Attached

Version bump

• application/single_app/config.py VERSION third segment bumped, or not needed because this is docs-only (0.261.261 -> 0.261.262)
• deployers/version.txt bumped, or not needed because deployers/ was not changed

Testing / validation

All results are from the merged tree: this branch plus V2 at d2d7b1d44. npm ci ran once before the merge, and the merge did not change the lockfile.

From functional_tests/:

Command	Result
python test_search_result_cache_admin_setting.py (new)	Passed, 7/7
python test_v2_admin_capability_placement.py	Passed, 8/8
python test_v2_admin_nested_setting_reads.py	Passed, 8/8
python test_v2_admin_secret_field_handling.py	Passed, 10/10
python test_admin_settings_fields_registry_integrity.py	Passed, 5/5
python test_v2_admin_knowledge_web_research.py	Passed, 9/9
python test_v2_admin_knowledge_extraction.py	Passed, 9/9
python test_v2_admin_knowledge_audio_video.py	Passed, 9/9
python test_v2_admin_knowledge_file_sync.py	Passed, 9/9
python test_v2_admin_schema_vocabulary.py	Passed, 10/10
python test_v2_admin_settings_normalization.py	Passed, 15/15
python test_v2_admin_field_renderer_coverage.py	Passed, 4/4
python test_v2_admin_settings_layout.py	Passed, 5/5
python test_shared_ai_connections_admin_schema.py	Passed
python test_docs_app_surface_coverage.py	Passed, 7/7
python test_docs_site_quality.py	Passed, 6/6

From the repo root:

Command	Result
python scripts\build_docs_inventory.py --check	Passed, inventory in sync
python -m pytest functional_tests/test_search_result_cache_admin_setting.py functional_tests/test_v2_admin_capability_placement.py -q -p no:cacheprovider	Passed, 15
npm --prefix application/v2_ui ci --no-audit --no-fund --loglevel=error	Passed
npm --prefix application/v2_ui run build	Passed (tsc -b and vite build)
python -m pytest ui_tests/test_v2_admin_search_result_cache.py ui_tests/test_v2_admin_settings_wide_layout.py -q -p no:cacheprovider	Passed, 18 (local Chromium)

Four tests already fail and are unrelated to this change. Each fails the same way on V2 d2d7b1d44 without this branch, checked in a clean worktree from functional_tests/:

• python test_v2_admin_settings_schema.py: 10/11. The default for core-plugin-toggles.m365_trusted_download_hosts is [], not a str.
• python test_admin_settings_nav_map.py: 3/4. The content-screening tab has no matching pane.
• python test_admin_settings_sidebar_card_parity.py: 3/4. The m365-retrieval-configuration card has no sidebar destination.
• python test_v2_admin_security_parity.py: 7/8. Nothing claims chat_content_settings_present in content-screening.html.

Manual: reviewed the Playwright screenshot shown above.

Documentation

• Release notes updated, or not needed
• Feature documentation updated, or not needed
• Fix documentation updated, or not needed

Security checklist

• New Flask routes include @swagger_route(security=get_auth_security()) (no new routes)
• Settings sent to non-admin frontends use sanitize_settings_for_user() (no change; only the admin field schema changed)
• Browser JavaScript is served from local SimpleChat static assets only; no CDN-hosted JS (no new browser assets)
• No secrets, keys, connection strings, or local-only artifacts are included