Zoeken (Typesense)

Full-text zoeken door alle libraries is optioneel en draait op Typesense. Zonder werkt de server prima — maar de GraphQL-query search faalt dan met een expliciete fout ("Search is not configured on this server"), hij geeft geen lege lijst terug. Mét krijgen clients snel, typefouttolerant, meertalig zoeken op titels, beschrijvingen en genres, gefilterd op de librarytoegang van de aanroeper (Gebruikers, delen en toegang).

Inschakelen

1. Draai een Typesense-instantie (één per cluster). docker-compose-local.yml toont een werkende servicedefinitie; in Kubernetes kan de chart hem voor je deployen.

2. Wijs de server ernaar:

   TYPESENSE_ENABLED=true
   TYPESENSE_HOST=typesense
   TYPESENSE_PORT=8108          # default
   TYPESENSE_PROTOCOL=http      # default
   TYPESENSE_API_KEY=<the key Typesense was started with>

3. Herstart de server en draai dan eenmalig de GraphQL-mutation rebuildSearchIndex om de initiële index op te bouwen. Tot je dat doet is bestaande media niet doorzoekbaar — alleen items die na het inschakelen worden aangeraakt zouden binnendruppelen. (De collectie en alias zelf worden bij het opstarten leeg aangemaakt, dus een lege-maar-aanwezige collectie in Typesense is normaal vóór de eerste reindex.)

De enabled-vlag wordt tijdens runtime gecontroleerd, niet in de image gebakken: dezelfde image bedient beide modi, en zoekevents worden simpelweg geconsumeerd en weggegooid zolang de vlag uitstaat. Je kunt TYPESENSE_ENABLED dus omzetten met alleen een herstart, zonder rebuild.

Actueel blijven

Na de initiële herindexering hoef je die nooit routinematig te draaien. De index onderhoudt zichzelf:

• nieuwe items worden geïndexeerd wanneer de scanner ze aanmaakt,
• metadataverrijking (TMDB en consorten) werkt het item bij zodra die binnenkomt,
• verwijderingen halen het item uit de index.

rebuildSearchIndex blijft het reparatiegereedschap: het bouwt opnieuw op in een verse collectie en wisselt een alias om, zodat zoeken live blijft tijdens de rebuild. Grijp ernaar na het inschakelen van zoeken op een bestaande database, na het terugzetten van een databaseback-up, of als de index er ooit niet synchroon uitziet.

Een taal toevoegen of verwijderen

Zoekvelden worden per geconfigureerde taal gegenereerd (title_en, description_nl, genre_de, …) — titelvelden wegen 5 in de ranking, beschrijvings- en genrevelden 1 — en het collectieschema ligt vast bij aanmaak, dus een taalwijziging is een kleine procedure:

1. Werk ISTER_LANGUAGES bij (bijv. en,nl,de) en herstart de server(s).
2. Haal metadata opnieuw op zodat de rijen van de nieuwe taal in PostgreSQL bestaan: draai de mutation refreshMetadata (of een re-scan) — de index kan alleen metadata tonen die in de database bestaat.
3. Draai eenmalig rebuildSearchIndex. Dat maakt een verse collectie met het nieuwe schema en wisselt de alias om.

Een taal verwijderen is hetzelfde minus stap 2: herindexeren laat de velden simpelweg vallen; er wordt niets uit PostgreSQL verwijderd.

Probleemoplossing

• Zoeken geeft een fout ("Search is not configured on this server") — TYPESENSE_ENABLED staat nog op false op de node die de query beantwoordde.
• Zoeken staat aan maar geeft een lege lijst — rebuildSearchIndex is na het inschakelen nooit gedraaid (de bij het opstarten aangemaakte collectie is leeg), of de API-key/host is verkeerd. Het serverlog toont verbindingsfouten bij het opstarten en bij elke indexeerpoging.
• Een reindex volgen in RabbitMQ — de mutation heet rebuildSearchIndex, maar de queue die hij voedt heet app.ister.server.SearchReindexRequested; zoek dus niet naar een "rebuild"-queue.
• Nieuwe taal niet doorzoekbaar — je hebt stap 2 of 3 hierboven overgeslagen.
• De index overleeft serverherstarts, maar leeft alleen in de datamap van Typesense; raak je dat volume kwijt, dan bouwt één rebuildSearchIndex alles opnieuw op uit PostgreSQL. Hij is wegwerpbaar — zie Onderhoud.

Hoe het indexeren intern werkt staat beschreven in de architectuurdocumentatie.