Skip to content

feat(search-api-graphql): search within a facet’s values - #1100

Merged
ddeboer merged 1 commit into
mainfrom
feat/facet-query
Nov 17, 2026
Merged

ddeboer merged 1 commit into
mainfrom
feat/facet-query

Conversation

@ddeboer

@ddeboer ddeboer commented Nov 17, 2026 •

Copy link
Copy Markdown
Member

Fix #533. A client can search a facet’s values: creator(query: "rem", limit: 10) returns the creators matching “rem”, counted over the current results. Linked Open Limburg needs it for creator, material and about (limburg/lol#221).

How it works

  • @lde/search: SearchQuery.facetQueries beside facetLimits. facetSearches gives each facet with a query a search of its own, and validateQuery rejects a query on a facet that takes none (not-queryable: unlabelled references, booleans, ranges, presence). Text shorter than three characters once trimmed (MIN_FACET_QUERY_LENGTH, facetQueryText) is no query: locally “r” matched 76 terms, “re” 5095 and “rem” 2, so below three the match is noise.
  • @lde/search-typesense:
    • A literal facet compiles to facet_query, whose stats.total_values counts only the matching values (checked on 30.2).
    • A reference facet takes two steps. Step 1 searches each target collection with that type’s own free-text search, for at most maxFacetQueryCandidates (default 50) referents per type. Step 2 counts each candidate with a search of its own, on the field the facet buckets, so a facet policy’s exclusions hold.
    • Counting candidates apart avoids two problems a single filtered facet search had. The works carrying a candidate also carry other values, which crowded matches out of the capped bucket list in a test with 30 of them. Fetching all values instead would make the response grow with the data (about has 10022 values in 19694 works), against ADR 12. Locally, 50 counts took 13 ms against 10 ms for one facet search.
    • totalValues is the number of candidates that occur, or absent when step 1 left referents out.
  • @lde/search-api-graphql: a query argument on each facet that takes one, beside limit: on a plain value facet and on a field’s facet object (‹Type›‹Field›Facet). Under a query a facet returns only matching values, selected or not: the one documented exception to reporting every selected value. A query on a reference facet costs 1 more per target type.

Left open

  • Step 1 ranks referents by text relevance in their own collection, not by whether they occur in the results. A common name (“Jan”) can fill the cap with referents that don’t occur, and the facet then shows fewer matches than exist.
  • Within one searchFacets batch, the other facets wait for the two candidate round-trips. The listing’s own hits search is unaffected, because GraphQL sends it separately.
  • A colon in a literal facet query becomes a space, so ::a reaches Typesense as a one-letter prefix after passing the length check.

- Add SearchQuery.facetQueries; facetSearches gives each facet with a query a search of its own,
  and validateQuery rejects a query on a facet that takes none
- Treat text shorter than three characters, once trimmed, as no query (facetQueryText)
- Compile a literal facet's query to Typesense facet_query, separating words at a colon
- Answer a reference facet's query in two steps: search each target collection for candidates,
  then count each candidate on the field the facet buckets (maxFacetQueryCandidates, default 50)
- Offer a query argument on each GraphQL facet that takes one, charged 1 more per target type
  on a reference facet
@ddeboer
ddeboer merged commit 86aa087 into main Nov 17, 2026
4 checks passed
@ddeboer
ddeboer deleted the feat/facet-query branch November 17, 2026 11:56
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Search within a facet’s values

1 participant