SmartSearch

Bitte beachten Sie, dass haupia mit Version 2.4.0 in SmartSearch umbenannt wurde. Während wir unsere Dokumentation entsprechend aktualisiert haben, könnten Sie "haupia" dennoch in älteren Code-Beispielen, APIs, Skripten und Konfigurationsdateien vorfinden. In solchen Fällen betrachten Sie bitte SmartSearch als den aktuellen und korrekten Begriff. Wir empfehlen, bei der Umsetzung von Lösungen aus älterer Dokumentation die entsprechenden Anpassungen vorzunehmen.

1. Einleitung

Eine Suche auf einer Internetseite ist besonders wichtig, da heutzutage immer mehr Informationen online verfügbar sind und Websites immer größer und komplexer werden. Eine effektive Suchfunktion ermöglicht es den Nutzenden, schnell und einfach die gewünschten Informationen zu finden, ohne sich durch unzählige Seiten und Links zu klicken. Es ist auch eine effiziente Möglichkeit, Zeit zu sparen und die User Experience zu verbessern, da es den Nutzenden ermöglicht, direkt zu den relevanten Inhalten zu gelangen, ohne sich mit unnötigen Informationen befassen zu müssen. Darüber hinaus kann eine gute Suchfunktion auch dazu beitragen, dass eine Website als userfreundlich und professionell wahrgenommen wird, was wiederum das Vertrauen der Nutzenden erhöht und dazu beitragen kann, dass sie sich länger auf der Website aufhalten und öfter wiederkommen. Insgesamt ist eine effektive Suche auf einer Internetseite ein wichtiger Faktor für eine positive User Experience und den Erfolg einer Website.

Die Suchfunktion auf der Internetseite auch als Marketinginstrument genutzt werden, um den Besuchern personalisierte Angebote und Empfehlungen zu unterbreiten. Wenn ein Besucher beispielsweise nach einem bestimmten Produkt sucht, kann das Unternehmen ihm ähnliche oder ergänzende Produkte empfehlen oder ihm spezielle Angebote unterbreiten, um seine Kaufbereitschaft zu erhöhen. Zudem können bestimmte Treffer besser in den Suchergebnissen platziert werden, um die Besuchenden der Internetseite auf bestimmte Inhalte aufmerksam zu machen.

Die Suche gibt dem Unternehmen wertvolle Einblicke in die Bedürfnisse und Interessen der Besucher. Durch die Analyse der Suchbegriffe und -ergebnisse können Unternehmen Trends und Muster identifizieren und ihre Website-Inhalte entsprechend anpassen, um den Bedürfnissen der Zielgruppe besser gerecht zu werden. Auf diese Weise kann die Website auch als Marktforschungsinstrument dienen.

Insgesamt kann eine gut gestaltete Suchfunktion auf der Internetseite nicht nur dazu beitragen, die User Experience zu verbessern und die Conversion-Rate zu erhöhen, sondern auch wertvolle Einblicke in die Bedürfnisse der Zielgruppe liefern und als Marketinginstrument zur Akquisition und Bindung von Kundenunternehmen genutzt werden.

Die SmartSearch bündelt Anforderungen, die an die Suchfunktion einer Online-Präsenz gestellt werden: Eine intuitiv bedienbare, hochperformante Suchlösung, die auf umfangreichen Webseiten einsetzbar ist und relevante Ergebnisse liefert. Sie bietet sowohl eine hohe Trefferqualität als auch einen optimalen Suchkomfort und bindet Nutzende somit auf der Webseite.

Gleichzeitig stellt sie Bearbeitenden durch das integrierte SmartSearch-Cockpit eine Web-Oberfläche bereit, die ohne IT-Kenntnisse verwendbar ist. Bearbeitende aus Fach- und Marketingabteilungen werden so in die Lage versetzt, Suchergebnisse auf der Webpräsenz zu steuern und zu überwachen. Das Cockpit stellt dafür Statistiken, Filter sowie Analysefunktionen bereit und erlaubt die Indizierung verschiedenster Datentypen (zum Beispiel XML, Audio, Video, Medien) aus unterschiedlichen Datenquellen. Mithilfe individualisierter Trefferlisten können Bearbeitende im Backend Suchergebnisse priorisieren und gewichten sowie ausgewählte Inhalte zu vordefinierten Suchanfragen ausgeben lassen.

1.1. Konzept

Die SmartSearch-Funktionalität, z. B. Einstellungen zu Userberechtigungen und Gruppenberechtigungen, kann ohne technisches Vorwissen im Browser-basierten SmartSearch-Cockpit verwaltet werden.

1.1.1. Datengenerator

Im SmartSearch-Cockpit können Sie Datengeneratoren anlegen, um durchsuchbare Daten zu erfassen.

Es gibt drei Typen von Datengeneratoren:

Web: Der Webcrawler verbessert die Durchsuchbarkeit einer existierenden Website.
XML: Der XML-Datei-Crawler beschleunigt die Verarbeitung von Daten, wenn sie als XML-Dateien vorliegen.
API: Unterstützt bei der Übergabe von Daten von einer selbst entwickelten Anwendung oder dem FirstSpirit-Modul SmartSearch Connect an eine API.

1.1.2. Prepared Search

Mithilfe eines Prepared Search können Sie das Suchergebnis konfigurieren, z. B. durch das Bündeln von Inhalten aus mehreren Datengeneratoren in einem Prepared Search.

1.1.3. Adaptable Result

In einem Adaptable Result können Sie die Suchergebnisse aktiv verändern, um z. B. bestimmte Suchergebnisse weiter oben in der Liste anzuzeigen, oder um Suchergebnisse aus der Liste auszuschließen.

1.1.4. Synonyme und Stoppwörter

Sie können ein Synonym festlegen, um einen Begriff mit der Suche zu verknüpfen, der im Website-Text nicht vorkommt, aber sinngemäß mit einem anderen Suchbegriff verbunden ist. Synonyme können z. B. aus häufigen Suchanfragen abgeleitet werden.

Sie können Stoppwörter verwenden, um bestimmte Begriffe bei der Suchanfrage zu ignorieren. Eine Liste mit typischen Stoppwörtern für die einzelnen Sprachen wird bereitgestellt und kann erweitert werden.

1.2. Architektur

Die Funktionalitäten der SmartSearch werden über eine Architektur verschiedener Komponenten realisiert (vgl. Abbildung Architektur).

Bei diesen Komponenten handelt es sich um:

ZooKeeper
Solr
SmartSearch

Abbildung 1. Architektur

Das Zusammenspiel der Komponenten erfolgt immer nach dem folgenden Schema:

Für die Erstellung des Suchindex muss die SmartSearch zunächst die notwendigen Daten erfassen. Dafür greift sie kundenunternehmensseitig auf die zu erfassenden Informationen zu, die in Form von Webseiten, Portalen oder Datenbanken vorliegen können. Darüber hinaus stellt eine REST-Schnittstelle die Möglichkeit bereit, den Suchindex von außen mit weiteren Daten zu befüllen.
Danach normalisiert der SmartSearch-Server die erfassten Daten und überträgt sie an den Solr-Server. Dieser nimmt die Daten entgegen und persistiert sie in einem Index.
Die Abfrage der Daten erfolgt äquivalent: Der SmartSearch-Server nimmt die Anfrage entgegen, modifiziert sie und leitet sie dann an den Solr-Server weiter. Dieser antwortet mit einem Suchergebnis, das der SmartSearch-Server über die REST-Schnittstelle an die Endanwendung des Kundenunternehmens zurückliefert.
Das SmartSearch-Cockpit ist losgelöst von den übrigen Komponenten zu sehen. Es dient der Verwaltung des SmartSearch-Servers und bietet dafür eine einfache, webbasierte Admin-Oberfläche an. In dieser sind unter anderem Suchlösungen erstell- und konfigurierbar.
Die Speicherung der im SmartSearch-Cockpit vorgenommenen Konfigurationen erfolgt neben den Solr-Konfigurationsdaten auf dem ZooKeeper-Server.

Die Kommunikation nach außen ist durch HTTPS geschützt, zwischen den Komponenten erfolgt sie per HTTP.

1.3. Technische Voraussetzungen

Der Einsatz der SmartSearch besitzt die folgenden technischen Voraussetzungen:

Java 21
ZooKeeper in der Version 3.9
Solr in der Version 9.7 im Cloud-Modus
SmartSearch in der neuesten Version

ZooKeeper und Solr sind nicht in der Auslieferung enthalten. Sie müssen daher vor der Installation in der angegebenen Version heruntergeladen werden.

2. SmartSearch-Cockpit

Das SmartSearch-Cockpit ist ein Bestandteil der SmartSearch. Es dient der Backend-seitigen Verwaltung der durch die SmartSearch erfassten Daten und bietet dafür eine einfache, webbasierte Oberfläche an. Diese gliedert sich in die Bereiche Konfiguration, Analyse, Daten und System, die über das Menü zu erreichen sind. Der Button mit dem Weltkugel-Icon stellt darüber hinaus einen Sprachumschalter zwischen Deutsch und Englisch bereit.

Das SmartSearch-Cockpit ist standardmäßig unter der folgenden URL erreichbar:

http://<Servername>:8181

Der erste Aufruf des Cockpits muss mit dem Master-Admin erfolgen. Er wird beim initialen Start des SmartSearch-Servers automatisch mit den Daten aus der application.yml erzeugt.

Ist die User- und Gruppenverwaltung über einen LDAP-Server realisiert, können die Zugangsdaten abweichen.

Nach der validen Eingabe wird der User automatisch auf das Dashboard des Cockpits weitergeleitet. Eine erneute Authentifizierung ist erst nach einer expliziten Abmeldung oder nach dem Ablauf einer Sitzung erforderlich.

Abbildung 2. SmartSearch-Dashboard

2.1. Konfiguration

Der Bereich Konfiguration gliedert sich in die Untermenüs Prepared Search, Stoppwörter und Synonyme. Diese ermöglichen die Konfiguration der Ausgabe der von der SmartSearch erfassten Daten.

Die nachfolgenden Unterkapitel beschreiben die Untermenüs und die durch sie zur Verfügung gestellten Funktionen.

2.1.1. Prepared Search

Die kundenunternehmensseitige Erfassung der benötigten Daten erfolgt über die sogenannten Datengeneratoren, die ein Bestandteil des Bereichs Daten sind. Für ihre Verwaltung stellt die SmartSearch die Prepared Searches zur Verfügung. Diese ermöglichen die Optimierung der Suchergebnisse durch die Priorisierung einzelner Daten.

Die Erstellung und Verwaltung der Prepared Searches erfolgt in der gleichnamige Oberfläche, die über den Menübereich Konfiguration Prepared Search aufrufbar ist.

Der Bereich zeigt eine Liste aller bereits existierenden Prepared Searches und ist initial leer.

Im Cloud-Modus wird in der Liste außerdem die Erreichbarkeit jeder Prepared Search angezeigt.

Abbildung 3. Prepared Searches

Neue Prepared Search

Für die Erstellung einer neuen Prepared Search existiert eine eigene Ansicht, die per Klick auf den Button Neue Prepared Search aufrufbar ist und sich in die drei Tabs Allgemein, Facetten und Vorschau gliedert.

Abbildung 4. Erstellen einer Prepared Search

Allgemein

Innerhalb des Tabs Allgemein ist zunächst ein Name für die neu zu erstellende Prepared Search anzugeben. Im Cloud-Modus befindet sich neben dem Eingabefeld für den Namen die zusätzliche Checkbox öffentlich Erreichbar. Mit ihr ist die Erreichbarkeit einer Prepared Search definierbar. Die Aktivierung der Checkbox ermöglicht die Abfrage der Prepared Search über das Internet (API Gateway). Ansonsten ist die Prepared Search nur so erreichbar, wie es das Cockpit auch ist.

Die anschließende Selektion beliebig vieler Datengeneratoren in der gleichnamigen Auswahlliste zeigt deren verfügbare Felder. Die initial aktivierte Checkbox Verbose blendet dabei alle technischen Felder ein bzw. aus. Die zusammen mit der Checkbox bereitgestellte Schaltfläche ermöglicht die Gewichtung der ausgewählten Felder.

Die Liste der Feldnamen pro Datengenerator ist gecached. Beim neu Anlegen eines Datengenerators und dessen ersten Durchlauf, kann es einige Minuten dauern, bis die Felder in der Liste auftauchen.

Die ausgewählten Felder lassen sich per Button in die Liste der für eine Suche relevanten Felder übernehmen, die standardmäßig die Felder content,link und title enthält. Eine zuvor definierte Gewichtung wird dabei automatisch jedem dieser Felder zugeordnet.

Die Liste stellt pro Feld die folgenden Konfigurationsmöglichkeiten bereit:

Highlight: Mit der Aktivierung dieser Checkbox wird ein Suchwort innerhalb eines Textausschnitts im Suchergebnis hervorgehoben. Die Länge des Textausschnitts ist dabei frei konfigurierbar (siehe unten).
Ausgabe: Diese Option definiert, ob das Feld im Suchergebnis sichtbar ist. Im Falle des Links, der lediglich auf das gesamte Dokument verweist, ist dies zum Beispiel möglicherweise nicht gewünscht.

Durchsuchen: Damit das zugehörige Feld von der Suche berücksichtigt wird, ist diese Checkbox zu aktivieren.

Die Deaktivierung der Option Durchsuchen blendet die nachfolgenden Optionen Teiltreffer und Gewichtung für das entsprechende Feld aus.

Teiltreffer: Diese Option ermöglicht die Berücksichtigung von Teiltreffern. Ist die Checkbox selektiert, findet die Suche nach Strom beispielsweise auch den Treffer Ökostromanbieter. Das Suchwort muss dabei eine Länge von drei bis zwanzig Zeichen besitzen.
Gewichtung: Die Gewichtung bietet die Möglichkeit, für Treffer der ausgewählten Felder eine Priorisierung festzulegen und damit das Suchergebnis zu beeinflussen.

Der Button mit dem Symbol eines Mülleimers, der für jedes Feld verfügbar ist, erlaubt die Löschung des entsprechenden Felds aus der Liste.

Der Tab enthält darüber hinaus die folgenden allgemeinen Konfigurationsmöglichkeiten:
Treffer pro Seite: Entsprechend ihres Namens gibt diese Schaltfläche die maximale, auf einer Suchergebnisseite dargestellte Anzahl von Treffern an. In Verbindung mit dem URL-Parameter page lässt sich außerdem eine Aufteilung der Suchergebnisse auf mehrere Seiten realisieren.
Länge Highlight (in Zeichen): Mithilfe dieser Schaltfläche lässt sich wie zuvor erwähnt die Länge des Textausschnitts definieren, in dem ein Suchbegriff visuell hervorgehoben wird.
Sortieren nach: Die Sortierung der Suchergebnisse ist standardmäßig absteigend nach ihrem Score. Ist eine andere Sortierung gewünscht, ermöglicht dieses Texteingabefeld eine entsprechende Anpassung. Dafür ist ein beliebiges Feld anzugeben und durch den Ausdruck ASC für eine aufsteigende oder DESC für eine absteigende Sortierung zu ergänzen.

Spellcheck (Trefferzahl kleiner als): Ist die Anzahl der Suchergebnisse kleiner als der an dieser Stelle konfigurierte Wert, erfolgt eine Rechtschreibprüfung und die Suche nach Suchwörtern ähnlicher Schreibweise.
Must Match: Für die Suche nach mehreren Begriffen legt die Eingabe dieses Texteingabefelds fest, wie diese zu verknüpfen sind:
- Der Wert 0 entspricht einer Oder-Beziehung zwischen den verwendeten Suchbegriffen.
- Der Wert 100% entspricht einer Und-Beziehung zwischen den verwendeten Suchbegriffen.
- Ein absoluter Wert definiert die Anzahl der Begriffe, die in einem Suchtreffer enthalten sein müssen. Der Wert 2 bei fünf Suchbegriffen besagt beispielsweise, dass zwei der fünf Ausdrücke innerhalb eines Suchergebnisses enthalten sein müssen. Die Werte 2 und 50% sind bei vier Suchbegriffen äquivalent zueinander.
Groovy-Skript: Prepared Searches erlauben darüber hinaus die Einbindung eines selbst zu implementierenden Groovy-Skripts. Ein solches Skript ermöglicht zusätzliche Modifikationen des Datenbestands. So lassen sich dem Datenbestand beispielsweise weitere Dokumente hinzufügen oder der bestehende Datenbestand bearbeiten.

Facetten: Facetten bieten die Möglichkeit, Trefferlisten nach Feldern, die in einem Dokument vorhanden sind, einzuschränken. Da sich Facetten immer auf die im Tab Allgemein selektierten Datengeneratoren beziehen, ist der Tab Facetten initial leer.

Abbildung 5. Facetten

Neue Facette

Für die Erstellung einer neuen Facette existiert eine eigene Ansicht, die per Klick auf den Button Neue Facette aufrufbar ist. Dieser ist nur dann aktiv, wenn im Tab Allgemein mindestens ein Datengenerator definiert ist.

Innerhalb des Tabs ist im gleichnamigen Dropdown zunächst ein Feld auszuwählen. Die verfügbaren Felder stammen dabei aus den selektierten Datengeneratoren. Mit der Auswahl eines Felds erscheint eine Liste der diesem Feld zugehörigen Werte, für die Facette gibt es folgende Konfigurationsmöglichkeiten:

Filter: Mit diesem Eingabefeld können Facettenwerte gesucht werden.
Nur gewichtete Werte anzeigen: Durch das Anwählen dieser Checkbox werden nur Facettenwerte angezeigt, die gewichtet wurden.
Gewicht: Mit einem klick auf das Feld Gewicht kann einem Facettenwert eine Gewichtung zugeordnet werden. Diese Zahl stellt einen Multiplikator des Scores dar und kann zwischen 0.00 und 9.99 liegen. Empfohlen ist ein Wert zwischen 0.00 und 2.00. Ergebnisse, die diesem Facettenwert angehören, erhalten eine Gewichtung und werden entsprechend höher oder niedriger in den Suchergebnissen gereiht.
Werte anzeigen bei Trefferzahl größer als: Mithilfe dieser Option lassen sich Werte, deren Trefferzahl den angegebenen Schwellwert unterschreiten, aus der Facettenliste ausschließen.
Mehrfachauswahl möglich: Diese Option erlaubt die Filterung der Suchergebnisliste nach unterschiedlichen Aspekten. So ist die Suche nach einem bestimmten Objekt beispielsweise im Anschluss sowohl auf eine bestimmte Größe als auch auf eine bestimmte Farbe einschränkbar. Die Suche ist dadurch spezifischer und die Suchergebnisliste minimiert.
Eigenen Filter exkludieren: Um für die Suche verschiedene Filteroptionen bereitzustellen, darf sich die Auswahl eines Filters nur auf die Suchergebnisliste, aber nicht auf die Filteroptionen beziehen. Andernfalls würden die übrigen Optionen durch die Suche ebenfalls ausgeblendet.

Existieren für die Facette Sprache beispielsweise die Filteroptionen Deutsch, Englisch und Französisch liefert die Suche bei der Auswahl der Option Englisch nur noch englische Dokumente zurück. Wird der Filter Englisch in diesem Fall nicht exkludiert, zeigt auch die Liste der zur Verfügung stehenden Filter nur noch Englisch an. In diesem Fall ist es nicht mehr möglich, auf einen anderen Filter zu wechseln oder in Zusammenhang mit der vorhergehenden Konfigurationsmöglichkeit eine Mehrfachauswahl zu treffen.

Vorschau

Das Vorschautab ermöglicht die Testung von Prepared Search-Konfigurationen auf einer Vorschauseite. Dazu ist es nicht notwendig, die Prepared Search zu speichern. Sämtliche Einstellungen aus den Tabs Allgemein und Facetten werden direkt für die Suchanfragen übernommen.

Auf der Seite befindet sich ein Eingabefeld für Suchbegriffe. Die Suche nach dem eingegebenen Begriff erfolgt anschließend in der aktuellen Prepared Search mit der zuvor eingestellten Konfiguration und das Vorschautab zeigt die Ergebnisse dieser Suchanfrage an. An jedem Suchergebnis befindet sich ein Button in Form eines nach oben gerichteten Pfeils. Ein Klick auf diesen zeigt unterhalb des Ergebnisses sämtliche Felder an, die in dieser Prepared Search ausgewählt sind.

Um eine neue Facette in die Vorschau zu übernehmen, genügt es, nach dem Anlegen der Facette die Konfiguration mit einem Klick auf OK zu bestätigen. Nach einem Wechsel zurück in das Vorschautab wird noch einmal automatisch mit dem letzten Suchbegriff gesucht und in der Spalte neben den Suchergebnissen erscheinen neue Filtermöglichkeiten. Diese erhalten ihre Namen und Werte aus der zuvor angelegten Facette. Mit der Vorschaufunktion lassen sich ebenfalls Gewichtungen oder Groovy-Skripte testen.

Bereits zuvor angelegte Adaptable Results erscheinen in der festgelegten Reihenfolge in der Vorschau.

Abbildung 6. Suchanfrage im Vorschautab

Liste bestehender Prepared Searches

Nach der Speicherung und erfolgreichen Erzeugung der Prepared Search wird sie der Liste bestehender Prepared Searches im gleichnamigen Bereich hinzugefügt. Die Liste gliedert sich in zwei Spalten mit den folgenden Informationen:

Name: Die Spalte enthält den Namen der Prepared Search, der während der Erzeugung angegeben wurde.
Letzte Bearbeitung: Die Informationen in dieser Spalte zeigen, wer und wann die letzte Änderung an der Prepared Search vorgenommen hat.

Prepared Search bearbeiten

Der Button mit dem Symbol eines Stifts ermöglicht die Bearbeitung einer Prepared Search. Ein Klick auf ihn öffnet die Detailansicht mit den vorgenommenen Eingaben. Diese lassen sich entsprechend der zuvor beschriebenen Möglichkeiten verändern.

Prepared Search löschen

Der Button mit dem Symbol eines Mülleimers ermöglicht die Löschung einer Prepared Search. Ein Klick auf diesen Button öffnet einen Dialog mit einer Sicherheitsabfrage, mit der die Löschung zu bestätigen ist.

Alternativ besteht über Checkboxen, die in der Übersichtsliste vor jeder Prepared Search sichtbar sind, die Möglichkeit, mehrere Prepared Searches für die Löschung auszuwählen. Der Button Ausgewählte löschen entfernt diese markierten Prepared Searches, nachdem zuvor ebenfalls eine Sicherheitsabfrage bestätigt wurde.

2.1.2. Stoppwörter

Jeder geschriebene Text enthält Artikel, Füllwörter und weitere Begriffe, die für eine Suchabfrage irrelevant und daher zu ignorieren sind. Aus diesem Grund besitzt die SmartSearch für jede der 26 unterstützten Sprachen eine Liste sogenannter Stoppwörter, die sie im Menübereich Konfiguration Stoppwörter in Form eines Drop-Down-Menüs bereitstellt. Die in diesen Listen enthaltenen Begriffe werden bei der Erfassung der Daten durch die Datengeneratoren ignoriert und nicht in den Suchindex aufgenommen.

Für die Bearbeitung einer Stoppwörter-Liste ist sie zunächst in dem Drop-Down-Menü zu selektieren. Die Oberfläche zeigt daraufhin alle in ihr enthaltenen Stoppwörter an.

