Help:Eingebettete Abfrage

Semantic MediaWiki beinhaltet für die semantische Suche eine einfache Abfragesprache, mit der eingebettete Abfragen erstellt werden können. Die Bearbeiter eines Wikis können mit ihnen bestimmte, auf dem Wiki hinterlegte Informationen, direkt abfragen. Aber auch Nutzer, welch die Inhalte des Wikis nur lesen, können von eingebetteten Abfragen profitieren, da die Abfrageergebnisse dynamisch erzeugt und auf der Seite eingebettet angezeigt werden. Von wenigen Nutzern erstellte eingebettete Abfragen, können somit von vielen Nutzern verwendet werden.

Eingebettete Abfrage sind anderen semantischen Suchfunktionen ähnlich und können auch auf einem Wiki beschränkt werden, um die Leistungsfähigkeit der Website zu wahren. Die von MediaWiki bereitgestellten Cachingmechanismen werden auch von den eingebetteten Abfragen genutzt. So ist es möglich, dass die allermeisten Abrufe von Seiten, die entsprechende dynamische Inhalte enthalten, ohne Leitungseinschränkungen auszuführen.

Parserfunktion #ask
Eingebettete Abfragen werden mit der Parserfunktion  erzeugt. Dabei werden die Abfrageanweisungen sowie die Ausgabeanweisungen direkt als Funktionsparameter angegeben. Die folgende Abfrage ist ein Beispiel hierfür:

Mit dieser Abfrage wird nach allen Städten gefragt, die sich in Deutschland befinden. Zudem werden zwei zusätzliche Ausgabeanweisungen genutzt, die erste ohne und die zweite mit weiteren Vorgaben. Nunmehr wird das folgende Ergebnis eingebettet auf der entsprechenden Seite ausgegeben.

Die Abfrageanweisungen werden direkt nach dem Funktionsaufruf  angegeben. Alle anderen Abfrageparameter, welche die Ausgabeanweisungen bilden, werden jeweils durch einen senkrechten Strich (Pipe) „ “ eingeleitet, und so voneinander getrennt, im Anschluss daran angegeben. Darin unterscheidet sich die Parserfunktion  nicht von allen anderen bei MediaWiki verfügbaren Parserfunktionen. Der Formatierung der Abfrage an sich ist nicht vorgegeben, im Sinn einer besseren allgemeinen Nachvollziehbarkeit hat es sich allerdings eingebürgert, je Ausgabeanweisung eine gesonderte Zeile zu nutzen. Diese Vorgehensweise entspricht dabei der bei derjenigen zur Erstellung von Vorlagen in MediaWiki und ist allgemein akzeptiert.

Es ist zu beachten, dass die bei der Parserfunktion  verwendeten Argumente bei der Generierung der Wikiseite ignoriert werden. Im obigen Beispiel wird also das Argument „ Liegt in::Deutschland “ nicht der Seite als Annotation hinzugefügt. Die folgenden Hinweise sind zudem im Zusammenhang mit dieser Parserfunktion wichtig:
 * Der senkrechte Strich (Pipe) „ “ wird dazu genutzt, die Abfrageanweisungen von den Ausgabeanweisungen zu trennen.
 * Die einzelnen Abfrageanweisungen bilden ein einziges Argument, so dass sie nicht durch einen senkrechten Strich (Pipe) „ “ voneinander getrennt werden.
 * Innerhalb einer Abfrage können Leerschritte und Umbrüche problemlos genutzt werden.
 * Das Format der Ausgabeanweisungen ändert sich mit der Abfrage zu Werten weiterer Attribute. Semantic MediaWiki wählt in diesem Zusammenhang ein passendes Standardausgabeformat für die Abfrageergebnisse. Die Ausgabe der Abfrageergebnisse kann allerdings detailliert gesteuert werden.

