vdc_search

vdc_search Einrichtung

Diese Readme erklärt, wie Sie die auf der elastischen Suche basierende Suchfunktionalität einrichten, warten und nutzen.

Die Erweiterung funktioniert mit der elasticsearch Version 2.x

Der Worttyp in dieser Readme ist immer der Dokumententyp der elastischen Suche.

1 Allgemeines

Diese Erweiterung besteht aus 3 verschiedenen Bereichen:

• cli-Befehl
• index-Phase
• suchphase

Die cli-Befehle werden zur Verwaltung des Suchindex verwendet. Während der Indexphase werden konfigurierbare Dokumente analysiert und in den elasticseach index geschrieben. Schließlich akzeptiert die Suchphase eine Suchanfrage, findet die passenden Dokumente und gibt die Suchergebnisse zurück.

2 Konfiguration

Die Konfiguration erfolgt hauptsächlich in den Erweiterungen ext_localconf.php, mit Ausnahme der allgemeinen elastischen Suche - dies muss in der .env-Datei mit den folgenden Variablen konfiguriert werden:

TYPO3__EXTCONF__vdc_search__elastische Suche__index
TYPO3__EXTCONF__vdc_search__elastische Suche__Server__A__Host
TYPO3__EXTCONF__vdc_search__elastische Suche__Server__A_port
TYPO3__EXTCONF__vdc_search__elastische Suche__Einstellungen__Anzahl_der_Splitter
TYPO3__EXTCONF__vdc_search__elastische Suche__Einstellungen__Anzahl_der_Repliken

Die Konfiguration der Erweiterung in ext_localconf.php erfolgt im Array:

$GLOBALS['TYPO3_CONF_VARS']['EXTCONF']['vdc_search']['config']]

Dieses Array enthält mehrere Strukturen. Im Detail sind die Strukturen:

2.1 Standardwerte

Diese Struktur enthält die Standardsuchparameter, die verwendet werden, wenn die Suchanfrage nur aus einigen (nicht allen) Werten besteht.

2.2 Doktypen

In dieser Sektion werden die Doktype-Mappings für Finder definiert.

2.3 Highlights

Diese Konfiguration kann verwendet werden, um den Suchmarker einzurichten.

2.4 Raupenfahrwerke

Die Crawler-Struktur ist ein Array, das alle Crawler enthält, die während der Indexphase verwendet werden sollen.

Um jede Art von Datenstruktur zu indizieren, muss ein Eintrag in diesem Array vorhanden sein.

Mit dieser Array-Struktur wird ein Crawler definiert:

news' => (Objekt) [
    className' => \Vdc\VdcSearch\Crawler\Type\Type\News::class,
    'enabled' => true,
]

Dabei ist der Schlüssel ein eindeutiger Name und der Klassenname zeigt auf eine Klasse, die einen Crawler repräsentiert. Diese Klasse muss das Vdc\VdcSearch\Crawler\Crawler\CrawlerInterface implementieren.

Es ist am besten, von Vdc\VdcSearch\Crawler\AbstractCrawler zu erweitern, da dies die Schnittstelle implementiert und einige Komfortmethoden hat, die häufig bei Crawlern verwendet werden

Das enabled Flag kann verwendet werden, um einen Crawler zu aktivieren/deaktivieren.

2.5 Finder

Ein Findereintrag ist vergleichbar mit einem Crawler-Eintrag. Während der Suchphase werden Finder verwendet.

Der einzige obligatorische Schlüssel ist der Klassenname, der auf eine Klasse zeigt, die die Vdc\VdcSearch\Search\Search\Search\SearchInterface implementiert. Es ist am besten, von Vdc\VdcSearch\Search\Search\AbstractSearch zu erweitern, da es die genannte Schnittstelle implementiert. Darüber hinaus hat AbstractSearch einige Hilfsmethoden für Finder.

Eine Finderkonfiguration kann die folgenden zusätzlichen Schlüssel haben:

2.5.1 Blacklist

Ein Array, das aus den Feldern besteht, die im Suchergebnis nicht zurückgegeben werden dürfen.

2.5.2 Verstärkung

Schlüssel-Wert-Paare, die eine Verstärkung pro Feld definieren.