Abbildung 7. Stoppwörter

Das Feld Neue Stoppwörter hinzufügen ermöglicht die kommaseparierte Eingabe weiterer Stoppwörter, die per Klick auf den Button mit dem Plus-Symbol in die Liste übernommen werden. Die Buttons mit dem Symbol eines Stifts bzw. eines Mülleimers, die pro Stoppwort sichtbar sind, erlauben die Bearbeitung bzw. Löschung eines einzelnen Eintrags der Liste.

Jede Änderung an der selektierten Liste erfordert abschließend eine Speicherung über den Button mit dem Symbol eines Hakens, der neben dem Drop-Down-Menü dargestellt ist. Erst mit diesem Klick erfolgt eine Übernahme der Anpassungen, auch wenn sie zuvor bereits in der Liste sichtbar sind.

Damit die Änderungen an den Stoppwörter-Listen berücksichtigt werden, ist ein erneuter Durchlauf der Datengeneratoren notwendig.

Die gleichzeitige Verwendung von Stoppwörtern und Synonymen für identische Begriffe ist nicht sinnvoll.

Ist zum Beispiel ein Stoppwort Energie gepflegt, so wird eine gleichzeitige Pflege von Synonymen für Energie nicht den gewünschten Ersetzungseffekt haben.

2.1.3. Synonyme und Ersetzungen

Ähnlich zu den Stoppwörtern, mit denen sich irrelevante Begriffe aus dem erfassten Datenbestand herausfiltern lassen, ermöglichen Synonyme und Ersetzungen die Ergänzung spezifischer Bezeichnungen. Im Menübereich Konfiguration Synonyme gibt es die Möglichkeit in einem Drop-Down-Menü eine Sprache auszuwählen. Darunter befinden sich zwei Reiter für die Eingabe von Ersetzungen und Synonymen. Im ausgewählten Reiter erscheint dann nach erfolgter Sprachauswahl eine Liste von Ersetzungen oder Synonymen zur ausgewählten Sprache. Diese ist initial leer und kann durch das entsprechende Eingabefeld erweitert werden.

Jeder eingegebene Begriff wird beim Speichern zu Kleinbuchstaben konvertiert.

Ersetzungen

Hierbei handelt es sich um eine Liste von Ersetzungen. Jeder Eintrag bildet einen Suchbegriff auf eine Reihe von Wörtern ab. Das Feld Neuen Suchbegriff hinzufügen ermöglicht die Eingabe eines Suchbegriffs. Nach der Bestätigung mit 'Enter' oder einem click auf den Button mit dem Plussymbol erscheint das Wort gemeinsam mit einer leeren Reihe von Ersetzungen in der Liste darunter. Über das Feld Neue Ersetzung hinzufügen lassen sich dem Suchbegriff die entsprechenden Ersetzungen zuordnen.

Es ist auch möglich mehrere, kommaseparierte Begriffe in das Feld Neuen Suchbegriff hinzufügen einzugeben. In diesem Fall wird der erste eingegebene Begriff zum Suchbegriff und die restlichen Wörter werden zu deren Ersetzungen. Ähnliches gilt auch für das Feld Neue Ersetzung hinzufügen.

Nach dem Speichern wird zukünftig eine Suche nach dem eingegeben Begriff ersetzt durch die Begriffe in der dazugehörigen Reihe.

Des Weiteren erlauben die Buttons mit dem Symbol eines Stifts bzw. eines Mülleimers, die pro Suchwort sichtbar sind, die Bearbeitung bzw. Löschung eines einzelnen Eintrags in der Liste.

Abbildung 8. Ersetzungen

Synonyme

Hierbei handelt es sich um eine Liste von Synonymreihen. Einträge einer Synonymreihe werden von der Suche als synonym behandelt. Das bedeutet, dass eine Suche nach einem Begriff aus einer Reihe Ergebnisse für alle Begriffe aus der Reihe liefert. Das Feld Neue Synonyme hinzufügen ermöglicht das anlegen einer neuen Reihe. Hier ist es ebenfalls möglich mehrere, kommaseparierte Begriffe einzugeben. In diesem Fall tauchen diese als einzelne Begriffe in einer neuen Synonymreihe in der Liste unterhalb auf.

Ersetzungen, die wie Synonyme funktionieren werden von SmartSearch erkannt und tauchen nach dem Speichern im Reiter Synonyme auf.

Beispiel: Eine Ersetzungliste mit dem Suchwort energie und den Ersetzungen energie und strom sowie dem Suchwort strom und den Ersetzungen energie und strom ist äquivalent zu einer Synonymliste mit den Begriffen energie und strom

Abbildung 9. Synonyme

Jede Änderung an der selektierten Liste erfordert abschließend eine Speicherung über den Button mit der Aufschrift "Speichern", der neben dem Drop-Down-Menü dargestellt ist. Erst mit diesem Klick erfolgt eine Übernahme der Anpassungen, auch wenn sie zuvor bereits in der Liste sichtbar sind.

Die gleichzeitige Verwendung von Stoppwörtern und Synonymen für identische Begriffe ist nicht sinnvoll.

Ist zum Beispiel ein Stoppwort Energie gepflegt, so wird eine gleichzeitige Pflege von Synonymen für Energie nicht den gewünschten Ersetzungseffekt haben.

2.2. Analyse

Der Bereich Analyse glieder sich in die Untermenüs Statistiken und Adaptable Results. Sie ermöglichen sowohl die Analyse der getätigten Suchabfragen als auch die manuelle Steuerung der Trefferreihenfolge für einzelne Suchbegriffe.

Die nachfolgenden Unterkapitel beschreiben die Untermenüs und die durch sie zur Verfügung gestellten Funktionen.

2.2.1. Statistiken

Der Bereich Statistiken ermöglicht die Analyse der Suchanfragen einer spezifischen Prepared Search. Das gleichnamige Feld listet dafür alle bestehenden Prepared Searches auf, aus der die zu analysierende Prepared Search per Checkbox auszuwählen ist.

Alle fünfzehn Minuten erfolgt eine automatische Aktualisierung der zu analysierenden Daten, so dass die Analyse jederzeit auf einem möglichst aktuellen Datenbestand basiert.

Die nachfolgenden Felder dienen der Spezifizierung der zu analysierenden Daten:

Das Drop-Down-Menü Anzahl Ergebnisse zeigt an, ob für die Analyse die 10, 25, 50 oder 100 meistgesuchten Suchwörter ausgegeben werden sollen.
Die Felder Von und Bis legen den zu berücksichtigenden Zeitraum fest.
Das Feld Tags ermöglicht die Anpassung der Statistik durch spezifische Filterkriterien. Sie dienen der Kategorisierung von Suchabfragen und lassen sich während deren Ausführung definieren. Standardmäßig erfolgt die Eingabe der Tags in der Basic-Ansicht, in der sie durch einfaches Anklicken auswählbar sind. Alle ausgewählten Tags sind durch eine Und- bzw. Oder-Verknüpfung miteinander verbunden. Der Button Advanced erlaubt darüber hinaus den Wechsel zu einer komplexeren Eingabe der Tags.

Beispiele zur Nutzung von Tags sind im Abschnitt Tags enthalten.

Ein Wechsel von der Basic- zur Advanced-Eingabe ist jederzeit möglich. Der Wechsel in die andere Richtung ist nur dann durchführbar, wenn sich die eingegebene Filterung in der Basic-Eingabe abbilden lässt.

Der Button Übernehmen führt die Ermittlung der häufigsten Suchwörter aus, die sich anhand der vorgenommenen Konfiguration für die ausgewählte Prepared Search ergeben. Sie werden anschließend als Liste in der Oberfläche angezeigt.

Abbildung 10. Statistiken

Der Button CSV herunterladen stellt sowohl die definierten Konfigurationsdaten als auch die auf ihrer Basis ermittelten Suchwörter in Form einer CSV-Datei bereit. Sie enthält zusätzlich zu diesen Informationen einen Deeplink und die absolute Summe aller Suchanfragen - mit und ohne Filterung. Der Deeplink ermöglicht den erneuten Download der Datei.

Abbildung 11. Statistiken für die folgende CSV-Datei

Die CSV-Datei, welche aus der gezeigten Statistik generiert wurde, beinhaltet den Deeplink (csv deep link) sowie folgende statistische Parameter:

Suchbegriffe (string)
Suchhäufigkeit (count)
Gewählter Zeitraum (start, end)
Namen der gewählten Prepared Search (hier Mithras)
Anfragesummen mit (total) und ohne (total without filter) Filter.

Abbildung 12. Die CSV-Datei für gezeigte Statistiken

Den in der CSV enthaltenen Deeplink stellt auch der Button Copy to clipboard > Deep Link CSV bereit. Der Button Copy to clipboard > Deep Link Cockpit stellt einen Link bereit, mit dem sich der Bereich Statistiken inklusive der vorgenommenen Konfiguration erneut aufrufen lässt. Auf diesem Weg können sowohl die Einstellungen als auch das auf ihnen basierende Ergebnis Dritten zur Verfügung gestellt werden.

2.2.2. Adaptable Results

Die Speicherung der durch die SmartSearch ermittelten Inhalte geschieht in einer Vielzahl unterschiedlicher Felder. Diesen lässt sich während der Konfiguration einer Prepared Search eine Gewichtung zugeordnen, um sie so unterschiedlich zu priorisieren. Sie erhalten dadurch einen sogenannten Score, der automatisch berechnet wird und jeweils die Reihenfolge einer Suchergebnisliste bestimmt. Die manuelle Steuerung dieser Suchergebnislisten, den sogenannten Adaptable Results, erfolgt im gleichnamigen Bereich.

Es ist ebenfalls möglich, Adaptable Results anzulegen für Suchbegriffe, die keine Ergebnisse liefern.

Abbildung 13. Adaptable Results

Der Bereich zeigt eine Liste aller bereits bestehenden Adaptable Results, die jeweils der Suchabfrage zu einem Suchwort einer Prepared Search entsprechen.

Adaptable Result anlegen

Für die Erstellung eines neuen Adaptable Results existiert eine eigene Ansicht, die per Klick auf den Button Neue Adaptable Result aufrufbar ist.

Abbildung 14. Neues Adaptable Result

Innerhalb der Ansicht ist eine Prepared Search auszuwählen und ein beliebiger Suchbegriff einzugeben, für den die Reihenfolge der Suchergebnisse verändert werden soll. Ein Klick auf den Button Übernehmen deaktiviert die beiden Felder und ermittelt anhand der Angaben die zugehörige Ergebnisliste, die in Form einer Tabelle angezeigt wird. Der Button Zurücksetzen blendet die Tabelle aus und aktiviert die beiden Felder wieder.

Neben dem Titel, dem Link und den ausgewerteten Tokens des dargestellten Dokuments zeigt jeder Eintrag in der Tabelle den ihm zugeordneten Score, aus dem sich seine Position in der Liste ergibt. Diese ist über die ebenfalls pro Eintrag angezeigten Buttons Elevate und Exclude beeinflussbar:

Elevate: Der Button Elevate hebt das Suchergebnis grün hervor und verschiebt es an die erste Position der Ergebnisliste. Über die anstelle des Elevate-Buttons erscheinenden Pfeil-Buttons lässt sich die Position des Eintrags noch genauer festlegen. Dabei ist jedoch zu beachten, dass sich die Positionierung über die Pfeil-Buttons nur auf die priorisierten Einträge bezieht. Eine Vermischung priorisierter und nicht priorisierter Einträge ist nicht möglich. Über den Button mit dem Symbol eines Minuszeichens kann die Priorisierung wieder aufgehoben werden.
Exclude/Include: Der Button Exclude hebt das Suchergebnis gelb hervor und entfernt es aus der Ergebnisliste. Dies bedeutet, dass es nicht mehr im Frontend angezeigt wird. Der stattdessen erscheinende Button Include fügt das Suchergebnis wieder der Liste hinzu.

Sowohl Elevations als auch Exclusions basieren auf Links, die zu einem bestimmten Zeitpunkt im Index vorhanden sind. Durch die Veränderung der Suchergebnisliste kann es daher zu Situationen kommen, in denen die Links nicht mehr verfügbar und somit vom Datengenerator nicht mehr erfassbar sind. Aufgrund ihrer fehlenden Entsprechung im Index sind diese Links nicht mehr in der Listenansicht anzeigbar. Es handelt sich bei ihnen um sogenannte verwaiste Elevations bzw. Exclusions.

Im Fall solcher Einträge erscheint in der Detailansicht eines Adaptable Results eine Warnung. Diese listet die verwaisten Links und ihre Dokumenten-IDs auf. Die Aktivierung des Häkchens unter der Warnung löst eine Bereinigung bei der Speicherung aus.

Das Feld Seite manuell hinzufügen ermöglicht die manuelle Ergänzung zusätzlicher Dokumente durch die Angabe ihrer URL. Diese müssen bereits im Index der Datengeneratoren, die der ausgewählten Prepared Search zugeordnet sind, enthalten sein. Die Eingabe der entsprechenden URL muss in der Form http[s]://www.newdocument.com zu erfolgen und ist mit dem Plus-Button zu bestätigen. Ist das Dokument im Index enthalten, wird es der Ergebnisliste hinzugefügt. Andernfalls erscheint ein entsprechender Hinweis.

Jede Änderung an der Suchergebnisliste ist mithilfe des Speichern-Buttons zu persistieren. Erst mit diesem Klick werden die Anpassungen übernommen, auch wenn sie zuvor bereits in der Liste sichtbar sind.

Liste bestehender Adaptable Results

Nach der Speicherung und erfolgreichen Erzeugung des Adaptable Results wird es der Liste bestehender Adaptable Results im gleichnamigen Bereich hinzugefügt. Die Liste gliedert sich in drei Spalten mit den folgenden Informationen:

Name: Das während der Erstellung des Adaptable Results verwendete Suchwort fungiert gleichzeitig als dessen Name und ist in dieser Spalte dargestellt.

Wird nicht nur ein Suchwort, sondern eine Liste an Suchwörtern übergeben, werden diese alphabetisch sortiert.

Prepared Search: Die Spalte enthält die Prepared Search, auf die sich die Suchanfrage bezieht. Sie wird während der Erstellung des Adaptable Results selektiert.
Letzte Bearbeitung: Die Informationen in dieser Spalte zeigen, wer und wann die letzte Änderung an dem Adaptable Result vorgenommen hat.

Adaptable Result bearbeiten

Der Button mit dem Symbol eines Stifts ermöglicht die Bearbeitung eines Adaptable Results. Ein Klick auf ihn öffnet die Detailansicht mit den vorgenommenen Eingaben. Diese lassen sich entsprechend der zuvor beschriebenen Möglichkeiten verändern.

Adaptable Result löschen

Der Button mit dem Symbol eines Mülleimers ermöglicht die Löschung eines Adaptable Results. Ein Klick auf diesen Button öffnet einen Dialog mit einer Sicherheitsabfrage, mit der die Löschung zu bestätigen ist.

Alternativ besteht über die Checkboxen, die in der Übersichtsliste vor jedem Adaptable Result sichtbar sind, die Möglichkeit, mehrere Adaptable Results für die Löschung auszuwählen. Der Button Ausgewählte löschen entfernt diese markierten Adaptable Results, nachdem zuvor ebenfalls eine Sicherheitsabfrage bestätigt wurde.

2.3. Daten

Für die Erstellung eines Suchindex greift die SmartSearch kundenunternehmensseitig auf die zu erfassenden Daten zu, die in Form von Webseiten, Portalen oder Datenbanken vorliegen können. Ihre Erfassung erfolgt über sogenannte Datengeneratoren, die unterschiedliche Konfigurationsmöglichkeiten bereitstellen. Die auf dem Solr-Server persistierten Daten lassen sich anschließend über den ebenfalls durch das Cockpit bereitgestellten Browser einsehen. Dieser stellt neben den Inhalten auch alle Metadaten dar.

Die nachfolgenden Unterkapitel beschreiben sowohl die Datengeneratoren als auch den Browser im Detail.

2.3.1. Datengeneratoren

Für die kundenunternehmensseitige Erfassung der benötigten Daten stellt die SmartSearch sogenannte Datengeneratoren bereit. Ihre Erstellung und Verwaltung erfolgt in der gleichnamigen Oberfläche, die über den Menübereich Daten Datengeneratoren aufrufbar ist.

Abbildung 15. Datengenerator

Der Bereich zeigt eine Liste aller bereits existierenden Datengeneratoren und ist daher initial leer. Bei der Erstellung weiterer Datengeneratoren ist zwischen drei Arten zu unterscheiden:

Web
XML
Extern

Neben diesen bei der manuellen Erstellung relevanten Datengeneratorarten existieren noch weitere, welche nicht manuell angelegt werden können. Ein Beispiel hierfür ist der Typ API, der bei Nutzung durch das SmartSearch Connect-FirstSpirit-Modul oder der Verwendung der Generic API erzeugt wird.

Datengenerator anlegen

Für die Erstellung eines neuen Datengenerators existiert eine eigene Ansicht, die per Klick auf den Button Neuer Datengenerator aufrufbar ist und sich in drei Tabs gliedert. Neben den zwei Tabs Allgemein und Enhancer, die für alle Datengeneratoren identisch sind, besitzt jeder von ihnen zusätzlich ein spezifisches Tab.

Abbildung 16. Datengenerator - Tabs

Die nachfolgenden Absätze beschreiben zuerst die beiden identisch Tabs, bevor eine Erläuterung der spezifischen Tabs folgt:

Allgemein

Innerhalb des Tabs Allgemein ist zunächst ein Name für den zu erstellenden Datengenerator anzugeben und eine Default-Sprache auszuwählen. Der Zähler Mindestanzahl Dokumente zur Synchronisation definiert einen Schwellenwert. Ab diesem Schwellenwert erfolgt eine Persistierung der erfassten Daten in den vom Solr-Server erzeugten Index. Die übrigen Einstellungen ermöglichen eine regelmäßige und automatische Erfassung der benötigten Daten und sind über die Checkbox Regelmäßig starten de-/aktivierbar. Dafür kann zwischen einem täglichen und wöchentlichen Startintervall gewählt und über die Angabe eines Datums sowie einer Uhrzeit der nächste Startzeitpunkt festgelegt werden.

Die Sprachen entsprechen hier den nach ISO 639-1 vorgesehenen Werten, also aus zwei Zeichen bestehenden Sprachcodes. Findet ein Datengenerator an Dokumenten längere Sprachkürzel vor, so wird alles nach dem zweiten Zeichen abgeschnitten. Auf diesem Weg wird beispielsweise aus dem Sprachcode de_DE im Rahmen der Generierung der Wert de.

Abbildung 17. Datengenerator - Allgemein

Enhancer: Der Tab Enhancer ermöglicht die Erzeugung konfigurierter Enhancer. Sie dienen der Modifikation der durch den Datengenerator erfassten Daten vor ihrer Indizierung auf dem Solr-Server. Pro Datengenerator-Konfiguration können mehrere Groovy-Skript-Enhancer hinterlegt werden. Diese werden in der Reihenfolge abgearbeitet, in der sie an der Konfiguration hinterlegt sind. Die Erstellung eines Enhancers erfolgt über einen Klick auf den Button Neuer Enhancer.

Eine detaillierte Beschreibung der erstellbaren Enhancer ist im nachfolgenden Enhancer-Kapitel enthalten.

Web-Crawler

Der Tab Web-Crawler ist spezifisch für den gleichnamigen Datengenerator und wird daher nur für diesen angezeigt. Er erfasst alle Inhalte eines bestehenden Webauftritts. Dies umfasst sowohl die HTML-Inhalte (jedoch ohne in ihnen enthaltene HTML-Kommentare) als auch alle Dateien jeglichen Formats. Dafür benötigt er zunächst eine Start-URL sowie die Angabe, wie viele Seiten maximal zu erfassen sind. Entspricht die Start-URL einer Sitemap, werden die in der Sitemap enthaltenen Verweise nacheinander erfasst.

Durch die Angabe des Werts Null für die zu erfassende Seitenanzahl wird der gesamte Webauftritt erfasst.

Um HTML-Inhalte bei der Erzeugung des Suchindex zu ignorieren, müssen diese durch HTML-Kommentare der Form <!-- NO INDEX -→ und <!-- INDEX -→ gekennzeichnet sein.

Enthalten die erfassten Seiten Verweise auf andere Inhalte, folgt der Datengenerator ihnen und erfasst die verlinkten Inhalte ebenfalls. Dabei werden auch kanonische Verweise berücksichtigt. Auf diesem Weg erfasst er den mit der Start-URL angegeben Webauftritt entweder vollständig oder bis zum angegebenen Limit.

Durch den Datengenerator zu ignorierende Verweise müssen mit Attribut rel="nofollow" gekennzeichnet sein.

Mit einem im Feld Check URL Script angegebenen, selbst implementierten Groovy-Skript lässt sich die Erfassung und Verarbeitung verlinkter Inhalte individuell beeinflussen. Der Button Validieren überprüft das erstellte Skript auf mögliche Fehler. Das Skript bestimmt, ob ein Link erfasst wird: Wenn das Skript true zurückgibt, wird jeder vom Crawler gefundene Link erfasst, was das Risiko eines nie endenden Crawlers birgt.

Groovy Skript Rumpf welcher jeden Link als zu crawlen markiert.

return true; // Achtung: Dies könnte zu einem nie endenden Crawler führen

Groovy Skript Rumpf um innerhalb der Domäne www.mithrasenergy.com keine Seiten mit '/shop/' in der URL zu erfassen

return url.startsWith("https://www.mithrasenergy.com") && !url.contains("/shop/");

Der Web-Crawler erkennt Sitemaps im XML-Format automatisch, falls sie als Start-URL angegeben sind. Er behandelt die in diesen Sitemaps verzeigerten Dokumente wie HTML-Links und erfasst sie entsprechend. Alternativ ist auch die Nutzung einer Index-Sitemap als Start-URL möglich. Hierbei ist zu beachten, dass sowohl XML-Sitemaps als auch Index-Sitemaps für sich alleine keine Dokumente sind und somit keine Aufnahme in den Index erfolgt.

Eine innerhalb einer HTML-Datei referenzierte sitemap.xml wird nicht als Sitemap, sondern als normales Dokument abgearbeitet. Um eine URL als Sitemap abzuarbeiten, muss die URL direkt als Start-URL oder als Inhalt einer Sitemap-Index-Datei aufgeführt sein.

Der Datengenerator kann ausschließlich Verweisen von HTTP- auf HTTP(S)-Seiten folgen. Der Wechsel von HTTPS zu HTTP ist ihm nicht möglich. Dies gilt auch bei der Verwendung einer Index-Sitemap, in der Verweise auf andere Sitemaps enthalten sind.

Die übrigen Einstellungen ermöglichen eine Spezifierung der Suchanfragen des Datengenerators:

Mit der De-/Aktivierung der Checkbox No-Script Bereiche im HTML ignorieren lässt sich bestimmen, ob die in diesen Bereichen enthaltenen Inhalte ebenfalls zu erfassen sind.
Ist die Checkbox robots.txt beachten aktiviert, berücksicht der Datengenerator die in der robots.txt-Datei der entsprechenden Webpräsenz definierten Einschränkungen. Andernfalls ignoriert er diese und erfasst den gesamten Inhalt des Webauftritts.
Enhalten die erfassten Links zusätzliche Parameter, können diese durch die Aktivierung der Checkbox Parameter aus URL entfernen übersprungen werden. Auf diesem Weg lassen sich Redundanzen in den erfassten Dokumenten vermeiden.
Das Feld Charset legt fest, mit welchem Charset die Persistierung der erfassten Daten erfolgt.
Sowohl für die Erfassung der Daten als auch für den Abruf der persistierten Dokumente bringt die SmartSearch den User-Agent smart-search-agent mit. Sein Referenzname ist in dem entsprechenden Feld enthalten und lässt sich beliebig überschreiben.
Der für den Abstand zwischen zwei Downloads definierte Wert bestimmt, wie schnell die SmartSearch die einzelnen Suchabfragen absetzt. Auf diese Weise ist eine Überlastung des Webservers aufgrund einer zu hohen Abfragefrequenz vermeidbar.

Erhält der Datengenerator auf eine Suchanfrage keine Antwort, gibt der Read and connect-Timeout die Zeitspanne bis zum Abbruch der Datenerfassung an.

Bei der Erfassung der Inhalte eines bestehenden Webauftritts kann der Web-Crawler unterschiedliche Status Codes erhalten. Diese werden wie folgt verarbeitet:

2xx: Diese Status Codes entsprechen den Standard Codes. In diesem Fall werden die Inhalte durch den Web-Crawler normal verarbeitet.
301: Dieser Status Code entspricht einem Redirect. Der Web-Crawler übernimmt an dieser Stelle die URL der neuen Seite.
302 und 307: Diese beiden Status Codes bezeichnen ebenfalls jeweils einen Redirect. Auch in diesem Fall übernimmt der Web-Crawler die Inhalte der neuen Seite, der alte Verweis bleibt jedoch erhalten.
4xx und 5xx: Diese Status Codes bezeichnen Fehlerstatus. Die betroffenen Seiten werden durch den Web-Crawler ignoriert und der Fehler als DEBUG geloggt.

Für die sich aus einem 3xx Status Code ergebenen Redirect-Verweise, wird die Strip Parameters-Konfiguration berücksichtigt.

Der Web-Crawler versucht zunächst aus folgenden Tags im Quelltext des gecrawlten HTML-Dokuments eine Sprachkennzeichnung auszulesen:

<html lang=de">
<body lang=de">
<meta name="language" content="de">
<meta http-equiv="content-language" content="de">
<meta property="og:locale" content="de_DE">
<meta property="DC:language" content="de">
<meta property="og:locale:alternative" content="de_AT">

<meta property="og:locale:alternative" content="de_CH">

Beim ersten vorhandenen Tag wird die angegebene Sprache als Sprache des Dokuments interpretiert und gespeichert.

Ist keines der Tags vorhanden, so versucht der Web-Crawler automatisch eine Sprache aus dem content-Bereich des Dokuments zu erkennen. Scheitert dies, so wird die am Datengenerator gepflegte Standardsprache am Dokument gespeichert.

Die SmartSearch speichert die Eingangssprache eines Dokuments standardmäßig im Feld language_original_stored_only. Diese Speicherung ist unabhängig von der im Rahmen der Spracherkennung und - verarbeitung vorgenommenen Änderungen an der Sprache eines Dokuments.

Verarbeitet die SmartSearch beispielsweise die am Dokument im Feld language_keyword übergebene Sprache de_DE und ändert sie in die unterstützte Sprache de, so ist der Wert des Felds language_original_stored_only dennoch de_DE.

Abbildung 18. Web-Crawler

XML-Crawler

Der Tab XML-Crawler ist ebenfalls spezifisch für den gleichnamigen Datengenerator und wird daher nur für diesen angezeigt. Er erfasst XML-Daten aus einer definierten Quelle, die nicht in Form einer Webseite vorliegt. Dafür ist im entsprechenden Feld eine XML-URL anzugeben, für deren Ziel zwei Dateitypen existieren:

Daten-XML-Datei
Die Daten-XML-Datei entspricht einer spezifischen Quelle. Sie erfasst die durch den Datengenerator zu verarbeitenden Dokumente in einer einzigen Datei.
Seed-XML-Datei
Besteht die Notwendigkeit, mehrere Quellen zu erfassen, lässt sich die URL einer Seed-XML-Datei übergeben. Der Datengenerator folgt dann den in dieser Datei enthaltenen Verweisen, deren Anzahl nicht limitiert ist.

Die Erfassung von XML-Sitemaps ist nur mithilfe des Web-Datengenerators möglich.

Der Zugriff auf zu verarbeitende Dateien findet ausschließlich per HTTP(S)-Request statt. Eine Erfassung von XML-Dateien auf dem SmartSearch-Server-Dateisystem oder anderen Dateiquellen ist nicht möglich. Erhält der Datengenerator auf eine solchen Request keine Antwort, gibt der Read and connect-Timeout die Zeitspanne bis zum Abbruch der Datenerfassung an.

Sowohl für die Erfassung der Daten als auch für den Abruf der persistierten Dokumente bringt die SmartSearch den User-Agent smart-search-agent mit. Sein Referenzname ist in dem entsprechenden Feld enthalten und lässt sich beliebig überschreiben.

Abbildung 19. XML-cw}

Daten-XML-Datei

Der XML-Crawler erfasst XML-Daten, die entweder aus einer einzelnen oder mehreren Quellen stammen. Eine Daten-XML-Datei entspricht einer einzelnen Quelle. Sie beinhaltet eine beliebige Anzahl von Dokumenten, die die SmartSearch im Rahmen einer XML-Datengenerierung verarbeitet. Mit dem Start eines XML-Datengenerators, der eine solche Datei erfasst, werden alle in der Datei enthaltenen Dokumente dem Suchindex hinzugefügt. Dies setzt jedoch voraus, dass die Dokumente valide sind.

Eine valide Daten-XML-Datei erfüllt folgende Anforderungen:

Das Wurzelelement ist ein documents-Element.

Das documents-Element enthält beliebig viele document-Elemente:

Ein document-Element ist eine Einheit, die mithilfe der Suche gefunden werden kann.
Ein document-Element besitzt ein 'uid'- Attribut, dessen Wert eine eindeutige alphanumerische Dokumenten-ID ist.

Die einzelnen document-Elemente können unterschiedlich viele field-Elemente beinhalten.

Verschiedene document-Elemente können aus unterschiedlich vielen Feldern bestehen.
Ein field-Element besitzt ein name-Attribut, dessen Wert dem gewünschten Feldnamen im Suchindex entspricht.
Ein field-Element beinhaltet den Wert, den das Feld am Dokument annehmen soll.
Mehrfachwerte (z.B. bei Feldern mit dem dynamischen Feldtyp *_keyword) können dadurch erzeugt werden, indem field-Elemente mit einem identischen name-Attributwert, aber mit unterschiedlichen Tag-Inhalten eingetragen werden (vgl. Wert category_keyword im nachfolgenden Beispiel).

Die Verarbeitung eines Feldwertes ist abhängig von der Namenskonvention des Feldnamens. Eine Erläuterung der verfügbaren Namenskonventionen und Feldtypen finden Sie im Abschnitt Verfügbare Felder und Feldtypen.

Es wird empfohlen, Feldwerte immer innerhalb eines CDATA-Blocks zusammenzufassen (siehe Beispiel).

Das folgende Beispiel zeigt eine exemplarische Struktur einer XML-Daten-Datei. Eine solche Datei kann direkt als XML-URL für einen XML-Datengenerator dienen.