Grundlegende Kenntnisse zu Abfrageanweisungen sowie die Ausgabeanweisungen sind im Regelfall ausreichend um eine Vielzahl unterschiedlicher Abfragen erstellen zu können. In etlichen Fällen wird die Standardausgabe allerdings nicht ausreichend sein. Aus diesem Grund gibt es für eingebettete Abfragen zudem eine Vielzahl von Parametern, welche die Ausgabeanweisungen ergänzen.

Die allgemeine Syntax einer eingebetteten Abfrage entspricht dem folgenden Schema:

Diese Dokumentationsseite erläutert die unterschiedlichen im Zusammenhang mit eingebetteten Abfragen verfügbaren Argumente.

Parserfunktion #show
Abfragen werden häufig dazu genutzt, lediglich einen einzelnen Attributwert auf einer Seite anzuzeigen. Beispielsweise könnte man die Bevölkerungszahl Berlins in einen Artikel einfügen. Anstatt diese Information manuell einzufügen, kann man auch eine Abfrage nutzen, um dies zu bewerkstelligen. Bei Semantic MediaWiki gibt es die Parserfunktion  oder ab SMW 1.7.0 alternativ auch , die eine derartige Abfrage vereinfacht. Man könnte z. B. angeben, um die Bevölkerung Berlins anzuzeigen (Ergebnis: ). Diese Parserfunktion funktioniert wie eine eingebettete Abfrage und daher können auch alle für eine eingebettete Abfrage verfügbaren Parameter mit der Parserfunktion  genutzt werden. Die vorherige Abfrage kann auch mit der Parserfunktion  erstellt werden:  Die Angabe des Parameters „ “ mit anschließendem „ “ entfernt hierbei die erste Ergebnisspalte sowie deren Bezeichnung.

Ergebnis:

Ohne die Angabe dieses Parameters würde eine Tabelle mit zwei Spalten und Zeilen ausgegeben.

Ergebnis:

Standardparameter
Allgemein werden mit einer eingebetten Abfrage Seiten ermittelt, die bestimmte Kriterien erfüllen sollen. Sie muss daher die folgenden drei Fragen beantworten:
 * 1) Welche Seiten sollen abgefragt werden? (siehe hierzu die Hilfeseite Seitenauswahl für Abfrageanweisungen)
 * 2) Welche auf diesen Seiten vorhandenen Informationen sollen ausgegeben werden? (siehe hierzu die Hilfeseite Informationsanzeige für Ausgabeanweisungen)
 * 3) Wie sollen die ermittelten Informationen angezeigt werden? (siehe hierzu die Hilfeseite Ergebnisformate für Ausgabeanweisungen)

Die ersten beiden Fragen werden ausführlich auf den entsprechenden Hilfeseiten beantwortet. Die dritte Frage ist bedeutsam für die Anzeige der ermittelten Informationen, unterscheidet sich allerdings deutlich von den anderen beiden. Ohne weiter Einstellungen erstellt Semantic MediaWiki entweder Tabellen wie im Beispiel oben oder einfache Listen. Mit dem Parameter  können abweichende Ausgabeformate festgelegt werden. Beispielsweise wird mit der Angabe  eine aufgezählte Liste ausgegeben:

Das Ergebnis ist die folgende Ausgabe:

Semantic MediaWiki stellt für eingebettete Abfragen eine Vielzahl an möglichen Ausgabeformaten bereit, und ermöglicht es zudem die Ergebnisausgabe mit Vorlagen noch weitergehender zu steuern. Der Parameter  ist daher einer der wichtigsten verfügbaren Parameter für die Festlegung der Ergebnisausgabe. Siehe hierzu auch die Hilfeseite Ergebnisformate für weitergehenden Informationen.

Die folgende Tabelle stellt einen Überblick zu den allgemeinen Parametern dar, die bei eingebetteten Abfragen genutzt werden können:

Ergänzend zu den in der obigen Tabelle enthaltenen Parameter, verfügen etliche Ergebnisformate über zusätzliche spezifische Parameter. Die entsprechend vorhanden Parameter sind auf den Beschreibungsseiten der einzelnen Ergebnisformate angegeben.