Felder, die nicht in dieser Liste enthalten sind, erhalten eine Standardanhebung von 1.

Felder in dieser Liste werden bei der Volltextsuche verwendet.

Wenn ein Feld markiert werden muss ([siehe Kapitel 2.5.3 Highlight](#2.5.3 Highlight)), muss es ebenfalls in die Boost-Liste aufgenommen werden.

2.5.3 Hervorhebung

Um die Such-Highlighting-Funktion der elastischen Suche zu nutzen, können Sie die zu markierenden Felder definieren.

news' => (Objekt) [
    className' => \Vdc\VdcSearch\Search\Search\Type\News::class,
    Blacklist' => [ [
        "uid",
        "Bodytext",
    ],
    boost' => [ [
        Titel' => 3,
        bodytext' => 2,
        "tx_flexiblenews_teaser" => 1,
        "tx_vdcnews_type" => 1,
    ],
    highlight' => [ [
        title' => (object) [],
        tx_flexiblenews_teaser' => (Objekt) [],
        tx_vdcnews_type' => (Objekt) [],
    ],
]

2.6 Filter, Analysator, Tokenizer, Tokenizer

In diesen Konfigurationselementen können die verfügbaren elastischen Suchfilter/Analysatoren/Tokenizer definiert werden.

Die Syntax ist eine 1:1-Konvertierung von der elasticsearch JSON-Konfiguration in ein PHP-Array.

Diese Konfigurationen werden in der getMapping-Methode der Crawler referenziert.

siehe auch https://www.elastic.co/guide/en/elasticsearch/guide/current/custom-analyzers.html

3 Hinzufügen neuer Dokumenttypen

