Allgemein

Abfragen gegen JDBC Content Stores werden in HQL (Hibernate Query Language) formuliert, der integrierten Abfragesprache von Hibernate, einer Software die zwischen den Objekten in WGA (Content-Dokumente, Struktureinträge etc.) und den relational gespeicherten Daten vermittelt. Eine umfangreiche Dokumentation zu HQL finden sie in der Hibernate-Dokumentation.

WGA vereinfacht die Verwendung von HQL soweit, dass sie nicht die Objekte angeben müssen, welche sie ermitteln wollen (was in WGA grundsätzlich Inhaltsdokumente sind) sondern lediglich die Bedingungen formulieren müssen, welche Inhaltsdokumente haben müssen um zum Suchergebnis zu gehören. Folgende HQL-Query beispielsweise sucht ein Dokument mit dem eindeutigen Namen "home":

<tml:query type="hql">content.uniquename = 'home'</tml:query>

Muss die gesamte HQL-Query formuliert werden (was in einigen Spezialfällen notwendig sein kann) so kann man den Querytypen als "fullhql" anstelle "hql" angeben. Hierbei wird dann eine komplette valide Hibernate-HQL-Abfrage als Eingabe erwartet, in welcher das zu ermittelnde Inhaltsdokument folgendermaßen anzugeben ist:

Generelle Syntax

Die Syntax von HQL ist objektorientiert. Man arbeitet mit Objekten und deren Eigenschaftswerten, die Text-, Nummer- oder Datumswerte sein können oder wiederum selbst Objekte mit eigenen Eigenschaftswerten.

Basis einer Query in WGA ist immer das Objekt "content". Fragt man eine Eigenschaft des Objektes „content“ ab, so stellt man sie mit einem Punkt dem Objektnamen hinten an:

content.title = 'Home'

Bestimmte Eigenschaften von Objekten sind wiederum selbst Objekte mit eigenen Eigenschaften. Will man die Eigenschaften dieser Objekte abfragen, stellt man sie wiederum mit einem Punkt hinten an:

content.language.name = 'de'

Hier wird die Eigenschaft „language“ des Objektes „content“ abgefragt. Da diese Eigenschaft selbst wieder ein Objekt "language" ist, können dessen Eigenschaften, wie „name“ in diesem Beispiel, durch Anfügen eines weiteren Punktes abgefragt werden.

Die verfügbaren Objekte und Eigenschaften der Objekte in WGA sind als Unterkapitel dieses Dokumentes dokumentiert.

Umgang mit Listeneigenschaften

Bestimmte Eigenschaften bestehen aus Listen von Einzelwerten oder Objekten. Diese Listen sind entweder mit einer Nummer oder einem Textbezeichner indiziert, d.h. über Angabe einer Nummer oder einem Textbezeichner gelangt man zu den einzelnen Objekten in der Liste.

Will man eines der Listenelemente einzeln adressieren, so setzt man den Index in eckige Klammern dem Bezeichner hinten an:

content.items['body'].text != ''

In diesem speziellen Fall beinhaltet die Content-Eigenschaft „items“ eine Liste, die mit Textbezeichnern (den Itemnamen) indiziert ist. Elemente dieser Liste sind wiederum Objekte vom Typ Objekt "contentItem" (der Typname ist hierbei unwichtig). Content-Items haben selbst eine Eigenschaft „text“, welche den Textinhalt des Items enthält, gesetzt den Fall es handelt sich um ein Text-Item.

Alle Listeneigenschaften haben selbst wiederum die Eigenschaft „size“, mit welcher Anzahl der Listenelemente geprüft werden kann:

content.items.size > 10

Weitere implizite Eigenschaften von Listen sind:

- „minIndex“ und „maxIndex“: Kleinster und größter Indexwert.

- „minElement“ und „maxElement“: Erstes und letztes Element aller Listenelemente (NICHT die Elemente am kleinsten und grössten Index!), wenn die Listenelemente selbst keine Objekte sind.

Diese Eigenschaften funktionieren nicht auf Datenbanksystemen, die keine Subqueries unterstützen (wie z.B. MySQL 4.0).

Allgemeine Operatoren

Allgemeine Operatoren sind solche Operatoren, die nicht in Abhängigkeit zu einer speziellen Funktion stehen, sondern generell überall verwendet werden können.