Ausgabebegrenzung / Link zu weiteren Ergebnissen
Der Abfrageparameter  wird dazu genutzt die maximale Anzahl der anzuzeigenden Ergebnisse zu steuern. Beispielsweise werden mit der folgenden Abfrage

maximal drei Städte in Deutschland als Ergebnis angezeigt:

Selbst wenn man keinen Wert für  festgelegt, wird SMW eine automatische Begrenzung der anzuzeigenden Ergebnisse entsprechend des für den Konfigurationsparameter $smwgQDefaultLimit festgelegten Wertes  (Standarteinstellung ist 50) vornehmen. Die maximal mögliche Anzahl der mit dem Parameter  festlegbaren Ausgabeergebnisse wird indes mit dem Konfigurationsparameter $smwgQMaxInlineLimit gesetzt (Standarteinstellung ist 500). Beide Konfigurationsparameter werden vom Websiteadministrator eingestellt und können weder vom Wikiadministrator noch einem Nutzer verändert werden. Die Festlegung erfolgt zumeist aufgrund von Überlegungen hinsichtlich der Leistungsfähigkeit der Website beim Rechnen und der Ergebnisausgabe.

Das Abfragebeispiel zeigt auch, dass im Fall weiterer vorhandener Ergebnisse, die nicht direkt angezeigt werden können, automatisch ein Link zu weiteren Ergebnissen gesetzt wird. Der Text dieses Links kann mit dem Abfrageparameter  an die jeweiligen Bedürfnisse angepasst werden (Standarteinstellung lautet „… weitere Ergebnisse“). Sofern der Abfrageparameter  mit keinem Wert gesetzt wird, dann wird kein Link zu weiteren Ergebnissen angezeigt. Es gibt allerdings auch Ergebnisformate zu denen die Anzeige dieses Links zu weiteren Ergebnissen nicht vorgesehen ist, bzw. nur sofern diese ausdrücklich mit der Abfrage festgelegt wird.

Eine interessante Einsatzmöglichkeit der beiden Abfrageparameter  und   ist es, nur einen Link anstatt von Ergebnissen anzeigen zu lassen. Dies erreicht man, indem man für  den Wert „ “  oder „ “ setzt. Ein Beispiel:

führt zu folgender Anzeige:

Der Link „Hier klicken, um die Liste der Städte einzusehen.“ erscheint hierbei nur für den Fall, dass Ergebnisse  vorhanden sind. In jedem Fall wird die Abfrage stets ausgeführt, um zu Ermitteln, ob Ergebnisse vorhanden sind. Sofern der Link stets angezeigt werden soll, gleich ob Ergebnisse ermittelt werden konnten oder nicht, wird  mit dem Wert „ “ festgelegt. Ein Vorteil hieraus besteht auch in der Redzuierung der für die Abfrage notwendigen Rechenleistung.

Textparameter,  und
Sofern SMW keine Seite ermitteln kann, die den Bedingungen der entsprechenden Abfrage entspricht, wird nichts angezeigt. Dies kann durchaus nützlich sein, allerdings nicht in allen Fällen. In manchen Fällen ist es sinnvoll Hinweise abhängig davon anzuzeigen, ob Ergebnisse vorhanden sind, oder auch nicht. Eine Abfrage könnte wie folgt angezeigt werden:

Die nächsten Veranstaltungen: SMWCon Spring 2012, SMWCon Fall 2012, &hellip;

Hier wird mit der Abfrage eine Liste anstehender Veranstaltungen erzeugt. Sofern zu einem Zeitpunkt keine weiteren Veranstaltungen stattfinden, würden keine Ergebnisse angezeigt sondern nur:

Die nächsten Veranstaltungen:

Dies ist nicht sinnvoll. Es gibt zwei Abfrageparameter mit denen dies geändert werden kann:


 * : Mit diesem Parameter wird ein Standardtext angegeben, der angezeigt wird, sofern keine Ergebnisse vorhanden sind. Auf unser Beispiel angewendet könnte man den Parameter wie folgt setzen:

