feat(search): Context-aware Facet Values API — return only search-relevant facet options in sidebar dropdowns

[mekarpeles]

Problem / Opportunity

Today when patrons search on openlibrary.org/search, the right-sidebar "Zoom In" section displays search facets (Language, Author, Subject, etc.) loaded asynchronously via /partials/SearchFacets.json (introduced in PR #9397 by @jimchamp). The current endpoint returns a full HTML partial for the entire sidebar — it does not expose individual facet field values as a JSON API.

As part of the new Search UX work (PR #12949 by @lokesh), individual facet fields are becoming interactive OlSelectPopover-based droppers. When a patron opens one of these droppers after performing a search, the options shown should reflect only the values relevant to that search — not every value known to the system.

Example: Searching "Lord of the Rings" and opening the Language dropper should show:

English   665
German     32
Spanish    18
French     15
Chinese    11

...not all 25+ languages in the system, many of which yield zero results for this query.

Why this matters: Showing irrelevant facet values steers patrons into dead ends (zero-result filtered pages) and degrades the search experience. Search-context-aware facets are a UX best practice used by major library and e-commerce platforms. With the new Search UX landing in #12949, this is the right moment to add the backing API.

Current UI for reference:

Success: When a patron opens any facet dropper with an active search query, the options shown are limited to values with ≥1 matching result, ordered by count descending.

Proposal

Add a new Facet Values JSON API endpoint — e.g., GET /search/facets.json — that accepts a Solr field name plus the current search parameters, and returns an ordered list of {value, count} pairs scoped to that search context.

Proposed behavior:

• With an active search query: Query Solr with facet=true&facet.field=<field>&rows=0 alongside the current search params; return only {value, count} pairs where count > 0, ordered by count descending.
• Without an active search (e.g., homepage, empty query): Fall back to a sensible default — e.g., popular values, browser-locale language prioritized, etc.
• Respects existing SFW filtering.

Example response for GET /search/facets.json?field=language&q=lord+of+the+rings:

[
  {"value": "English", "count": 665},
  {"value": "German",  "count": 32},
  {"value": "Spanish", "count": 18}
]

Implementation Details (for maintainers)

Summary

We'd continue to use search.json for search. There would be a second Facets JSON API (that defines responses/values for each facet type that gets triggered on-click of each Search UX Facet to populate its relevant, context-aware results)

Related files

Refer to this map of common Endpoints:

• openlibrary/fastapi/partials.py — Add new endpoint here alongside the existing GET /partials/SearchFacets.json (L33–51)
• openlibrary/plugins/openlibrary/partials.py — SearchFacetsPartial.generate_async() (L324–374) for Solr query reference; the new endpoint can reuse the same Solr query plumbing with rows=0 and facet.field=<field>
• openlibrary/templates/search/work_search_facets.html — current sidebar template showing which facet fields are supported
• openlibrary/plugins/openlibrary/js/search.js — current JS handler for /partials/SearchFacets.json (L67–130); new dropper components will call the new endpoint instead
• openlibrary/components/lit/OlSelectPopover.js — Lit dropper component that will call the new endpoint on open

Requirements Checklist

Checklist of requirements that need to be satisfied in order for this issue to be closed:

• New JSON endpoint (e.g. GET /search/facets.json) in FastAPI accepting field, q, and active facet filters as query params
• Endpoint queries Solr with facet=true&facet.field=<field>&rows=0 alongside the current search params
• Returns only values with count > 0, ordered by count descending, as [{value, count}] JSON
• OlSelectPopover/OlFacetSelect components wire up to call the new endpoint when opening a dropper with an active search
• Sensible fallback when no search query is present
• SFW filter cookie is respected
• Unit tests for the new endpoint

Stakeholders

• @RayBB — lead; drives implementation and PR reviews
• @mekarpeles — assignee; product direction and scope approval
• @lokesh — author of OlSelectPopover/OlFacetSelect and PR Shared reading preference + author-page filter bar (results-toolbar Phase 0–1) #12949; integration point for new API
• @jimchamp — original author of async search facets partial (PR Asynchronously load search facets sidebar #9397); architectural reference

---

Instructions for Contributors

• Before creating a new branch or pushing up changes to a PR, please first run these commands to ensure your repository is up to date, as the pre-commit bot may add commits to your PRs upstream.

[mekarpeles]

⚠️ Contributors — this issue will be ready to work on once:

• Triage — maintainers will add a Priority: * label to replace Needs: Triage

---

Context

• SearchFacetsPartial.generate_async() (openlibrary/plugins/openlibrary/partials.py:331) already calls run_solr_query_async with rows=0, facet=True — the exact Solr query pattern the new endpoint needs. The new endpoint can call the same function with a single facet.field parameter rather than all facet fields at once.

• WorkSearchScheme.facet_fields (openlibrary/plugins/worksearch/schemes/works.py:121) enumerates the 10 supported Solr facet fields (language, author_facet, subject_facet, publisher_facet, person_facet, place_facet, time_facet, first_publish_year, has_fulltext, public_scan_b). The new endpoint should validate the field query parameter against this frozenset.

• /search.json explicitly disables facets (openlibrary/fastapi/search.py:180): facet=False with comment "We do not support returning facets from /search.json, so disable it. This makes it much faster." A dedicated /search/facets.json is the intended architectural separation. The existing JSON search endpoints (/search/subjects.json, /search/authors.json, /search/lists.json) all live in fastapi/search.py — that module is a better fit for a pure JSON endpoint than fastapi/partials.py, which serves HTML partials.

• Issue Search facets say there is a dutch book but clicking it yields no results #8971 ("Search facets say there is a dutch book but clicking it yields no results") is an open related issue. The proposed API — returning only count > 0 values — would address that class of user-facing inconsistency as a side effect.

• PR Shared reading preference + author-page filter bar (results-toolbar Phase 0–1) #12949 (new Search UX, OlSelectPopover/OlFacetSelect by @lokesh) is currently open and is the direct integration point. Coordinate with @lokesh before wiring up the frontend call, as the component API may still be in flux.

---

Issue assessment

Open question

• The requirements checklist references OlFacetSelect but the existing codebase contains OlSelectPopover (openlibrary/components/lit/OlSelectPopover.js). Are these the same component, or is OlFacetSelect a planned new wrapper in PR Shared reading preference + author-page filter bar (results-toolbar Phase 0–1) #12949?

Action items

• Attach or remove the screenshot placeholder — it is currently an empty italicized note and adds no information in its current state.
• Confirm module placement for the new endpoint: fastapi/search.py (alongside /search/subjects.json) vs fastapi/partials.py (alongside /partials/SearchFacets.json). Given the endpoint returns JSON data rather than an HTML partial, search.py fits the existing convention.

---

Full triage checklist (maintainers / Richy)

• Triage — Needs: Lead removed (RayBB identified as lead and assigned); Needs: Breakdown removed (7-item requirements checklist present); Needs: Triage remains until Priority: * is set
• Problem / opportunity — problem is clear, audience (patrons on search results page) identified, actionable
• Scope — well-scoped to a single new JSON endpoint + frontend wiring in OlSelectPopover/OlFacetSelect
• Justification — stated explicitly: zero-result dead ends, UX best practice on major library/e-commerce platforms
• Success & testing criteria — defined (count > 0, ordered by count desc, unit tests required)
• Proposal & breakdown — 7-item requirements checklist present in Implementation Details
• Screenshot — placeholder is unfilled ("Screenshot to be attached")
• Risks, concerns, open questions — OlFacetSelect vs OlSelectPopover naming discrepancy surfaced; module placement question raised
• Richy context — SearchFacetsPartial, WorkSearchScheme.facet_fields, search.py facet-disable comment, Search facets say there is a dutch book but clicking it yields no results #8971, PR Shared reading preference + author-page filter bar (results-toolbar Phase 0–1) #12949 reviewed

Note

This comment was automatically generated by Richy, via PAM, Open Library's Project AI Manager, on behalf of @mekarpeles. Richy is designed to provide status visibility, perform basic project management functions and relevant codebase research, and provide actionable feedback so contributors aren't left waiting.

[RayBB]

We shouldn't call it a partial if it's not returning html but otherwise seems pretty straightforward.

I do think it should probably accept multiple facet types and be able to return multiple instead of having to do one API call for each facet type. Even if we only want one for now it seems a likely expansion.