Das neue ‚bin/post‘-Dienstprogramm von Solr 5

Einführung in die Serie Dies ist der erste Teil einer dreiteiligen Serie, in der wir Ihnen zeigen, wie Sie mit…

Einführung in die Serie

Dies ist der erste Teil einer dreiteiligen Serie, in der wir Ihnen zeigen, wie Sie mit ein paar einfachen Befehlen eine echte Anwendung erstellen können. Die drei Teile dieser Serie sind:

• Daten mit bin/post in Solr übertragen
• Visualisierung von Suchergebnissen: /browse und mehr
• Realistische Zusammenstellung: example/files – ein konkretes nützliches domänenspezifisches Beispiel für bin/post und /browse

Einführung von bin/post: ein in Solr 5 integriertes Werkzeug zur Indizierung von Daten

Am Anfang war die Befehlszeile… Im Rahmen der Verbesserungen der Benutzerfreundlichkeit von Solr 5 wurde das Tool bin/post entwickelt, mit dem Sie Daten und Dokumente noch einfacher indizieren können. Dieser Artikel veranschaulicht und erklärt, wie Sie dieses Tool verwenden können.

Solr-Veteranen (vor Version 5.0), die höchstwahrscheinlich das „Beispiel“ von Solr verwendet haben, werden mit post.jar vertraut sein, das Sie unter example/exampledocs finden. Vielleicht haben Sie es nur benutzt, wenn Sie Solr zum ersten Mal gestartet haben, um beispielsweise technische Produkte oder Buchdaten zu indizieren. Auch wenn Sie post.jar noch nicht verwendet haben, sollten Sie diese neue Schnittstelle einmal ausprobieren, und sei es nur, um gelegentlich administrative Befehle an Ihre Solr-Instanzen zu senden. Im Folgenden finden Sie einige interessante einfache Tricks, die Sie mit diesem Tool ausführen können.

Lassen Sie uns damit beginnen, Solr zu starten und eine Sammlung zu erstellen:

$ bin/solr start
$ bin/solr create -c solr_docs

Das Tool bin/post kann einen Verzeichnisbaum von Dateien indizieren, und die Solr-Distribution enthält ein praktisches docs/ Verzeichnis, um diese Fähigkeit zu demonstrieren:

$ bin/post -c solr_docs docs/

java -classpath /Users/erikhatcher/solr-5.3.0/dist/solr-core-5.3.0.jar -Dauto=yes -Dc=solr_docs -Ddata=files -Drecursive=yes org.apache.solr.util.SimplePostTool /Users/erikhatcher/solr-5.3.0/docs/
SimplePostTool version 5.0.0
Posting files to [base] url http://localhost:8983/solr/solr_docs/update...
Entering auto mode. File endings considered are xml,json,csv,pdf,doc,docx,ppt,pptx,xls,xlsx,odt,odp,ods,ott,otp,ots,rtf,htm,html,txt,log
Entering recursive mode, max depth=999, delay=0s
Indexing directory /Users/erikhatcher/solr-5.3.0/docs (3 files, depth=0)
.
.
.
3575 files indexed.
COMMITting Solr index changes to http://localhost:8983/solr/solr_docs/update...
Time spent: 0:00:30.705

30 Sekunden später ist das Verzeichnis docs/ von Solr indiziert und für die Suche verfügbar. Als Vorgeschmack auf den nächsten Beitrag in dieser Serie, sehen Sie sich http://localhost:8983/solr/solr_docs/browse?q=faceting an, um zu sehen, was Sie da haben. Gibt es irgendetwas, das bin/post tun kann, was cleveres Curlingnicht tun kann? Nichts, obwohl Sie für ganz vergleichbare Fähigkeiten über einen Verzeichnisbaum von Dateien iterieren oder das Web crawlen und die zu verfolgenden Links parsen müssten. bin/post soll die (Befehlszeilen-)Schnittstelle für viele gängige Solr-Ingestions- und Befehlsanforderungen vereinfachen.

Verwendung

Das Tool bietet solide -h Hilfe, wobei die abgekürzte Verwendungsangabe lautet:

