Umgang mit Solr-Query

Dynamische Listen erzeugen

Solr-Queries sind einfache oder komplexe Suchskripte, um Abfragen über die OpenCms-Elemente laufen zu lassen. Auf dieser Seite lernen Sie, wie Solr-Queries aufgebaut sind, was Ihnen der Solr-Index zur Verfügung stellt und welche praktischen Anwendungsmöglichkeiten es gibt.

(Icon: pdf)

Anleitung dieser Seite als PDF (Folien einer Bildschirmpräsentation). Datei ist nicht barrierefrei.

Bemerkungen zu dieser Seite

In den Beispielen sind Variablen – Ausdrücke, die Sie durch etwas Sinnvolles ersetzen müssen – mit geschweiften Klammern dargestellt,
z. B. {Jahr}. In der Anwendung schreiben Sie dann das benötigte Jahr aus.

1. Was ein Solr-Query ist und wo er bei uns vorkommt

Was ist ein Solr-Query?

  • Mit Solr-Query meinen wir eine Zeichenkette, mit der die in OpenCms installiert Suchmaschine „Solr“ des Herstellers Apache angesprochen wird.
  • Eine gelungene Solr-Query-Anfrage ruft eine Liste mit Ergebnissen aus dem Solr-Index hervor.

Wo kommt bei uns ein Solr-Query vor?

  • Überall, wo OpenCms Listen ausgibt.
  • In allen dynamischen Listungen in OpenCms, auch wenn Sie für die Einstellungen einfach nur z. B. Dateityp, Verzeichnis und Kategorien wählen.
  • Eingeben können Sie Solr-Query
    • in Auszügen im Feld „Solr-Option“,
    • vollständig im Feld „Solr-Query“,
    • im Servlet handleSolrSelect.

Dynamische Listenelemente in OpenCms

Diese Elemente greifen auf das Sub-Schema „Datenquelle“ zurück:

Das Sub-Schema „Datenquelle“

Sub-Schema Datenquelle
Screenshot des Teil-Schemas im Acacia-Editor
  • In der „Datenquelle“ können Sie nutzungsfreundlich Ihre Sucheinstellungen konfigurieren oder als Profi die komplette Suchanfrage selbst schreiben.
  • Die Datenquelle hat eine einfache Bedienoberfläche für Ihre Such- und Listkriterien.
  • Unter „Solr-Option“ können Sie an die Suchkriterien noch Solr-Codeschnipsel im Bereich des fq-Parameters anhängen.
  • Das Feld Solr-Query bedeutet, Sie definieren alles. Die Angaben aus den vorangehenden Formularfeldern werden ignoriert. Nur das Makro „%(link1)“ usw. greift auf das erste „Ordner“-Feld usw. zurück.

Doku: Sub-Schema Datenquelle

2. So bauen Sie Ihren Solr-Query auf

Grundaufbau

fq={suchkriterien}
&sort={sortierangaben}
&start={beginn_mit_nr}
&rows={anzahl}
  • fq, sort, start und rows sind Parameter mit Werten, die Sie festlegen.
  • Parameter verbinden Sie mit &.
  • Es dürfen mehrere fq-Parameter enthalten sein. Der Rest darf nur einfach vorkommen.

Die Suchkriterien

Häufige Datenfelder: Globale Felder

Feld

Beschreibung

Beispiele

type

OpenCms-Elementtyp

news_v3, introbox_v3, containerpage, binary

parent-folders

Elternverzeichnis in beliebiger Höhe, unter dem alles durchsucht wird. Beginnt für Webseiten bei uns immer mit /sites/default/

/sites/default/fak6/ifb/

category

Kategorie aus einem verfügbaren Kategorienverzeichnis. Es funktionieren sowohl Pfade als auch die letzten Ordner.
  • universitaet/fakultaeten/fak6/ifb/
  • ifb/
  • veranstaltungen/homepage/

content

Unformatierter vollständiger Inhalt eines OpenCms-Elements

  

suffix

Dateiendung

html, xml, pdf

path

Interner Pfad der Datei

/sites/default/fak6/ifb/.content/news_v3/news_00001.html

Häufige Datenfelder: Eigenschaften