Um eine neue Dokumentart anzulegen, müssen Sie einen Crawler und einen Finder implementieren und fügen Sie es der Konfiguration hinzu ([siehe Kapitel 2.4 Crawler](#2.4 Crawler) und[siehe Kapitel 2.5 Finder](#2.5 Finder)).

3.1 einen Crawler implementieren

Ein Crawler muss die folgenden Methoden implementieren:

öffentliche Funktion hasType(): bool;
public function getType(): string;
öffentliche Funktion getMapping(): array;
public function crawl(): array;

Die Crawler-Klasse muss sich im Namensraum Vdc\VdcSearch\Crawler\Type befinden

Wenn Sie von Vdc\VdcSearch\Crawler\AbstractCrawler ausgehen, müssen Sie den geschützten $type = "Events" setzen; mit einem Wert, der Ihrem Typ entspricht.

3.1.1 hasType

Muss zurückkehren, wenn der Crawler einen Typensatz hat.

Wenn Sie von Vdc\VdcSearch\Crawler\AbstractCrawler\AbstractCrawler ausgehen, müssen Sie diese Methode nicht implementieren.

3.1.2 getType

Muss die Dokumentart zurückgeben.

Wenn Sie von Vdc\VdcSearch\Crawler\AbstractCrawler\AbstractCrawler ausgehen, müssen Sie diese Methode nicht implementieren.

3.1.3 getMapping

Muss das Mapping für elasticsearch indexer zurückgeben.

Diese Methode muss ein Array zurückgeben, das das elasticsearch mapping enthält. Die Syntax ist eine 1:1-Konvertierung von der elasticsearch JSON-Konfiguration in ein PHP-Array.

Siehe https://www.elastic.co/guide/en/elasticsearch/guide/current/mapping-intro.html

3.1.4 kriechen

Muss die zu indizierenden Dokumente zurückgeben.

Diese Methode muss ein Array mit der folgenden Struktur zurückgeben:

[documentId] = [ [
    taste1 => Wert1,
    taste2 => Wert2,
    ...
]

wobei documentId zur elasticsearch document id wird und die Anordnung der Schlüssel/Wertpaare das zu indexierende Dokument darstellt

3.2 einen Finder implementieren

Ein Finder muss die folgenden Methoden implementieren:

öffentliche Funktion hasType(): bool;
public function getType(): string;
öffentliche Funktion getQuery(\stdClass $query): array;
öffentliche Funktion getFieldBlacklist(): array;
öffentliche Funktion processResultSet(array $resultSet): \stdClass;
öffentliche Funktion getFilter(\stdClass $search): array;
öffentliche Funktion getHighlight(): array;

Die Crawler-Klasse muss sich im Namensraum Vdc\VdcSearch\Search\Search\Type befinden

Wenn Sie von Vdc\VdcSearch\Crawler\AbstractSearch ausgehen, müssen Sie geschützten $type = "Events" setzen; mit einem Wert, der Ihrem Typ entspricht.

3.2.1 hasType

Muss zurückkehren, wenn der Finder eine Dokumentart hat.

Wenn Sie von Vdc\VdcSearch\Crawler\AbstractSearch ausgehen, müssen Sie diese Methode nicht implementieren.

3.2.2 getType

Muss die Dokumentart zurückgeben.

Wenn Sie von Vdc\VdcSearch\Crawler\AbstractSearch ausgehen, müssen Sie diese Methode nicht implementieren.

3.2.3 getQuery

Muss die Abfrage nach elasticsearch zurückgeben.

Wenn Sie von Vdc\VdcSearch\Crawler\AbstractSearch ausgehen, müssen Sie diese Methode nicht implementieren.

3.2.4 getFieldBlacklist

Muss ein Array von Feldnamen zurückgeben, die bei der Abfrage nicht zurückgegeben werden dürfen

Wenn Sie von Vdc\VdcSearch\Crawler\AbstractSearch ausgehen, müssen Sie diese Methode nicht implementieren. Die Daten werden aus der Finderkonfiguration abgerufen ([siehe Kapitel 2.5.1 Blacklist](#2.5.1 Blacklist))

3.2.5 ProzessErgebnisSatz

Muss ein Objekt mit Eigenschaften zurückgeben:

• treffer: Anzahl der gefundenen Dokumente
• dokumente: gefundene Dokumente

Wenn Sie von Vdc\VdcSearch\Crawler\AbstractSearch ausgehen, müssen Sie diese Methode nicht implementieren.

3.2.6 getFilter

Muss die Filter zurückgeben, die bei einer Abfrage verwendet werden sollen.

Auch wenn Sie von Vdc\VdcSearch\Crawler\AbstractSearch ausgehen, müssen Sie diese Methode implementieren.

Dieses Verfahren muss ein Array zurückgeben, das den elastischen Suchfilter definiert, der bei der Abfrage des Index verwendet werden soll.

Die Syntax ist eine 1:1-Konvertierung von der elasticsearch JSON-Konfiguration in ein PHP-Array.

Siehe https://www.elastic.co/guide/en/elasticsearch/guide/current/combining-filters.html

3.2.7 getHighlight

Muss die Markierungsfelder zurückgeben, die bei einer Abfrage verwendet werden sollen

Wenn Sie von Vdc\VdcSearch\Crawler\AbstractSearch ausgehen, müssen Sie diese Methode nicht implementieren. Die Daten werden aus der Sucherkonfiguration abgerufen ([siehe Kapitel 2.5.3 Highlight](#2.5.3 Highlight))

4 Client-Befehle

Die Erweiterung bietet einen komfortablen Befehl für die Verwendung mit der typo3cms Client-Konsole:

• suche:deleteindex
• search:indexall
• suche:rebuildall
• search:setupindex

4.1 Suche:deleteindex

Löscht den Index und alle darin abgelegten Dokumente.

4.2 Suche:setupindex

Erstellt und initialisiert die Mappings und Einstellungen des elasticsearch index.

4.3 Suchen:indexall

Schleifen über alle aktivierten Crawler, die in der Erweiterung konfiguriert sind.

Für jeden Crawler wird die Crawl-Methode aufgerufen und die zurückgegebenen Dokumente werden in den elasticsearch index geschrieben.

4.4 suchen:rebuildall

Dies ist ein Wrapper-Aufruf an:

• löschen
• erstellen
• indexall

5 Suchen nach Dokumenten

Die Suche nach Dokumenten erfolgt über einen HTTP POST-Aufruf an /index.php?type=1488360328 Um den Master zu verwenden, müssen Sie einen Proxy zu Ihrer nginx-Konfiguration hinzufügen:

standort /Suche/ { {
    proxy_pass http://master.vdc-fellbach.de.dev0.itplusx.de/index.php?type=1488360328;
}

Der POST-Body muss eine JSON-Zeichenkette haben, die wie folgt aussieht:

5.1 minimaler Suchbegriff

{
    " Typ": " Neuigkeiten"
}

Es muss nur die Dokumentart definiert werden (dies ist obligatorisch). Das Ergebnis ist eine Liste aller Dokumente im Index, die dem angegebenen Typ entsprechen.

5.2 maximale Suchbegriffe

{
    " Typ": " Neuigkeiten",
    " Abfrage": " Palette",
    " Größe": 10,
    "von": 0,
    " Lang": "de",
    " Sortieren": {
        " Verabredung": "Abstieg",
        " Titel": " Aufstieg"
    },
    "Filter": {
        " Typen": [1,2],
        " Kategorien": [
            [52, 26],
            [163, 132]
        ],
        "von": "07.12.17",
        "Bis": "08.12.17"
    }
}

Ein vollständiger Suchbegriff besteht aus mehreren Teilen, die in den folgenden Kapiteln erläutert werden.

5.2.1 Abfrage

Dieser Parameter kann einen Suchbegriff für die Volltextsuche enthalten.

Die zu durchsuchenden Felder werden in der Einstellung Finder / Boost konfiguriert ([siehe Kapitel 2.5.2 Boost](#2.5.2 Boost)))

5.2.2 Größe

Mit dem Größenparameter können Sie die maximale Anzahl der Treffer konfigurieren, die zurückgegeben werden sollen.

5.2,3 von

Der Parameter from definiert den Offset vom ersten Ergebnis, das Sie holen möchten.

5.2.4 lang

noch nicht implementiert

Der Parameter lang legt die Sprache für die zu durchsuchenden Dokumente fest.

5.2.5 Sortierung

Sort ist eine Liste von Schlüssel/Wertpaaren, die die Sortierung des Suchergebnisses definieren.

Der erste Parameter ist das zu sortierende Feld, der zweite ist die Sortierrichtung.

5.2.6 filter

Die Filterstruktur kann zum Filtern des Suchergebnisses verwendet werden.

Zur Zeit können folgende Felder gefiltert werden

• typen
• kategorien
• datumsbereich (nur für Ereignisse)

5.2.6.1 typen

Der Typ-Filter ist ein Array von Typ-IDs.

Es werden nur die Dokumente zurückgegeben, die einem der definierten Typen entsprechen.

5.2.6.2 Kategorien

Der Kategorienfilter ist ein Array von Arrays mit der folgenden Logik.

Die im inneren Array definierten Werte werden durch ein logisches ODER verknüpft, dann werden diese durch ein logisches UND verknüpft.

Werfen Sie einen Blick auf dieses Beispiel:

" Kategorien": [
    [52, 26],
    [163, 132]
]

Dies führt zu Dokumenten mit Kategorie-ID:

(52 ODER 26) UND (163 ODER 132)

5.2.6.3 Datumsbereich

Der Datumsbereichsfilter ist derzeit nur für den Typ "Events" implementiert.

Es besteht aus zwei Zeichenkettenfeldern "von" und "bis", die jeweils ein Datum im Format d.m.y halten

Es muss mindestens einer der Datumsbereichsfilter gesetzt sein.

Die Suche liefert Dokumente, die jünger als das Feld "von" und / oder älter als das Feld "bis" sind.

5.3 Ergebnisdatenstruktur

Die Suche gibt einen JSON-String zurück, der aus zwei Teilen besteht:

• meta
• ergebnisse

5.3.1 meta

Die Metadaten zeigen zusätzliche Informationen zum Suchergebnis:

• typ: der bei der Suche verwendete Typ
• query: die Abfragestruktur
• lang: die Sprache
• treffer: Gesamtzahl der gefundenen Dokumente
• anzeige: Anzahl der zurückgegebenen Dokumente
• mehr: Flag, das anzeigt, dass mehr Dokumente abgerufen werden können
• größe: Anzahl der zurückzugebenden Dokumente
• von: Paging-Start
• sortierung: Sortierung angewendet

5.3.2 ergebnisse

Die Ergebnisse enthalten die resultierenden Dokumente aus der letzten Suche.