$ bin/post -h
Usage: post -c <collection> [OPTIONS] <files|directories|urls|-d ["...",...]>
    or post -help

   collection name defaults to DEFAULT_SOLR_COLLECTION if not specified
...

In der vollständigen Ausgabe bin/post -h finden Sie weitere Einzelheiten zu den Parametern und Beispielen für die Verwendung. Eine Sammlung oder URL muss immer mit -c (oder durch DEFAULT_SOLR_COLLECTION in der Umgebung) oder -url angegeben werden. Es gibt Parameter zur Steuerung der Basis-URL von Solr mit -host, -port oder der vollständigen -url. Beachten Sie, dass es sich bei -url um die vollständige URL handeln muss, einschließlich des Kernnamens bis hin zum /update Handler, wie z.B. -url http://staging_server:8888/solr/core_name/update.

Indizierung von „Rich Documents“ aus dem Dateisystem oder Web Crawl

Die Indizierung des Dateisystems wurde oben demonstriert, indem das Verzeichnis docs/ von Solr indiziert wurde, das eine Menge HTML-Dateien enthält. Ein weiteres unterhaltsames Beispiel ist die Indizierung Ihres eigenen Dokumentenordners wie folgt:

$ bin/solr create -c my_docs
bin/post -c my_docs ~/Documents

Es gibt eine eingeschränkte Liste von Dateitypen (nach Dateierweiterung), die bin/post an Solr weitergibt und die anderen überspringt. bin/post -h liefert die standardmäßig verwendete Liste. Um z.B. eine .png-Datei zu indizieren, setzen Sie den Parameter -filetypes: bin/post -c test -filetypes png image.png. Um keine Dateien zu überspringen, verwenden Sie „*“ für die Einstellung filetypes: bin/post -c test -filetypes "*" docs/ (beachten Sie die doppelten Anführungszeichen um das Sternchen herum, sonst könnte Ihre Shell dies zu einer Liste von Dateien erweitern und nicht wie beabsichtigt funktionieren) Durchsuchen Sie Ihre eigenen Dokumente unter http://localhost:8983/solr/my_docs/browse

Rudimentäres Webcrawlen

Vorsicht: Das Crawlen von Websites ist keine triviale Aufgabe, die man gut erledigen kann. Das Web-Crawling von bin/post ist sehr grundlegend, single-threaded und nicht für ernsthafte Geschäfte gedacht. Aber es macht Spaß, eine einfache Website relativ schnell zu indizieren und ein Gefühl dafür zu bekommen, mit welchen Problemen bei der Verarbeitung von Inhalten und der Abfrage von Daten zu rechnen ist, wenn ein Crawler im Produktionsmaßstab oder andere Mittel zur Erfassung von Inhalten in Arbeit sind:

$ bin/solr create -c site
$ bin/post -c site https://lucidworks.com -recursive 2 -delay 1  # (this will take some minutes)

Beim Web-Crawling gelten dieselben Inhalts-/Dateityp-Filter wie beim oben erwähnten Dateicrawling; verwenden Sie -filetypes nach Bedarf. Probieren Sie auch hier /browse aus; für dieses Beispiel verwenden Sie http://localhost:8983/solr/site/browse?q=revolution

Indizierung von CSV-Dateien (spaltengetrennt)

Die Indizierung von CSV-Dateien könnte nicht einfacher sein! Es geht einfach so: data.csv ist eine Standard-CSV-Datei:

$ bin/post -c collection_name data.csv

CSV-Dateien werden an den /update Handler mit dem Inhaltstyp „text/csv“ übergeben. Er erkennt, dass es sich um eine CSV-Datei handelt, und zwar anhand der Dateierweiterung „.csv“. Da die Dateierweiterung zur Auswahl des Inhaltstyps herangezogen wird und es derzeit nur eine feste „.csv“-Zuordnung zu text/csv gibt, müssen Sie den Inhalt -type ausdrücklich so einstellen, wenn die Datei eine andere Erweiterung hat:

$ bin/post -c collection_name -type text/csv data.file