Die nächsten Veranstaltungen:

Damit wird die folgende Ausgabe erreicht:

Die nächsten Veranstaltungen: keine


 * : Dieser Parameter legt den Text fest, welcher der Ergebnisausgabe einer Abfrage vorangestellt werden soll, sofern ein oder mehrere Ergebnisse vorhanden sind. Bleiben wir bei unserem Beispiel:

Sofern keine Ergebnisse vorhanden sind, wird nicht angezeigt. Im vorliegenden Beispiel wird „&amp;nbsp;“ dazu verwendet ein Leerzeichen nach dem Doppelpunkt zu setzen, da die herkömmlichen Leerzeichen aus technischen Gründen am Anfang und Ende der Abfrageparameter automatisch entfernt werden.

Beide gerade dargestellten Lösungen werden die gewünschte Ausgabe anzeigen, sofern Ergebnisse vorhanden sind. Es ist zudem möglich beide Parameter zu kombinieren. Für die Angabe der Parameterinhalte kann auch Wikitext genutzt werden, also auch Links oder Vorlagen eingefügt werden, solange es zu keinen Konflikten mit der Parserfunktion #ask führt.

Mit dem Parameter  kann Text angegeben werden, der im Anschluss an Abfrageergebnisse ausgegeben werden soll. Auch dies kann sinnvoll sein.

Hinweise:
 * Abfragen ohne Ergebnis führen standardmäßig zu keiner Ausgabe, also weder zu einer Leerzeile noch zu einem Leerschritt. Dadurch fügen sich ergebnislose Abfragen gut in Seiten und Fließtexte ein. Dadurch kann allerdings deren Vorhandensein auch leichter übersehen werden.
 * Es ist nicht empfehlenswert zu viele Abfragen in eine Seiten einzufügen, da jede Abfrage, gleich ob sie zu Ergebnissen führt oder nicht, Rechenleistung in Anspruch nimmt. Daher sollte jede nicht mehr benötige Abfrage wieder entfernt werden. In diesem Zusammenhang ist die Nutzung der hier beschriebenen Textparameter sinnvoll, wenn man sicherstellen möchte, dass man vorhandene Abfragen leicht erkennen kann und somit nicht in Vergessenheit geraten.

Sortierung
Auf der Hilfeseite Seitenauswahl wurde erläutert, dass Abfrageergebnisse nach mehr als einem Attribut sortiert werden können. Hierbei verfügt die Spezialseite Spezial:Semantische Suche über zusätzliche Eingabefelder mit denen festgelegt werden kann, nach welchen Attributen sowie in welcher Reihenfolge diese sortiert werden sollen. Bei eingebetteten Abfragen wird die Sortierung mit dem Abfrageparameter  und die Sortierreihenfolge mit dem Abfrageparameter   angegeben. Die Werte für   können  „ “ und „ “ oder „ “ bzw. deren Kurzformen „ “ sowie „ “ sein. Wird nichts bei  angegeben, so wird automatisch „ “ angenommen. Auch der Wert „ “ bzw. dessen Kurzform „ “, mit dem eine zufällige Sortierung erreicht wird, ist möglich. Die zufällige Sortierung kann allgemein mit dem Konfigurationsparamter $smwgQRandSortingSupport deaktiviert werden.

Ein Beispiel für die Sortierung ist die folgende Abfrage nach den drei größten Städten in Deutschland:

Die mit der Sortieranweisung angegebenen Sortierbedingungen können auch die Anzahl der Abfrageergebnisse beeinflussen (siehe hierzu die Hilfeseite Seitenauswahl). Im obigen Fall werden daher lediglich die Städte in Deutschland berücksichtigt, zu denen die Bevölkerungszahl hinterlegt wurde.

Für den Fall, dass nach mehr als einem Attribut sortiert werden soll, können die Parameter  und   auch mehrerer Werte aufnehmen, die durch Kommata voneinander zu trennen sind. Hierzu folgendes Beispiel:

Diese Abfrage gibt alle Städte in Deutschland aus, zu denen sowohl Angaben zum Bundesland sowie zur Bevölkerungszahl gemacht wurde. Zunächst wird dabei alphabetisch aufsteigend nach Bundesland und hernach innerhalb des jeweiligen Bundeslands absteigend nach Bevölkerungszahl sortiert.

Es ist auch möglich die Hauptergebnisspalte eindeutig für die Sortierung festzulegen, sofern mehr als eine Sortierbedingung angegeben wird. Die Festlegung erfolgt durch das, je nach Sortierposition, Voranstellen oder Anschließen eines Kommas „ “ in der Sortieranweisung. Die nicht vorhandene Bezeichnung wird als Hauptergebnisspalte interpretiert. Ein Beispiel:

Diese Abfrage gibt alle Städte in Deutschland aus, zu denen eine Angabe zum Bundesland gemacht wurde. Zunächst wird dabei alphabetisch aufsteigend nach Bundesland und hernach innerhalb des jeweiligen Bundeslands alphabetisch absteigend nach Stadt sortiert.

Bezeichnungen/Spaltenüberschriften konfigurieren
Abfragen mit denen mehr als nur die Ergebnisseiten ausgeben werden, z. B. im obigen Beispiel auch die Bevölkerungszahl, zeigen zu den unterschiedlichen Ausgaben auch die jeweils entsprechenden Bezeichnungen an. Standardmäßig wird dabei der Name des jeweiligen Attributs angegeben, bzw. die Bezeichnung Kategorie, sofern Kategorien angezeigt werden. Die Namen der Attribute werden dabei auf die zugehörige Attributseiten im Namensraum Attribut verlinkt.

Bei den Ergebnisformaten table und broadtable erscheinen diese Namen als Spaltenüberschriften. Bei anderen Ergebnisformaten können die Bezeichnungen auch direkt vor der Ergebnisausgabe erscheinen. Der Text der Bezeichnungen kann entspechend den Erläuterungen auf der Hilfeseite Informationsanzeige verändert werden, indem man direkt zur jeweiligen Festlegung der Ergebnisausgabe ein Gleichzeitszeichen „ “ setzt, dem die gewünschte Änderung folgt. Ein Beispiel:

Das Ergebnis der Abfrage ist:

Leere sowie ausgeblendete Bezeichnungen sind für Ergebnisspalten ebenso möglich. Im Fall von Tabellen wird allerdings stets die Kopfzeile angezeigt, auch wenn sie nicht angezeigt werden soll. Um die Kopfzeile der Tabelle auszublenden oder zu verändern, gibt es den Abfrageparameter, zu dem die folgenden drei Werte gesetzt werden können:
 * : Bezeichnungen/Spaltenüberschriften anzeigen (Standardeinstellung, auch wenn der Parameter nicht gesondert angegeben wird)
 * : Bezeichnungen/Spaltenüberschriften ohne Verlinkung zur Attributseite (verfügbar sein SMW 1.4.3)
 * : Bezeichnungen/Spaltenüberschriften nicht anzeigen

Dieser Abfrageparameter kann für Tabellen sowie andere Ausgabeformate genutzt werden. Der letztgenannte Abfrageparameter  wird in den letztgenannten Fällen alle Bezeichnung ausblenden, selbst wenn eine Bezeichnung ausdrücklich bestimmt wurde.

Änderungen an der ersten Ergebnisspalte
Abfragen geben standardmäßig die Ergebnisseite an erster Stelle aus, z. B. in der ersten Spalte einer Ergebnistabelle. Dabei wird die Spaltenbezeichnung leer gelassen. Um die Bezeichnung der Spalte zu ändern, an einer anderen Position anzeigen lassen oder gar die gesamte Spalte mit den Ergebnisseiten auszublenden, nutzt man den Abfrageparameter. Die mit diesem Parameter angegebene Bezeichnung wird als Bezeichnung der ersten Ergebnisspalte ausgegeben. Ein Beispiel:

Folgende Tabelle wird ausgegeben:

Der Paramter kann auch dazu genutzt werden, die erste Spalte komplett auszublenden. Hierzu gibt man anstatt einer Bezeichnung ein Minuszeichen „ “ an. Um die Spalte zudem an einer anderen Stelle einzufügen, wird ein Fragezeichen „ “ gefolgt von einem Gleichheitszeichen „ “ gesetzt. Ggf. wird zudem noch die gewünschte Bezeichnung für die Spalte angegeben.

Das folgende Beispiel wandelt das vorhergehende Beispiel ab, indem die Spalte mit den Städten nach der Spalte mit der Anzahl der Einwohner angezeigt wird:

Folgende Tabelle wird ausgegeben:

Ergebnisformate
Mit dem Abfrageparameter  wird festgelegt in welchem Format die Ergebnisse der Abfrage ausgegeben werden sollen. Auf der Hilfeseite Ergebnisformate befindet sich eine detaillierte Übersicht zu den verfügbaren Ergebnisformaten.

Ergebnisse exportieren
Einige der Ergebnisformate ermöglichen den Export von Daten aus dem Wiki. Zusätzlich stellt die Erweiterung Semantic Result Formats weitere Exportformate bereit. Die Exportformate unterscheiden sich in zweierlei Hinsicht von den anderen Ergebnisformaten:
 * 1) Anstatt die Abfrageergebnisse in der Seite eingebettet auszugeben, wird lediglich ein Link auf die Spezialseite Semantische Suche angezeigt, der nach dem Anklicken die Daten im entsprechenden Exportformat zum Herunterladen anbietet. Dieser Link ist dem Link „… weitere Ergebnisse“ ähnlich, verwendet aber einen abweichenden Standardtext, wie bspw. „RSS“. Es ist daher möglich den Text des Links mit dem Abfrageparameter   anzupassen.
 * 2) Sie nutzen festgelegte Standardformate, um die Abfrageergebnisse zu vorher nicht festgelegten und frei angebbaren Inhalten auszugeben. Daher muss, abgesehen von den Exportformaten CSV und DSV, beim Erstellen der Abfrage angegeben werden, welches Attribut welchem Datenfeld beim Export zuzuordnen ist.

Aufgrund des zweiten Unterschieds müssen also mit den Ausgabeanweisungen zu den Attributen, auch die jeweils entsprechenden, für den Datenexport verfügbaren Datenfelder zugeordnet werden. Beispielsweise können mit dem Format „vCard“ alle möglichen Informationen zu den Kontaktdaten einer Person angegeben werden, jedoch nicht mit Hilfe beliebiger Attribute. Um anzugeben, welches Attribut welchem Exportdatenfeld zuzuordnen ist, wird zum auszugebenden Attribut, die zugehörige, durch das Exportformat festgelegte, Bezeichnung angegeben. Das Format „vCard“ unterstützt, neben weiteren hier nicht genannten Datenfeldern, die Datenfelder „firstname“ für Vorname, „lastname“ für Nachname und „homepage“ für die Homepage. Eine entsprechende Abfragen würde wie folgt aussehen:

Das Beispiel zeigt, dass im Wiki die Attribute mit den Namen „firstname“ und „lastname“ bereits vorhanden sind. Eine gesonderte Bezeichnung ist daher nicht anzugeben. Die Angabe zur Homepage wird im Wiki allerdings mit dem Attribut „url“ gespeichert, d. h. für die korrekte Ausgabe muss die Zuordnung zum Datenfeld „homepage“ mit der Ausgabebezeichnung „homepage“ angegeben werden, damit der entsprechende Attributwert während des Exports erkannt werden kann. Auf diese Weise können beliebig festgelegte Attributnamen genutzt und dennoch problemlos exportiert werden. Auf den Dokumentationsseiten der entsprechenden Exportergebnisformate sind die jeweils verfügbaren Datenfeldbezeichnungen dokumentiert.