Übersicht
Der CSV-Konnektor bietet die Funktionalität, Daten aus CSV-Dateien abzurufen und im Fess-Index zu registrieren.
Für diese Funktion ist das Plugin fess-ds-csv erforderlich.
Voraussetzungen
Die Installation des Plugins ist erforderlich
Zugriff auf die CSV-Datei ist erforderlich
Die Zeichenkodierung der CSV-Datei muss bekannt sein
Plugin-Installation
Methode 1: JAR-Datei direkt platzieren
Methode 2: Über die Administrationsoberfläche installieren
Öffnen Sie „System“ -> „Plugins“
Laden Sie die JAR-Datei hoch
Starten Sie Fess neu
Konfiguration
Konfigurieren Sie über die Administrationsoberfläche unter „Crawler“ -> „Datenspeicher“ -> „Neu erstellen“.
Grundeinstellungen
| Einstellung | Beispielwert |
|---|---|
| Name | Products CSV |
| Handler-Name | CsvDataStore |
| Aktiviert | Ein |
Parameter-Einstellungen
Lokale Datei:
Mehrere Dateien:
Bemerkung
Die Anführungszeichen- (Quote-) Verarbeitung und die Escape-Verarbeitung sind in Fess 15.9 standardmäßig aktiviert. CSV-Dateien (RFC 4180-konform), bei denen Felder in Anführungszeichen eingeschlossen sind und Trennzeichen oder Zeilenumbrüche enthalten, werden ohne zusätzliche Parameter korrekt verarbeitet. Wie Sie zum bisherigen Verhalten (Anführungszeichenverarbeitung deaktivieren) zurückkehren und was dabei zu beachten ist, erfahren Sie im Abschnitt „Deaktivierung der Anführungszeichen- und Escape-Verarbeitung“ weiter unten.
Parameterliste
| Parameter | Erforderlich | Beschreibung |
|---|---|---|
files | Nein | Pfad zur CSV-Datei (lokaler Pfad, mehrere kommagetrennt möglich). Entweder files oder directories muss angegeben werden. Werden beide angegeben, hat files Vorrang. Die angegebenen Dateien müssen die Endung .csv oder .tsv haben; Dateien mit anderen Endungen werden übersprungen. |
directories | Nein | Pfad zu Verzeichnissen, die CSV-Dateien enthalten (mehrere kommagetrennt möglich). Es werden nur .csv- und .tsv-Dateien im Verzeichnis verarbeitet. Wird verwendet, wenn files nicht angegeben ist. |
file_encoding | Nein | Zeichenkodierung (Standard: UTF-8) |
has_header_line | Nein | Vorhandensein einer Kopfzeile (Standard: false) |
separator_character | Nein | Trennzeichen (Standard: Komma ,). Escape-Sequenzen wie \t können angegeben werden (für Tab-Trennung). |
quote_character | Nein | Anführungszeichen (Standard: doppeltes Anführungszeichen "). Die Anführungszeichenverarbeitung ist standardmäßig aktiviert (siehe quote_disabled). |
escape_character | Nein | Escape-Zeichen (Standard: dasselbe Zeichen wie quote_character; gemäß RFC 4180 werden Anführungszeichen durch Verdopplung escaped). Ob die Escape-Verarbeitung aktiv ist, richtet sich nach dem aufgelösten Wert von quote_disabled (siehe escape_disabled). |
Bemerkung
Wenn sowohl files als auch directories leer sind, tritt ein Fehler (DataStoreException) auf. Geben Sie mindestens einen der beiden Parameter an.
Erweiterte Parameter
Die folgenden Parameter steuern das CSV-Parsing-Verhalten sowie das Indexierungsverhalten im Detail:
| Parameter | Beschreibung |
|---|---|
quote_disabled | Gibt an, ob die Anführungszeichenverarbeitung deaktiviert ist (Standard: false). RFC 4180-konforme Felder mit Anführungszeichen werden standardmäßig korrekt verarbeitet. Geben Sie true an, um zum bisherigen Verhalten (Anführungszeichen als normale Zeichen) zurückzukehren. |
escape_disabled | Gibt an, ob die Escape-Verarbeitung deaktiviert ist (Standard: identisch mit dem aufgelösten Wert von quote_disabled). Ein explizit angegebener Wert hat Vorrang. |
delete_old_docs | Gibt an, ob nach Abschluss des Crawlings Dokumente gelöscht werden, die zu dieser Datenspeicher-Konfiguration gehören und in der aktuellen Crawling-Sitzung nicht erneut registriert wurden (Standard: true). Wenn Sie mehrere CSV-Dateien zu unterschiedlichen Zeitpunkten in dieselbe Datenspeicher-Konfiguration einspeisen, geben Sie false an – sonst werden die zuvor eingespeisten Dokumente gelöscht (Details siehe Abschnitt zur Fehlerbehebung weiter unten). |
keep_expires_docs | Gibt an, ob beim Löschen über delete_old_docs Dokumente ausgenommen werden, deren Ablaufzeitpunkt („expires“, z. B. über time_to_live gesetzt) noch nicht erreicht ist (Standard: true). Bei false werden nicht erneut registrierte Dokumente auch innerhalb ihrer Ablaufzeit gelöscht. |
time_to_live | Nach wie vielen Minuten ab dem Registrierungszeitpunkt der Ablaufzeitpunkt eines Dokuments gesetzt wird (in Minuten; Standard: nicht gesetzt, d. h. unbegrenzt). |
skip_lines | Anzahl der zu überspringenden Kopfzeilen (Standard: 0) |
ignore_line_patterns | Reguläres Ausdrucksmuster für zu ignorierende Zeilen (z. B. ^#.* zum Ignorieren von Kommentarzeilen) |
ignore_empty_lines | Gibt an, ob leere Zeilen ignoriert werden sollen (Standard: false) |
ignore_trailing_whitespaces | Gibt an, ob nachgestellte Leerzeichen ignoriert werden sollen (Standard: false) |
ignore_leading_whitespaces | Gibt an, ob führende Leerzeichen ignoriert werden sollen (Standard: false) |
null_string | Zeichenkette, die als Null-Wert behandelt wird |
break_string | Zeichenkette, durch die Zeilenumbrüche in Feldwerten ersetzt werden |
readInterval | Wartezeit in Millisekunden zwischen der Verarbeitung einzelner Datensätze (Standard: 0) |
Skript-Einstellungen
Die Werte der einzelnen Felder werden unter Bezugnahme auf die Spaltenwerte der CSV-Datei zusammengestellt. Auf die Spalten der CSV-Datei kann im Skript direkt als Variablen ohne Präfix zugegriffen werden (es wird kein Präfix wie data. verwendet).
Mit Kopfzeile (Referenz über Spaltenname):
Ohne Kopfzeile (Referenz über Spaltenindex):
Verfügbare Felder
<Spaltenname>- Direkter Zugriff über den Spaltennamen der Kopfzeile (nur beihas_header_line=true; gültig, wenn der Spaltenname nicht leer ist)cell<N>- Zugriff über den Spaltenindex (cell1,cell2… beginnend bei 1; unabhängig vom Vorhandensein einer Kopfzeile verfügbar)csvfile- Vollständiger Pfad der aktuell verarbeiteten CSV-Dateicsvfilename- Dateiname der aktuell verarbeiteten CSV-Datei
Bemerkung
Enthält ein Spaltenname Leerzeichen, Bindestriche oder andere Zeichen, die als Groovy-Bezeichner ungültig sind, kann nicht über den Spaltennamen zugegriffen werden. Verwenden Sie in diesem Fall cell<N>.
CSV-Format-Details
Standard-CSV (RFC 4180-konform)
Bemerkung
Um wie im obigen Beispiel bei "Book, Programming" Trennzeichen innerhalb eines Feldes durch Einschließen in Anführungszeichen zu verwenden, wird das Feld mit den Standardeinstellungen (Anführungszeichenverarbeitung aktiviert) bereits korrekt als ein einziges Feld verarbeitet. Wie Sie zum bisherigen Verhalten (Anführungszeichen als normale Zeichen, Aufteilung der Felder am Trennzeichen) zurückkehren, erfahren Sie im Abschnitt „Deaktivierung der Anführungszeichen- und Escape-Verarbeitung“ weiter unten.
Deaktivierung der Anführungszeichen- und Escape-Verarbeitung
Die Anführungszeichen- und Escape-Verarbeitung ist in Fess 15.9 standardmäßig aktiviert. Als Anführungszeichen wird standardmäßig das doppelte Anführungszeichen " verwendet, als Escape-Zeichen standardmäßig dasselbe Zeichen wie das Anführungszeichen (gemäß RFC 4180 durch Verdopplung escaped); Standard-RFC-4180-CSV-Dateien lassen sich so ohne zusätzliche Parameter verarbeiten.
Warnung
Enthält eine CSV-Datei bei aktivierter Anführungszeichenverarbeitung auch nur ein einziges " ohne passendes schließendes Anführungszeichen, wird der gesamte Rest der Datei ab diesem Anführungszeichen (einschließlich der folgenden Zeilen) als ein einziger Feldwert eingelesen, und für die übrigen Zeilen werden keine Dokumente mehr erzeugt. Da frühere Versionen jede Zeile unabhängig verarbeitet haben, kann dieses Verhalten erst nach einem Upgrade zutage treten. Da delete_old_docs (siehe oben) standardmäßig aktiviert ist, können dabei nicht nur die nicht erzeugten Dokumente, sondern auch bereits durch ein früheres Crawling registrierte Dokumente gelöscht werden. Prüfen Sie Ihre CSV-Dateien vor dem Upgrade auf nicht geschlossene Anführungszeichen, oder erwägen Sie, mit quote_disabled=true zur bisherigen Verarbeitungsweise zurückzukehren.
Anführungszeichenverarbeitung deaktivieren (bisheriges Verhalten wiederherstellen):
Mit quote_disabled=true wird gleichzeitig auch die Escape-Verarbeitung deaktiviert (außer Sie geben explizit escape_disabled=false an).
Nur die Escape-Verarbeitung deaktivieren:
Trennzeichen ändern
Tab-getrennt (TSV):
Semikolon-getrennt:
Benutzerdefinierte Anführungszeichen
Einfache Anführungszeichen:
Zeichenkodierung
Japanische Datei (Shift_JIS):
Japanische Datei (EUC-JP):
Anwendungsbeispiele
Produktkatalog-CSV
CSV-Datei (products.csv):
Parameter:
Skript:
Filterung nach Lagerbestand:
Mitarbeiterverzeichnis-CSV
CSV-Datei (employees.csv):
Parameter:
Skript:
CSV ohne Kopfzeile
CSV-Datei (data.csv):
Parameter:
Skript:
Mehrere CSV-Dateien zusammenführen
Parameter:
Skript:
Tab-getrennte Datei (TSV)
TSV-Datei (data.tsv):
Parameter:
Skript:
Fehlerbehebung
Datei nicht gefunden
Symptom: Das Crawling wird ausgeführt, aber die Datei wird nicht verarbeitet; im Log erscheint is not found
Zu überprüfen:
Überprüfen Sie, ob der Dateipfad korrekt ist (absoluter Pfad empfohlen)
Überprüfen Sie, ob die Datei existiert
Überprüfen Sie, ob die Dateiendung
.csvoder.tsvist (Dateien mit anderen Endungen werden übersprungen)Überprüfen Sie die Leseberechtigungen der Datei
Überprüfen Sie, ob der Fess-Ausführungsbenutzer Zugriff hat
Zeichenkodierungsprobleme
Symptom: Umlaute oder Sonderzeichen werden nicht korrekt angezeigt
Lösung:
Geben Sie die richtige Zeichenkodierung an:
Zeichenkodierung der Datei ermitteln:
Spalten werden nicht korrekt erkannt
Symptom: Das Spaltentrennzeichen wird nicht korrekt erkannt, oder in Anführungszeichen eingeschlossene Felder werden aufgeteilt
Zu überprüfen:
Überprüfen Sie, ob das Trennzeichen korrekt ist:
Felder mit Anführungszeichen (Felder, die Trennzeichen enthalten) werden standardmäßig korrekt verarbeitet. Prüfen Sie, ob Sie nicht versehentlich
quote_disabled=truegesetzt haben.Überprüfen Sie das CSV-Dateiformat (RFC 4180-konform?). Enthält die Datei ein
"ohne passendes schließendes Anführungszeichen, wird der gesamte Rest der Datei ab dieser Stelle als ein einziger Feldwert eingelesen.
Kopfzeilen-Behandlung
Symptom: Erste Zeile wird als Daten erkannt
Lösung:
Bei vorhandener Kopfzeile:
Ohne Kopfzeile:
Keine Daten abrufbar
Symptom: Crawling erfolgreich, aber 0 Einträge
Zu überprüfen:
Überprüfen Sie, ob die CSV-Datei nicht leer ist
Überprüfen Sie die Skript-Einstellungen (ob Spaltenname- oder
cell<N>-Referenzen ohnedata.-Präfix angegeben sind)Überprüfen Sie die Spaltennamen (bei has_header_line=true)
Überprüfen Sie die Logs auf Fehlermeldungen
Prüfen Sie, ob ein Parametername falsch geschrieben ist (ein nicht erkannter Parametername wird ohne Warnung ignoriert;
has_headerline=truebelässthas_header_linebeispielsweise beim Standardwertfalse)
Der Index aus einem vorherigen Crawling verschwindet nach einem zweiten CSV-Import
Symptom: Nachdem eine erste CSV-Datei gecrawlt wurde, verschwinden nach dem Crawling einer zweiten CSV-Datei mit derselben Datenspeicher-Konfiguration an einem späteren Tag die aus der ersten CSV-Datei registrierten Dokumente aus den Suchergebnissen.
Ursache:
Nach Abschluss eines Crawlings löscht Fess aus dem Index alle Dokumente, die zu dieser Datenspeicher-Konfiguration gehören und in der aktuellen Sitzung nicht erneut registriert wurden (delete_old_docs, Standard: true). Wenn Sie mehrere CSV-Dateien zu unterschiedlichen Zeitpunkten in dieselbe Datenspeicher-Konfiguration einspeisen, gelten beim Crawling der später eingespeisten Datei die durch die frühere Datei registrierten Inhalte als „in der aktuellen Sitzung nicht erneut registriert“ und werden gelöscht.
Lösung:
Wenn Sie mehrere CSV-Dateien zu unterschiedlichen Zeitpunkten in dieselbe Datenspeicher-Konfiguration einspeisen und deren Inhalte kumulieren möchten, geben Sie Folgendes an.
Große CSV-Dateien
Symptom: Speicherüberlauf oder Timeout
Lösung:
Teilen Sie die CSV-Datei in mehrere auf
Verwenden Sie nur benötigte Spalten im Skript
Erhöhen Sie die Heap-Größe von Fess
Filtern Sie nicht benötigte Zeilen
Felder mit Zeilenumbrüchen
Im RFC 4180-Format können Felder durch Einschließen in Anführungszeichen Zeilenumbrüche enthalten. Da die Anführungszeichenverarbeitung standardmäßig aktiviert ist, wird dies ohne zusätzliche Parameter korrekt verarbeitet:
Parameter:
CsvListDataStore
Das Plugin fess-ds-csv enthält neben CsvDataStore auch den Handler CsvListDataStore.
CsvListDataStore erweitert CsvDataStore und bietet folgende zusätzliche Funktionen:
Multithread-Verarbeitung (gesteuert über den Parameter
numOfThreads)Automatisches Löschen verarbeiteter CSV-Dateien
Zeitstempelbasierte Dateifilterung (überspringt Dateien, die noch beschrieben werden)
Alle Parameter und Skript-Einstellungen von CsvDataStore können unverändert verwendet werden.
Grundeinstellungen
| Einstellung | Beispielwert |
|---|---|
| Handler-Name | CsvListDataStore |
Zusätzliche Parameter
| Parameter | Erforderlich | Beschreibung |
|---|---|---|
timestamp_margin | Nein | Vergangene Zeit seit der letzten Änderungszeit der Datei in Millisekunden. Dateien, bei denen diese Zeit noch nicht verstrichen ist, werden als noch im Schreibvorgang befindlich betrachtet und übersprungen (Standard: 10000) |
numOfThreads | Nein | Anzahl der Verarbeitungs-Threads (Standard: 1) |
delete_processed_file | Nein | Gibt an, ob die CSV-Datei nach Abschluss der Verarbeitung gelöscht wird (Standard: true) |
ignore_data_store_exception | Nein | Gibt an, ob das gesamte Crawling fortgesetzt wird, wenn bei der Verarbeitung einer einzelnen CSV-Datei eine Ausnahme auftritt (Standard: true) |
Warnung
CsvListDataStore löscht CSV-Dateien nach Abschluss der Verarbeitung automatisch (delete_processed_file ist standardmäßig true). Tritt während der Verarbeitung ein Fehler auf, wird die Datei stattdessen in .txt umbenannt (schlägt die Umbenennung fehl, wird die Datei gelöscht). Wenn Dateien nicht gelöscht werden sollen, geben Sie delete_processed_file=false an.
CSV-Zeilenformat (Ereignistyp)
CSV-Dateien, die an CsvListDataStore übergeben werden, benötigen pro Zeile mindestens zwei Spalten: einen „Ereignistyp“ und eine „URL“. Weitere Spalten können hinzugefügt und als cell3, cell4 … referenziert werden (z. B. um einen Wert an timestamp.overwrite zu übergeben).
Für den Ereignistyp stehen die folgenden drei Werte zur Verfügung.
create- eine Datei wurde erstelltmodify- eine Datei wurde geändertdelete- eine Datei wurde gelöscht
create und modify werden als derselbe Vorgang behandelt (Crawling und Indexierung der Ziel-URL). Es gibt keinen Unterschied im Verhalten.
Der Spaltenname (bei vorhandener Kopfzeile) und der Wert für jeden Ereignistyp lassen sich über die folgenden Parameter anpassen.
| Parameter | Beschreibung |
|---|---|
field.event_type | Spaltenname, in dem der Ereignistyp gespeichert ist (Standard: event_type) |
event.create | Wert für „erstellt“ (Standard: create) |
event.modify | Wert für „geändert“ (Standard: modify) |
event.delete | Wert für „gelöscht“ (Standard: delete) |
Beispiel für eine CSV-Datei:
Beispiel-Skript (ohne Kopfzeile):
Überschreiben von Feldwerten (.overwrite)
Wird der Name eines im Skript zusammengestellten Indexfelds mit .overwrite versehen, wird der Wert dieses Feldes nicht aus dem tatsächlichen Crawling-Ergebnis der Datei, sondern aus dem in der CSV gesetzten Wert überschrieben.
Bemerkung
Das Datumsfacet in der Suchoberfläche filtert nicht über created, sondern über das Feld timestamp. Wenn Sie den Zeitstempel mit einem Wert aus der CSV überschreiben möchten, geben Sie timestamp.overwrite anstelle von created.overwrite an.
Übernahme von Authentifizierungs- und Proxy-Einstellungen
CsvListDataStore crawlt tatsächlich die in der CSV enthaltenen URLs; Authentifizierungs- und Proxy-Einstellungen, die in der Datenspeicher-Konfiguration des Datei- oder Web-Crawlings konfiguriert sind, werden dabei jedoch nicht übernommen. Geben Sie benötigte Einstellungen einzeln als Parameter dieser Datenspeicher-Konfiguration an.
Beispiel für SMB-Authentifizierung:
Beispiel für Proxy-Einstellungen:
Erweiterte Skript-Beispiele
Datenverarbeitung
Bedingte Indizierung
Bemerkung
Wie oben gezeigt, wird eine Zeile, in der url den Wert null liefert, nicht als Fehler behandelt, sondern stillschweigend übersprungen. Die Anzahl der übersprungenen Zeilen wird pro CSV-Datei gezählt und jeweils nach Abschluss der Leseschleife dieser Datei als eine einzelne zusammenfassende WARN-Logzeile ausgegeben (es wird nicht jede fehlgeschlagene URL einzeln protokolliert; werden mehrere CSV-Dateien verarbeitet, erscheint pro Datei eine WARN-Zeile).
Mehrere Spalten kombinieren
Datumsformatierung
Weiterführende Informationen
Übersicht der Datenspeicher-Konnektoren - Übersicht der Datenspeicher-Konnektoren
JSON-Konnektor - JSON-Konnektor
Datenbank-Konnektor (Datenbank-Suche) - Datenbank-Konnektor
Datenspeicher-Crawl - Leitfaden zur Datenspeicher-Konfiguration