Wenn die durch Trennzeichen getrennte Datei keine erste Zeile mit Spaltennamen enthält, einige Spalten ausgeschlossen oder Namen zugeordnet werden müssen, die Datei durch Tabulatoren und nicht durch Kommas getrennt ist oder Sie eine der verschiedenen Optionen für den CSV-Handler angeben müssen, kann die Option -params verwendet werden. Um zum Beispiel eine tabulatorgetrennte Datei zu indizieren, setzen Sie den Parameter separator wie folgt:

$ bin/post -c collection_name data.tsv -type text/csv -params "separator=%09"

Die in -params angegebenen Schlüssel=Wert-Paare müssen URL-kodiert und durch kaufmännische Zeichen getrennt sein (Tabulator ist URL-kodiert als %09). Wenn die erste Zeile einer CSV-Datei aus Daten und nicht aus Spaltennamen besteht oder Sie die Spaltennamen überschreiben müssen, können Sie den Parameter fieldnames angeben und header=true setzen, wenn die erste Zeile ignoriert werden soll:

$ bin/post -c collection_name data.csv -params "fieldnames=id,foo&header=true"

Hier ist ein netter Trick, den Sie mit CSV-Daten anwenden können: Fügen Sie eine „Datenquelle“ oder eine Art Feld hinzu, um zu identifizieren, aus welcher Datei oder welchem Datensatz jedes Dokument stammt. Fügen Sie einen literal.<field_name>= Parameter wie diesen hinzu:

$ bin/post -c collection_name data.csv -params "literal.data_source=temp"

Wenn Ihr Schema ein data_source-Feld für Dokumente zulässt, wird jede Datei oder jede Gruppe von Dateien, die Sie laden, mit einem Schema Ihrer Wahl versehen, so dass Sie diese Teilmenge von Daten leicht filtern, löschen und bearbeiten können. Ein anderer wörtlicher Feldname könnte der Dateiname selbst sein. Achten Sie nur darauf, dass die geladene Datei mit dem Wert des Feldes übereinstimmt (es ist leicht, einen Teil der Befehlszeile zu ändern, nicht aber einen anderen, der synchron gehalten werden sollte).

Indizierung von JSON

Wenn Ihre Daten im Solr JSON-Format vorliegen, ist es einfach bin/post -c collection_name data.json. Beliebige JSON-Daten, die nicht von Solr stammen, können ebenfalls gemappt werden. Unter Verwendung der Prüfungsdaten und des Beispiels von hier können die Aufteilungs- und Zuordnungsparameter wie folgt angegeben werden:

$ bin/post -c collection_name grades.json -params "split=/exams&f=first:/first&f=last:/last&f=grade:/grade&f=subject:/exams/subject&f=test:/exams/test&f=marks:/exams/marks&json.command=false"

Beachten Sie, dass json.command=false angegeben werden musste, damit das JSON als Daten und nicht als potenzielle Solr-Befehle interpretiert wird.

Indizierung von Solr XML

