Typeahead artist suggestions miss free-text credits; album_artist 404s — value-converted list columns have no suggestion source #662

Closed
opened 2026-07-26 23:00:59 +02:00 by timothy · 1 comment
Owner

Split out of #578 on pickup (2026-07-26). It was the one item in that issue's list that is a backend change with its own design question, so folding it into #578's frontend PR would have been scope creep.

The limitation

GetSearchFieldValuesHandler sources the artist typeahead field from ArtistMetadata.Title — i.e. entity artists only. Two other artist-bearing shapes are searchable but offered no suggestions:

  • Music videos: MusicVideoArtist.Name — free-text artist credits.
  • Songs: SongMetadata.Artists — a value-converted IList<string> column.

album_artist is excluded outright and returns 404 for the same reason: it is also a value-converted list column, so there is no distinct-value source to project.

Why it isn't just "add the columns"

api.search-field-values is explicit that this endpoint returns distinct whole values from the database — deliberately not the Lucene term dictionary, because analyzed TextFields store lowercased word tokens ("Science Fiction" → science/fiction), which are useless as typeahead suggestions.

A value-converted IList<string> stored as a single delimited column cannot be SELECT DISTINCT-ed into whole values by the database — the conversion happens in EF, client-side. So this needs an actual decision, not a one-line addition:

  • project and split in memory (bounded how? the songs table can be large), or
  • persist a normalized side table / denormalized distinct-values projection, or
  • accept the gap and make the 404 an explicit documented "no suggestion source" response rather than an incidental one.

The third option is a legitimate outcome — the free-text fallback already covers these cases functionally, which is why #578 rated it non-blocking.

Done-when

  • A decision is recorded on whether value-converted list columns are a typeahead suggestion source at all (extends or amends api.search-field-values)
  • If sourced: artist suggestions include music-video and song credits, and album_artist stops 404ing — with a bounded, non-table-scanning query path
  • If not sourced: the 404 is a documented, deliberate response for list-valued fields, and docs/endpoint-index.md / the field allow-list say so
  • Adversarial review passed

Parent: #578. Original context: #434/#435/#438 (PR #577).

Split out of #578 on pickup (2026-07-26). It was the one item in that issue's list that is a **backend** change with its own design question, so folding it into #578's frontend PR would have been scope creep. ## The limitation `GetSearchFieldValuesHandler` sources the `artist` typeahead field from `ArtistMetadata.Title` — i.e. **entity** artists only. Two other artist-bearing shapes are searchable but offered no suggestions: - **Music videos**: `MusicVideoArtist.Name` — free-text artist credits. - **Songs**: `SongMetadata.Artists` — a value-converted `IList<string>` column. `album_artist` is excluded outright and returns **404** for the same reason: it is also a value-converted list column, so there is no distinct-value source to project. ## Why it isn't just "add the columns" `api.search-field-values` is explicit that this endpoint returns distinct **whole** values **from the database** — deliberately not the Lucene term dictionary, because analyzed `TextField`s store lowercased word tokens ("Science Fiction" → `science`/`fiction`), which are useless as typeahead suggestions. A value-converted `IList<string>` stored as a single delimited column cannot be `SELECT DISTINCT`-ed into whole values by the database — the conversion happens in EF, client-side. So this needs an actual decision, not a one-line addition: - project and split in memory (bounded how? the songs table can be large), or - persist a normalized side table / denormalized distinct-values projection, or - accept the gap and make the 404 an explicit documented "no suggestion source" response rather than an incidental one. The third option is a legitimate outcome — the free-text fallback already covers these cases functionally, which is why #578 rated it non-blocking. ## Done-when - [ ] A decision is recorded on whether value-converted list columns are a typeahead suggestion source at all (extends or amends `api.search-field-values`) - [ ] If sourced: `artist` suggestions include music-video and song credits, and `album_artist` stops 404ing — with a bounded, non-table-scanning query path - [ ] If not sourced: the 404 is a documented, deliberate response for list-valued fields, and `docs/endpoint-index.md` / the field allow-list say so - [ ] Adversarial review passed Parent: #578. Original context: #434/#435/#438 (PR #577).
timothy added the apipriority: low labels 2026-07-26 23:00:59 +02:00
Author
Owner

Closing — folded back into #578, which is being worked now.

Splitting this out was my call and it was the wrong one: #578's Done-when should reflect what that issue actually describes, and the artist / album_artist suggestion-source gap is one of the four items it describes. Carving it into a separate issue would have let #578 close with three-quarters of its own contents unaddressed.

The design analysis written up here is preserved in #578's Done-when and scope note. No work is lost.

Closing — folded back into **#578**, which is being worked now. Splitting this out was my call and it was the wrong one: #578's Done-when should reflect what that issue actually describes, and the `artist` / `album_artist` suggestion-source gap is one of the four items it describes. Carving it into a separate issue would have let #578 close with three-quarters of its own contents unaddressed. The design analysis written up here is preserved in #578's Done-when and scope note. No work is lost.
Sign in to join this conversation.
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: timothy/ersatztv#662