Mehrere Ausdrücke können mit Operatoren verbunden werden, wie sie in SQL üblich sind:

content.title = 'Home' AND content.language.name = 'de'
content.title = 'Home' OR content.language.name = 'de'
content.title = 'Home' AND NOT content.language.name = 'en'

Mit Klammerungen kann die Präzedenz der Operatoren festgelegt werden:

content.title = 'Home' AND
(content.language.name = 'en' OR  content.language.name = 'de')

Auf leere Eigenschaften kann mit folgendem Operator getestet werden:

content.virtuallink is not null

Neben dem Gleichheits-Operator gibt es auch den Ungleichheits-Operator und Grösser/Kleiner-Operatoren:

content.structentry.position != 0
content.structentry.position > 0
content.structentry.position >= 0

Desweiteren gibt es den „like“-Operator, der eine String-Matching-Funktionalität ausführt. Als Wildcards wird „?“ für eine einzelnes beliebiges Zeichen und „%“ für eine beliebige Anzahl beliebiger Zeichen verwendet:

content.title like '%wga%'

Der „in“-Operator prüft, ob sich ein Wert in einer Menge von Werten befindet:

content.structentry.doctype.name in ('Standard', 'Homepage', 'News')

Der „between“-Operator prüft, ob ein Wert sich in einem Wertbereich befindet:

content.structentry.position between 0 and 10

Der Operator „exists“ prüft auf das Vorhandensein von Listenelementen:

exists content.items['body']

Sortierung

Es ist möglich, HQL eine Sortierung der Ergebnisse vorzugeben. Das ist in aller Regel performanter, als die (nachträgliche) Sortierung per WebTML. Dazu muss dem Selektionsausdruck (wenn vorhanden) eine „order by“-Klausel angefügt werden:

order by content.title, content.created

Auch die Sortierung nach Itemwerten ist seit WGA4 möglich:


Items in HQL

Items sind in HQL eigene Objekte, die in der Listeneigenschaft „items“ des Content-Objektes gespeichert sind. Diese Listeneigenschaft ist mit den Namen der Items - in Kleinbuchstaben - indiziert:

content.items['body']

Die Items wiederum besitzen selbst Eigenschaften, welche ihre Inhaltswerte enthalten. Je nach Datentyp des Items muss eine andere Eigenschaft abgefragt werden:

content.items['body'].text
content.items['weight'].number
content.items['salestime'].date

Items können  auf bestimmte Werte überprüft werden:

content.items['type'].text = 'article'
content.items['count'].number = 5
content.items['startdate'].date > '2005-05-01 10:00:01.0' 

Seit WGA 4.0 ist auch die beliebig kombinierte Abfrage mehrerer Itemwerte möglich:

content.items['type'].text = 'article' AND content.items['count'].number = 5

Funktionen

Funktionen haben einen Funktionsnamen und übernehmen in runden Klammern Parameter.

Eine Funktion, die Tests gegen alle Elemente einer Liste erlaubt, ist „elements“:

'Hamburg' in elements(content.keywords)

Dieses Beispiel selektiert Contents, in deren Keywords sich das Wort „Hamburg“ befindet.

In Kombination mit dem „in“-Operator kann man so gegen alle Werte eines Items testen.

Ein weiterer Operator, der in Zusammenhang mit „elements“ benutzt werden kann, ist „all“. Er testet, ob alle von Elemente einer Liste demselben Wert entsprechen:

„nav“ = all elements(content.ishiddenfrom)

Dieses Beispiel prüft, ob ein Dokument nur für Navigatoren versteckt ist.

Die Funktionen „upper“ und „lower“ erlauben die Manipulation von Strings, so dass diese nur aus Gross- bzw. Kleinbuchstaben bestehen:

upper(content.title) like „%HAMBURG%“

Hibernate erlaubt es, spezielle Funktionen, die vom verwendet

en Datenbank-Server unterstützt werden, in HQL zu integrieren. So kann z.B. die MySQL-Funktion „date_sub“ auch in HQL verwendet werden, wenn als Datenbank-Backend ein MySQL-Server fungiert:

content.lastmodified < date_sub(NOW(), INTERVAL 10 DAY)

Diese Query ermittelt die Content-Dokumente, die in den letzten 10 Tagen verändert worden sind.