// stack · schnittstelle
Algolia ist ein gehosteter Suchdienst: Deine Inhalte werden vorher in einen Index geschrieben, die Suchanfrage läuft danach gegen die Infrastruktur des Anbieters. Für siteway ist das der Weg, wenn große Datenmengen, Facetten, Tippfehler-Toleranz und eine steuerbare Trefferreihenfolge gebraucht werden. Diese Seite beschreibt, wie wir Algolia anbinden — und wo die eigentliche Arbeit steckt.
// definition
gehostet · index statt datei
Algolia ist ein gehosteter Suchdienst. Das ist der ganze Unterschied zu einer Suche, die auf deinem eigenen Server läuft: Die Inhalte werden nicht dort durchsucht, wo sie liegen, sondern vorher als Records in einen Index beim Anbieter geschrieben. Tippt jemand in dein Suchfeld, geht die Anfrage an dessen Infrastruktur und kommt als fertige Trefferliste zurück.
Ein Index ist dabei mehr als ein Datenspeicher. An ihm hängen die Einstellungen, die aus Daten eine Suche machen: welche Attribute überhaupt durchsucht werden, welche als Facette filterbar sind, und in welcher Reihenfolge Treffer erscheinen. Wer diese drei Schrauben nicht dreht, bekommt eine Suche, die zwar antwortet, aber nicht sortiert.
Daraus folgt eine Erwartung, die vorher geklärt sein sollte: Eine gute Suche mit Algolia ist Konfigurationsarbeit, kein Datenexport. Der Datenexport ist der einfache Teil. Die Zeit geht in die Frage, welches Attribut wie schwer wiegt und was am Ende oben steht — nachzulesen im Kapitel Technik im Detail. Wie wir Suche insgesamt angehen, steht im Hub Suche.
// praxis
indexieren serverseitig · suchen im frontend
Am Anfang steht kein Code, sondern eine Liste: Was ist eigentlich ein Treffer? Eine Seite, ein Produkt, ein Datenblatt, ein Abschnitt? Diese Entscheidung legt fest, wie ein Record aussieht — und damit alles Weitere. Wir schneiden die Records so, dass ein Treffer für den Besucher eine sinnvolle Antwort ist, nicht der Anfang einer zweiten Suche.
Dann kommt das Mapping: Welches Feld aus dem CMS wird welches Attribut im Record, was ist durchsuchbar, was wird Facette, was ist nur Anzeige. Hier fällt auch die Entscheidung, was den Index gar nicht erst erreicht — interne Notizen, Preise mit Sonderkonditionen, geschützte Bereiche. In den Index geht, was für die Suche gebraucht wird. Alles andere bleibt, wo es ist.
Indexiert wird serverseitig, in zwei Stufen. Zur Einrichtung läuft eine Voll-Indexierung über den kompletten Bestand, gebündelt statt Record für Record — die Dokumentation rät ausdrücklich dazu, in Stapeln zu senden. Danach laufen nur noch Änderungen: angelegt, geändert, gelöscht. Weil Algolia die Indexierung als Aufgabe im Hintergrund verarbeitet, ist ein Record nicht in derselben Millisekunde suchbar, in der er gesendet wurde — für eine Redaktion völlig unkritisch, für einen automatisierten Test sehr wohl.
Der Rückweg ist der Praxisstolperstein. Ein Inhalt, der im CMS gelöscht oder auf Entwurf zurückgesetzt wird, verschwindet nicht von selbst aus dem Index — er muss aktiv entfernt werden. Sonst führt ein Treffer ins Leere oder zeigt eine Überschrift, die noch niemand sehen sollte. Wir behandeln „löschen“ und „depublizieren“ deshalb als eigene Ereignisse mit eigenem Code, nicht als Nebeneffekt des Speicherns. Dasselbe gilt für geschützte Bereiche: Was hinter einem Login liegt, wird entweder gar nicht indexiert oder nur mit einem Schlüssel gesucht, der auf diesen Ausschnitt begrenzt ist.
Gesucht wird im Frontend — mit dem reinen Such-Schlüssel und einer Oberfläche, die wir selbst bauen: Eingabefeld, Treffer während des Tippens, Facetten als Filter daneben, ein Zustand für null Treffer. Und wie bei jeder Anbindung planen wir den Fehlerfall mit: Antwortet der Dienst nicht, bleibt die Seite bedienbar und fällt auf die Navigation oder eine einfache Suche im eigenen Bestand zurück. Die buchbare Leistung dahinter ist die Komponente Suche, die Anbindung selbst gehört zur Schnittstellenentwicklung.
// technik · 6 details
belegt aus der doku
Was hier steht, stammt aus der öffentlichen Dokumentation von Algolia — Begriffe, Einstellungen und Reihenfolgen im Original. Preise und harte Grenzwerte lassen wir bewusst weg: Sie ändern sich, und was für dein Projekt gilt, steht in deinem Vertrag und nicht auf einer Agenturseite.
// d-01datenmodell
Ein Index ist ein durchsuchbarer Datenbestand samt seinen Einstellungen, ein Record ein Objekt darin mit benannten Attributen. Jeder Record braucht eine eindeutige objectID — entweder du vergibst sie, oder Algolia erzeugt sie. Über sie laufen später Aktualisierung und Löschung.
zweck: struktur der daten
// d-02relevanz
Nicht jedes Attribut soll durchsucht werden. Über die durchsuchbaren Attribute legst du fest, worin gesucht wird und in welcher Rangfolge — ein Titel wiegt anders als ein Fließtext. Die Dokumentation nennt diese Einstellung zusammen mit dem Custom Ranking als die beiden zentralen Hebel für Relevanz.
zweck: worin gesucht wird
// d-03facetten
Ein Attribut wird zur Facette, sobald es in attributesForFaceting steht — Schreibweise exakt wie im Record. Algolia liefert Trefferzahlen je Wert mit, bei sehr großen Indizes angenähert; das meldet exhaustiveFacetsCount. Facettenwerte lassen sich durchsuchen, Kategorien mehrstufig abbilden.
zweck: eingrenzen
// d-04reihenfolge
Algolia vergleicht Treffer nach einer festen Kriterienreihe und geht erst weiter, wenn Gleichstand herrscht: Tippfehler, geografische Nähe, optionale Wörter, passende Filter, Wortnähe, getroffenes Attribut, exakte Übereinstimmung — und zuletzt dein Custom Ranking, etwa nach Beliebtheit.
zweck: was oben steht
// d-05toleranz
Ein Tippfehler ist ein fehlender, zusätzlicher, vertauschter oder falscher Buchstabe; gemessen wird der Abstand zweier Wörter. Toleriert werden bis zu zwei Tippfehler je Wort. Nicht angewendet wird die Toleranz unter anderem bei Anfragen in Anführungszeichen. Synonyme ergänzen das um Begriffe, die dieselbe Sache meinen.
zweck: trotzdem finden
// d-06schlüssel
Der Admin-Schlüssel hat vollen Kontozugriff und bleibt serverseitig — die Dokumentation sagt ausdrücklich, ihn in keiner Anwendung zu verwenden. Schreiben läuft ebenfalls serverseitig. Fürs Frontend gibt es den reinen Such-Schlüssel. Abgeleitete Schlüssel können zusätzlich einschränken und ablaufen, aber nie Rechte hinzufügen.
zweck: trennung der rechte
Ein gehosteter Dienst bedeutet sachlich zweierlei: Deine Inhalte liegen als Records bei einem Dritten, und jede Suchanfrage deiner Besucher geht dorthin. Beides ist kein Ausschlussgrund, aber beides gehört vor dem Start auf den Tisch — nicht in die Datenschutzerklärung nach dem Launch.
Drei Punkte klären wir dafür im Projekt. Erstens die Region: Beim Anlegen einer Anwendung wird festgelegt, wo sie betrieben wird; Algolia dokumentiert Cluster in mehreren Regionen, darunter in Europa. Zweitens die Auftragsverarbeitung — wer im Auftrag verarbeitet, braucht einen Vertrag darüber, genau wie der Hoster. Drittens Datensparsamkeit: Algolia dokumentiert selbst, dass Suchprotokolle standardmäßig 90 Tage aufbewahrt werden und unter anderem Anfrage, Filter und eine gekürzte IP-Adresse enthalten — und rät davon ab, personenbezogene Daten als Nutzerkennung zu verwenden oder sie in Metadaten und Indexnamen abzulegen.
Unsere Konsequenz daraus ist schlicht: In den Index geht der Ausschnitt, der für die Suche gebraucht wird — und Attribute, die zwar für einen Filter nötig, aber nicht zur Anzeige bestimmt sind, lassen sich als nicht abrufbar markieren. Wie das mit dem Rest der Auslieferung zusammenpasst, steht im Stack unter Sicherheit & Datenschutz. Eine Rechtsberatung ist das ausdrücklich nicht.
// integration
drei systeme · ein muster
Der Weg ist in jedem System derselbe, weil er sich aus der Aufgabe ergibt und nicht aus dem CMS. Die eine Hälfte ist die Indexierung — und die läuft serverseitig: Der Inhalt wird dort gelesen, wo er redaktionell gepflegt wird, in Records übersetzt und in den Index geschrieben. Zur Einrichtung einmal komplett, danach nur noch das, was sich ändert. Dafür braucht es zwei Auslöser: ein Ereignis beim Speichern, damit eine Änderung sofort ankommt, und einen geplanten Lauf als Grundsicherung, falls ein Ereignis einmal ausfällt. Und es braucht die Gegenrichtung — gelöschte und depublizierte Inhalte müssen aktiv aus dem Index entfernt werden, sonst bleiben Treffer stehen, deren Seite es nicht mehr gibt.
Die andere Hälfte ist die Suche im Frontend. Sie fragt den Dienst direkt aus dem Browser — und zwar mit einem eingeschränkten Such-Schlüssel, der nur suchen kann. Das ist die Stelle, an der Anbindungen scheitern, deshalb steht sie hier so deutlich: Der Admin-Schlüssel gehört nie ins Frontend. Er hat vollen Zugriff auf das Konto, liegt ausschließlich auf dem Server und taucht weder im Quelltext einer Seite noch in einem JavaScript-Bundle auf. Ins Frontend darf nur der reine Such-Schlüssel. Wo Inhalte hinter einer Anmeldung liegen, kommt ein abgeleiteter Schlüssel dazu, der den Zugriff zusätzlich auf den erlaubten Ausschnitt begrenzt und ablaufen kann. Was das CMS darunter unterscheidet, ist nur, wo Ereignis, geplanter Lauf und Schlüssel jeweils hingehören.
// cms-01typo3
Wir bauen die Anbindung als eigene Extension. Die Voll-Indexierung läuft als Scheduler-Task über die Seiten und Records, die im Mapping stehen; dazu kommt ein Hook, der beim Speichern eines Datensatzes genau diesen einen Record nachzieht — und beim Löschen oder Verstecken wieder aus dem Index nimmt. Die Schlüssel liegen in der Extension-Konfiguration, der Admin-Schlüssel bleibt dort und wird nie ins Template gereicht. Fürs Sucheingabefeld und die Trefferliste nutzen wir Fluid, sodass die Suche im Design der Website steht und nicht daneben. Mehrsprachigkeit bildet sich über eigene Indizes je Sprache ab.
// cms-02wordpress
Die Anbindung entsteht als eigenes Plugin und nicht als Theme-Code — so überlebt sie einen Theme-Wechsel. Indexiert wird beim Speichern eines Beitrags oder Produkts und zusätzlich als geplanter Lauf für den Gesamtbestand. Statuswechsel behandeln wir mit: Was von veröffentlicht auf Entwurf, privat oder Papierkorb wechselt, wird aus dem Index entfernt. Die Schlüssel stehen in der wp-config.php oder als Umgebungsvariable, nicht in der Datenbank und nicht im Frontend-Skript. Für die Oberfläche kommen Template-Dateien und ein Block für den Editor dazu, damit die Redaktion Suchfeld und Facetten platzieren kann.
// cms-03statamic
Unter Statamic liegt Laravel, und das macht die Anbindung geradlinig. Ein Artisan-Command baut den Index über die Collections auf und läuft im Scheduler als Grundsicherung. Daneben hängt ein Ereignis beim Speichern eines Entries, das genau diesen einen Record aktualisiert; das Gegenstück beim Löschen nimmt ihn wieder heraus. Der Blueprint gibt vor, welche Felder in den Record wandern und welche im Control Panel bleiben. Die Schlüssel liegen in der .env, ins gerenderte Frontend geht ausschließlich der Such-Schlüssel. Antlers oder Blade rendern Suchfeld, Facetten und Trefferliste.
// entscheidung
zuordnung statt rangliste
Die nützliche Frage lautet nicht „welche Suche ist die beste“, sondern „was wird eigentlich durchsucht, wie oft ändert es sich, und wer soll es betreiben“. Drei Antworten, drei Zuordnungen — alle drei sind bei siteway im Werkzeugkasten.
// e-01pagefind
Unternehmensseite, Magazin, Dokumentation, Handbuch: Bestände aus Text, die sich mit dem Deploy ändern. Dafür ist Pagefind gemacht — Index beim Build, Suche im Browser, kein Dienst dahinter, keine Anfrage nach draußen.
index beim build
// e-02algolia
Große Datenmengen, Filter über mehrere Achsen, Tippfehler-Toleranz und eine Reihenfolge nach Geschäftslogik — und ein Bestand, der sich unabhängig vom Build ändert. Das ist das Terrain von Algolia: gehostet, mit ausgereifter Ranking-Steuerung.
gehostet · facetten · ranking
// e-03meilisearch
Dieselbe Aufgabe, andere Betriebsform: Meilisearch ist ein Suchdienst, den du selbst betreibst. Passt, wenn Inhalte und Suchanfragen die eigene Infrastruktur nicht verlassen sollen und der Betrieb dafür mitgeplant wird.
selbst betrieben
Fünf Fragen entscheiden die Richtung, und sie lassen sich in einem Gespräch beantworten. Wie viele Einträge sind es, und wie oft ändern sie sich? Wonach soll gefiltert werden — und stehen diese Merkmale sauber in den Daten? Wonach soll bei Gleichstand sortiert werden? Was darf den eigenen Server verlassen? Und wer betreibt die Suche im Alltag, wenn sich am Datenmodell etwas ändert?
Danach steht das Mapping als Dokument, bevor gebaut wird. Die Kategorie darüber beschreibt der Hub Suche, die buchbare Komponente liegt in der Expertise unter Suche. Wo ein Katalog mit Attributen und Filtern das eigentliche Thema ist, führt der Weg über Produktkatalog — dort geht es um die Datenpflege, hier um die Technik darunter. Welche Suche ein Projekt bekommt, klären wir im Konzept — vor dem Bauen, mit Begründung.
// faq
Algolia ist ein gehosteter Suchdienst. Deine Inhalte werden nicht auf deinem Server durchsucht, sondern vorher als Records in einen Index beim Anbieter geschrieben; die Suchanfrage läuft dann gegen dessen Infrastruktur. Ein Index ist dabei mehr als ein Datenspeicher: An ihm hängen die Einstellungen, die bestimmen, welche Attribute überhaupt durchsucht werden, welche als Facette filterbar sind und in welcher Reihenfolge Treffer erscheinen. Genau deshalb ist eine gute Suche mit Algolia Konfigurationsarbeit und nicht nur ein Datenexport.
Die Frage ist nicht, welche Suche die beste ist, sondern was durchsucht wird. Bei einem Textbestand, der sich mit dem Deploy ändert — Unternehmensseite, Magazin, Dokumentation — ist Pagefind der passende Weg: Index beim Build, Suche im Browser, kein Suchdienst dahinter. Algolia ist der Weg, wenn große Datenmengen, Facetten über mehrere Achsen, Tippfehler-Toleranz und eine Reihenfolge nach Geschäftslogik gebraucht werden und der Bestand sich unabhängig vom Build ändert. Meilisearch beantwortet dieselbe Aufgabe als Suchdienst, den du selbst betreibst. Drei Zuordnungen für drei Situationen — welche greift, klären wir im Konzept.
In zwei Stufen. Zur Einrichtung läuft eine Voll-Indexierung: Der Bestand wird einmal komplett gelesen und als Records in den Index geschrieben, gebündelt statt einzeln, weil die Dokumentation genau dazu rät. Danach laufen nur noch Änderungen — angelegt, geändert, gelöscht. Jeder Record trägt dafür eine objectID; über sie erkennt der zweite Lauf denselben Inhalt wieder und aktualisiert ihn, statt eine Dublette anzulegen. Und der Rückweg ist der Teil, den man leicht vergisst: Ein Inhalt, der im CMS gelöscht oder auf Entwurf gesetzt wird, muss aktiv aus dem Index entfernt werden — sonst steht er dort weiter und taucht in der Suche auf, obwohl die Seite nicht mehr existiert. Wir legen deshalb vor der ersten Zeile Code fest, welcher Zustand indexiert wird und welcher nicht.
Facetten sind die Attribute, über die sich eine Trefferliste eingrenzen lässt — Kategorie, Marke, Material, Preisspanne, Sprache. Damit ein Attribut als Facette funktioniert, muss es in den Index-Einstellungen unter attributesForFaceting stehen; die Schreibweise muss exakt zum Attribut im Record passen. Algolia liefert zu jedem Facettenwert die Trefferzahl mit, sodass ein Filter zeigen kann, wie viel dahinter liegt; bei sehr großen Indizes können diese Zahlen laut Dokumentation angenähert sein, was die Antwort über exhaustiveFacetsCount mitteilt. Facettenwerte lassen sich auch selbst durchsuchen, und mehrstufige Kategorien werden über Ebenen abgebildet. Der eigentliche Aufwand steckt nicht im Anzeigen, sondern in der Entscheidung, welche Attribute überhaupt Facetten werden.
Über zwei Ebenen. Die erste ist das Ranking: Algolia vergleicht Treffer nach einer festen Reihe von Kriterien und geht erst zum nächsten über, wenn das vorherige unentschieden bleibt. In der dokumentierten Standardreihenfolge sind das Tippfehler, geografische Nähe, optionale Wörter, Anzahl passender Filter, Nähe der Suchwörter zueinander, das getroffene Attribut samt Wortposition, exakte Übereinstimmung — und ganz am Ende dein eigenes Kriterium. Das ist die zweite Ebene: das Custom Ranking. Hier legst du fest, wonach bei Gleichstand entschieden wird, etwa nach einem Beliebtheitswert oder einer Kennzeichnung als hervorgehoben. Genau dort wird aus einer technisch korrekten Suche eine, die zur Sache passt — und genau dort steckt die Arbeit.
Algolia trennt die Schlüssel nach dem, was sie dürfen. Der Admin-Schlüssel hat vollen Zugriff auf das Konto; die Dokumentation ist an dieser Stelle unmissverständlich und sagt, dass er in keiner Anwendung verwendet werden soll — er bleibt serverseitig. Ein Schlüssel zum Schreiben, der Records anlegt, ändert und löscht, gehört ebenfalls auf den Server. Ins Frontend darf ausschließlich der reine Such-Schlüssel, der nur suchen kann. Daneben gibt es eingeschränkte Schlüssel, die von einem bestehenden Schlüssel abgeleitet werden, ein Ablaufdatum tragen und den Zugriff weiter begrenzen können — sie dürfen Rechte nur wegnehmen, nie hinzufügen. Wir legen die Schlüssel in der Umgebungskonfiguration ab statt im Quelltext, so wie es die Dokumentation empfiehlt.
Sachlich betrachtet passieren zwei Dinge: Deine Inhalte liegen als Records bei einem externen Dienst, und jede Suchanfrage deiner Besucher geht dorthin. Daraus folgen die Punkte, die vor dem Start geklärt gehören — die Region, in der die Anwendung betrieben wird, die Auftragsverarbeitung mit dem Anbieter und die Frage, was überhaupt in den Index muss. Algolia dokumentiert selbst, dass Suchprotokolle standardmäßig 90 Tage aufbewahrt werden und unter anderem Anfrage, Filter und eine gekürzte IP-Adresse enthalten, und rät davon ab, personenbezogene Daten als Nutzerkennung zu verwenden oder sie in Metadaten und Indexnamen abzulegen. Unsere Konsequenz ist Datensparsamkeit: In den Index geht, was für die Suche gebraucht wird — und sonst nichts. Wie wir das im Projekt einordnen, steht im Stack unter Sicherheit & Datenschutz. Eine Rechtsberatung ist das nicht.
Ja, in allen drei Systemen — und wir bauen die Anbindung jeweils selbst mit den Bordmitteln des Systems. Die Kette ist überall dieselbe: Der Inhalt wird serverseitig in Records übersetzt und in den Index geschrieben, ein Ereignis beim Speichern zieht Änderungen sofort nach, ein geplanter Lauf hält den Bestand als Grundsicherung nach, und das Frontend fragt mit dem reinen Such-Schlüssel. In TYPO3 entsteht dafür eine eigene Extension mit der Indexierung als Scheduler-Task, einem Hook beim Speichern und dem Sucheingabefeld in Fluid. In WordPress bauen wir ein eigenes Plugin statt Theme-Code, mit Indexierung beim Speichern und als geplantem Lauf. In Statamic liegt Laravel darunter: ein Artisan-Command im Scheduler und ein Ereignis beim Speichern eines Entries. Der Admin-Schlüssel liegt dabei in jedem System in der Konfiguration und nie im Browser.
// womit das zusammenhängt
hub, technik & leistung
// stack · hub
Die Kategorie über diesem Dienst: wie wir pro Projekt zwischen statischer Suche und Suchdienst auswählen — und was das im Betrieb bedeutet.
zum hub →
// stack · statisch
Der Weg für Textbestände: Index beim Build, Suche im Browser, ohne Suchserver. Diese Website sucht damit.
zur technik →
// stack · suchdienst
Dieselbe Aufgabe, andere Betriebsform: ein Suchdienst, den du selbst betreibst — Facetten und Toleranz auf eigener Infrastruktur.
zur technik →
// stack · grundlage
Wenn Inhalte und Suchanfragen zu einem externen Dienst gehen: Region, Auftragsverarbeitung, Datensparsamkeit, Schlüssel serverseitig.
zur technik →
// leistung · buchbar
Die fertige Suchfunktion für deine Website: Index, Gewichtung, Oberfläche und die passende Technik nach Größe. Hier wird gebucht.
zur leistung →
// leistung · katalog
Wo Facetten herkommen: saubere Attribute im Katalog sind die Voraussetzung dafür, dass Filter in der Suche überhaupt funktionieren.
zur leistung →
// Eine Suche, die auch bei Menge noch findet?
Projekt anfragen