Beispiel für eine Daten-XML-Datei

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<documents>
   <document uid="0815">
           <field name="title"><![CDATA[Das Erklärvideo zur SmartSearch-XML-Datei]]></field>
                <field name="link"><![CDATA[https://www.youtube.com/watch?v=...]]></field>
                <field name="content">
                   <![CDATA[Hier steht inhaltlich, wie Sie eine SmartSearch-XML-Datei erstellen.]]>
                </field>
                <field name="language_keyword"><![CDATA[de]]></field>
                <field name="publishing_date"><![CDATA[ 2019-05-23T10:00:01Z ]]></field>
                <field name="favorites_count_long"><![CDATA[34]]></field>
                <field name="category_keyword"><![CDATA[socialmedia]]></field>
                <field name="category_keyword"><![CDATA[presse]]></field>
                <field name="meta_keywords"><![CDATA[SmartSearch Erklärvideo Facetten]]></field>
   </document>
        ...
        <document uid="4711">
           <field name="title"><![CDATA[Die Hilfeseiten zu SmartSearch.]]></field>
                ...
        </document>
</documents>

Ein Dokument ist nur valide, wenn im entsprechenden document-Element die Felder title, link und content vorhanden sind. Hierbei werden die Felder title und content sprachabhängig verarbeitet.

Der Feldname id darf nicht verwendet werden. Dieser wird intern genutzt und ein Vorhandensein im Quelldokument führt zu einem Fehler bei der Datengenerierung.

Es wird außerdem empfohlen, die Sprache des Dokuments über den Feldnamen language_keyword zu übergeben. Weitere Informationen zu den verfügbaren Sprachkürzeln sind im Abschnitt Details zu den Sprachen enthalten.

Seed-XML-Datei

Im Gegensatz zur Daten-XML-Datei stellt eine Seed-XML-Datei Daten aus verschiedenen Quellen bereit. Sie beinhaltet daher eine unlimitierte Anzahl von Verweisen auf reine Daten-XML-Dateien oder weitere Seed-XML-Dateien. Die Angabe weiterer Seed-XML-Dateien ermöglicht eine beliebig tiefe Baumstruktur. Bei der Verabreitung der Seed-XML-Datei folgt der Datengenerator allen diesen Verweisen und erfasst sie so, als wären sie direkt als XML-URL angegeben worden. Auch in diesem Fall müssen alle Dokumente valide sein.

Eine valide Seed-XML-Datei erfüllt folgende Anforderungen:

Das Wurzelelement ist ein seeds-Element.
Das seeds-Element enthält beliebig viele seed-Elemente:
- Ein seed-Element stellt eine Daten-XML-Datei oder eine weitere Seed-XML-Datei dar.
- Ein seed-Element ist leer, hat jedoch ein Attribut url mit dem Ziel des Verweises.

Das folgende Beispiel zeigt eine Seed-XML-Datei, die sowohl Verweise auf Daten- als auch auf Seed-XML-Dateien enthält:

Beispiel für eine Seed-XML-Datei

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<seeds>

    <!-- Verweise auf Daten-XML-Dateien -->
        <seed url="https://www.customer.com/.../.../documents-01.xml" />
        <seed url="https://www.customer.com/.../.../documents-02.xml" />

    <!-- Verweise auf weitere Seed-XML-Dateien -->
        <seed url="https://www.customer.com/.../.../another-seed.xml" />

</seeds>

Externer Crawler

Der externe Datengenerator sammelt selbst keine Informationen, sondern erfasst ausschließlich Daten, die er von außen über die REST-Schnittstelle übergeben bekommt. Er besitzt daher in seinem spezifischen Tab keine zusätzlichen Konfigurationsmöglichkeiten. Die in den Tabs Allgemein und Enhancer vorgenommenen Einstellungen sind für ihn ausreichend.

Die Übertragung der Daten an die REST-Schnittstelle ist durch eine Eigenimplementierung zu realisieren. Die dafür notwendigen Informationen sind in der Dokumentation SmartSearch REST API for external datagenerators enthalten.

Der externe Datengenerator wird zukünftig in seiner Funktionalität durch die generische API ersetzt und nicht weiterentwickelt. Bei neuen Projekten sollte also direkt diese neue Vorgehensweise zur Indizierung von extern generierten Dokumenten verwendet werden.

Liste bestehender Datengeneratoren

Nach der Speicherung und erfolgreichen Erzeugung des Datengenerators wird er der Liste bestehender Datengeneratoren im gleichnamigen Bereich hinzugefügt. Die Liste gliedert sich in eine vierspaltige Tabelle mit den folgenden Informationen:

Name: Die Spalte enthält den Namen des Datengenerators, der während der Erzeugung angegeben wurde.
Typ: Diese Spalte gibt an, ob es sich um einen Datengenerator des Typs Web, XML oder Extern handelt.
Status: Diese Spalte zeigt den Zustand an, in dem sich der Datengenerator aktuell befindet. Je nach Vorgang kann er einen der folgenden Status besitzen: Bereit, Erfassen, Erster bzw. Zweiter Enhancer, Synchronisiert oder Fehler.
Letzte Bearbeitung: Die Informationen in dieser Spalte zeigen, wer und wann die letzte Änderung an dem Datengenerator vorgenommen hat.

Datengenerator bearbeiten

Der Button mit dem Symbol eines Stifts ermöglicht die Bearbeitung des Datengenerators. Ein Klick auf ihn öffnet die Detailansicht mit allen vorgenommenen Konfigurationen. Diese lassen sich entsprechend der zuvor beschriebenen Möglichkeiten verändern.

Datengenerator ausführen

Der Button mit dem Play-Symbol startet manuell die Ausführung des Datengenerators. Er erfasst daraufhin die Daten der konfigurierten Quelle und überträgt sie an den Solr-Server.

Die Persistierung der Daten durch den Solr-Server findet in regelmäßigen Intervallen statt. Es kann daher bis zu fünfzehn Minuten dauern, bis die Daten abrufbar sind.

Der Button Collection neu laden ermöglicht die sofortige Synchronisation. Er ist ausschließlich für Mitglieder der Gruppe ADMIN sichtbar und berücksichtig die erfassten Daten aller Datengeneratoren. Die Synchronisation der Daten eines einzelnen Datengenerators ist nicht möglich.

Datengenerator löschen

Der Button mit dem Symbol eines Mülleimers ermöglicht die Löschung eines Datengenerators. Ein Klick auf diesen Button öffnet einen Dialog mit einer Sicherheitsabfrage, mit der die Löschung zu bestätigen ist.

Alternativ besteht über die Checkboxen, die in der Übersichtsliste vor jedem Datengenerator sichtbar sind, die Möglichkeit, mehrere Datengeneratoren für die Löschung auszuwählen. Der Button Ausgewählte löschen entfernt diese markierten Datengeneratoren, nachdem zuvor ebenfalls eine Sicherheitsabfrage bestätigt wurde.

Datengenerator leeren

Der Button mit dem Symbol eines Radiergummis ermöglicht die Löschung der indizierten Dokumente eines Datengenerators. Ein Klick auf den Button Ausgewählte leeren öffnet einen Dialog mit einer Sicherheitsabfrage, mit der die Löschung zu bestätigen ist.

2.3.2. Browser

Für die Darstellung der per Datengenerator erfassten und durch den Solr-Server persistierten Daten stellt die SmartSearch einen Browser bereit. Dieser ist über den Menüpunkt Daten Browser aufrufbar.

Für die Darstellung ist im Drop-Down-Menü zunächst ein Datengenerator auszuwählen. Der Browser listet daraufhin alle Dokumente auf, die durch diesen Datengenerator erfasst wurden. Per Klick auf ein solches Dokument lassen sich außerdem alle Felder und die in ihnen gespeicherten Metainformationen anzeigen. Die Buttons Vorheriges Dokument und Nächstes Dokument ermöglichen ein Durchblättern durch die erfassten Dokumente, deren Gesamtanzahl zwischen ihnen ablesbar ist.

Abbildung 20. Browser

2.3.3. Aufbereitung von Daten durch Enhancer

Im Rahmen einer Datengenerierung ist es häufig nötig, die hierbei für den Index vorbereiteten Dokumente anzupassen. Dies ist erforderlich, um die Auffindbarkeit von Dokumenten zu erhöhen, ungültige Dokumente zu entfernen oder die generelle Datenqualität zu erhöhen.

Die SmartSearch nutzt hierfür sogenannte Enhancer. Bei diesen handelt es sich sowohl um mitgelieferte als auch um projektabhängig konfigurierte Komponenten, die ein Bestandteil der Konfiguration eines Datengenerators sind. Bei einer Datengenerierung werden für jedes erfasste Dokument die Enhancer ausgeführt und deren Effekte auf das zu indizierende Dokument angewendet.

Generell gibt es drei Arten von Enhancern, die in folgender Reihenfolge ausgeführt werden:

Allgemeine Enhancer

Die allgemeinen Enhancer werden von der SmartSearch bereitgestellt. Sie sind für die Nutzenden transparent und konfigurativ nicht anpassbar. Des Weiteren ermöglichen sie beispielsweise die Durchführung von Sprachanalysen, deren Ergebnisse in den folgenden, konfigurierten Enhancern nutzbar sind.
Konfigurierte Enhancer

Mit den konfigurierten Enhancern bietet die SmartSearch die Möglichkeit, eigene Logik zur Verarbeitung und Anpassung von Dokumenten im Rahmen einer Datengenerierung zu konfigurieren. Die Arten konfigurierter Enhancer und ihre Anwendungsfälle sind im folgenden Abschnitt erläutert.
Abschließende (Finishing-)Enhancer

Die abschließenden (Finishing-)Enhancer werden analog zu den allgemeinen Enhancern von der SmartSearch bereitgestellt. Auch sie sind für die Nutzenden transparent und ebenfalls konfigurativ nicht anpassbar.

Der Tab Enhancer in der Konfigurationsansicht eines Datengenerators ermöglicht die Erzeugung konfigurierter Enhancer. Diese dienen der Modifikation der durch den Datengenerator erfassten Daten vor ihrer Indizierung auf dem Solr-Server. Pro Datengenerator-Konfiguration können mehrere Groovy-Skript-Enhancer hinterlegt werden. Diese werden in der Reihenfolge abgearbeitet, in der sie an der Konfiguration hinterlegt sind. Die Erstellung eines Enhancers erfolgt über einen Klick auf den Button Neuer Enhancer.

Groovy-Skript-Enhancer

Dieser Enhancer ermöglicht die Einbindung eines selbst zu implementierenden Groovy-Skripts. Die dafür erforderliche Editiermaske öffnet sich nach der Erstellung des Enhancers über den Menüpunkt Groovy-Skript-Enhancer. Ein solches Skript ermöglicht zusätzliche Modifikationen des Datenbestands und den Zugriff auf die Daten am Dokument, die im Rahmen der Ausführung der allgemeinen Enhancer generiert werden. So lassen sich beispielsweise weitere Dokumente dem Datenbestand hinzufügen oder bestehende Dokumente bearbeiten bzw. löschen. Eine getätigte Eingabe ist mithilfe des Buttons Validieren auf mögliche Syntaxfehler überprüfbar.

Das folgende Code-Beispiel zeigt den Aufbau eines Groovy-Skript-Enhancers:

Aufbau eines Groovy-Skript-Enhancers

void manipulate(final Document document, final String html, final org.jsoup.nodes.Document jsoupDocument)  {

// Nur dieser Methoden-Rumpf ist zu befüllen.
// Die Signatur wird in der Editiermaske automatisch um den konfigurierten Code geklammert.

}

Dem Groovy-Skript wird ein Objekt document, ein String html sowie ein Object jsoupDocument übergeben:

Das Objekt document beinhaltet das aktuell in der Verarbeitung stehende SmartSearch-Dokument. Diesem können im Rahmen der Verarbeitung weitere Daten hinzugefügt oder entfernt werden:
```
document.addData("Feldname","Feldwert")
document.removeData("zuEntfernendesFeld")
```
Der String html beinhaltet im Falle eines Web-Datengenerators das HTML der ursprünglich vom Crawler erfassten Seite, welche aktuell in ein SmartSearch-Dokument umgewandelt wird.

Für andere Datengenerator-Arten ist dieses Objekt nicht relevant.
Das Object jsoupDocument beinhaltet im Falle eines Web-Datengenerators eine Repräsentanz der Seite als Jsoup-Dokument. Dies ermöglicht eine objektbasierte Verarbeitung der Seite:
```
document.addData("Seitentitel", jsoupDocument.title())
```
Dieses Objekt ist ebenfalls nur für Datengenerator des Typs WEB relevant.

Soll ein Dokument im Rahmen der Generierung nicht in den Index übernommen werden, so kann dies durch die Definition des Boost-Werts 0 erreicht werden:

Definition des Boost-Werts

document.setBoost(0)

Weitere Beispiele für Groovy-Skripte und deren Nutzung sind im Kapitel Beispiele für Groovy-Skript-Enhancer enthalten.

Extrahieren von Namen und Nomen

Entsprechend seines Namens extrahiert dieser Enhancer Namen und Nomen und speichert sie in den Feldern names_multi_keyword und nouns_multi_keyword.

Dieser Enhancer ist nur für die Sprache Deutsch einsetzbar und besitzt für andere Sprachen keine Funktion.

2.3.4. Verfügbare Felder und Feldtypen

Mit der SmartSearch wird eine Datenstruktur - das sogenannte Solr-Schema - ausgeliefert, welche die für erfasste Dokumente vorhandenen Felder definiert. Diese Felder am Dokument beinhalten nach einer Datenerfassung strukturierte Inhalte, die im Bezug auf das Dokument im Index gespeichert sind. Da die Inhalte verschiedener Felder potenziell Einfluss auf die Ergebnisse einer Suchabfrage haben, werden im folgenden einige relevante Felder erläutert. Einige Felder werden während des Laufs von Datengeneratoren automatisch angelegt und mit Werten befüllt. Der Groovy-Skript-Enhancer bietet außerdem die Möglichkeit, weitere Felder und Werte hinzuzufügen.

Grundsätzlich besteht ein Feld aus einem Bezeichner und einem oder mehreren Werten. Es existieren drei Arten von Feldern, welche sich in ihrem Gebrauch und ihrer Funktion unterscheiden können:

Pflichtfelder
statische Felder
dynamische Felder

Ein Feld kann abhängig vom Feldtyp einen oder mehrere Werte haben. Weitere Informationen hierzu sind im Abschnitt "Felder mit Mehrfachwerten pro Dokument" zu finden.

Für die Nutzung der SmartSearch ist es wichtig, Anwendungsfälle und Inhalt der verfügbaren Felder zu verstehen. Die folgenden Tabellen geben eine Übersicht über die drei Feldarten sowie den relevanten Teil der vorhandenen Felder und skizzieren deren Inhalt:

Pflichtfelder

Die Bezeichner sowie Werte von Pflichtfeldern sind zwingend an jedem Dokument vorhanden, erstere sind außerdem unveränderbar.

Die nachfolgende Tabelle zeigt eine Übersicht von Feldern dieser Art:

Tabelle 1. Pflichtfelder
Bezeichner	Beschreibung	Inhalt
id	Eindeutige ID eines Dokuments	Mit dem Inhalt dieses Felds ist jedes Dokument im Index eindeutig identifizierbar.
title	Titel eines Dokuments	Der Titel eines Dokuments ist beispielsweise als Überschrift auf einer Suchergebnisseite nutzbar.
content	Inhalt eines Dokuments	Der Inhalt des Dokuments ist - neben dem Titel - die inhaltliche Grundlage für die Suchfunktion. Inhalte, die für die Auffindung des Dokuments relevant sind, sind im Normalfall während der Datengenerierung in dieses Feld zu schreiben.
link	URL des Dokuments	Die URL eines Dokuments ist die Sprungmarke, mit der die Quelle des indizierten Dokuments im Rahmen eines Suchvorgangs von der endanwendenden Person abrufbar ist. Dies kann zum Beispiel ein Link hinter dem Titel des Dokuments sein, welcher dann zum eigentlichen Dokument führt.

Statische Felder

Die Bezeichner statischer Feld sind ebenso wie die der Pflichtfelder unveränderbar. Im Gegensatz zu diesen besitzen statische Felder jedoch nicht zwingend einen Wert.

In der folgenden Tabelle sind einige typische statische Felder aufgeführt:

Tabelle 2. Statische Felder
Bezeichner	Beschreibung	Inhalt
thumbnail	Kompaktansicht als Bildverweis	Um die Kompaktansicht der Dokumente in einer Suchergebnisseite anzuzeigen, ist die URL einer solchen Kompaktansicht in diesem Feld zu speichern.
keywords	Schlagwörter	Dieses Feld ist für Begriffe vorgesehen, die vor der Übernahme in den Index keine sprachliche Verarbeitung wie beispielsweise Stemming durchlaufen sollen.
language	Sprachkürzel	Dieses Feld beinhaltet das Sprachkürzel nach ISO 639-1. Das Kapitel Datengeneratoren enthält weitere Informationen hierzu.

Dynamische Felder

Die Bezeichner dynamischer Felder folgen einer Namenskonvention und können in Abhängigkeit des Einsatzes und Dokuments vorhanden oder nicht vorhanden sein. Dynamische Felder sind dafür vorgesehen, das Schema flexibel für zukünftig nötige Daten und die Anwendung somit robuster zu gestalten.

Dynamische Felder verhalten sich wie statische Felder, außer dass ihre Bezeichner einen Platzhalter enthalten. Werden durch den Start einer Datengenerierung Dokumente indiziert, können Daten, welche keinem statischen Feld zuordenbar sind, durch ein dynamisches Feld aufgefangen werden.

So kann ein Dokument beispielsweise ein Feld custom_date beinhalten, welches im Solr-Schema nicht vorhanden ist. Die Daten in diesem Feld würden über das dynamische Feld *_date dennoch in den Index übernommen.

Weitere Informationen zu dynamischen Feldern sind der Solr-Dokumentation zu entnehmen.

Eine Übersicht der wichtigsten verfügbaren dynamische Felder ist folgender Tabelle zu entnehmen:

Tabelle 3. Dynamische Felder
Namensschema	Beschreibung	Inhalt	Unterstütze Funktionalitäten
*_integer	Integer-Ganzzahlwerte	Felder dieser Art tragen Ganzzahlwerte aus dem Wertebereich Integer (`32-bit signed integer`).	Sortierung
*_long	Long-Ganzzahlwerte	Felder dieser Art tragen Ganzzahlwerte aus dem Wertebereich Long (`64-bit signed integer`).	Sortierung
*_double	Double-Gleitkommazahlenwerte	Felder dieser Art tragen Gleitkommazahlenwerte aus dem Wertebereich Double (`64-bit IEEE floating point`).	Sortierung
*_date	Datumswerte	Felder dieser Art tragen Datumswerte und sind entsprechend für zum Beispiel zeitliche Sortierungen zu verwenden. Die Werte sind im UTC-Format angegeben: zum Beispiel `2020-10-05T12:14:29.058Z`	Sortierung
*_date_range	Datumswerte	Felder dieser Art tragen eine andere Art von Datumswerten: Anders als bei `_date` geht es bei `_date_range` nicht um einen genauen Zeitpunkt, sondern um einen Zeitraum. Beachten Sie, dass Felder dieses Typs nicht sortierbar sind, da sich Datumsbereiche überschneiden, überlappen oder verschachtelt sein können. Beispielweise einen Tag oder Jahr: `2020-10-05` or `2023`.
*_keyword	Schlagwörter	Analog zum statischen Feld `keywords` beinhalten Felder dieses Typs Schlagwörter. Liegt ein solches Feld an einem Dokument vor, so wird der Wert automatisch als Facettenwert verarbeitet. Existiert die Facette noch nicht, so wird sie angelegt.	Mehrfachwerte
*_keyword_lc	Schlagwörter in Kleinbuchstaben	Felder dieses Typs beinhalten Schlagwörter, welche im Rahmen der Indizierung automatisch in Kleinbuchstaben umgewandelt wurden.	Mehrfachwerte
*_sort	Sortierwerte	Dieser Feldtyp ermöglicht die Speicherung sortierbarer Werte. Die Werte in diesen Feldern sind in Kleinbuchstaben umgewandelt und von Leerzeichen bereinigt.	Sortierung
*_sort_de	Sortierwerte – Spezialfall Deutsch	Dieser Feldtyp verhält sich analog zu `*_sort`. Er besitzt jedoch die Besonderheit, dass Umlaute sowie das `ß` bei den entsprechenden Vokalen beziehungsweise dem `s` einsortiert werden.	Sortierung
*_token	Gruppierungswerte	Dieser Feldtyp ermöglicht die Gruppierung von Dokumenten anhand der Feldinhalte, zum Beispiel Dokument- oder Produktkategorien.	Gruppierung
*_pnt	Räumliche Punktwerte	Felder dieses Typs beinhalten räumliche Punktwerte, um z.B. geografische Informationen zu hinterlegen. Die Werte haben das Format `lat,lon` (basierend auf den englischen Begriffen `latitude` und `longitude` für den Breiten- und Längengrad), zum Beispiel `1.23,4.56` Weitere Informationen sind in der Dokumentation zur zugrundeliegenden Solr-Spatial-Search enthalten.
*_facet_string	Textfacettenwerte	Felder dieses Typs beinhalten textuelle Werte zur Nutzung als Facettenausprägungen. Diese Felder werden durch die Nutzung von Bezeichnern der Art `*_keyword` automatisch angelegt und mit Facettenwerten befüllt.	Mehrfachwerte
*_facet_double	Gleitkommazahlenfacettenwerte	Felder dieses Typs beinhalten numerische Werte zur Nutzung als Facettenausprägungen. Um beispielsweise einen numerischen Facettenwert für die Facette `price_keyword` zu nutzen, ist ein entsprechender Wert in ein Feld `price_facet_double` einzutragen (zum Beispiel per Groovy-Skript-Enhancer).	Mehrfachwerte
*_stored_only	Unverarbeitete Werte	Felder dieses Typs beinhalten Inhalte mit bis zu 32766 Zeichen, welche nicht durchsuchbar gemacht oder in sonstiger Weise verarbeitet sind. Sie können jedoch beim Abruf von Dokumenten zur Anzeige mit abgefragt werden.	Mehrfachwerte
*_stored_only_big	Große unverarbeitete Werte	Felder dieses Typs beinhalten Inhalte unbeschränkter Größe, welche nicht durchsuchbar gemacht oder in sonstiger Weise verarbeitet werden sollen. Sie können jedoch beim Abruf von Dokumenten zur Anzeige mit abgefragt werden.	Mehrfachwerte
*_autocomplete	Begriffe für die Autovervollständigung	Felder dieses Typs beinhalten Begriffe, welche neben dem Inhalt des Dokuments zur Autovervollständigung verwendbar sind. Begriffe, die auf diese Weise verwendet werden, werden in diesem Feld als leerzeichengetrennte Liste ausgegeben.
*_expanded_autocomplete	Begriffe für wortübergreifende Autovervollständigung	Felder dieses Typs beinhalten Begriffe, welche neben dem Inhalt des Dokuments zur Autovervollständigung über zwei Worte hinweg verwendbar sind. Begriffe, die auf diese Weise verwendet werden, werden in diesem Feld als leerzeichengetrennte Liste ausgegeben.

Statische/dynamische Felder für Sprachkürzel

Neben den oben beschriebenen Arten von Feldern existieren noch Felder, welche pro Sprache an Dokumenten vorhanden sein können und deren Namensschemata die folgende Tabelle veranschaulichen soll:

Tabelle 4. Statische/dynamische Felder für Sprachkürzel [de/en/fr/…]
Namensschema	Beschreibung	Inhalt	Unterstütze Funktionalitäten
*_text_de	Sprachabhängiger textueller Inhalt	Diese Felder enthalten Inhalte, die sprachabhängig textuell verarbeitet sind.	Mehrfachwerte
*_autocomplete_de	Sprachabhängige Begriffe für die Autovervollständigung	Felder dieses Typs beinhalten sprachabhängige Begriffe, welche neben dem Inhalt des Dokuments zur Autovervollständigung verwendbar sind. Begriffe, die auf diese Weise verwendet werden, werden in diesem Feld als leerzeichengetrennte Liste ausgegeben.	Mehrfachwerte
*_expanded_autocomplete_de	Sprachabhängige Begriffe für wortübergreifende Autovervollständigung	Felder dieses Typs beinhalten sprachabhängige Begriffe, welche neben dem Inhalt des Dokuments zur Autovervollständigung über zwei Worte hinweg verwendbar sind. Begriffe, die auf diese Weise verwendet werden, werden in diesem Feld als leerzeichengetrennte Liste ausgegeben.	Mehrfachwerte

Felder mit Mehrfachwerten pro Dokument

Bei der Nutzung der SmartSearch können für Felder in bestimmten Fällen mehrere Werte für einen Feldnamen indiziert werden. Dieses Anlegen von Mehrfachwerten ist nicht für jedes statische und dynamische Feld möglich.

Welche statischen und dynamischen Felder Mehrfachwerte unterstützen, kann der Tabelle im Abschnitt "Verfügbare Felder und Feldtypen" entnommen werden. Von Usern frei definierte Felder, welche keinem der Tabellenwerte zugeordnet werden können, erlauben Mehrfachwerte grundsätzlich.

Wird ein Feld welches keine Mehrfachwerte unterstützt dem Index mit mehreren Werte übergeben, so wird das Dokument dennoch indiziert. Es wird jedoch für das Feld nur ein Wert übernommen, in der Regel der erste Wert welcher für das Feld übergeben wurde. Im Log der Applikation findet sich in diesem Fall eine entsprechende Warnung.

2.3.5. Details zu den Sprachen

Die SmartSearch speichert die kundenunternehmensseitig erfassten Inhalte in einer Vielzahl unterschiedlicher Felder, für deren Definition sie die Prepared Searches bereitstellt. Diesen kann bei der Ausführung eine Sprache übergeben werden, um die Erfassung der Daten sprachabhängig durchzuführen. Die nachfolgende Tabelle zeigt eine Übersicht aller derzeit für die SmartSearch konfigurierten Sprachen inklusive ihrer Kürzel (nach ISO 639-1) und der für sie verfügbaren Features. Die Anwendung der Features erfolgt automatisch bei der Verarbeitung der erfassten Informationen. Weitere Informationen zu den einzelnen Sprachen sind in der Solr-Dokumentation enthalten.

Aktuell ordnet die SmartSearch den Sprachen die folgenden Features zu:

Lowercase: Die interne Persistierung der erfassten Daten erfolgt in Kleinschreibweise. Dies hat keinerlei Auswirkung auf die Ausgabe der Informationen und dient lediglich deren Verarbeitung.
Normalisierung: Die Normalisierung dient der Angleichung ähnlicher Schreibweisen von Wörtern. In skandinavischen Sprachen wird beispielsweise eine Ersetzung der Zeichen æÆäÄöÖøØ (sowie der Varianten aa, ao, ae, oe und oo) zu åÅæÆøØ durchgeführt. Die verschiedenen Schreibweisen blåbärsyltetöj und blaabaersyltetoej ergeben somit die normalisierte Form blåbærsyltetøj.
Stemming: Das Stemming ermöglicht die Verknüpfung verschiedener, morphologischer Varianten eines Worts mit ihrem gemeinsamen Wortstamm. Die Begriffe Wörter, Worte und Wortes besitzen beispielsweise den gemeinsamen Wortstamm Wort.
Stoppwörter: Die Stoppwörter bezeichnen eine Liste von Begriffen, die sehr häufig in einer Sprache vorkommen. Zu ihnen gehören beispielsweise Artikel, Pronomen und Bindewörter. Aufgrund ihrer Häufigkeit sollen sie für den Suchindex nicht in Betracht gezogen werden. Die Auslieferung enthält für jede Sprache eine solche Liste, deren Konfiguration über das SmartSearch-Cockpit möglich ist.
Synonyme: Für Sprachen, die Synonyme zulassen, besteht innerhalb des SmartSearch-Cockpits die Möglichkeit, eine Liste zu erstellen, die einem Begriff andere, ähnliche Wörter zuordnet. Diese Wörter werden bei einer Suche gleich behandelt.

Tabelle 5. Sprachen
Sprache	Kürzel	Lowercase	Normalisierung	Stemming	Stoppwörter	Synonyme
Arabisch	ar	✔	✔	✔	✔	✔
Bengali	be	✔	✘	✘	✔	✔
Bulgarisch	bg	✔	✘	✔	✔	✔
Chinesisch Traditionell	zh-tw	✔	✔	✘	✔	✔
Chinesisch Vereinfacht	zh-cn	✔	✔	✔	✔	✔
Dänisch	da	✔	✔	✔	✔	✔
Deutsch	de	✔	✘	✔	✔	✔
Englisch	en	✔	✘	✔	✔	✔
Estnisch	et	✔	✘	✘	✔	✔
Finnisch	fi	✔	✘	✔	✔	✔
Französisch	fr	✔	✔	✔	✔	✔
Griechisch	gr	✔	✘	✘	✔	✔
Holländisch	nl	✔	✘	✔	✔	✔
Indonesisch	id	✔	✘	✔	✔	✔
Italienisch	it	✔	✔	✔	✔	✔
Japanisch	ja	✔	✘	✘	✔	✔
Koreanisch	ko	✔	✔	✘	✔	✔
Kroatisch	hr	✔	✘	✘	✔	✔
Lettisch	lv	✔	✘	✔	✔	✔
Litauisch	lt	✔	✘	✔	✔	✔
Malaiisch	ms	✔	✘	✘	✔	✔
Norwegisch	no	✔	✘	✔	✔	✔
Polnisch	pl	✔	✘	✔	✔	✔
Portugiesisch	pt	✔	✘	✔	✔	✔
Rumänisch	ro	✔	✘	✔	✔	✔
Russisch	ru	✔	✘	✔	✔	✔
Schwedisch	sv	✔	✔	✔	✔	✔
Serbisch	sr	✔	✔	✘	✔	✔
Slowakisch	sk	✔	✘	✘	✔	✔
Spanisch	es	✔	✘	✔	✔	✔
Thai	th	✔	✘	✘	✔	✔
Tschechisch	cs	✔	✘	✔	✔	✔
Türkisch	tr	✔	✔	✔	✔	✔
Ukrainisch	uk	✔	✘	✔	✔	✔
Ungarisch	hu	✔	✘	✔	✔	✔
Vietnamesisch	vi	✔	✘	✘	✔	✔

2.4. System

Der Bereich System besitzt als einzigen Unterpunkt das Usermanagement. Dieses dient der Erzeugung und Konfiguration von Usern und Gruppen und gliedert sich daher in zwei gleichnamige Reiter. Die folgenden Unterkapitel erläutern die Funktionalitäten der beiden Reiter im Detail.

Ist die User- und Gruppenverwaltung auf Basis von LDAP realisiert, besitzt das SmartSearch-Cockpit ausschließlich einen lesenden Zugriff auf sie. Das Cockpit dient in diesem Fall nur der Auflistung der User und Gruppen, jedoch nicht ihrer Bearbeitung oder Löschung. Lediglich die Verwaltung der Berechtigungen erfolgt auch im LDAP-Fall über das SmartSearch-Cockpit.

Abbildung 21. Usermanagement

2.4.1. User

Der Zugriff auf das SmartSearch-Cockpit setzt einen aktiven User voraus. Für die initiale Anmeldung existiert daher ein Master-Admin, mit dem weitere User erstellbar sind. Die Berechtigungen eines Users ergeben sich aus seiner Gruppenzugehörigkeit, die während seiner Erzeugung zu definieren ist. Die Erstellung und Verwaltung der User erfolgt im gleichnamigen Reiter des Usermanagements.

Ist das Usermanagement auf Basis von LDAP realisiert, besitzt das SmartSearch-Cockpit ausschließlich lesenden Zugriff auf sie. Die Erstellung, Bearbeitung und Löschung von Usern ist in diesem Fall innerhalb des Cockpits nicht möglich.

Abbildung 22. Reiter - User

Der Reiter zeigt eine Liste aller bereits bestehender User, die initial lediglich den Master-Admin enthält.

Benutzer anlegen

Für die Erstellung eines neuen Users existiert eine eigene Ansicht, die per Klick auf den Button Neuer User aufrufbar ist.

Abbildung 23. User anlegen

Innerhalb der Ansicht ist zunächst die E-Mail-Adresse des neuen Users anzugeben sowie ein Passwort zu definieren. Des Weiteren können User an dieser Stelle direkt einer oder mehreren Gruppen hinzugefügt werden. Das Drop-Down-Menü Gruppen zeigt dafür die Liste existierender Gruppen. Die User-Zuweisung zu einer aus der Liste ausgewählten Gruppe erfolgt über das Plus-Symbol neben dem Drop-Down-Menü. Über das Mülleimer-Symbol, das für jede zugewiesen Gruppe sichtbar ist, lässt sich eine Zuordnung wieder rückgängig machen.

Während die Gruppenzuordnung optional ist, handelt es sich bei Angabe der E-Mail-Adresse und der Definition des Passworts um Pflichtfelder.

Liste bestehender User

Nach der Speicherung und erfolgreichen User-Erzeugung wird der User-Eintrag der Liste bestehender User im gleichnamigen Reiter hinzugefügt. Die Liste gliedert sich in eine vierspaltige Tabelle mit den folgenden Informationen:

Name: Die sortierbare Spalte enthält den Namen und die bei der User-Erstellung angegebene E-Mail-Adresse. Der Name wird automatisch aus der E-Mail-Adresse generiert.
Gruppen: Die Spalte enthält die Liste aller zugewiesenen User-Gruppen. Die den Gruppen zugeordneten Berechtigungen bestimmen die Zugriffsmöglichkeiten der User.
Aktiv: Der Schieberegler in dieser Spalte ermöglicht die User-Deaktivierung ohne ein direktes Löschen des User-Eintrags. Nach der Deaktivierung ist die Anmeldung im SmartSearch-Cockpit nicht mehr möglich.

Eine Deaktivierung des Master-Admins ist nicht möglich. Daher steht der Schieberegler für ihn nicht zur Verfügung.

Letzte Bearbeitung: Die Informationen in dieser sortierbaren Spalte zeigen, wer und wann die letzte Änderung an dem User-Eintrag vorgenommen hat.

Für User werden, mit Ausnahme des Master-Admins, in der Tabelle außerdem zwei Buttons angezeigt, die eine User-Bearbeitung beziehungsweise -Löschung ermöglichen.

User bearbeiten

Der Button mit dem Symbol eines Stifts ermöglicht die User-Bearbeitung. Ein Klick auf ihn öffnet die Detailansicht mit allen Informationen. In der Ansicht lässt sich die User-Gruppenzuordnung ändern. Hier können weitere Gruppenzugehörigkeiten hinzugefügt oder entfernt werden. Die Zuweisung erfolgt über die Auswahl einer Gruppe aus dem Drop-Down-Menü Gruppen und einem anschließenden Klick auf das Plus-Symbol. Das Entfernen aus einer Gruppe ist über das Mülleimer-Symbol möglich, das für jede zugewiesene Gruppe sichtbar ist.

User löschen

Der Button mit dem Symbol eines Mülleimers ermöglicht die Löschung von Usern. Ein Klick auf diesen Button öffnet einen Dialog mit einer Sicherheitsabfrage, mit der die Löschung zu bestätigen ist. Der Dialog enthält eine Checkbox, die standardmäßig aktiviert ist. Sie bewirkt die Entfernung aller Referenzen des zu löschenden User-Eintrags auf das Userkonto. Stattdessen werden sie durch den technischen User ANONYMUS ersetzt und dadurch anonymisiert. Eine Deaktivierung der Checkbox erhält die User-Referenzen. Sie lassen sich im Nachhinein über den Button Referenzen zu gelöschten Benutzern entfernen anonymisieren.

Der Master-Admin kann niemals gelöscht werden. Daher steht der Lösch-Button für ihn nicht zur Verfügung.

Alternativ besteht über Checkboxen, die in der Übersichtsliste vor dem jeweiligen User-Eintrag sichtbar sind, die Möglichkeit, mehrere User für die Löschung auszuwählen. Der Button Ausgewählte löschen entfernt diese markierten Einträge, nachdem zuvor ebenfalls eine Sicherheitsabfrage bestätigt wurde.

Auch bei der Löschung mehrerer User lassen sich deren bestehende Referenzen durch einen technischen User-Eintrag ersetzen und damit anonymisieren. Wurde diese Option deaktiviert, lassen sich die Referenzen im Nachhinein über den Button Referenzen zu gelöschten Benutzern entfernen entfernen. Er stellt dieselbe Funktion bereit und anonymisiert die Referenzen aller nicht mehr existierenden User, indem er sie durch den technischen User-Eintrag ANONYMUS ersetzt.

2.4.2. Gruppen

Der Zugriff auf die Bereiche und Funktionen des SmartSearch-Cockpits setzt verschiedene Berechtigungen voraus. Sie werden über Gruppen definiert, denen die einzelnen User zuzuordnen sind. Initial existiert lediglich ein Master-Admin, für den zuerst die notwendigen Berechtigungen zur Erstellung neuer User und Gruppen aktiviert werden müssen. Die Erstellung und Verwaltung der Gruppen erfolgt im gleichnamigen Reiter des Usermanagements.

Ist die Gruppenverwaltung auf Basis von LDAP realisiert, besitzt das SmartSearch-Cockpit ausschließlich lesenden Zugriff auf sie. Die Erstellung und Löschung von Gruppen ist in diesem Fall innerhalb des Cockpits nicht möglich.

Des Weiteren ist die Bearbeitung der Gruppen auf die Konfiguration der Berechtigungen beschränkt.

Abbildung 24. Reiter - Gruppen

Der Reiter zeigt eine Liste aller bereits bestehenden Gruppen, die initial lediglich die Admin- und User-Gruppe enthält.

Gruppe anlegen

Für die Erstellung einer neuen Gruppe existiert eine eigene Ansicht, die per Klick auf den Button Neue Gruppe aufrufbar ist.

Abbildung 25. Gruppe anlegen

Innerhalb der Ansicht ist ein Gruppenname zu vergeben, der lediglich Buchstaben, Zahlen und Bindestriche enthalten darf. Des Weiteren können der Gruppe an dieser Stelle direkt User hinzugefügt werden. Das Drop-Down-Menü Benutzer zeigt dafür die Liste bestehender User. Die Zuweisung eines aus der Liste ausgewählten User-Eintrags erfolgt über das Plus-Symbol neben dem Drop-Down-Menü. Über das Mülleimer-Symbol, das für jeden zugewiesenen User-Eintrag sichtbar ist, lässt sich eine Zuordnung wieder rückgängig machen.

Darüber hinaus lassen sich in dieser Ansicht die Berechtigungen der Gruppe bestimmen. Dafür sind alle Bereiche des Cockpits aufgelistet, für die einzeln die Berechtigungen Lesen, Bearbeiten und Löschen per Checkbox de-/aktivierbar sind. Für die Bereiche Datengenerator und Search steht außerdem das Recht Ausführen zur Verfügung. Der Button Alle selektieren ermöglicht die gleichzeitige Aktivierung aller dargestellten Berechtigungen.

Während die Zuordnung der Berechtigungen optional ist, handelt es sich bei der Angabe des Namens um ein Pflichtfeld.

Liste bestehender Gruppen

Nach der Speicherung und erfolgreichen Erzeugung der neuen Gruppe wird sie der Liste bestehender Gruppen im gleichnamigen Reiter hinzugefügt. Die Liste gliedert sich in eine zweispaltige Tabelle mit den folgenden Informationen:

Name: Die Spalte enthält den während der Erzeugung angegebenen Namen der Gruppe.
Letzte Bearbeitung: Die Informationen in dieser Spalte zeigen, wer und wann die letzte Änderung an der Gruppe vorgenommen hat.

Mit Ausnahme der Gruppen ADMIN und USER zeigt die Tabelle pro Gruppe außerdem zwei Buttons an, die eine Bearbeitung oder Löschung der Gruppe ermöglichen.

Gruppe bearbeiten

Der Button mit dem Symbol eines Stifts ermöglicht die Bearbeitung einer Gruppe. Ein Klick auf ihn öffnet die Detailansicht der Gruppe mit allen Informationen. In der Ansicht lassen sich die der Gruppe zugeordneten User sowie die Berechtigungen ändern. Die Zuordnung eines User-Eintrags zur Gruppe erfolgt über seine Auswahl aus dem Drop-Down-Menü Benutzer und einem anschließenden Klick auf das Plus-Symbol. Die Entfernung eines User-Eintrags aus der Gruppe ermöglicht das Mülleimer-Symbol, das für jeden zugewiesenen User-Eintrag sichtbar ist. Die De-/Aktivierung der Berechtigungen ist mithilfe der pro Berechtigung angezeigten Checkbox möglich.

Gruppe löschen

Der Button mit dem Symbol eines Mülleimers ermöglicht die Löschung einer Gruppe. Ein Klick auf diesen Button öffnet einen Dialog mit einer Sicherheitsabfrage, mit der die Löschung zu bestätigen ist. Die Löschung entfernt die Gruppe und alle durch sie definierten Berechtigungen.

Eine Löschung der Gruppen ADMIN und USER ist niemals möglich. Daher steht der Lösch-Button für sie nicht zur Verfügung.

Alternativ besteht über Checkboxen, die in der Übersichtsliste vor jeder Gruppe sichtbar sind, die Möglichkeit, mehrere Gruppen für die Löschung auszuwählen. Der Button Ausgewählte löschen entfernt diese markierten Gruppen, nachdem zuvor ebenfalls eine Sicherheitsabfrage bestätigt wurde.

3. Anwendungsfälle

Im Rahmen einer Integration der SmartSearch können verschiedene Anwendungsfälle auftreten, welche bestimmte Konfigurations- beziehungsweise Entwicklungstätigkeiten erfordern. Die folgenden Abschnitte beschreiben derartige Anwendungsfälle gemeinsam mit typischen Lösungsansätzen.

Solche Lösungsansätze können Anpassungen im Cockpit an den Konfigurationen von Prepared Searches sowie Datengeneratoren beinhalten. Dies schließt die Erstellung und Anpassung von Groovy-Skript-Enhancern ein. Außerdem können die vorgestellten Lösungsansätze Anpassungen an den Anfragen gegen die Such-API mit sich führen. Somit richtet sich der nachfolgende Abschnitt vor allem an Entwickler.

Die hier skizzierten Ansätze sind lediglich als Implementierungs- und Integrationsansätze und somit als Ergänzung der Dokumentation, jedoch nicht als vollumfängliche Erläuterung der angeschnittenen Themen zu verstehen.

3.1. Nutzung der SmartSearch-APIs

Abgesehen von Konfigurationen im Cockpit, geschieht die Interaktion mit der SmartSearch durch Zugriffe auf API-Endpunkte. Dieses Kapitel beschreibt die grundsätzliche Nutzung der SmartSearch-APIs.

Grundsätzlich geschieht jeder Zugriff auf die SmartSearch-APIs per HTTPS-Abfrage. Eine solche kann zum Beispiel als JavaScript-Aufruf per Browser oder mithilfe von Tools wie Insomnia oder CURL erfolgen.

SmartSearch selbst verwendet bestimmte APIs auf der Serverseite für seine Cockpit-Funktionalität. Diese dürfen nicht für andere Zwecke verwendet werden. Dies betrifft alle API-Endpunkte unterhalb von '/rest/backend/'.

Die Beispiele in dieser Dokumentation entsprechen CURL-Aufrufen. Der folgende exemplarische Aufruf stellt die Suche nach dem Suchbegriff suchbegriff in einer Prepared Search demo auf einem SmartSearch-Server dar. Der Server ist dabei auf dem Host localhost und dem Port 8181 erreichbar.

CURL-Aufruf für eine Suche

curl
-X GET 'https://localhost:8181/rest/api/v1/prepared_search/demo/execute?query=suchbegriff'

3.1.1. API-Gateway und SmartSearch-Server

Grundsätzlich existieren zwei verschiedene Betriebs- und Nutzungsmodi für die SmartSearch: Die Nutzung der SmartSearch als Cloud-Service sowie die Nutzung von selbstbetriebenen SmartSearch-Instanzen.

Die Verwendungsszenarien der in der SmartSearch vorhandenen APIs und die für diese Szenarien erforderlichen Parameter und Aufrufmethoden sind in beiden Fällen identisch. Situativ unterscheidet sich jedoch das Aufrufziel:

Bei der Nutzung selbstbetriebener SmartSearch-Instanzen richten sich alle API-Anfragen gegen die SmartSearch-Instanz, deren Cockpit genutzt wird.
Bei der Nutzung des Cloud-Services richten sich ebenfalls alle Anfragen gegen die SmartSearch-Instanz, deren Cockpit genutzt wird, außer es wird explizit darauf hingewiesen, sie gegen das sogenannte API-Gateway zu richten. In allen Kapiteln, in denen API-Aufrufe beschrieben werden, ist demzufolge auf Hinweise auf das API-Gateway zu achten.

Die Nutzung der JavaScript-Bibliothek SmartSearch.js setzt das API-Gateway voraus und ist somit nur bei der Verwendung des Cloud-Services möglich.

3.1.2. Authentifizierung und Autorisierung

Zugriffe auf die SmartSearch-Server-APIs unterliegen den zuvor beschriebenen Userrechten. Welche Userrechte für welchen Zugriff konfiguriert sein müssen, hängt von der Art und dem Ziel des Zugriffs ab. In den nachfolgenden Anwendungsfällen sind die erforderlichen Rechte explizit genannt.

Zugriffe auf das API-Gateway unterliegen keiner Authentifizierung oder Autorisierung.

Ist für einen Zugriff eine Authentifizierung nötig, so muss ein entsprechender HTTP-Header Authorization gesetzt und an den Server gesendet werden. Der Inhalt dieses Headers muss "Basic " gefolgt von dem als Base64-Darstellung codierten Wert des Ausdrucks Benutzername:Passwort sein. Im folgenden Beispiel entspricht der Wert YWRtaW5AbG9jYWxob3N0LmRlOmFkbWlu der Base64-Darstellung des Ausdrucks admin@localhost.de:admin.

CURL-Aufruf inklusive Authorization-Header

curl
-X GET 'https://localhost:8181/rest/api/v1/prepared_search/demo/execute?query=suchbegriff'
-H 'Authorization: Basic YWRtaW5AbG9jYWxob3N0LmRlOmFkbWlu'

3.2. Suchabfrage

Die Suchabfrage ist die Kernfunktion der SmartSearch. Sie basiert auf einem Suchindex und gibt die relevantesten Ergebnisse zu einem Suchbegriff zurück. Die Konfiguration, welche Felder im Dokument für den Suchindex relevant sind und wie die Ergebnisse aussehen, erfolgt über die entsprechende Prepared Search.

Für Suchabfragen sind zwei Formen unterscheidbar:

einfache Suche
facettierte Suche

Die nachfolgenden Unterkapitel beschreiben diese Formen im Detail.

3.2.1. Einfache Suche

Die einfache Suche ist die Basisfunktionalität der SmartSearch. Bei einer neu angelegten Prepared Search liefert sie standardmäßig bis zu zehn Suchtreffer zurück. Diese sind nach der Relevanz sortiert. Aufbauend auf den Ergebnissen kann die Suche Schritt für Schritt verfeinert werden.

Die einfachste Form der Suchabfrage für eine Prepared Search mithras mit dem Suchbegriff solar sieht wie folgt aus. Die Zeichenfolge entspricht dabei dem Wert des Parameters query.

Einfache Abfrage gegen das API-Gateway

curl -X GET 'https://mithras-search-api.e-spirit.cloud/v1/prepared_search/mithras/execute/?query=solar'

Einfache Abfrage gegen eine selbstbetriebene SmartSearch-Instanz

curl -X GET 'https://localhost:8181/rest/api/v1/prepared_search/mithras/execute/?query=solar
-H 'Authorization: Basic YWRtaW5AbG9jYWxob3N0Lsdf5Re'

Eine mögliche Antwort auf diese Abfrage könnte folgendermaßen aussehen:

beispielhafte Antwort (kann sich stark unterscheiden)

...
{
   "link": "https://mithrasenergy.com/content/Homepage/Startseite.html",
   "id": "fbfead657bf7118b92f2d91eb254710f0df563cf51fbb288a9e13eb1d5cf5099",
   "title": [
      "Herzlich Willkommen! - mithrasenergy"
   ]
},
{
   "link": "https://mithrasenergy.com/content/Services/Leistungen/Umwelt/Umweltaspekte-bei-der-Herstellung-der-Solarmodule.html",
   "id": "bedd3862818d2bd04809a44014c622f3402b75d1c1a7e49f116b10197eebb2c1",
   "title": [
      "Umweltaspekte bei der Herstellung der Solarmodule. CO2 Footprint. - mithrasenergy"
   ]
}
...

In allen Fällen ist der Parameter query auf eine Länge von 313 Zeichen beschränkt.

3.2.2. Facettierte Suche

Liefert eine Suche sehr viele Suchergebnisse zurück, kann deren Einschränkung dabei helfen, Suchenden das gewünschte Ergebnis zu liefern. Um dies zu erreichen, ermöglicht die SmartSearch eine Einschränkung der Ergebnisse. Zur Einschränkung auf bestimmte Bereiche dienen Facetten. Facetten bieten die Möglichkeit, Trefferlisten nach Feldern, die in einem Dokument vorhanden sind, einzuschränken. Die Konfiguration der Facetten erfolgt in der Prepared Search.

Das folgende Beispiel zeigt eine Abfrage nach dem Begriff solar für die Prepared Search mithras, deren Ergebnis ausschließlich deutsche Treffer enthält. Die Einschränkung wird durch die Facette language erreicht, die als Suchparameter übergeben wird.

Abfrage nach mit der Facette language gegen das API-Gateway

curl -X GET 'https://mithras-search-api.e-spirit.cloud/v1/prepared_search/mithras/execute/?query=solar&language=de'

Abfrage nach mit der Facette language gegen eine selbstbetriebene SmartSearch-Instanz

curl -X GET 'https://localhost:8181/rest/api/v1/prepared_search/mithras/execute/?query=solar&language=de
-H 'Authorization: Basic YWRtaW5AbG9jYWxob3N0Lsdf5Re'

3.3. Paginierung

In manchen Fällen liefert eine Suchanfrage viele Suchergebnisse zurück. Diese können für eine bessere Übersicht auf mehrere Seiten aufgeteilt werden. Die SmartSearch bietet dafür zwei Paginierungsformen an, die in den nachfolgenden Unterkapiteln ausführlicher beschrieben sind:

Klassische Paginierung: Bei der klassischen Paginierung gibt eine Suchanfrage lediglich die Suchergebnisse einer bestimmten Seite zurück. Mit ihr lässt sich beispielsweise die von Google bekannte Paginierung umsetzen.
Scroll-Paginierung: Bei der Scroll-Paginierung liefert eine Suchanfrage eine bestimmte Anzahl an Suchergebnissen ab einem bestimmten Treffer zurück. Sie ermöglicht zum Beispiel die Umsetzung des Infinite Scrollings.

Die SmartSearch bietet die JavaScript-Bibliothek SmartSearch.js an, die einige der notwendigen Implementierungen bereits übernimmt.

3.3.1. Klassische Paginierung

Der Konfigurationsdialog einer Prepared Search besitzt unter anderem das Feld Treffer pro Seite. Der für dieses Feld definierte Wert bestimmt die maximale Anzahl von Treffern, die eine einfache Suchanfrage zurückgibt. Sie entsprechen der ersten Seite der Paginierung. Um die Suchergebnisse weiterer Seiten zu erhalten, ist die Anfrage um den Parameter haupia_pageNumber zu ergänzen. Die Zählung beginnt bei 0, so dass die zweite Seite beispielsweise die Übergabe des Werts 1 erfordert.

Abfrage der zweiten Seite gegen das API-Gateway

curl -X GET 'https://mithras-search-api.e-spirit.cloud/v1/prepared_search/mithras/execute/?query=solar&haupia_pageNumber=1'

Abfrage der zweiten Seite gegen eine selbstbetriebene SmartSearch-Instanz

curl -X GET 'https://localhost:8181/rest/api/v1/prepared_search/mithras/execute/?query=solar&haupia_pageNumber=1
-H 'Authorization: Basic YWRtaW5AbG9jYWxob3N0Lsdf5Re'

Der Parameter haupia_pageSize ermöglicht die Überschreibung der Anzahl an Suchergebnissen pro Seite, die in der Prepared Search konfiguriert ist. Die nachfolgenden Abfrage liefert n Ergebnisse ab dem Ergebnis ((m-1)*n)+1.

Abfrageparameter

haupia_pageSize=n&haupia_pageNumber=m

3.3.2. Scroll Paginierung

Neben der klassischen Paginierung bietet die SmartSearch die Möglichkeit der Scroll Paginierung, deren Fokus auf dem Infinite Scrolling liegt. Dabei werden weitere Suchergebnisse nachgeladen, sobald das Ende der aktuell angezeigten Ergebnisse erreicht ist.

Eine neue angelegte Prepared Search gibt standardmäßig maximal zehn Ergebnisse zurück. Für den Erhalt der nächsten zehn Treffer ist die Definition eines Anfangspunkts der Ergebnisse erforderlich. Dieser lässt sich mithilfe des Parameters haupia_start setzen.

Abfrage der Suchergebnisse nach den ersten zehn Treffern (API-Gateway)

curl -X GET 'https://mithras-search-api.e-spirit.cloud/v1/prepared_search/mithras/execute/?query=solar&haupia_start=10'

Abfrage der Suchergebnisse nach den ersten zehn Treffern (selbstbetriebene SmartSearch-Instanz)

curl -X GET 'https://localhost:8181/rest/api/v1/prepared_search/mithras/execute/?query=solar&haupia_start=10
-H 'Authorization: Basic YWRtaW5AbG9jYWxob3N0Lsdf5Re'

Der Parameter haupia_rows ermöglicht die Überschreibung der Anzahl an Suchergebnissen pro Seite, die in der Prepared Search konfiguriert ist. Die nachfolgende Abfrage liefert n Ergebnisse ab dem Ergebnis m.

Abfrageparameter

haupia_rows=n&haupia_start=m

3.4. Autocomplete

Beim Autocomplete handelt es sich um eine Funktion, die Sucheingaben von Usern sinnvoll ergänzt. Grundlage für diese Ergänzung sind die sich im Suchindex befindlichen Daten, welche abhängig von der bisher getätigten Eingabe als sinnvolle Suchbegriffe vorgeschlagen werden.

Als Datengrundlage für die Autocomplete-Funktion dienen die Inhalte des content-Felds, welches auch zur Generierung des Suchindex herangezogen wird. Somit ist die Funktion im Normalfall nutzbar, ohne dass für eine Prepared Search eine spezifische Konfiguration notwendig ist. Die Sprachabhängigkeit wird hierbei für Nutzende transparent gestaltet, eine Konfiguration bezogen auf die zur Vervollständigung genutzte Sprache ist somit nicht nötig.

Grundsätzlich senden Nutzende der Autocomplete-Funktion eine Abfrage mit einem Präfix an die SmartSearch. Die Antwort auf diese Anfrage beinhaltet eine definierte Anzahl von Begriffen, welche mit dem übergebenen Präfix beginnen und von der SmartSearch für diesen als relevant identifiziert wurden - zum Beispiel, weil sie häufig in Dokumenten vorkommen. Daraufhin können Verwendende durch die Eingabe erweiterter Zeichenfolgen und somit einer erneuten Abfrage eine verfeinerte Vorschlagsliste abrufen.

Senden Nutzende zum Beispiel den Präfix son an die SmartSearch, so könnte eine Antwort zum Beispiel wie folgt aussehen:

beispielhafte Antwort

[
   "sondern",
   "sonnenenergie",
   "sonnenspektrums"
]

Erweitern Anfragende die Eingabe zu "sonn", führt ein Absenden der Abfrage zu einer verfeinerten Liste:

verfeinerte Liste

[
   "sonnenenergie",
   "sonnenspektrums"
]

Im Folgenden werden die Abfragen beschrieben, welche ein solches Verhalten ermöglichen. Dieses Beispiel basiert auf der Annahme, dass eine Prepared Search mithras vorhanden ist, welche als Ziel der Autocomplete-Abfragen dient.

Weiterhin besteht die Annahme, die Prepared Search sei, wie im Kapitel Prepared Search beschrieben, mit einen Datengenerator verknüpft, dessen indizierte Dokumente das Beispiel ermöglichen. Konkret heißt dies, die in den Beispielen aufgeführten Suchwortvorschläge befinden sich in den indizierten Inhalten.

Einschränkungen, die an der Prepared Search im Bezug auf das Suchergebnis gemacht werden, beeinflussen auch die Ergebnisse der Autocomplete-Abfrage.

3.4.1. Sprachunabhängiger Autocomplete

Die einfachste Form der Autocomplete-Abfrage für eine Prepared Search mithras für die Zeichenfolge "son" sieht aus wie folgt. Die Zeichenfolge entspricht dabei dem Wert des Parameters prefix.

/rest/api/v1/prepared_search/mithras/autocomplete?prefix=son

Wurde eine solche Abfrage durch Nutzende abgesetzt, so kann eine Antwort (abhängig von der Datenbasis) wie folgt aussehen:

beispielhafte Antwort

[
   "sonningen",
   "sonnenenergie",
   "sonnigen",
   "sondern",
   "sonnenspektrums"
]

3.4.2. Sprachabhängiger Autocomplete

Das bisherige Beispiel betrachtet den Fall, dass eine Autocomplete-Abfrage sprachunabhängig über alle Dokumente hinweg erfolgt. Dies kann jedoch dazu führen, dass Begriffe aus mehreren im Index vorhandenen Sprachen vorgeschlagen werden:

mehrsprachige Vorschläge

[
   "song",
   "sonne"
]

Durch das Hinzunehmen des Sprachparameters language zur Abfrage ist es möglich, auf eine bestimmte Sprache einzuschränken:

language-Parameter

/rest/api/v1/prepared_search/mithras/autocomplete?prefix=son&language=de

So führt die zuvor stehende beispielhafte Abfrage für die Sprache Deutsch mit dem Kürzel de zu einem entsprechenden Ergebnis:

sprachabhängige Antwort

[
   "sonne"
]

3.4.3. Wortübergreifendes Autocomplete

In manchen Anwendungsfällen kann es gewünscht sein, die vorgeschlagenen Begriffe nicht auf durch Leerzeichen getrennte Wörter, sondern über Leerzeichen hinweg zu erweitern. Ein typisches Beispiel sind Suchbegriffe wie "Modell 4A Version 2", "Presse aktuell" oder "Vertrag kündigen".

Soll die Autocomplete-Funktion solche mehrwortigen Begriffe vorschlagen, so gibt es grundsätzlich zwei Möglichkeiten dies umzusetzen:

mehrwortige Autocomplete-Funktion für freien Inhalt
mehrwortige Autocomplete-Funktion für definierte Begriffe

Mehrwortige Autocomplete-Funktion für freien Inhalt

Für einen zwei Worte umfassenden Autocomplete über ein Leerzeichen hinweg besteht für Nutzende die Möglichkeit, dynamische Felder vom Typ _expandend_autocomplete zu nutzen. Diese werden bei einer Datengenerierung für das Feld content automatisch befüllt, und können durch das Anhängen des Suffixes _expanded über den Parameter field abgerufen werden:

expanded-Suffix

/rest/api/v1/prepared_search/mithras/autocomplete?prefix=ene&field=content_expanded

mehrwortige Vorschläge

[
   "energy",
   "energy facts",
   "energy locations"
]

Sollen die Inhalte anderer Felder für eine solche mehrwortige Autovervollständigung genutzt werden, so müssen die Inhalte bei der Datengenerierung in einem Groovy-Skript-Enhancer in ein entsprechendes Feld vom Typ *_expanded_autocomplete_[Sprachkürzel] übertragen werden. In diesem Beispiel wird ein freier Text in das Feld texte_expanded_autocomplete_en kopiert:

Feld texte_expanded_autocomplete_en

document.addData("texte_expanded_autocomplete_en", "Solar energy is the energy of the future, and we have dedicated ourselves to this future. With our solutions and products, we would like to make sure that you are best equipped for this energy of the future. This is the only way for each of us to achieve the highest levels of sustainability and environmental protection for ourselves, our families and our companies")

Nutzende können nun eine Abfrage gegen dieses Feld (ohne den Suffix _autocomplete_[Sprachkürzel]) senden:

Abfrage des Felds

/rest/api/v1/prepared_search/mithras/autocomplete?prefix=sol&field=texte_expanded

Die Antwort auf diese Abfrage beinhaltet eine leerzeichenübergreifende Autovervollständigung, falls entsprechende Begriffe in den indizierten Daten vorhanden sind:

leerzeichenübergreifende Vorschläge

[
   "solar energy",
   "solutions",
   "solar",
   "solutions and"
]

Mehrwortige Autocomplete-Funktion für definierte Begriffe

In manchen Situationen kann es als Suchanbieter hilfreich sein, die Wortvorschläge sehr genau kontrollieren zu können. Sind die indizierten Inhalte zum Beispiel Produkte, so soll die Vervollständigung der Eingabe "mod" eventuell die Vorschläge "modell 4a version 1" sowie "modell 4a version A" anbieten.

Um dieses Verhalten zu erreichen, steht das sprachunabhängige dynamische Feld _keyword_lc zur Verfügung. Dazu muss bei der Einrichtung des Datengenerators an einem an der Prepared Search konfigurierten Datengenerator in einem Groovy-Skript-Enhancer ein solches Feld befüllt werden. Folgender exemplarischer Groovy-Skript-Code setzt den Wert des dynamischen Felds model_keyword_lc auf modell 4a version 1:

Ersetzung eines dynamischen Felds

document.setSingleValue("model_keyword_lc", "modell 4a version 1")

Gibt es nun im Index Dokumente mit den Werten modell 4a version 1 bzw. modell 4a version 2, können User die Autocomplete-Funktion durch den Parameter field das Feld model_keyword_lc gezielt zur Vervollständigung der Eingabe "mod" nutzen:

gezielte Vervollständigung

/rest/api/v1/prepared_search/mithras/autocomplete?prefix=mod&field=model_keyword_lc

Anders als bei den bisherigen Beispielen, in denen nur passende Auszüge aus Feldinhalten zurückgegeben wurden, beinhaltet die Antwort auf eine solche Abfrage alle vollständigen Werte des übergebenen dynamischen Felds. Im aktuellen Beispiel könnte die Antwort entsprechend wie folgt aussehen:

Antwort mit vollständigen Werten

[
   "modell 4a version 2",
   "modell 4a version 1"
]

3.4.4. Anmerkungen

Die Autocomplete-Funktion schlägt keine Wörter vor, die in Stopwortlisten vorkommen. Bei Änderungen an einer Stopwortliste ist eine erneute Indizierung durch einen Datengenerator-Lauf nötig, damit sich die Änderung in der Liste der ausgelieferten Autocomplete-Vorschläge niederschlägt.

Es ist ratsam, keine Autocomplete-Anfragen für Prefixe mit weniger als drei Buchstaben an die SmartSearch zu senden. Wenn auch grundsätzlich möglich, können Abfragen mit solch kurzen Prefixen eine erhöhte Last verursachen. Auch sind die Vorschläge in den Antworten solcher kurzen Anfragen häufig nicht sinnvoll, da die Anzahl der möglichen Vorschläge noch sehr lang und somit wenig eingrenzend ist.

Grundsätzlich sind die Vorschlagslisten um sogenannte Filter-Queries erweiterbar. Solche Filter-Queries schränken die Liste der Vervollständigungsvorschläge weiter ein, indem sie die Menge der ihnen zugrunde liegenden Dokumente durch eine Anfrageklausel verkleinern. Die ist durch eine Erweiterung des Parameters fq durch eine solche Klausel erreichbar. Das folgende Beispiel zeigt entsprechend nur noch Vorschläge aus Dokumenten an, in deren indiziertem Inhalt das Feld mime_type den Wert 'html' enthält.

Einschränkung durch Filter-Queries

rest/api/v1/prepared_search/mithras/autocomplete?prefix=ene&fq=mime_type:html

3.5. Sortierung

Für Suchende zeichnet sich eine erfolgreiche Suche dadurch aus, dass der beste Treffer an erster Stelle steht. Die Reihenfolge der Suchtreffer richtet sich bei der SmartSearch nach deren Score. Der Score entspricht der Relevanz eines Treffers bezogen auf den Suchbegriff. Die Standardeinstellung einer neu angelegten Prepared Search ist eine auf dem Score basierende absteigende Reihenfolge. Dies ist zum Beispiel durch die Gewichtung der einzelnen Felder beeinflussbar.

In den meisten Fällen ist der Score für die Sortierung am sinnvollsten. Manchmal ist eine andere Sortierung, wie beispielsweise nach dem Datum, jedoch besser geeignet. Um die Sortierung zu beeinflussen, bietet die Prepared Search das Textfeld Sortieren nach. Das Feld erwartet zunächst die Eingabe des Felds, das als Grundlage für die Sortierung dienen soll. Getrennt durch ein Leerzeichen ist danach die Reihenfolge anzugeben (ASC oder DESC).

Um die Suchergebnisse nach der Veröffentlichung anhand des Beispielfelds publication_date zu sortieren, muss das Feld Sortieren nach die folgende Eingabe enthalten:

Beispieleingabe

publication_date DESC

Soll die Sortierung durch Suchende beeinflussbar sein, sind zwei Schritte notwendig: Zum einen ist das Groovy-Skript an der Prepared Search anzupassen und zum anderen muss im FrontEnd ein entsprechender Aufruf erfolgen.

In dem nachfolgend dargestellten Beispiel lässt sich der Prepared Search der Parameter sortDate übergeben. Je nachdem, ob der Parameter den Wert asc oder desc hat, erfolgt eine Anpassung der Sortierung.

Der folgende Code-Ausschnitt zeigt ein Beispiel für das Setzen der Sortierung mithilfe eines Groovy-Skripts an der Prepared Search.

Beispiel für das Setzen der Sortierung

import org.apache.solr.client.solrj.SolrQuery

// Getting a parameter (sortDate) out of the request
def sortDateParam = parameter.get("sortDate")?.get(0)

// Set the sort order, depending on the given value asc/desc
if (sortDateParam?.equals("asc")) {
   solrQuery.setSort("sort_date", SolrQuery.ORDER.asc)
} else if (sortDateParam?.equals("desc")) {
   solrQuery.setSort("sort_date", SolrQuery.ORDER.desc)
}

Bei einer Verwendung des SmartSearch.js im FrontEnd ist für eine Übergabe des Sortierungsparameters an die Prepared Search folgende Anpassung erforderlich:

Beispiel für die Sortierung mittels SmartSearch.js

const smaseOptions = {
   autocompleteOptions: {
      language: this.options.language
   },
   customParams: [{
      "sortDate": "desc"
   },
   {
      "someOtherParam": "some other value"
   }]
}
this.smartSearch = new SmartSearch(DEFAULT_HOST, this.options.preparedSearch, smaseOptions)

Die Sortierung ist nur bei sogenannten primitiven Feldern (numerics, string, boolean, dates) durchführbar. Auf Felder wie content ist die Sortierung hingegen nicht möglich. Das Kapitel Verfügbare Felder und Feldtypen enthält weitere Details zu Feldern, die ebenfalls eine Sortierung unterstützen. Eigene Felder, die für die Sortierung verwendet werden sollen, müssen die Endung *sort besitzen. Damit stellt die _SmartSearch sicher, dass das entsprechende Feld für die Suche geeignet ist.

Bei der Sortierung deutschsprachiger Textfelder werden Umlaute durch den entsprechenden Vokal und ß durch ss ersetzt. Darüber hinaus ist bei einer deutschsprachigen Sortierung die Verwendung der Endung *_sort_de empfohlen.

Beispiel für die Sortierung bei Umlauten:

Abend
Äcker
Advent

3.6. Nutzung der generischen API zur Indizierung von Dokumenten

Im Abschnitt zu Datengeneratoren wurden Möglichkeiten erläutert um mit SmartSearch Daten in Formaten wie XML und HTML von bestimmten konfigurierbaren Quellen abzurufen und zu indizieren. Für Anwendungsfälle in denen Dokumente regelmäßig einzeln oder in kleinen Mengen hinzugefügt, angepasst oder entfernt werden sollen, bietet SmartSearch die sogenannte generische API zur Indizierung von Dokumenten an.

Die generische API bietet Endpunkte für folgende Aufrufe an:

Hinzufügen eines Dokuments
Hinzufügen mehrerer Dokumente
Entfernen eines Dokuments

Die verfügbaren Aufrufe lassen sich in einer interaktiven Oberfläche einsehen und ausführen. Diese Oberfläche ist auf jeder SmartSearch-Instanz unter der relativen URL /swagger-ui/index.html erreichen. Im Cockpit ist sie durch Aufrufen des Links API Dokumentation zu erreichen:

Abbildung 26. Aufruf der API-Dokumentation im Cockpit

Das Datenaustauschformat ist im Falle der generischen API JSON, im Folgenden wird Struktur und Ziel dieser Aufrufe für die verfügbaren Operationen beispielhaft erläutert.

3.6.1. Hinzufügen eines Dokuments

Das Hinzufügen eines einzelnen Dokuments geschieht per Aufruf der http-Methode PUT gegen eine URL welche den Namen des Datengenerators als auch die eindeutige Dokument-ID enthält. Die explizite Angabe der Sprache ist optional:

https://localhost:8181/rest/api/v1/smartsearchconnect/myDatagenerator/00001

https://localhost:8181/rest/api/v1/smartsearchconnect/myDatagenerator/de/00001

Die Struktur des zu sendenden JSON-Dokuments ist eine flache Struktur aus Feldname-Wert-Paaren, wobei Werte auch Arrays aus Werten sein können, wie in folgendem exemplarischen Dokument zu erkennen:

Beispiel eines JSON-Dokuments mit den Pflichtfelder 'title', 'link' und 'content' sowie beliebigen weiteren Feldern

{
  "link": "https://www.mithrasenergy.com/myDocument01.html",
  "title": "My document 01.",
  "content": "Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.",
  "myCategory": "Article",
  "multiValuedField" : [ "Value 01", "Value 02" ]
}

So kann z.B. folgender Aufruf dieses Dokument gegen die API senden:

Beispiel eines cURL-Aufrufs zum Senden des obigen Dokuments an die generische API

curl -X 'PUT' \
'https://localhost:8181/rest/api/v1/smartsearchconnect/myDatagenerator/de/00001' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"link": "https://www.mithrasenergy.com/myDocument01.html",
"title": "My document 01.",
"content": "Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.",
"myCategory": "Article",
"multiValuedField" : [ "Value 01", "Value 02" ]
}'

3.6.2. Hinzufügen mehrerer Dokumente

Sollen mehrere Dokumente indiziert werden, so können mehrere JSON-Dokumente einer http-Methode POST übergeben werden. In diesem Fall unterscheidet sich die JSON-Struktur neben der Klammerung der Dokumente in ein Array durch das nötige Hinzufügen einer jeweiligen Dokumenten-ID uid, da diese nicht Bestandteil der POST-URL ist:

Beispiel mehrerer JSON-Dokumente mit den Pflichtfelder 'title', 'link' und 'content' sowie beliebigen weiteren Feldern

[
  {
    "uid": "00001",
    "link": "http://localhost/myDocument01.html",
    "title": "My document 01.",
    "content": "Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.",
    "myCategory": "Article",
    "multiValuedField" : [ "Value 01", "Value 02" ]
  },
  {
    "uid": "00002",
    "link": "http://localhost/myDocument02.html",
    "title": "My document 02",
    "content": "Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.",
    "myCategory": "Article",
    "multiValuedField" : [ "Value 01", "Value 02" ]
  }
]

Der entsprechende cURL-Aufruf sähe zum Beispiel aus wie folgt:

Beispiel eines cURL-Aufrufs zum Senden der obigen Dokumente an die generische API

curl -X 'POST' \
'https://localhost:8181/rest/api/v1/smartsearchconnect/myDatagenerator' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '[
{
"uid": "00001",
"link": "http://localhost/myDocument01.html",
"title": "My document 01.",
"content": "Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.",
"myCategory": "Article",
"multiValuedField" : [ "Value 01", "Value 02" ]
},
{
"uid": "00002",
"link": "http://localhost/myDocument02.html",
"title": "My document 02",
"content": "Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.",
"myCategory": "Article",
"multiValuedField" : [ "Value 01", "Value 02" ]
}
]'

