Volltextsuche

Die Docsbook-Suche ist ein Postgres-Volltextindex über Ihre Seiten, der als Suchschaltfläche im Header und als Suchfeld in der Seitenleiste verfügbar ist. Pro Abfrage fallen keine Kosten an – es wird kein Modell aufgerufen – und die Abfragen, die keine Ergebnisse lieferten, sind eines der beiden nützlichsten Signale, die Ihre Dokumentation erzeugt.

Was Sie erhalten#

• Ein Suchfeld im Header, in der Seitenleiste oder in beiden. Beide können gleichzeitig ausgeführt werden; eines reicht normalerweise aus.
• Ergebnisse mit einem hervorgehobenen Ausschnitt — ein Kontextfenster aus dem Seitentext rund um die Übereinstimmung, nicht aus den ersten 200 Zeichen der Seite.
• Direkte Links zur genauen Überschrift. Ein Treffer innerhalb eines Abschnitts enthält den tatsächlichen Anker dieses Abschnitts, sodass der Leser beim Absatz statt am Anfang einer langen Seite landet.
• Übersetzte Seiten zuerst. Befindet sich der Leser in einer übersetzten Spracheinstellung, wird die übersetzte Zeile bevorzugt; nicht übersetzte Seiten werden weiterhin angezeigt, sodass eine teilweise übersetzte Website vollständig durchsucht wird.
• Eine Aufzeichnung jeder Suche, die keine Ergebnisse geliefert hat, in Form eines search.no_results-Webhooks und eines Berichts zu fehlgeschlagenen Suchen.

Wie wird der Index erstellt?#

Write-through beim Rendern, nicht beim Push. Eine Seite wird in den Index aufgenommen, wenn Docsbook sie rendert — nachdem die Antwort gesendet wurde, sodass die Indizierung die Seite niemals verzögert. Eine übersetzte Seite wird auf dieselbe Weise indiziert, sobald ihre Übersetzung im Cache liegt. Es gibt nichts, was man manuell neu aufbauen müsste, und keinen Button zum erneuten Indizieren.

Die Konsequenz sollte man kennen: Eine Seite, die seit ihrer Veröffentlichung niemand geöffnet hat, befindet sich noch nicht im Index. Eine brandneue Website liefert daher zunächst nur wenige Suchergebnisse, bis ihre Seiten einmal besucht wurden. Solange noch kein einziger Datensatz existiert, greift das Suchfeld auf die Übereinstimmung mit Dateinamen aus der Seitenliste zurück, sodass es niemals ohne Ergebnis bleibt.

Was in einen Datensatz eingeht:

Die Suche erfolgt anhand eines generierten tsvector, in dem der Titel das Gewicht A und der Inhalt das Gewicht B erhält — die Gewichtungsbezeichnungen von PostgreSQL existieren, damit „Wörter aus verschiedenen Teilen eines Dokuments von Ranking-Funktionen unterschiedlich gewichtet werden können“ (PostgreSQL: Zusätzliche Textsuchfunktionen). Diese Spalte wird mit GIN indiziert.

Wie wird eine Abfrage beantwortet?#

1. Stoppwörter werden entfernt. websearch_to_tsquery „verknüpft nicht in Anführungszeichen gesetzte Textbegriffe mit dem &-Operator (AND)“ (PostgreSQL: Steuern der Textsuche), sodass ein vollständiger Satz voraussetzt, dass die Seite auch jedes Füllwort enthält. Eine englische Stoppwortliste mit 45 Wörtern wird zuerst entfernt, jedoch nur außerhalb von Anführungszeichen — daher funktionieren "exact phrase", OR und -word weiterhin.
2. Englische Abfragen werden stemming-basiert verarbeitet. Für englische und nicht übersetzte Inhalte werden Abfrage und Dokument anhand der Konfiguration english abgeglichen, die einen Snowball-Stemmer verwendet, der „gängige Varianten von Wörtern auf eine Grundform oder einen Stamm zurückführt“ (PostgreSQL: Wörterbücher). Ohne diese Funktion stimmt eine Seite mit „served“ nicht mit einer Abfrage überein, die „serve“ enthält.
3. Andere Sprachen verwenden den gespeicherten Index. Nicht-englische Gebietsschemata werden mit dem gespeicherten simple-Vektor abgeglichen, der „das Eingabetoken in Kleinbuchstaben umwandelt“ und kein Stemming durchführt. Auf nichtlateinischen Text angewendete englische Stemming-Regeln führen zu unsinnigen Ergebnissen und werden daher bewusst nicht angewendet.
4. Der englische Pfad normalisiert den Rang nach der Länge. Bei englischen Abfragen wird ts_rank mit dem Normalisierungsflag 1 ausgeführt, das „den Rang durch 1 plus den Logarithmus der Dokumentlänge teilt“. Ohne diese Funktion würde ein 76 KB großes Änderungsprotokoll, das jeden Abfragebegriff beiläufig erwähnt, die kurze Seite übertreffen, die sich tatsächlich mit der Frage befasst. Der nicht-englische Pfad ruft ts_rank ohne Normalisierungsflag auf, sodass eine lange Seite in diesen Gebietsschemata nicht wegen ihrer Länge benachteiligt wird — siehe Einschränkungen.
5. Eine Zeile pro Seite. Original und Übersetzung werden zu einem einzigen Ergebnis zusammengeführt, wobei zunächst die Sprache des Lesers und anschließend der Rang bevorzugt werden. Ein Treffer im Titel wird gegenüber Treffern ausschließlich im Textkörper höher eingestuft.
6. Das Snippet wird serverseitig erstellt. ts_headline gibt ein Fragment mit 5–18 Wörtern rund um den Treffer zurück; der Client hebt die Begriffe erneut hervor.