Feld Beschreibung Beispiel
Title_prop (Interne) Titeleigenschaft eines OpenCms-Elements  
Description_prop (Interne) Beschreibung eines OpenCms-Elements  
NavText_prop Navigationstext-Eigenschaft eines OpenCms-Elements  
con_locales Sprachversion
  • de
  • en
beginn_{locale}_dt Unser Newsstream-Datum für alle Newsstream-Elemente bzw. Startdatum für Veranstaltungen.  
ende_{locale}_dt Enddatum für Veranstaltungen  
search.priority_prop Von Hand eingestellte Priorität-Eigenschaft 1

Mit {eigenschaftsname}_prop kann nach allen OpenCms-Eigenschaften mit deren Werten gesucht werden.

Vergleiche

Enthält exakt

Eine exakte Entsprechung mehrerer Wörter rufen Sie mit Anführungszeichen hervor.
Title_prop_s:"Onlinekurs mit Solr-Queries arbeiten"

Enthält

Wenn ein Feld eine bestimmte Zeichenfolge enthalten soll, verwenden Sie keine Anführungszeichen und an Stelle der beliebigen Zeichen die Wildcart "*".
Title_prop_s:*Solr-Queries*

Ist ungleich bzw. Ausschluss

Um einen Parameter auszuschließen, setzen Sie Minus vor den Feldnamen:
-path:"%(link1)"index.html
bedeutet, dass die Containerseite eines Ordners nicht mit gelistet wird.

Verschachtelungen

Und

Die Und-Verknüpfung in den Suchkriterien geht mit  AND .
Bei nicht-verschachtelten Suchkriterien können Sie auch einen neuen „Filterquery“ (fq=) anhängen.

Oder

Die Oder-Verknüpfung in den Suchkriterien geht mit  OR .

Klammern