3.6.3. Entfernen eines Dokuments

Zum Entfernen eines Dokuments muss ein Aufruf mit der http-Methode DELETE an die gleiche URL, welche zum Indizieren des Dokuments verwendet werden konnte geschehen:

Beispiel eines cURL-Aufrufs zum Entfernen des obigen Dokuments an die generische API

curl -X 'DELETE' \
'https://localhost:8181/rest/api/v1/smartsearchconnect/myDatagenerator/de/00001' \
-H 'accept: application/json'

3.6.4. Anmerkungen zu Datengeneratoren der generischen API

Datengeneratoren des Typs API werden automatisch angelegt, sobald ein erstes Dokument an sie gesendet wird und ein Datengenerator mit dem Namen nicht existiert. Bei Operationen mit der generischen API wird ein Datengeneratorname verlangt, unter dem sie in Folge im Cockpit konfigurierbar sind, um z.B. Enhancer hinzuzufügen. Ein solcher Datengenerator hat den Typ API, und muss im Cockpit weder gestartet noch gestoppt werden. Auch wird bei erwähntem automatischen Anlegen des Datengenerators eine gleich benannte Prepared Search angelegt, und mit dem Datengenerator verknüpft.

Operationen gegen die generische API werden nicht sofort im Index wirksam, jedoch bereits nach sehr kurzer Zeit im Rahmen von Minuten. Eine genauere Zeitangabe ist aufgrund der technischen Hintergründe der Indizierung nicht möglich.