Was passiert bei einem Tippfehler?#

Nichts wird gefunden. Die Docsbook-Suche verwendet keine unscharfe Suche, keine Trigrammähnlichkeit und keinen Fallback über die Edit-Distanz. Stemming deckt Flexionen ab — serve findet served —, aber keine Rechtschreibfehler: documnetation findet nichts.

Das ist eine bewusste Abwägung und kein Versehen. Als Ausgleich gibt es einen Mechanismus: Jede Suchanfrage ohne Ergebnis wird Ihnen gemeldet. Der Bericht wird zusammengefasst, sodass eine Suche ein Signal ergibt und nicht eines pro Tastendruck:

• Der Browser wartet 1,5 Sekunden, nachdem der Leser aufgehört hat zu tippen, bevor er einen Fehlschlag meldet, und meldet ihn sofort, wenn der Leser den Dialog mitten in der Suche schließt — gemessen an einem Live-Arbeitsbereich: Ein Leser, der ein Wort eintippte, pausierte zwischen den Zeichen 0,9–1,3 Sekunden, wodurch vor dieser Änderung acht Berichte für ein einziges Wort erzeugt wurden.
• Der Server unterdrückt unabhängig davon einen Fehlschlag, der innerhalb eines kurzen Zeitfensters vom selben Leser eine strikte Präfixerweiterung des vorherigen ist, da der Endpunkt öffentlich ist und nicht davon ausgehen kann, dass irgendein Client eine Entprellung vorgenommen hat.

Dass documnetation in Ihrem Bericht über fehlgeschlagene Suchen auftaucht, ist also kein Fehler der Suche — die Suche teilt Ihnen mit, dass ein Leser die Seite nicht finden konnte; genau darauf können Sie reagieren. Wiederkehrende Tippfehler beheben Sie am besten in Ihren Inhalten, indem Sie den Begriff aufnehmen, den der Leser tatsächlich eingibt.

Wo das Suchfeld platziert wird#

Aktivieren Sie die Schaltfläche im Header unter Float Widget → Design → Header → Suchschaltfläche. Aktivieren Sie das Feld in der Seitenleiste unter Float Widget → Design → Linke Seitenleiste → In der Seitenleiste suchen. Beide Optionen sind in jedem Tarif kostenlos.

Warum dies der richtige Weg ist (Belege)#

Der gleiche Index ist einer der beiden Retriever hinter dem KI-Chat — auch dort ist er kein minderwertiger Fallback.

Grenzen#

• Keine Fehlertoleranz bei Tippfehlern. Siehe oben. Wenn eine falsche Schreibweise für Ihre Zielgruppe relevant ist, fügen Sie den Begriff der Seite hinzu.
• Codeblöcke sind nicht durchsuchbar. Eingezäunter Code wird vor der Indexierung entfernt, und <pre>-Blöcke werden aus dem Abschnittstext entfernt. Leser, die nach einem Funktionsnamen suchen, der nur innerhalb eines Codebeispiels vorkommt, werden ihn nicht finden. Infrage gestellt: In der älteren Dokumentation wurde behauptet, dass Codeblöcke indexiert und „unterhalb von Fließtext eingestuft“ würden; der Indexierer entfernt sie stattdessen vollständig.
• Die Abdeckung hängt vom Datenverkehr ab, nicht von Ihrem Repository. Eine Seite wird bei ihrer ersten Darstellung in den Index aufgenommen. Eine veröffentlichte, aber nie geöffnete Seite fehlt in den Suchergebnissen, bis sie jemand öffnet.
• Wir veröffentlichen keine Latenzangabe. Englische Abfragen berechnen ihren tsvector zum Abfragezeitpunkt, anstatt den gespeicherten simple-Index zu lesen. Das bedeutet, dass der englische Pfad pro Abfrage mehr Arbeit verrichtet, wenn der Korpus wächst. Wir haben keinen Benchmark veröffentlicht und werden keinen angeben, bevor wir einen haben.
• Die Längennormalisierung ist nur für Englisch verfügbar. Der englische Abfragepfad übergibt das Normalisierungsflag 1 an ts_rank; der für andere Sprachen verwendete Pfad ruft ts_rank ganz ohne Flag auf, wodurch keine Längennormalisierung erfolgt. Auf einer nicht englischsprachigen Website kann eine sehr lange Seite daher eine kurze Seite übertreffen, die sich präziser auf die Abfrage bezieht. Infrage gestellt, bis die beiden Pfade angeglichen sind.
• Die Suche erfolgt pro Projekt. Der Index ist auf einen Arbeitsbereich beschränkt; es gibt keine projektübergreifende Suche.
• Das Signal für eine fehlgeschlagene Suche wird zusammengefasst und ist nicht exakt. Der erste Fehlschlag einer Eingabekette wird an einen aktiven Webhook übermittelt, sodass die übermittelte Abfrage ein kürzeres Präfix der Abfrage sein kann, bei der der Leser letztendlich geblieben ist. Der historische Bericht stellt die endgültige Abfrage wieder her.

Verwandte Inhalte#

• KI-Chat — der Assistent, der diesen Index als einen seiner Retriever verwendet.
• Antwortqualität — wie lexikalische und Vektor-Suche zusammengeführt werden.
• Analysen: wonach Leser gesucht haben — die Suchanfragen, die keine Ergebnisse geliefert haben.
• Seitenfeedback — das andere Signal dafür, dass eine Seite fehlt oder falsch benannt ist.