Setzen Sie Klammern, um die Rangfolge der Parameter zu definieren. Klammern können Sie sowohl innerhalb eines Ausdrucks als auch um ganze Ausdrücke herum setzen.
type:(news_v3 OR event_v3) ist gleichbedeutend mit (type:news_v3 OR type:event_v3) ist gleichbedeutend mit ((type:news_v3) OR (type:event_v3)

Tipps

  • Es ist hilfreich, den Query mehrzeilig mit Einrückungen durch Leerzeichen zu notieren, um den Überblick zu bewahren. Solr kennt bei fehlenden geschlossenen Klammern keine Gnade.
  • Ein Leerzeichen vor dem ersten fq führt zu fehlerhaftem Ergebnis.
  • Kommentare innerhalb des Querys sind zulässig und empfehlenswert:
    /* Kommentar */
  • Beim Einsatz im Sub-Schema Datenquelle können Sie Makros verwenden:
    • „%(link1)“ verweist auf den ersten „Ordner“-Eintrag, „%(link2)“auf den zweiten usw.
    • „%(locale)“ wird je nach Sprachumgebung durch (de/en) ersetzt.

Suche nach Datum

  • Datumsfelder enden im OpenCms-Solr-Index mit _dt. Sie werden anders durchsucht, nämlich mit Ausdrücken in eckigen Klammern.
  • Suchen Sie innerhalb eines Zeitraums, werden zwei Zeitangaben (absolut oder relativ) benannt und mit dem Wort TO verbunden.
  • Für einen beliebigen Zeitpunkt (in der Vergangenheit wie auch in der Zukunft) steht „*“.
  • Beispiel „Daten innerhalb der kommenden 50 Tage“: 
    fq=beginn_de_dt:[NOW TO NOW+50DAYS]

Relativer Zeitpunkt

  • Als Zeitpunkt für „jetzt“ steht der Begriff NOW.
  • Mit Minus und Plus zu Zeiträumen erweitern: NOW+7DAYS ist heute in einer Woche.
  • Relative Punkte, die sich am Jetzt-Zeitpunkt orientieren, generieren Sie mit NOW und Schrägstrich, um den Beginn des Zeitraums zu erhalten:
    NOW/DAY
    Beginn des heutigen Tages (00:00 Uhr)
    NOW/WEEK
    Beginn dieser Woche (Sonntag 00:00 Uhr)
    NOW/MONTH
    Beginn des 1. dieses Kalendermonats (00:00 Uhr)
    NOW/YEAR
    1. Januar dieses Jahres (00:00 Uhr)

Absoluter Zeitpunkt

  • Ein absolutes Datum steht im Schema {Jahr}-{Monat}-{Tag}T{Stunde}:{Minute}:{Sekunde}Z
  • Das Jahr besteht aus vier Ziffern, der Rest aus je zwei Ziffern.
  • Beispiel für eine Abfrage von Veranstaltungen im Sommersemester 2023: 
    fq=(
       beginn_de_dt:[2023-04-01T00:00:00Z TO 2023-09-30T23:59:59Z]
     OR 
       ende_de_dt:[2023-04-01T00:00:00Z TO 2023-09-30T23:59:59Z]
    )

Reihenfolge und Anzahl

sort={sortierangaben}
Eine oder mehrere Suchangaben stehen immer in der Kombination {Feld} und {Richtung}. Die Richtung ist asc oder desc.
Aufsteigende Sortierung nach Priorität aufsteigend, dann nach Datum absteigend: 
sort=search.priority_prop_s asc, beginn_%(locale)_dt desc
Zufallssortierung mit sort=random_1234 asc oder random_1234 desc.
start={beginn_mit_nr}
Optional und bei uns selten im Einsatz. Ohne Angabe automatisch 0.
rows={anzahl}
Die ersten sechs Treffer in der Liste ausgeben:
rows=6

3. Das Servlet handleSolrSelect

Achtung: Für Datumssuchen URL encodieren, z. B. mit dem URLEncoder.org.

Das Servlet handleSolrSelect liefert Solr-Ergebnisse im XML- oder JSON-Format.

Der Solr-Index

  • Eine Komplettausgabe des Solr-Index‘ erhalten Sie mit der URL-Abfrage im Uni-Netz über ein Servlet: https://opencms.uni-stuttgart.de/opencms/handleSolrSelect
  • Sie hängen an die URL ein Fragezeichen und Ihre komplette Suche (!ohne Varibeln und Makros!), z. B.: https://opencms.uni-stuttgart.de/opencms/handleSolrSelect?fq=parent-folders:/sites/default/ze/tik/%20AND%20type:%22event_v3%22%20AND%20Title_prop_s:*Solr-Queries*
  • In den Ergebnissen erkennen Sie praktischerweise alle Felder im Index. So können Sie ggf. Elemente nach bestimmten Feldern und Kriterien ausschließen.

Feldanzeige im Servlet handleSolrSelect

  • Das Servlet liefert Ihnen die Ergebnisse im JSON-Format;
    wenn Sie den Parameter &wt=xml anhängen, bekommen Sie eine XML-Ausgabe.
  • Der Knoten numFound auf der ersten Ebene zeigt, wie viele Treffer es für den fq-Parameter gibt.
  • Unterhalb von docs finden Sie die abgefragten Elemente samt existierender Solr-Felder und aller Element-Eigenschaften.
  • Aus Performance-Gründen ist die Zahl der angezeigten Elemente in allen Suchen auf 1000 begrenzt (0 bis 999).

Beispielcode: Futter für das handleSolrSolect

Weil das Servlet nicht mit dem Subschema Datenquelle bedienbar ist, sind Solr-Query-Grundkenntnisse hilfreich. Ein Standard-Newsstream für ein Institut mit Kategorie:

fq=type:(news_v3 OR event_v3 OR social-media_v3 OR video_v3 OR stellenwerk_v3)
   AND category:"startseite/"
   AND parent-folders:"/sites/default/fak7/ist/"
   AND con_locales:de

&sort=beginn_de_dt desc
&start=0
&rows=9

4. Beispiele für den Hausgebrauch

  • Nutzen Sie die Felder der Datenquelle und tragen Sie die Begrenzungen in der Solr-Option ein.
  • Fester Zeitraum: 
    (beginn_%(locale)_dt:[2022-10-01T00:00:00Z TO 2023-03-31T23:59:59Z] 
OR ende_%(locale)_dt:[2022-10-01T00:00:00Z TO 2023-03-31T23:59:59Z])
  • Relativer Zeitraum: 
    (beginn_%(locale)_dt:[NOW/YEAR+10MONTHS TO NOW/YEAR+15MONTHS] 
OR ende_%(locale)_dt:[NOW/YEAR+10MONTHS TO NOW/YEAR+15MONTHS])
  • Sie stellen in der Dateiliste als gewünschten Typ containerpage ein.
  • Solr-Option, um die anzeigende Übersichtsseite von der Liste auszunehmen: 
    *:* AND -path:"%(link1)index.html"
  • Lässt sich mit Hausmitteln umsetzen; bei der Datenquelle eintragen:
    • Sortierschlüssel: search.priority_prop, beginn_%(locale)_dt
    • Sortierreihenfolge: desc, desc
  • Im Query wäre es folgender Code: sort=search.priority_prop desc, beginn_%(locale)_dt desc
  • Beachten: Die Priorität-Eigenschaft gilt pro Element. Alle Listen, die (auch) nach Priorität sortieren, werden diese Eigenschaft berücksichtigen.
  • Zwei Listenelemente benötigt.
    • Ein repräsentatives, das nur eine bestimmte überschaubare Anzahl (3 bis 8) enthält.
    • Ein platzsparendes mit identischer Konfiguration, nur zusätzlichem start-Parameter.
  • Weil die Datenquelle-Felder als Strings aneinandergefügt werden, können Sie den start-Parameter direkt an den Wert des rows-Parameters mit & anhängen:
    Anzahl: im Feld '999&start=9' eintragen
  • Abgefragte Elemente stehen mit OR nebeneinander.
  • Klammern sind hierbei die Lösung – die Datumsabfrage bezieht sich durch die AND-Verknüpfung ausschließlich auf Elemente vom Typ event_v3.
  • Im nachfolgenden Beispiel ist für eine stabile Referenzierung das ParentFolders-Verzeichnis im Feld „Ordner“ hinterlegt und mit %(link1) im Code aufgerufen.

Der Code

fq=(
    parent-folders:"%(link1)"
  AND
     (
       (type:(news_v3 OR video_v3 OR social-media_v3))
     OR
      (
       (type:(event_v3))
        AND
        (beginn_%(locale)_dt:[NOW TO *] OR ende_%(locale)_dt:[NOW TO *])
       )
    )
)
&fq=con_locales:%(locale)
&sort=search.priority_prop_s desc, beginn_%(locale)_dt desc
&rows=9
  • Wenn Sie z. B. eine Teamliste haben, die Mitglieder aus verschiedenen Webauftritten versammelt.
  • Gewünschte Mitarbeiter*in-Datensätze in „Ordner“ eintragen.
  • Bei Solr-Query mit path-Feld arbeiten. Nur so viele „link“-Einsätze verwenden, wie es Einträge bei „Ordner“ gibt, sonst führt die Liste zum Absturz der Seite.
  • Achtung: Sortierung mitdenken!

Der Code

fq=path:"%(link1)"
    OR path:"%(link2)"
    OR path:"%(link3)"
    OR path:"%(link4)"
  &sort=Title_prop_s asc
  &rows=4
  • Meldungen einer Fakultät oder eines mit einer Fakultät assoziierten Studiengangs könnten auf Instituts-Seiten ausgegeben werden.
  • Es bietet sich ein gemeinsames Kategorienmanagement an, bzw. einigen Sie sich auf eine bestehende globale Kategorie.
  • Nehmen Sie Abstand von der Idee, einen kompletten Stream-Inhalt zu übernehmen – setzen Sie dann lieber einen Link auf die Quelle!

Der Code

fq=
type:("news_v3" OR "event_v3" OR "social-media_v3" OR "video_v3“)
AND
   (
      parent-folders:"%(link1)“
   OR
      (
          parent-folders:"%(link2)"
      AND
               category:"gemeinsame_kategorie/"
    )
    )
&sort=beginn_%(locale)_dt desc
&rows=9

Support vom Webteam

 

TIK - NFL - Webteam

Allmandring 30, 70550 Stuttgart

Zum Seitenanfang