Das gute alte Solr XML, kinderleicht: bin/post -c collection_name example/exampledocs/*.xml. Wenn Sie nicht wissen, was Solr XML ist, werfen Sie einen Blick auf die Solr Beispiel/exampledocs/*.xml Dateien. Leider gibt es derzeit keine Splitting- und Mapping-Funktionen für beliebiges XML mit bin/postVerwenden Sie den Data Import Handler mit dem XPathEntityProcessor, um dies zu erreichen. Siehe SOLR-6559 für weitere Informationen zu dieser zukünftigen Verbesserung.

Senden von Befehlen an Solr

Neben der Indizierung von Dokumenten, bin/post kann auch verwendet werden, um Solr Befehle zu erteilen. Hier sind einige Beispiele:

• Übertragen: bin/post -c collection_name -out yes -type application/json -d '{commit:{}}' Hinweis: Für eine einfache Übergabe ist eigentlich keine Daten-/Befehlszeichenfolge erforderlich. Ein leeres, nachgestelltes -d reicht aus, um eine Übergabe zu erzwingen, etwa so – bin/post -c collection_name -d
• Löschen Sie ein Dokument nach ID: bin/post -c collection_name -type application/json -out yes -d '{delete: {id: 1}}'
• Dokumente nach Abfrage löschen: bin/post -c test -type application/json -out yes -d '{delete: {query: "data_source:temp"}}'

-out yes gibt den HTTP-Antwortkörper der Solr-Anfrage wieder, was im Allgemeinen bei Indizierungsfehlern nicht weiter hilfreich ist, aber bei Befehlen wie commit und delete auch bei Erfolg gut zu sehen ist. Befehle oder sogar Dokumente können durch bin/post geleitet werden, wenn -d am Ende der Befehlszeile hängt:

# Pipe a commit command
$ echo '{commit: {}}' | bin/post -c collection_name -type application/json -out yes -d

# Pipe and index a CSV file
$ cat data.csv | bin/post -c collection_name -type text/csv -d

Innenleben der Tonne/Post

Die bin/post Tool ist ein einfaches Unix-Shell-Skript, das Befehlszeilenargumente verarbeitet und validiert und ein Java-Programm startet, das die Datei(en) an den entsprechenden Update-Handler-Endpunkt sendet. Derzeit ist SimplePostTool die Java-Klasse, die diese Arbeit erledigt (der Kern des berüchtigten post.jar von früher). Tatsächlich existiert post.jar noch und wird unter bin/post verwendet, aber das ist ein Implementierungsdetail, das bin/post verbergen soll. SimplePostTool (nicht das Wrapper-Skript bin/post) verwendet die Dateierweiterungen, um den Solr-Endpunkt zu bestimmen, der für jeden POST verwendet werden soll. Es gibt drei spezielle Dateitypen, die an den /update-Endpunkt von Solr gepostet werden: .json, .csv und .xml. Alle anderen Dateierweiterungen werden an den Endpunkt URL+/extract gesendet, der eine Vielzahl von Dateitypen analysiert. Wenn Sie CSV-, XML- oder JSON-Daten indizieren und die Dateierweiterung nicht übereinstimmt oder es sich nicht um eine Datei handelt (wenn Sie die Option -d verwenden), müssen Sie -type explizit auf text/csv, application/xml oder application/json einstellen.

Dumme Mülltonnen-/Posttricks

Introspect Rich Document Parsing und Extraktion

Möchten Sie sehen, wie das Rich Document Parsing von Solr Ihre Dateien sieht? Das ist keine neue Funktion, aber eine nette, die Sie über bin/post nutzen können, indem Sie ein Dokument im Debug-Modus an den Extract-Handler senden und eine XHTML-Ansicht des Dokuments mit allen Metadaten zurückgeben. Hier ist ein Beispiel mit der Einstellung -params und einigen zusätzlichen Einstellungen, die weiter unten erläutert werden:

$ bin/post -c test -params "extractOnly=true&wt=ruby&indent=yes" -out yes docs/SYSTEM_REQUIREMENTS.html
java -classpath /Users/erikhatcher/solr-5.3.0/dist/solr-core-5.3.0.jar -Dauto=yes -Dparams=extractOnly=true&wt=ruby&indent=yes -Dout=yes -Dc=test -Ddata=files org.apache.solr.util.SimplePostTool /Users/erikhatcher/solr-5.3.0/docs/SYSTEM_REQUIREMENTS.html
SimplePostTool version 5.0.0
Posting files to [base] url http://localhost:8983/solr/test/update?extractOnly=true&wt=ruby&indent=yes...
Entering auto mode. File endings considered are xml,json,csv,pdf,doc,docx,ppt,pptx,xls,xlsx,odt,odp,ods,ott,otp,ots,rtf,htm,html,txt,log
POSTing file SYSTEM_REQUIREMENTS.html (text/html) to [base]/extract
{
  'responseHeader'=>{
    'status'=>0,
    'QTime'=>3},
  ''=>'<?xml version="1.0" encoding="UTF-8"?>
<html >
<head>
<meta
name="stream_size" content="1100"/>
<meta name="X-Parsed-By"
            content="org.apache.tika.parser.DefaultParser"/>
<meta
name="X-Parsed-By"
            content="org.apache.tika.parser.html.HtmlParser"/>
<meta
name="stream_content_type" content="text/html"/>
<meta name="dc:title"
            content="System Requirements"/>
<meta
name="Content-Encoding" content="UTF-8"/>
<meta name="resourceName"
            content="/Users/erikhatcher/solr-5.2.0/docs/SYSTEM_REQUIREMENTS.html"/>
<meta
name="Content-Type"
                content="text/html; charset=UTF-8"/>
<title>System Requirements</title>
</head>
<body>
<h1>System Requirements</h1>
   ...
</body>
</html>
',
  'null_metadata'=>[
    'stream_size',['1100'],
    'X-Parsed-By',['org.apache.tika.parser.DefaultParser',
      'org.apache.tika.parser.html.HtmlParser'],
    'stream_content_type',['text/html'],
    'dc:title',['System Requirements'],
    'Content-Encoding',['UTF-8'],
    'resourceName',['/Users/erikhatcher/solr-5.3.0/docs/SYSTEM_REQUIREMENTS.html'],
    'title',['System Requirements'],
    'Content-Type',['text/html; charset=UTF-8']]}
1 files indexed.
COMMITting Solr index changes to http://localhost:8983/solr/test/update?extractOnly=true&wt=ruby&indent=yes...
Time spent: 0:00:00.027

Die Einstellung extractOnly=true weist den extract handler an, die strukturierten geparsten Informationen zurückzugeben, anstatt das Dokument tatsächlich zu indizieren. Durch die Einstellung wt=ruby (ah ja! Probieren Sie es ruhig in json oder xml aus 🙂 und indent=yes wird die Ausgabe (geben Sie unbedingt -out yes an!) in einer Konsole lesbar dargestellt.

Prototyping, Fehlersuche, Basteln, Demonstrieren

Es ist wirklich praktisch, wenn man eine Funktion von Solr testen und demonstrieren kann, indem man „das Einfachste tut, was funktioniert“ und bin/post macht dies zu einer wahren Freude. Hier sind einige Beispiele –

Passt es?

Mit dieser Technik können Sie auf einfache Weise Daten indizieren und schnell sehen, wie Abfragen mit ihnen funktionieren. Erstellen Sie einen „Spielplatz“-Index und stellen Sie ein einzelnes Dokument mit den Feldern id, description und value ein:

$ bin/solr create -c playground
$ bin/post -c playground -type text/csv -out yes -d $'id,description,valuen,are we there yet?,0.42'

Unix-Hinweis: Das Dollar-Zeichen vor der CSV-Zeichenfolge in einfachen Anführungszeichen ist wichtig, damit die Zeilenumbrüche ordnungsgemäß verarbeitet werden können. Sie können aber auch die gleichen Daten posten, indem Sie die Feldnamen in einen separaten Parameter mit bin/post -c playground -type text/csv -out yes -params "fieldnames=id,description,value" -d '1,are we there yet?,0.42' eingeben und so die Notwendigkeit eines Zeilenumbruchs und das damit verbundene Problem vermeiden.

Stimmt es mit einer Fuzzy-Abfrage überein? their~, in der /select-Anfrage unten, ist buchstäblich eine FuzzyQuery und endet mit dem indizierten Dokument (basierend auf der Unschärfe der String-Edit-Distanz), rows=0, so dass wir nur die numFound- und debug=query-Ausgabe sehen:

$ curl 'http://localhost:8983/solr/playground/select?q=their~&wt=ruby&indent=on&rows=0&debug=query'
{
  'responseHeader'=>{
    'status'=>0,
    'QTime'=>0,
    'params'=>{
      'q'=>'their~',
      'debug'=>'query',
      'indent'=>'on',
      'rows'=>'0',
      'wt'=>'ruby'}},
    'response'=>{'numFound'=>1,'start'=>0,'docs'=>[]
  },
  'debug'=>{
    'rawquerystring'=>'their~',
    'querystring'=>'their~',
    'parsedquery'=>'_text_:their~2',
    'parsedquery_toString'=>'_text_:their~2',
    'QParser'=>'LuceneQParser'}}

Verwenden Sie einfach ein id-Feld und alle Felder, die in Ihren Testabfragen vorkommen. So erhalten Sie schnell einen Einblick in die Indizierung von Dokumenten, die Analyse von Text und die Übereinstimmung von Abfragen. Mit diesem CSV-Trick können Sie eine Vielzahl von Szenarien testen, einschließlich komplexer Facettierung, Gruppierung, Hervorhebung usw., und das oft mit nur wenigen repräsentativen CSV-Daten.

Windows, es tut mir leid. Aber verzweifeln Sie nicht.

bin/post ist ein Unix-Shell-Skript. Es gibt keine vergleichbare Windows-Befehlsdatei, wie es sie für bin/solr gibt. Der Entwickler von bin/post ist ein grauhaariger Unix-Muffel und sagt spöttisch „Patches willkommen“, wenn er gefragt wird, wo die Windows-Version ist. Aber verzweifeln Sie nicht, bevor es bin/post gab, gab es post.jar. Und es gibt immer noch post.jar. Im Abschnitt “ Windows-Unterstützung“ des Referenzhandbuchs finden Sie Einzelheiten dazu, wie Sie das Äquivalent zu allem, was bin/post kann, ausführen können, aber mit den obigen Beispielen ist es ein schnelles Kopieren/Einfügen, um loszulegen. Das Tool bin/post gibt die Java-Befehlszeile wieder, kurz bevor es gestartet wird, so dass Sie die obigen Beispiele einfach kopieren/einfügen/anpassen können. Um zum Beispiel die solr_docs aus dem ersten Beispiel zu posten, nehmen Sie die Zeile „java -classpath ….“ und passen sie an die Windows-Pfade an:

> java -classpath <path to Solr>distsolr-core-5.3.0.jar -Dauto=yes -Dc=solr_docs -Ddata=files -Drecursive=yes 
  org.apache.solr.util.SimplePostTool <path to Solr>docs

Zukunft

Was will man mehr von einem Tool, mit dem man Inhalte in Solr veröffentlichen kann? Eine ganze Menge, wie sich herausstellt! Hier sind ein paar Ideen für Verbesserungen:

• Zunächst einmal wird SolrCloud-Unterstützung benötigt. Im Moment ist der exakte HTTP-Endpunkt erforderlich, während die SolrCloud-Indizierung am besten mit ZooKeeper-Cluster und der Kenntnis der Sammlungstopologie erfolgt. Vielleicht passt dies unter SOLR-7268.
• SOLR-7057: Bessere Erkennung und Behandlung von Inhaltstypen (.tsv-Dateien könnten automatisch als mit separator=%09 getrennt betrachtet werden)
• SOLR-6994: Hinzufügen einer vergleichbaren Windows-Befehlszeilenschnittstelle
• SOLR-7042: Verbessern Sie den Umgang von bin/post mit beliebigem JSON
• SOLR-7188: Und vielleicht, nur vielleicht, könnte dieses Tool auch das Front-End für den Client-seitigen Data Import Handler sein

Und zweifellos gibt es zahlreiche weitere Verbesserungen, um die Befehlszeilensyntax und die Robustheit dieses praktischen kleinen Tools zu verbessern.

Fazit

$ bin/post -c your_collection your_data/

Nein, bin/post ist nicht unbedingt der „richtige“ Weg, um Daten in Ihr System zu bekommen, wenn es um Streaming Spark-Jobs, Datenbankinhalte, umfangreiches Web-Crawling oder andere Solr-Integrationskonnektoren geht. Aber aus pragmatischer Sicht ist es vielleicht genau das Richtige, um Befehle zum Übertragen/Löschen an einen Ihrer Solr-Server zu senden oder um einige schnelle Tests durchzuführen. Und wenn Sie z.B. einen nächtlichen Prozess haben, der neue Daten als CSV-Dateien erzeugt, wäre ein Cron-Job für bin/post genauso pragmatisch und „produktionstauglich“ wie alles andere.

Der nächste Schritt…

Mit bin/post haben Sie Ihre Daten mit einem einfachen, leicht zu bedienenden Befehl in Solr übertragen. Das ist ein wichtiger Schritt, wenn auch nur die Hälfte der Gleichung. Wir indizieren Inhalte, damit wir sie abfragen, analysieren und visualisieren können. Der nächste Artikel in dieser Serie befasst sich mit den Funktionen von Solr zur Erstellung von Antwortvorlagen, die eine typische (und erweiterbare) Benutzeroberfläche für Suchergebnisse bieten.