Die generische API wird zum Teil auch die Integration von FirstSpirit und dem SmartSearch Connect Modul genutzt. So finden sich im Rahmen der Nutzung gelegentlich Hinweise auf diese Nutzung, wie Verweise auf entsprechende Pflichtfelder, zum Beispiel fsTitle. Diese Anmerkungen können für die FirstSpirit-unabhängige Nutzung der API jedoch ignoriert werden.

3.7. Datengeneratoren starten

Das Starten von Datengeneratoren kann komfortabel über das Cockpit erfolgen. In einigen Fällen ist aber notwendig einen Datengenerator automatisiert starten zu können. Beispielweise, um nach einer Vollgenerierung in FirstSpirit direkt ein Crawl-Vorgang anzustoßen. Für solche Fälle bietet die SmartSearch einen API-Endpunkt an.

Der Aufruf des Endpunkts erfolgt über den Typ und den Namen des Datengenerators, wie folgendes Beispiel zeigt:

CURL-Aufruf für den Start eines Datengenerators "mithras"

curl -X GET 'https://localhost:8181/rest/api/v1/datagenerator/WEB/mithras/start' -H 'Authorization: Basic YWRtaW5AbG9jYWxob3N0Lsdf5Re'

Der Statuscode 200 in der Antwort informiert über einen erfolgreichen Start des Datengenerators. Läuft der Datengenerator zum Zeitpunkt des Aufrufs bereits, liefert die SmartSearch den Statuscode 409 zurück.

3.8. Datengeneratoren stoppen

Um einen laufenden Datengenerator erneut zu starten, ist ein vorheriger Stopp erforderlich Wie auch beim Start wird der Endpunkt anhand des Typ und den Namen des Datengenerators ausgeführt.

CURL-Aufruf zum Stoppen eines Datengenerators "mithras"

curl -X GET 'https://localhost:8181/rest/api/v1/datagenerator/WEB/mithras/stop' -H 'Authorization: Basic YWRtaW5AbG9jYWxob3N0Lsdf5Re'

3.9. Hot Injection und Hot Deletion

Grundsätzlich erfordern Änderungen am Datensatz der SmartSearch dessen Neuerfassung. Diese Neuerfassung nimmt eine gewisse Zeitspanne in Anspruch, die bei kleinen Datenmengen zu Verzögerungen führt. Mit der Hot Injection und der Hot Deletion bietet die SmartSearch die Möglichkeit, Dokumente schnell anzupassen oder aus den Suchergebnissen zu entfernen, sollte dies kurzfristig erforderlich sein.

Die auf die Hot Injection und Hot Deletion bezogenen API-Aufrufe sind nur am SmartSearch-Server, nicht jedoch am API-Gateway, verfügbar. Dies hat zur Folge, dass Anfragen an die Hot Injection- sowie Hot Deletion-API einen HTTP-Header Authorization benötigen. Eine genauere Beschreibung dazu ist im Kapitel Authentifizierung und Autorisierung zu finden. User, die für den Aufruf genutzt werden, bzw. die Gruppe, aus welcher die Berechtigung hervorgeht, müssen im SmartSearch-Cockpit mit der Berechtigung "Datengenerator ausführen" versehen sein.

Die nachfolgenden Unterkapitel beschreiben die Hot Injection und die Hot Deletion im Detail.

3.9.1. Hot Injection

Die Hot Injection ist im Rahmen der SmartSearch der schnellste Weg, dem Index eines Datengenerators Daten hinzuzufügen. Die auf diese Weise hinzugefügten Daten sind nach spätestens fünfzehn Minuten im Index verfügbar.

Grundsätzlich findet der HTTPS-Aufruf zur Nutzung der Hot Injection am wie folgt definierten Endpunkt statt:

Methode: PUT
URL: /rest/api/v1/datagenerator/{type}/{name}/inject

Tabelle 6. URL-Parameter eines Hot Injection-Aufrufs
Parameter	Beschreibung
`type`	Der Typ des Datengenerators, dem die beim Aufruf übergebenen Daten hinzugefügt werden. (zum Beispiel `Web` oder `XML`).
`name`	Der Name des Datengenerators, dem die beim Aufruf übergebenen Daten hinzugefügt werden.

Der HTTP-Status-Code der Antwort auf eine solche Anfrage entspricht im Normalfall einem der folgenden Werte:

Der Status-Code HTTP 200 - No Content bedeutet, dass die Anfrage erfolgreich war. Das Dokument wird somit dem Index hinzugefügt.
Im Fall der Rückgabe von HTTP 404 - Not found existiert der angefragte Datengenerator nicht.
Alle 4xx- oder 5xx-Fehler-Codes weisen darauf hin, dass die Anfrage fehlgeschlagen ist und keine Verarbeitung stattgefunden hat. In diesem Fall sind dem Log weitere Details zu entnehmen.

Das Format der übergeben Daten ist bei einer Hot Injection-Abfrage vom Typ des Datengenerators abhängig, dem die Daten hinzugefügt werden.

Übergabe an einen Web-Datengenerator

Der Web-Datengenerator akzeptiert eine Liste von URLs, die verarbeitet werden sollen. Ihre Verarbeitung läuft auf die gleiche Art ab, als würden sie vom Crawler im Rahmen einer Datengenerierung erfasst. Die Übergabe der Liste der URLs ist entweder als zeilenweise getrennter Text oder als JSON-Array möglich:

Beispiel für eine zeilenweise getrennte URL-Liste

http://www.mithrasenergy.com/page1.html
http://www.mithrasenergy.com/page2.html

Beispiel für eine URL-Liste als JSON-Array

[
   "http://www.mithrasenergy.com/page1.html",
   "http://www.mithrasenergy.com/page2.html"
]

In Abhängigkeit des für die Übergabe gewählten Formats ist an der Anfrage der HTTP-Header Content-Type zu setzen. Dieser muss entweder den Wert text/plain oder application/json haben. Standardmäßig nimmt die SmartSearch den Wert text/plain an, der die Übergabe einer zeilenweise getrennten URL-Liste voraussetzt.

Beispiel für einen CURL-Aufruf mit einer zeilenweise getrennten URL-Liste

curl -X PUT 'https://localhost:8181/rest/api/v1/datagenerator/WEB/demo/inject'
-H 'Content-Type: text/plain'
-H 'Authorization: Basic YWRtaW5AbG9jYWxob3N0LmRlOmFkbWlu'
--data-raw 'http://www.mithrasenergy.com/page1.html
http://www.mithrasenergy.com/page2.html'

Beispiel für einen CURL-Aufruf mit einer URL-Liste als JSON-Array

curl -X PUT 'https://localhost:8181/rest/api/v1/datagenerator/WEB/mithras/inject'
-H 'Content-Type: application/json'
-H 'Authorization: Basic YWRtaW5AbG9jYWxob3N0LmRlOmFkbWlu'
--data-raw '[
   "https://mithrasenergy.com/content/Career/Jobs.html",
   "https://mithrasenergy.com/content/Services/Services-2.html"
]'

Des Weiteren sind bei der Übergabe von URL-Listen folgende Punkte zu beachten:

Jede der übergebenen URLs wird einzeln erfasst und verarbeitet.
Weiterführenden Verweisen auf den Seiten wird nicht gefolgt. Dieses Verhalten unterscheidet sich von dem bei einer Generierung mittels eines Web-Datengenerators und gilt auch für kanonische Verweise. Enthält ein übergebener Verweis einen kanonischen Verweis auf eine andere Ursprungsseite, so wird diese Seite weder in den Index aufgenommen noch dem kanonischen Link gefolgt.
Das Log enthält eine Info über die Anzahl neuer, geänderter und ignorierter Seiten.

Bei einer Hot Injection findet keine Auswertung des an Web-Datengeneratoren pflegbaren Felds Check URL Script statt.

Übergabe an einen XML-Datengenerator

Bei einem XML-Datengenerator akzeptiert die Hot Injection eine Liste von URLs in gleicher Weise wie bei einem Web-Datengenerator. Diese können sowohl aus Daten-XML-Dateien als auch aus Seed-XML-Dateien bestehen. Auch eine beliebige Mischung aus Daten-XML-Dateien und Seed-XML-Dateien ist möglich, wie das folgende Beispiel aus dem Kapitel XML-Datengenerator zeigt:

Beispiel für eine Seed-XML-Datei mit gemischten Verweisen

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<seeds>

    <!-- Verweise auf Daten-XML-Dateien -->
        <seed url="https://www.customer.com/.../.../documents-01.xml" />
        <seed url="https://www.customer.com/.../.../documents-02.xml" />

    <!-- Verweise auf weitere Seed-XML-Dateien -->
        <seed url="https://www.customer.com/.../.../another-seed.xml" />

</seeds>

Bei der Hot Injection eines XML-Datengenerators ist auch die direkte Übergabe von Daten möglich. Dafür muss der Content-Type text/xml gesetzt sein und der Body der Abfrage dem XML-Format des XML-Datengenerators entsprechen:

Beispiel für eine Daten-XML-Datei, deren Inhalt so auch einer Hot Injection-Anfrage verwendbar ist

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<documents>
   <document uid="0815">
           <field name="title"><![CDATA[Das Erklärvideo zur SmartSearch-XML-Datei]]></field>
                <field name="link"><![CDATA[https://www.youtube.com/watch?v=...]]></field>
                <field name="content">
                   <![CDATA[Hier steht inhaltlich, wie Sie eine SmartSearch-XML-Datei erstellen.]]>
                </field>
                <field name="language_keyword"><![CDATA[de]]></field>
                <field name="publishing_date"><![CDATA[ 2019-05-23T10:00:01Z ]]></field>
                <field name="favorites_count_long"><![CDATA[34]]></field>
                <field name="category_keyword"><![CDATA[socialmedia]]></field>
                <field name="category_keyword"><![CDATA[presse]]></field>
                <field name="meta_keywords"><![CDATA[SmartSearch Erklärvideo Facetten]]></field>
   </document>
        ...
        <document uid="4711">
           <field name="title"><![CDATA[Die Hilfeseiten zu SmartSearch.]]></field>
                ...
        </document>
</documents>

Eine dieser Struktur entsprechende Hot Injection Anfrage könnte wie folgt aussehen:

Exemplarischer CURL-Aufruf einer Hot Injection an einen XML-Datengenerator

curl -X PUT 'https://localhost:8181/rest/api/v1/datagenerator/XML/test/inject'
-H 'Content-Type: text/xml'
-H 'Authorization: Basic YWRtaW5AbG9jYWxob3N0LmRlOmFkbWlu'
--data-raw '<documents>
    <document uid="0815">
        ...
    </document>
</documents>'

3.9.2. Hot Deletion

Die Hot Deletion ermöglicht die schnelle und unmittelbare Entfernung von Dokumenten aus dem Index.

Ihr Aufruf findet an folgendem Endpunkt statt:

Methode: DELETE
URL: /rest/api/v1/datagenerator/{type}/{datageneratorName}/delete

Tabelle 7. URL-Parameter eines Hot Deletion-Aufrufs
Parameter	Beschreibung
`type`	Der Typ des Datengenerators, aus dessen Index das Dokument entfernt wird (zum Beispiel `Web` oder `XML`).
`name`	Der Name des Datengenerators, aus dessen Index das Dokument entfernt wird.

Da die Entfernung von Dokumenten aus dem Index dessen Neuindizierung auslöst, ist die Delete-Methode nur in Maßen zu benutzen!

Für die langfristige Löschung einer größeren Anzahl von Dokumenten aus dem Index, ist eine entsprechende Konfiguration des Datengenerators erforderlich, so dass dieser sie nicht weiter erfasst. Auf diese Weise sind die Dokumente nach erneuten Datengenerator-Läufen nicht mehr im Index vorhanden.

Die Übergabe einer der folgenden Informationen definiert das zu löschende Dokument. Die Information muss dem JSON-Rumpf des Aufrufs entsprechen.

Die Solr-ID, welche im Feld id am Dokument existiert.
Die URL, welche im Feld link am Dokument vorhanden ist.

Beispiel eines Hot Deletion-Aufrufs mit der id des Dokuments

{
   "id" : "1234567890"
}

Beispiel eines Hot Deletion-Aufrufs mit dem link des Dokuments

{
   "url" : "https://www.foo.bar/foo/bar.html"
}

Der HTTP-Status-Code der Antwort auf eine solche Anfrage entspricht im Normalfall einem der folgenden Werte:

Eine Rückgabe von HTTP 200 - No Content bedeutet, dass die Anfrage erfolgreich war. Das Dokument wird somit aus dem Index entfernt.
Im Fall der Rückgabe von HTTP 404 - Not found existiert der angefragte Datengenerator nicht.
Alle 4xx- oder 5xx-Fehler-Codes weisen darauf hin, dass die Anfrage fehlgeschlagen ist und keine Verarbeitung stattgefunden hat. In diesem Fall sind dem Log weitere Details zu entnehmen.

3.10. Highlighting

Der Konfigurationsdialog einer Prepared Search enthält unter anderem die Felder Highlight und Länge Highlight (in Zeichen). Diese dienen dazu, Suchbegriffe in den Suchtreffern hervorzuheben. Für jede Prepared Search ist konfigurierbar, auf welche Felder das Highlighting angewandt wird. Standardmäßig ist das Highlighting für den Content definiert und auf 200 Zeichen begrenzt.

Die Rückgabe einer Suchanfrage enthält neben den results das highlighting. Die Verbindung zwischen einem Suchtreffer und dem dazugehörigen Highlighting lässt sich mithilfe der ID herstellen. Die Hervorhebung des konfigurierten Suchbegriffs erfolgt durch das HTML-Element <strong>. Eine weitere Konfiguration ist nicht notwendig.

Beispiel für Highlights in einem Suchergebnis

"results": [
   {
      "link": "https://www.e-spirit.com/de/produkt/hybrid-cms/",
      "id": "dfee2187ac7113a788dfc9aa262255b1c281bfa8df0729fb5d636613219a99c7",
      "title": [
         "FirstSpirit Hybrid Headless CMS & CaaS | e-Spirit"
      ]
   },
   ...
],
...
"highlighting": {
   "dfee2187ac7113a788dfc9aa262255b1c281bfa8df0729fb5d636613219a99c7": {
      "title": [
         "FirstSpirit Hybrid Headless <strong>CMS</strong> & CaaS | e-Spirit"
      ],
   },
   ...
}

Um dem Highlighting weitere Felder hinzuzufügen, reicht eine Aktivierung des Highlights für das entsprechende Feld im Konfigurationsdialog der Prepared Search aus. Die Länge der Highlights ist über das gleichnamige Feld definierbar.

Tiefergehende Änderungen an der Konfiguration lassen sich mithilfe eines Groovy-Skripts durchführen. Dieses wird der Prepared Search hinzugefügt und nimmt die gewünschten Anpassungen am SolrQuery-Objekt vor.

Das folgende Beispielskript ändert den Prä- und Postfix des Highlightings, um zum Beispiel das oben genannten hervorhebenden HTML-Element anzupassen:

Beispielskript - Definition des Präfix und Postfix beim Highlighting

solrQuery.setHighlightSimplePre("<em>");
solrQuery.setHighlightSimplePost("</em>");

In der Konfiguration der Prepared Search kann über das Feld Länge Highlight (in Zeichen) die ungefähr gewünschte Größe der Highlight-Sektion angegeben werden. SmartSearch wird durch Weitergabe dieses Parameters an {solr} versuchen, ein Highlight zu generieren, welche ungefähr dieser Zeichenanzahl entspricht.

In der Standardkonfiguration wird SmartSearch jedoch versuchen, vollständige Sätze um den Suchtreffer herum als Highlight auszugeben. Dies kann - z.B. bei Feldern wie 'content', welche mit sehr vielen Teils unstrukturierten Daten angefüllt werden - zu ungewünscht langen oder unstrukturierten Highlights führen.

Diesem kann beigekommen werden, indem über den Parameter 'hl.bs.type' das Trennverhalten bei der Ausgabe von Highlights angepasst wird. Wie oben beim Definieren des Prä- und Postfixes kann das Trennverhalten im Groovy-Skript der Prepared Search wie folgt angepasst werden:

Beispielskript - Festlegen des Trennverhaltens beim Highlighting

solrQuery.set("hl.bs.type", "WORD");

Obiges Skript setzt das Trennverhalten auf Wörter ('WORD') statt Sätze (Standardkonfiguration - 'SENTENCE'). Weitere mögliche Werte für diesen Parameter wie z.B. exakte Zeichentrennung ('CHARACTER') können der entsprechenden {solr}-Dokumentation entnommen werden.

Diese Anpassung des Trennverhaltens kann folglich dazu führen dass das ausgegebene Highlight mitten innerhalb eines Satzes oder gar Wortes endet.

3.11. Facettierung

Liefert eine Suche sehr viele Suchergebnisse zurück, kann deren Einschränkung dabei helfen, Suchenden das gewünschte Ergebnis zu liefern. Um dies zu erreichen, stellt die SmartSearch sogenannte Facetten bereit. Facetten stellen eine Möglichkeit dar, Suchergebnisse zu filtern und zu verfeinern. Sie werden durch bestimmte Felder eines Dokuments repräsentiert, deren Werte zur Eingrenzung der Suche verwendbar sind. Die Produktsuche eines Onlineshops könnte zum Beispiel Facetten enthalten, die eine Filterung nach Farben, Größen oder Preisen ermöglichen. Im konkreten Fall Farbe, wäre der Name der Facette "Farbe" und "Rot", "Blau", "Grün" usw. wären mögliche Facettenwerte.

Die nachfolgenden Unterkapitel beschreiben die Erstellung und Verwendung von Facetten. Weitere Informationen sind im Kapitel Prepared Search enthalten.

Die JavaScript-Bibliothek SmartSearch.js unterstützt ebenfalls Facettierungen. Die zugehörige Dokumentation beinhaltet einige erklärende Beispiele in englischer Sprache.

3.11.1. Erzeugung von Facetten

Die Erstellung einer Facette erfolgt an einem Datengenerator durch die Generierung eines Felds mit dem Suffix _keyword (zum Beispiel color_keyword). Dies ist beispielsweise mithilfe eines Groovy-Skript-Enhancers möglich. Die auf diesem Weg erstellten Felder erscheinen in der Bearbeitungsansicht einer Prepared Search, sobald der entsprechende Datengenerator ausgewählt ist. Sie sind mit dem Begriff Facette gekennzeichnet.

Das folgende Code-Beispiel zeigt ein Groovy-Skript, das eine Facette mit dem Namen content_category erzeugt.

Groovy-Skript

// Check the value of three fields: fsType_keyword, schema, entityType

if (document.getData("fsType_keyword").contains("Dataset")
    && document.getData("schema").contains("Regional")
    && document.getData("entityType").contains("News")) {

      // Always delete the field and the value bevor creating it
      document.removeData("content_category_keyword")

      // We create a new field with the value news
      document.addData("content_category_keyword", "news")
}

Auf diese Art erstellte Facetten heißen Field-Value-Facetten. Zusätzlich zu diesen existieren zwei weitere Facettenarten: die Range-Facetten und die Pivot-Facetten. Diese unterstützt die SmartSearch jedoch aktuell nicht out of the Box.

3.11.2. Verwendung von Facetten

Die SmartSearch beantwortet jede Suchanfrage mit JSON-Daten, die bereits alle erforderlichen Informationen für eine Facettierung beinhalten. Der folgende Ausschnitt zeigt eine solche Serverantwort auf eine Suchanfrage in gekürzter Form.

Ausschnitt aus einer Serverantwort

// ...
"facets": [
   {
      "name": "language_facet_string",
      "counts": [{
         "value": "de",
         "count": 347,
         "filterQuery": "language_facet_string:de",
         "urlFilterQuery": "facet.filter.language=de"
      },
      {
         "value": "en",
         "count": 311,
         "filterQuery": "language_facet_string:en",
         "urlFilterQuery": "facet.filter.language=en"
      },
      {
         "value": "us",
         "count": 266,
         "filterQuery": "language_facet_string:us",
         "urlFilterQuery": "facet.filter.language=us"
      }]
   },
   {
      "name": "color_facet_string",
      "counts": [{
         "value": "red",
         "count": 897,
         "filterQuery": "color_facet_string:red",
         "urlFilterQuery": "facet.filter.color=red"
      },
      {
         "value": "blue",
         "count": 27,
         "filterQuery": "color_facet_string:blue",
         "urlFilterQuery": "facet.filter.color=blue"
      },
      {
         "value": "green",
         "count": 423,
         "filterQuery": "color_facet_string:green",
         "urlFilterQuery": "facet.filter.color=green"
      }]
   }
],

// ...

"facetConfigs": [
   {
      "baseName": "language",
      "multiSelect": false
   },
   {
      "baseName": "color",
      "multiSelect": true
   }
],
// ...

Die Reihenfolge der Facette im JSON lässt sich nicht beeinflussen. Eine Sortierung muss daher auf der Suchergebnisseite beispielsweise mittels JavaScript gemacht werden.

Die Facette color kann in diesem Beispiel drei Werte annehmen: red, green und blue. Der Schlüssel urlFilterQuery gibt für jeden Wert den genauen String an, mit dem die Abfrage-URL zu erweitern ist, um die Ergebnisse auf diesen Facettenwert einzuschränken. Die Einschränkung der Ergebnisse auf rote Schuhe erfordert beispielsweise die folgende Anfrage-URL:

https://hostname/v1/preparedSearch/ShoeSearch/execute?query=shoes&facet.filter.color=red

Darüber hinaus definiert der Wert des Schlüssels multiSelect unter facetConfigs, ob die entsprechende Facette mehrere Werte erlaubt.

Die Facette language stellt einen Sonderfall dar, weil die Erweiterung einer Anfrage um den URL-Parameter ?language (statt ?facet.filter.language) ebenfalls die Filterung nach einer spezifischen Sprache ermöglicht.

3.12. Filter Queries

Beim Abfragen von Suchtreffern an einer Prepared Search kann die Abfrage um sogenannte Filter Queries erweitert werden. Solche Filter Queries dienen der Verringerung und somit Schärfung der Treffermenge, ohne die Reihenfolge der Treffer untereinander zu verändern. Mittels Filter Queries ist es möglich, Zeiträume, Werte oder Werteräume zu definieren, aus denen die Suchtreffer stammen. Filter Queries sind dabei auch auf Feldern anwendbar, die nicht in der Prepared Search zur Ausgabe als Facette ausgewählt wurden.

Diese Option garantiert keine Suchtreffer in diesem Bereich, wie es bei Facetten üblich ist.

In der Praxis ist dadurch eine Einschränkung der Suchtreffer möglich: beispielsweise auf die Anzeige max. eine Woche alter Ergebnisse oder auf Produkte, deren Preis 100€ nicht überschreitet.

Filter Queries sind in der SmartSearch über zwei Wege definierbar: Zum einen im Groovy-Skript der Prepared Search oder als Parameter am Request der SmartSearch-API. Die nachfolgenden Unterkapitel beschreiben diese Optionen.

3.12.1. Filter Queries mittels Groovy-Skript

Um im Groovy-Skript eine Filter Query zu setzen, muss diese der SolrQuery hinzugefügt werden. Dies erfolgt über die Methode addFilterQuery. Um beispielsweise nur News in den Suchtreffern zu haben, die nicht älter als eine Woche sind, muss der Aufruf im Groovy-Skript wie folgt aussehen:

Filter Query im Groovy-Skript hinzufügen

solrQuery.addFilterQuery("creation_date:[NOW-7DAY TO NOW]");

Es können mehrere Filter Queries hinzugefügt werden.

Die Verwendung von Filter Queries im Groovy-Skript ist sinnvoll, wenn der zu durchsuchende Wertebereich durch Suchende weder beeinflussbar sein soll noch darf. Soll der Wert der Filter Query dagegen flexibel sein, bietet sich die Verwendung eines Parameters an, der dem Request angehängt wird.

Filter queries können die von Solr unterstützten Schlüsselwörter für Zeiträume/-punkte/-spannen nutzen. Obiges Beispiel enthält z.B. (neben der Zeitspanne 7DAY) die Zeitpunkte NOW und NOW-7DAY , um den Zeitraum von vor einer Woche bis jetzt mit NOW-7DAY TO NOW zu beschreiben.

ACHTUNG: Zeitpunkte wie NOW werden IMMER in UTC ausgewertet.

3.12.2. FilterQueries mittels Parameter

Alternativ zur Verwendung im Groovy-Skript lassen sich Filter Queries dem Request als Parameter hinzufügen. Der Parameter heißt dabei fq. Um beispielsweise nur Produkte in den Suchtreffern vorzufinden, die nicht älter als eine Woche sind, muss der Request wie folgt aussehen:

API-Request mit Filter Query

curl -X GET -G 'https://mithras-search-api.e-spirit.cloud/v1/prepared_search/mithras/execute/' --data-urlencode "query=*&fq=_storage_date:[NOW-7DAY TO NOW]"

Der Parameter fq kann mehrfach übergeben werden.

Suchenden ist es möglich, Parameter zu beeinflussen. Aus diesem Grund ist ihre Verwendung in Verbindung mit sensiblen Daten nicht zu empfehlen. Stattdessen bieten sich Filter Queries im Groovy-Skript der Prepared Search an.

Bei der Nutzung von SmartSearch.js ist eine Übergabe der Filter Queries mittels Parameter wie folgt möglich:

Filter Query Nutzung bei SmartSearch.js

const fsss = new SmartSearch(host, preparedSearch)
fsss.setCustomParams({fq: "\"_storage_date:[NOW-7 to NOW]\""})

Zum besser Verständnis von Filtern, die auf Felder vom Typ _date angewendet werden, folgen einige Beispiele:

Alles im Jahr 2020: [2020-01-01T00:00:00Z TO 2020-12-31T23:59:59Z]
Alles von 2020 bis heute: [2020-01-01T00:00:00Z TO NOW]
Alles ab 2020 : [2020-01-01T00:00:00Z TO *]

Handelt es sich bei dem Feld, um ein Feld vom Typ _date_range, dann eine Filterung für bestimmte Jahre zb. so umgesetzt werden:

fq={!field f=dateRange op=Contains}[2013 TO 2018]

Detailliertere Informationen für die Verwendung von Filtern im Bezug auf Datumsfelder können der SOLR Dokumentation entnommen werden.

3.13. Tags

Wie im Kapitel Statistiken erläutert, stellt das SmartSearch-Cockpit die Möglichkeit bereit, Informationen über in beliebigen Zeiträumen getätigte Suchabfragen zu erhalten So kann die Statistik-Funktion zum Beispiel die meistgesuchten Begriffe für eine ausgewählte Prepared Search im letzten Monat, im letzten Jahr oder für andere Zeiträume anzeigen. Im Rahmen einer solchen Verwendung kann es für Nutzende relevant sein, diese Rangfolge der Suchabfragen nicht nur anhand von Zeiträumen oder Prepared Searches zu differenzieren, sondern auch nach im Rahmen der Implementierung frei definierten Kriterien.

Im folgenden Beispiel wird eine Prepared Search demo auf zweierlei Weise durch Suchabfragen genutzt:

Suchabfragen in der Suchmaske eines Web-Portals
Suchabfragen aus einer Smartphone-App

Um die in der SmartSearch erfassten Statistiken um die Information zu erweitern, ob eine Abfrage aus einem Portal oder einer App kommt, kann einer Suchabfrage der Parameter tag übergeben werden. Die Werte, die dieser Parameter annehmen darf, sind grundsätzlich frei wählbar. Im Rahmen dieses Beispiels sind sie je nach Quelle der Suchabfrage portal oder app:

Die folgenden Befehle zeigen jeweils einen CURL-Aufruf nach dem Begriff Presse gegen eine Prepared Search demo. Beide Aufrufe enthalten einen Authorization-Header und den Parameter tag, der entweder den Wert portal oder app besitzt.

CURL-Aufruf aus einem Portal

curl
-X GET 'https://localhost:8181/rest/api/v1/prepared_search/demo/execute?query=Presse&tag=portal'
-H 'Authorization: Basic YWRtaW5AbG9jYWxob3N0LmRlOmFkbWlu'

CURL-Aufruf aus einer App

curl
-X GET 'https://localhost:8181/rest/api/v1/prepared_search/demo/execute?query=Presse&tag=app'
-H 'Authorization: Basic YWRtaW5AbG9jYWxob3N0LmRlOmFkbWlu'

Nutzende können in diesem Beispiel nachfolgend für beliebige Zeiträume entsprechende Daten im Cockpit abfragen:

Die folgende Abbildung zeigt die Rangfolge der Suchanfragen aus dem Portal, die in diesem Fall auf nur einer Suchanfrage basiert. Die Tags-Klausel der Statistikseite ist an dieser Stelle mit dem Ausdruck `tags='portal'`gefüllt.

Abbildung 27. Rangfolge der Suchabfragen für den Tag-Wert portal

Die folgende Abbildung zeigt die Rangfolge der Suchanfragen aus der App, die ebenfalls auf nur einer Suchanfrage basiert. Die Tags-Klausel der Statistikseite ist mit dem Ausdruck `tags='app'`gefüllt.

Abbildung 28. Die Rangfolge der Suchabfragen für den Tag-Wert app

Die folgende Abbildung zeigt die Rangfolge der Suchabfragen über beide Parameter hinweg. Die Tags-Klausel enthält in diesem Fall die OR-Verknüpfung tags='portal' or tags='app'.

Abbildung 29. Die aufsummierte Rangfolge beider Tag-Werte

3.14. Gruppierung

Eine häufige Anforderung an eine Suchfunktion ist die Erzeugung zweier Ergebnislisten: zum Beispiel eine für Suchtreffer aus dem Produktbereich eines Portals und eine für den redaktionellen Bereich. Eine Möglichkeit dafür ist das Gruppieren von Suchergebnissen anhand von Schlüsselwörtern zu Dokumenten. Dafür müssen die Dokumenten-Schlüsselwörter einzeln in Felder eingetragen werden.

Im folgenden Beispiel werden die Dokumente anhand des category_token-Felds gruppiert.

Das Feld, anhand dessen die Gruppierung erfolgt, heißt in diesem Fall category_token. Es gilt damit als dynamisches Feld des Typs *_token. Dieser dynamische Feldtyp ermöglicht die Durchführung einer Gruppierung.

Ohne eine Gruppierung würde eine Suchanfrage die Dokumente aller Kategorien gemeinsam anzeigen. Das folgende Beispiel zeigt eine Suchanfrage nach dem in allen Titeln enthaltenen Begriff Beispiel gegen eine eine Prepared Search demo sowie die nicht gruppierte Antwort auf diese Anfrage.

Suchanfrage

https://localhost/rest/api/v1/prepared_search/demo/execute?query=Beispiel

Antwort mit nicht gruppierten Ergebnisse

{
   "numRows": 4,
   "results": [
      {
         "link": "https://www.e-spirit.com/de/page/01/",
         "id": "fcf8e686f9362a90ab1139549c4b4c0ad0721e3d0086d91e5a5fc8fedfef44f7",
         "title": [
            "Beispiel Seite 01"
         ],
         "category_token": "page"
      },
      {
         "link": "https://www.e-spirit.com/de/page/02/",
         "id": "8cfbca43a63fcf882f38f692508034ed3329b30a20de21e0374c8a0af2f59fd1",
         "title": [
            "Beispiel Seite 02"
         ],
         "category_token": "page"
      },
      {
         "link": "https://www.e-spirit.com/de/product/01/",
         "id": "e24f3487b79b146f3d91efb4a9cc1cab7d1ab728e2de035db9a40f4652d87df0",
         "title": [
            "Beispiel Produkt 01"
         ],
         "category_token": "product"
      },
      {
         "link": "https://www.e-spirit.com/de/product/02/",
         "id": "c5febe92fe119120e0d84093d06dda813956b5be22ee6d994867dd75a74f5f83",
         "title": [
            "Beispiel Produkt 02"
         ],
         "category_token": "product"
      }
   ],
   ...
}

Um nun eine Gruppierung auszulösen, ist es nötig an die entsprechende Prepared Search, in diesem Fall demo, die entsprechenden Parameter an der Solr-Query zu setzen.

Die Parameter haben folgende Funktionen:

group: Dieser Parameter aktiviert (true) oder deaktiviert (false, Standardwert) die Gruppierung. Er ist daher für die Nutzung der Funktion zwingend erforderlich und muss in diesem Fall auf true gesetzt sein.
group.field: Dieser Parameter definiert, anhand welchen Felds vom Typ _token die Gruppierung erfolgt. Im beschriebenen Fallbeispiel ist dies das Feld category_token.
group.limit: Dieser Parameter definiert die Anzahl der Ergebnisse, welche pro Gruppe in der Antwort enthalten sein sollen. Der Standardwert für diesen Parameter ist 1. In dem in diesem Kapitel enthaltenen Fallbeispiel besitzt der Parameter den Wert -1. Dies führt zur Rückgabe aller verfügbaren Dokumente der Gruppen.

Um die genannten Parameter zu setzen, ist das Groovy-Skript in der Konfigurationsoberfläche der entsprechenden Prepared Search anzupassen. Dabei ist darauf zu achten, dass die Methodensignatur bereits vorgegeben ist und somit lediglich der Methodenrumpf einzutragen ist.

Der folgende Code-Ausschnitt zeigt eine solche Konfiguration einer Prepared Search:

Konfiguration der Prepared Search

void apply(SolrQuery solrQuery, Map<String,List<String>> parameter) {
   solrQuery.set('group', true)
   solrQuery.set('group.field', 'category_token')
   solrQuery.set('group.limit', '-1')
}

Eine erneute Ausführung der zuvor genannten Suchanfrage gegen die Prepared Search demo liefert nun ein gruppiertes Ergebnis. Dieses unterscheidet sich von dem nicht gruppierten Ergebnis vor allem in folgenden Punkten:

Der Wert numRows, der die Anzahl der Gesamtergebnisse widerspiegelt, ist nun 0, da dieser für nicht gruppierte Ergebnisse vorgesehen ist.
Der Wert result enthält aus diesem Grund ebenfalls keine Ergebnisse mehr.
Stattdessen enthält der Wert groups die gruppierten Ergebnisse:
- Der Wert matches besagt wie viele Treffer insgesamt gruppiert wurden.
- Der Wert name enthält den Feldnamen category_token, anhand dessen die Gruppierung erfolgte.
- Für jede konkrete Ausprägung value des Felds category_token enthält der Wert groups eine Liste results. Diese entspricht allen Dokumenten der Gruppe und zeigt als Wert des Parameters numRows deren Anzahl an.

Antwort mit gruppierten Ergebnisse.

{
   "numRows": 0,
   "results": [],
   ...
   "groups": [
      {
         "matches": 4,
         "name": "category_token",
         "groups": [
            {
               "results": [
                  {
                     "link": "https://www.e-spirit.com/de/page/01/",
                     "id": "fcf8e686f9362a90ab1139549c4b4c0ad0721e3d0086d91e5a5fc8fedfef44f7",
                     "title": [
                        "Beispiel Seite 01"
                     ],
                     "category_token": "page"
                  },
                  {
                     "link": "https://www.e-spirit.com/de/page/02/",
                     "id": "8cfbca43a63fcf882f38f692508034ed3329b30a20de21e0374c8a0af2f59fd1",
                     "title": [
                        "Beispiel Seite 02"
                     ],
                     "category_token": "page"
                  }
               ],
               "value": "page",
               "numRows": 2
            },
            {
               "results": [
                  {
                     "link": "https://www.e-spirit.com/de/product/01/",
                     "id": "e24f3487b79b146f3d91efb4a9cc1cab7d1ab728e2de035db9a40f4652d87df0",
                     "title": [
                        "Beispiel Produkt 01"
                     ],
                     "category_token": "product"
                  },
                  {
                     "link": "https://www.e-spirit.com/de/product/02/",
                     "id": "c5febe92fe119120e0d84093d06dda813956b5be22ee6d994867dd75a74f5f83",
                     "title": [
                        "Beispiel Produkt 02"
                     ],
                     "category_token": "product"
                  }
               ],
               "value": "product",
               "numRows": 2
            }
         ]
      }
   ],
   ...
}

Im Rahmen dieses Beispiels sind die Produktseiten (Gruppe product) in der Abfrageantwort anhand des Dokumentenmerkmals category_token von den redaktionellen Seiten (Gruppe page) getrennt. Beide Gruppen sind somit zum Beispiel in der weiteren Verarbeitung als zwei separate Listen anzeigbar.

Auch die SmartSearch-JavaScript-Bibliothek smartsearch.js unterstützt Grouping. Details sind der SmartSearch.js-Dokumentation zu entnehmen.

3.15. Did you mean

Bei der Eingabe einer Suchanfrage können Tipp- oder Rechtschreibfehler auftreten. Um trotzdem eine erfolgreiche Suche zu ermöglichen, schlägt die SmartSearch alternative, ähnliche Suchbegriffe vor. Diese Vorschläge sind einem Array mit dem Schlüssel didYouMean gespeichert, das in den JSON-Daten der Antwort enthalten ist. Damit die SmartSearch automatische Alternativen anbietet, darf die Anzahl der Suchtreffer für einen Begriff den in der Prepared Search angegebenen Schwellwert nicht übersteigen.

Für die Vorschläge wird ausschließlich das content Feld herangezogen. Es muss daher sichergestellt werden, dass alle Inhalte, für die Alternativvorschläge verwendet werden sollen, in diesem Feld gespeichert sind.

Bei der Filterung nach einer Sprache über eine Sprachfacette stammen auch die Vorschläge nur aus dieser Sprache.

Das folgende Beispiel zeigt eine Suchanfrage inklusive eines Tippfehlers und eines didYouMean-Vorschlags:

Suchanfrage

{
   "numRows": 0,
   "results": [],

   ...

   "didYouMean": [
      "content"
   ],

   ...

   "requestParameters": {
      "query": [
         "cotnent"
      ]
   },

   ...
}

3.16. Beispiele für Groovy-Skript-Enhancer

Zur Anpassung von Dokumenten während einer Datengenerierung können Enhancer um Groovy-Skripte erweitert werden. Im folgenden Abschnitt sind exemplarisch einige solcher Skripte enthalten, um den Einstieg in die Entwicklung zu erleichtern.

Verhinderung der Indizierung

Soll ein Dokument im Rahmen der Generierung nicht in den Index übernommen werden, so kann dies durch die Definition des Boost-Werts 0 erreicht werden. Für Facettenwerte ist das durch eine entsprechende Facettenkonfiguration möglich.

Definition des Boost-Werts

document.setBoost(0)

Speicherung mehrerer Werte an einem Feld

Die Methode addData ermöglicht die Speicherung weiterer Werte an einem Feld. Dafür ist ihr der Feldname sowie der gewünschte Wert zu übergeben.

Methode addData

document.addData("Feldname", "erster Wert")
document.addData("Feldname", "zweiter Wert")

Ersetzung aller Werte eines Felds

Mithilfe der Methode setSingleValue lassen sich alle Werte eines Felds durch einen einzelnen neuen Wert ersetzen. Die Methode benötigt den Feldname sowie den neuen Wert.

Methode setSingleValue

document.setSingleValue("Feldname", "neuer Wert")

Entfernung aller Werte eines Felds

Für die ersatzlose Löschung aller Werte eines Felds stellt die SmartSearch die Methode removeData. Sie erwartet als Übergabeparameter lediglich den Feldnamen.

Methode removeData

document.removeData("Feldname")

Einordung eines Werts in eine Kategorie

Die Methode contains erlaubt die Überprüfung eines Felds an einem Dokument auf einen bestimmten Wert. Dadurch sind abhängige Bedingungen umsetzbar, die das Feld mithilfe der zuvor erwähnten setSingleValue-Methode in einer bestimmten Kategorie einordnen, wenn es spezifische Werte enthält. Auf diesem Weg sind die Werte des Felds auch in einer Facette verfügbar.

Abhängige Bedingung

if (document.getData("category").contains("Artikel")
    || document.getData("category").contains("Produkt")
    || document.getData("category").contains("News")) {

    document.setSingleValue("category_keyword", document.getData("category"))
}

3.17. Ortsbezogene Suche

Zusätzlich zu den üblichen Suchfunktionen, in denen Text gesucht wird, ermöglicht SmartSearch auch die ortsbezogene Suche. Auf diese Weise können Sie Dokumente anhand ihres Standorts suchen. Nachfolgend finden Sie Information über das Durchführen einer ortsbezogenen Suche mithilfe von SmartSearch.

3.17.1. Beispiel: Ortsbezogene Suche nach Städten

Die ortsbezogene Suche mit SmartSearch wird anhand von Dokumenten vorgestellt, in denen Städte mit dem Stadtnamen und den jeweiligen Geokoordinaten enthalten sind. Das Ziel ist, bei einer ortsbezogenen Suche alle Städte innerhalb einer bestimmten Entfernung von einem bestimmten Punkt zu identifizieren, bzw. nach dieser Entfernung zu sortieren.

Für dieses Beispiel werden in den Dokumenten die Geokoordinaten von drei zufällig ausgewählten Städten hinzugefügt: München, Dortmund und Paris. Der Groovy Script Enhancer wird verwendet, um jedem Dokument ein Feld namens "city_pnt" hinzuzufügen, das die Geokoordinaten der jeweiligen Stadt enthält.

Anschließend wird eine ortsbezogene Suche durchgeführt, um alle Städte zu finden, die sich im Radius von 100 km um Augsburg (ca. 60 km westlich von München) befinden, und eine weitere Suche, um nach der Entfernung zu dieser Stadt zu sortieren.

3.17.2. Feldanforderungen für die ortsbezogene Suche

Um eine ortsbezogene Suche durchzuführen, müssen die Dokumente ein Feld enthalten, welches mit "_pnt" im Feldnamen endet und die Breiten- und Längengradwerte in einem kommagetrennten Format beinhaltet.

Im Beispiel unten fügt ein Groovy Script Enhancer während der Indexierung ein solches Feld hinzu:

Random rnd = new Random()
def rndInt = rnd.nextInt(3)
def city = "munich"
def latLon = "48.137154,11.576124"
if(rndInt == 1) {
  city = "dortmund"
  latLon = "51.514244,7.468429"
} else if(rndInt == 2) {
  city = "paris"
  latLon = "48.864716,2.349014"
}
document.addData("city_keyword", city)
document.addData("city_pnt", latLon)

Im Beispiel unten wird * ein neues Feld mit dem Namen "city_pnt" erstellt, welches die Breiten- und Längengradwerte der jeweiligen Stadt enthält. * ein neues Feld namens "city_keyword" erstellt, um die Richtigkeit der Suchergebnisse zu prüfen.

3.17.3. Durchführen einer ortsbezogenen Suche

Fügen Sie einem Prepared Search ein Groovy Script hinzu, um eine ortsbezogene Suche durchzuführen. Die zwei Beispiele unten verwenden die bereits oben erwähnten Daten:

// geofilt example
{slr}Query.add("fq", "{!geofilt sfield=city_pnt}")
{slr}Query.add("pt", "48.366512,10.894446")
{slr}Query.add("d", "100")

// bbox example
{slr}Query.add("fq", "{!bbox sfield=city_pnt}")
{slr}Query.add("pt", "48.366512,10.894446")
{slr}Query.add("d", "100")

In beiden Beispielen gibt der Parameter "pt" den Punkt an, um welchen herum die Suche durchgeführt wird, während der Parameter "d" die Entfernung in Kilometern angibt.

Der Parameter "fq" im ersten Beispiel ist eine Filterabfrage, in welcher mithilfe der Funktion "geofilt" eine ortsbezogene Suche durchgeführt wird. Mit dem Parameter "sfield" wird das Feld angegeben, in dem die Werte für den Breiten- und Längengrad enthalten sind.

Der Parameter "fq" im zweiten Beispiel ist eine Filterabfrage, in welcher mithilfe der Funktion "bbox" eine ortsbezogene Suche durchgeführt wird. Der Parameter "sfield" funktioniert genauso, wie "geofilt" im ersten Beispiel.

3.17.4. Unterschiede zwischen "bbox" und "geofilt"

Der Hauptunterschied zwischen "bbox" und "geofilt" ist die Form des Suchbereichs: * Mit "geofilt" wird eine kreisförmige Suche um die angegebenen Koordinaten durchgeführt * Mit "bbox" wird die Suche in einem Rechteck-Bereich durchgeführt.

Die Wahl von "bbox" oder "geofilt" hängt von den genauen Anforderungen Ihres Systems ab. Bei den folgenden Aussagen handelt es sich um Verallgemeinerungen. Die tatsächliche Leistung und Genauigkeit der einzelnen Ansätze hängt von der Implementierung und den verwendeten Daten ab:

"geofilt" ist in der Regel schneller als "bbox" für kleine Suchgebiete, aber langsamer für größere Gebiete.
"bbox" kann bei unregelmäßig geformten Suchgebieten genauer sein als "geofilt", ist aber bei kreisförmigen Suchgebieten weniger genau.
"geofilt" ist normalerweise einfacher in der Anwendung als "bbox", weil für die Ausführung weniger Angaben erforderlich sind.

3.17.5. Sortieren nach Entfernung

Die Suchergebnisse können nach der Entfernung zu einem bestimmten Punkt sortiert werden. Das Groovy-Script-Beispiel unten führt eine ortsbezogene Suche aus und sortiert die Ergebnisse nach Entfernung:

solrQuery.add("fq", "{!geofilt}")
solrQuery.add("sfield", "city_pnt")
solrQuery.add("pt", "48.366512,10.894446")
solrQuery.add("d", "10000")
solrQuery.set("sort", "geodist() asc")

Im Beispiel oben wird mit dem Parameter "fq" eine Filterabfrage ausgeführt, in der die "geofilt"-Funktion verwendet wird, um eine ortsbezogene Suche durchzuführen. Der Parameter "sfield" gibt das Feld an, welches die Breiten- und Längengradwerte beinhaltet. Der Parameter "pt" gibt die Koordinaten an, um die herum die Suche durchgeführt wird, und der Parameter "d" gibt die Entfernung in Kilometern an. Der Parameter "sort" gibt die Sortierreihenfolge an. Hier wird die Funktion "geodist" verwendet, um die Ergebnisse aufsteigend nach Entfernung zu sortieren.

Die Sortierung nach Entfernung ist im Fall von großen Datensätzen teuer. Es wird deshalb empfohlen, sie nur bei einem Mehrwert für die Leistung einzusetzen.

3.17.6. Schlussfolgerung

Die obigen Beispiele zeigen nur einen Auszug der Möglichkeiten einer ortsbezogenen Suche mit SmartSearch. Abhängig von den spezifischen Anforderungen Ihres Systems können auch etliche andere Ansätze und Techniken zum Einsatz kommen. Weitere Informationen zur ortsbezogenen Suche mit Solr finden Sie in der Solr-Dokumentation unter https://solr.apache.org/guide/8_6/spatial-search.html.

4. Logging

Für eine ausführliche Diagnose des SmartSearch-Servers kann es notwendig sein das Logging anzupassen. Im folgenden Kapitel werden verschiedene Vorgehen genauer beschrieben.

In der Standardkonfiguration des SmartSearch-Servers liegt im root Ordner eine lockback-spring.xml. Um Details über den Aufbau der lockback-spring.xml zu erfahren empfielt es sich die Dokumentation dazu bei Spring zu lesen. Änderungen an der lockback-spring.xml behalten auch nach einem Neustart des SmartSearch-Serves ihre Gültigkeit.

Für eine kurzfristige Anpassung der Log-Level, die nach einem Neustart des Servers wieder verworfen werden, gibt es einen API-Endpunkt. In dem unten stehenden Beispiel würde das Log-Level für die Klasse ApiCrawler auf DEBUG gesetzt.

Beispiel für die Anpassung des Log Levels via API-Endpunkt.

curl -X POST 'https://mithras-search.e-spirit.cloud/actuator/loggers/de.arithnea.haupia.datageneration.crawler.api.reactive.ApiCrawler'
--header 'Authorization: Basic YWRdsgdfg8wxob3N0LmRlOmFkbWlu' \
--header 'Content-Type: application/json'
--data-raw '{
  "configuredLevel": "DEBUG"
}'

Neben einzelnen Klassen können auch die Log-Level aller Klassen eines Packages gesetzt werden. Um das Log-Level einer Klasse zu erfahren kann der entsprechende API-Endpunkt mittels GET abgefragt werden. Eine GET Abfrage gegen …/actuator/loggers liefert alle Klassen mit den entsprechenden Log-Level. Auf diesem Wege ist zudem möglich die Pfade der benötigten Packages und Klassen herauszufinden.

Bei der Abfrage der Log-Level werden die Level entweder als configuredLevel oder effectiveLevel zurückgegeben. configuredLevel ist dabei ein explizit gesetztes Level für diese Klasse. effectiveLevel ist ein geerbtes Level durch ein übergeordnetes Element.

SmartSearch verwendet Simple Logging Facade for Java (SLF4J) als Logging Framework.

5. DSGVO

Die Datenschutzgrundverordnung (DSGVO) ist eine EU-Verordnung, die das Grundrecht europäischer Bürger auf Privatsphäre schützt und den Umgang mit personenbezogenen Daten regelt. Vereinfacht gesagt, haben alle Personen, von denen Daten erhoben werden, über die DSGVO unter anderem die folgenden Möglichkeiten:

zu erfahren, welche personenbezogenen Daten von ihnen gespeichert und wie diese verarbeitet werden (Informationspflicht und Auskunftsrecht),
die Datenerhebung einzuschränken (Recht auf Einschränkung der Verarbeitung),
die erhobenen Daten zu beeinflussen (Recht auf Berichtigung) und
die erhobenen Daten zu löschen (Recht auf Vergessen).

Was sind personenbezogene Daten?

Personenbezogene Daten sind alle Informationen, durch die eine natürliche Person direkt oder indirekt identifizierbar ist. Dies schließt jegliche potenziellen Identifizierungsmerkmale ein:

direkte Identifizierungsmerkmale, wie etwa
- Namen
- E-Mail-Adressen
- Telefonnummern
indirekte Identifizierungsmerkmale, wie
- Standortdaten
- Kundennummern
- Personalnummern
Online-Identifizierungsmerkmale, wie zum Beispiel
- IP-Adressen
- Cookies
- Tracking Pixel

Ausführliche Informationen zur DSGVO finden sich im Blogpost DSGVO - Alles Wichtige auf einen Blick.

5.1. DSGVO und die SmartSearch

Die Such-Engine SmartSearch speichert Daten als Dokumente, die auf verschiedenen Plattformen zur Verfügung gestellt werden können. Art und Umfang der Daten, im Folgenden "erfasste Daten" genannt, sind abhängig vom Einsatzzweck des Produkts.

Der Hersteller Crownpeak Technology GmbH weist ausdrücklich darauf hin, dass es in der Verantwortung des Kundenunternehmens liegt, erfasste Daten daraufhin zu prüfen, ob sie personenbezogene Daten enthalten und entsprechende Maßnahmen sicherzustellen.

Neben den redaktionellen Daten speichert die SmartSearch personenbezogene Daten (grundsätzlich die E-Mail, bei Verwendung von LDAP den Username), die zur Anmeldung an dem System und beim Auditieren von Konfigurationen verwendet werden, um gegebenenfalls Kontakt mit der Person aufnehmen zu können, welche ein Element bearbeitet hat. Teile dieser Daten werden in Logdateien vorgehalten. Diese Daten werden im Folgenden „Personenbezogene Systemdaten“ genannt (siehe unten).

5.2. Personenbezogene Systemdaten in der SmartSearch

Die Crownpeak Technology GmbH nimmt den Schutz und die Sicherheit Ihrer Daten sehr ernst. Selbstverständlich halten wir uns an die gesetzlichen Datenschutzbestimmungen und behandeln personenbezogene Daten aber auch nicht-personenbezogene Daten unserer User mit entsprechender Sorgfalt. Wir erheben personenbezogene Daten nur dann, wenn sie für die Sicherheit und die Funktionsfähigkeit der SmartSearch notwendig sind.

Die nachfolgenden Unterkapitel informieren über die Erhebung von und den Umgang mit personenbezogenen Daten in der SmartSearch.

5.2.1. Daten zur User-Autorisierung und -Authentifizierung in der SmartSearch

Die SmartSearch arbeitet mit einem durchgängigen User- und Rechtesystem. Neue User werden über das Usermanagement angelegt und verwaltet. Nach der Erstellung sind User auf dem Server bekannt und können sich (mit einem gültigen Login) über das SmartSearch-Cockpit anmelden. Der Zugriff auf die Konfigurationselemente wird über Gruppenrechte/Rollen erteilt.

Warum werden die Daten benötigt?

Durch die Autorisierung und Authentifizierung ist sichergestellt, dass nur authentifizierte User Zugriff auf die SmartSearch erhalten und diese User Elemente nur gemäß der ihnen erteilten Rechte bearbeiten dürfen. Diese Daten sind für die Sicherheit der Informationen also zwingend erforderlich.

Wo werden die Daten verwendet beziehungsweise angezeigt?

User-Informationen werden an diversen Stellen angezeigt, zum Beispiel:

bei der Anmeldung am Cockpit
bei der Vergabe von Gruppenrechten
beim Ändern eines Objektes über die Auditierung
u. v. m.

Wo werden die Daten gespeichert?

User-Anmeldeinformationen werden grundsätzlich in der Konfigurationskomponente gespeichert. Im Falle von LDAP werden die personenbezogenen Systemdaten nur lesend aus dem LDAP des Kundenunternehmens geladen.

Wie lange werden die Daten gespeichert?

Bei der Entfernung von Usern über das Usermanagement werden die User-Anmeldeinformationen sofort aus der Konfigurationskomponente entfernt.

Die User-Deaktivierung im Usermanagement führt nicht zum Löschen der User-Daten.

5.2.2. Daten für die Fehleranalyse und Fehlerbehebung in der SmartSearch (Protokollierung)

Die SmartSearch verwendet Logfiles, um Aktionen und Ereignisse auf dem SmartSearch-Server zu protokollieren. Logfiles werden zur Aufrechterhaltung des sicheren Betriebs erhoben. Sie können verwendet werden, um Fehlerzustände zu analysieren und zu beheben.

Warum werden die Daten benötigt?: Einige der von der SmartSearch verwendeten Logfiles enthalten unter anderem IP-Adressen, Login-Namen, Datumsangaben, Uhrzeiten, Requests usw. und damit personenbezogene Daten.
Wo werden die Daten gespeichert?: Grundsätzlich werden Logfiles in das Unterverzeichnis logs des SmartSearch-Servers geschrieben.
Wie lange werden die Daten gespeichert?: Standardverhalten: Wird eine fest eingestellte Dateigröße von 100 MB erreicht, wird die aktuelle Logdatei archiviert. Es werden bis zu neun archivierte Dateien behalten. Wenn dann eine neue Datei archiviert wird, wird die älteste gelöscht. Dieses Verhalten kann über die Konfigurationsdatei logback-spring.xml angepasst werden.

5.2.3. Daten für die Auditierung von Konfigurationselementen

Bei jeder Änderung, die an Konfigurationselementen (zum Beispiel einer Prepared Search) vorgenommen werden, wird daran vermerkt, wer die letzte Änderung vorgenommen hat und wann. Damit wird eine eventuell bestehende letzte Änderung überschrieben.

Wird ein Konfigurationselement neu angelegt, wird daran vermerkt, wer das Element angelegt hat und wann.

Warum werden die Daten benötigt?: Eine Zielsetzung der Datenspeicherung in der SmartSearch ist die Nachvollziehbarkeit der letzten Änderungen, aber auch Informationen über die Erstellung von Konfigurationselementen. Dazu speichert die SmartSearch Auditierungsdaten.
Wo werden die Daten verwendet beziehungsweise angezeigt?: Die Auditierungsdaten (Wer hat eine Änderung durchgeführt und wann?) werden in Listenansichten für die Konfigurationselemente angezeigt.
Wo werden die Daten gespeichert?: Die Daten werden an den Konfigurationselementen in der Konfigurationkomponente gespeichert.
Wie lange werden die Daten gespeichert?: Standardverhalten: Bei der User-Löschung werden die zugehörigen Referenzen anonymisiert. Es ist zudem möglich, nachträglich Referenzen von bereits gelöschten Usern zu anonymisieren, für den Fall, dass bei der Löschung nicht das Standardverhalten angewandt wurde. Nach der Anonymisierung wird ein Bericht angezeigt, in welchen Elementen die Referenz anonymisiert wurde. Es werden dazu keine Informationen geloggt. Der Bericht ist die einzige Möglichkeit, Informationen über die Anonymisierung zu bekommen.

5.2.4. Verwendung von Cookies im Cockpit

Cookies sind Information, die im Browser des Betrachtenden zu einer besuchten Website gespeichert werden können.

Warum werden die Daten benötigt?: Die SmartSearch verwendet im Cockpit Cookies, um die Session zu speichern und zum Schutz vor XSRF-Attacken.
Wo werden die Daten verwendet bzw. angezeigt?: Die Cookies werden im Browser gespeichert und ab dem Einloggen mit jeder Interaktion mit dem Cockpit mitgeschickt.
Wie lange werden die Daten gespeichert?: Die Lebenszeit der Cookies wird auf session gesetzt.

6. Rechtliche Hinweise

Die SmartSearch ist ein Produkt der Crownpeak Technology GmbH, Dortmund, Germany.
Für die Verwendung des Produkts gilt nur die mit der Crownpeak Technology GmbH vereinbarte Lizenz.

7. Hilfe

Der Technical Support der Crownpeak Technology GmbH bietet qualifizierte technische Unterstützung zu allen Themen, die FirstSpirit™ als Produkt betreffen. Weitere Hilfe zu vielen relevanten Themen erhalten und finden Sie in auch in unserer Community.