Suche über die IES-API

Aus SiteparkWiki
Zur Navigation springen Zur Suche springen

Für die IES API wurde ein neuer Query-Parser entwickelt der die Anforderung an die IES API erfüllt. Eine Query muss folgender Syntax entsprechen:

   SELECT {field}[§{type}][#{locale}][->{field}[§{type}][#{locale}]] [AS {alias}], ...
   [
      PARENT {parent} |
      REFERRER {parent} {field}[§{type}][#{locale}][->{field}[§{type}][#{locale}]] |
      REFERENCE {parent} {field}[§{type}][#{locale}][->{field}[§{type}][#{locale}]]
   ]
   WHERE {where_condition}
   [SORT {field}[§{type}][#{locale}][->{field}[§{type}][#{locale}]]][ ASC | DESC], ...|RANDOM
   [LIMIT {offset} [,{row_count}]]
   [OPTIONS {name}={value}, ...]


Felddefinition für SELECT, REFERRER, REFERENCE, WHERE und SORT

Felder über Links

Es ist möglich Felder von Objekten zurückzuliefern, auf die das Treffer-Objekt verweist. So wird mit

sp_mylink->sp_mytext

auf das Feld 'sp_mytext' des Objektes zugegriffen auf das das Treffer-Objekt über den Link 'sp_mylink' verweist.

Feldtypen (Nur für IES-2 Abwärtskompatibilität)

Um auf Felder zuzugreifen bei denen ein Type definiert wurde wird der Trenner § verwendet. So wird mit

sp_mylink§link

auf das Feld 'sp_mylink' vom Type link zugegriffen.

Sprache des Feldes

Bei mehrsprachigen Feldern kann die gewünschte Sprache mit dem Trenner # angegeben werden. So wird mit

sp_mytext#de

das Feld mit der Sprache de zurückgegeben.

Wird keine Sprache angegeben, wird die Default-Sprache verwendet

sp_mytext

ist äquivalent zu

sp_text#default

Um Sprachübergreifend zu suchen, kann * angegeben werden

sp_text#*

Achtung: Sprachübergreifende Suchen können nicht im Volltext-Index (LUCENE_SEACH()) angewendet werden. Der Grund dafür ist, das sprachspezifische Stopp-Wörter und Wort-Stämme in dem Volltext-Index relavant sind.

Wildcards für hierarchische Feldnamen

Für hierarchische Feldnamen können Wildcards angegeben werden, um Feldnamen in verschiedenen Ebenen anzusprechen. Hierfür kann ein einfacher Stern (*) für eine Ebenen oder zwei Sterne (**) für beliebige Ebenen verwendet werden.

Beispiele: Ein bestimmtes Feld in einer Ebene

*.sp_mytext

Verwendet alle Felder mit dem Namen sp_mytext, die in der zweiten Ebene liegen wie

mylist[2].sp_mytext
mylist[5].sp_mytext
mysub.sp_mytext


Beispiele: Ein bestimmtes Feld in beliebiger Ebene

**.sp_mytext

Verwendet alle Felder mit dem Namen sp_mytext, die in mindestens der zweiten Ebene liegen

mylist[2].sp_mytext
mylist[5].sp_mytext
mysub.sp_mytext
mysub.mylist[1].mytext
mylist[5].mysub.sp_mytext
mylist[5].mysublist[3].sp_mytext
mylist[5].mysublist[3].mysub.sp_mytext


Beispiele: Beliebiges Feld in einer bestimmten Ebene

sp_mylist.*

Verwendet alle Felder die in der ersten Ebene vom sp_mylist liegen

sp_mylist[2].sp_text
sp_mylist.sp_text2


Beispiele: Beliebiges Feld ab einer bestimmten Ebene

sp_mylist.**

Verwendet alle Felder die unterhalb von sp_mylist liegen

sp_mylist[2].sp_text
sp_mylist.sp_text2
sp_mylist[4].sp_sub.sp_text3


Bei tieferen Strukturen können * und ** kombiniert werden. Hier einige Beispiele

*.a.**
**.a.**
**.a.*.c
*.a.x.**

Aus Performanz-gründen können maximal 4 Felder angegeben. Bei Feldnamen mit mehr als 4 Ebenen kann nur nach den ersten bzw. letzten Ebenen gesucht werden. Folgender Feldname

a.b.c.d.e.f.g

kann nur bis zu den ersten 3 Feldern oder den letzten 3 Felder mit Wildcards angegeben werden

a.b.c.**
a.**.g
**.e.f.g

Alle Kombinationen die sich auf die ersten und letzten Felder beschränken sind möglich.


Wildcards innerhalb von Feldnamen wie sp_* sind nicht möglich!

Kombinationen für die Felddefinition

Die Oben angegebenen Felddefinitionen können beliebig mit einander kombiniert werden. Wichtig ist dabei nur das die Reihenfolge

{field}§{type}#{locale}->{field}...

eingehalten wird. Hier ein paar Beispiele

sp_mylink§systemlink->sp_mytext#de
sp_mylink§link->sp_myLocaleLink#de->sp_mytext
sp_myLocaleLink#de->sp_myimage§url
**.sp_mylink§systemlink->mylist.**.sp_mytext#de

SELECT

Alle nach SELECT angegebenen Felder werden im QueryResult zurückgegeben. Folgende Felder werden immer zurückgegeben:

  • id - ID des Treffers
  • real - ID des Objektes (nur wenn id ein symbolischer Link ist.
  • anchor - Anchor des Treffers oder null, wenn Treffer keinen Anchor hat
  • parent - Parent des Treffers

Zu den Möglichkeiten Felder zu definieren siehe: Felddefinition

Alias

Der in dem QueryResult enthaltene Feldname kann mit Hilfe von {field} AS {alias} gändert werden. So kann Beispielsweise mit

sp_mytext AS text

das Feld sp_mytext in dem QueryResult unter dem Name text enthalten sein.

Sonderfelder

Folgende Feldnamen sind Schlüsselwörter und übernehmen Sonderfunktionen

worklist
Mit diesem Schlüsselwort kann eine Worklist eines Nutzers oder einer Nutzergruppe abgefragt werden. Z.Z. in nur der gleich-Operator möglich. Als Wert kann eine ID oder ein Anchor angegeben werden
worklist = 100010100000001076-3002
responsible
Mit diesem Schlüsselwort kann der Verantworliche für Objekte des Systems abgefragt werden. Z.Z. in nur der gleich-Operator möglich. Als Wert kann eine ID oder ein Anchor angegeben werden
responsible = 100010100000007846-1015

Geplante Erweiterung:

Merhfachwerte als Liste zurück liefern.
list({field})
Wenn mehrere Felder mit dem Namen field existieren wird eine Liste zurück geliefert.
field: [ "value1", "value2", "value3" ]
Mehrfachwerte mit erweiterten Daten
complex({field})
Wenn mehrere Felder mit dem Namen field existieren wird eine Liste zurück geliefert.
field: [ { path: "mylist[1].mylink->100010100000001143-1015:mylist[3]" value: "value1" },{ path: "mylist[3].mylink->100010100000001143-1015:mylist[4]" value: "value2" } ]
Condition innerhalb eines Iterator-Blocks
{ mynum = 10 & mytext = "hans" }
Nur Objekte finden, in denen die beiden Felder innerhalb eines Iterator-Blocks die angegebenen Werte haben
{ mynum = 10 & { mylink->mylink->{mytext = "hans" | mytext = "peter" } } }
Nur Objekte finden, die innerhalb eines Iteratorblocks mynum = 10 haben und mylink entsprechend gesetzt ist.

PARENT | REFERRER | REFERENCE

Mit diesen Schlüsselwörtern kann eine NodeQuery definiert werden. Eine NodeQuery ist eine Suchabfrage die Objekte anhand einer Verknüpfung zu einen obergeordneten Objekt zurückliefert.

Im IES gibt es 3 verschiedene Arten von Verknüpfungen, die hierarchische Strukturen abbilden können:

  • Parent eines Objektes: Jedes Objekt besitzt einen Parent, in dem es eingeordnet ist (Im IES-2 wird diese Parent 'Pool' genannt, Im IES-3 sollte hier nur noch von Parent gesprochen werden)
  • Link auf ein übergeordnetes Objekt: Ein Objekt ist mit einem übergeordneten Objekt verknüpft. Über diese Art der Verknüpfung werden z.B. in Infosite Navigations-Strukturen für Webseite definiert.
  • Link auf ein Untergeordnetes Objekt Ein Objekt ist min einem untergeordnetem Objekt verknüfpt.

Mit Hilfe der Schlüsselwörter PARENT, REFERRER und REFERENCE kann die Art der Verknüpfung angegeben werden über die nach den Untergeordneten Objekten gesucht werden soll.


Mit {parent} wird der Parent angegeben, dessen Unterelemente zurück geliefert werden sollen. Hier kann der Anchor oder die ID angegeben werden.

PARENT 100080100000002418-1017

oder

PARENT gui.informations


PARENT {parent}
Definition einer NodeQuery, die Objekte zurück liefert, die den angegebenen Parent haben.
Im IES-2 ist es nicht möglich Unter-Elemente und Unter-Pools in einer Suchabfrage zurück zuliefern (das Datenmodell lässt das nicht zu). Deswegen muss in dem WHERE Statement eine Einschränkung wie
WHERE objectclass = 'Parent'
oder
WHERE objectclass != 'Parent'
angegeben werden. Dadurch ist gewährleistet das die Query auch im IES-3 die gleichen Treffer liefern wird. Wird diese Einschränkung nicht angegeben wird ein Fehler zurückgegeben.
REFERRER {parent} {field}[§{linktype}][#{locale}]
Definition einer NodeQuery, die Objekte zurück liefert, die auf das mit {parent} definierten Objekt verlinken. Weiter muss angegeben werden, über welchen Link die Verknüpfung angelegt ist.
REFERRER information.g09.homepage sp_parent§link
Zu den Möglichkeiten Felder zu definieren siehe: Felddefinition


REFERENCE {parent} {field}[§{linktype}][#{locale}]
Definition einer NodeQuery, die Objekte zurück liefert, auf die das mit {parent} definierte Objekt verlinkt. Weiter muss angegeben werden, über welchen Link die Verknüpfung angelegt ist.
REFERENCE information.g09.homepage sp_parent§link
Zu den Möglichkeiten Felder zu definieren siehe: Felddefinition


WHERE

Der Ausdruck nach dem WHERE bestimmt die Filterkriterien, nach denen die Ergebnisse zurück geliefert werden sollen. Filterkriterien können mit AND und OR verknüpft und mit Klammern verschachtelt werden.

(a = 1 AND b = 2) OR ((a = 2 AND b = 1) AND (c = 3))

Um einzelne Ausdrücke zu negieren wird NOT verwendet

a = 1 AND NOT(b = 2)

Ausrücke sind entweder Bedingungen oder Funktionen

Bedingungen

Bedingungen bestehen immer aus einem Feld, einem Operator und einem Wert

a = 1

Mögliche Felder siehe: Felddefinition

Operatoren sind:

= gleich
!= ungleich
< kleiner als
> grösser gleich
<= kleiner gleich als
>= grösser gleich als
LIKE Textvergleich mit Platzhaltern. '_' für ein beliebiges Zeichen und '%' für kein, ein oder mehrere beliebige Zeichen.
a LIKE 'abc%' - (alles was mit 'abc' beginnt)
a LIKE 'a_c' - (alles was drei Zeichen lang ist und mit 'a' beginnt und mit 'c' endet)
a LIKE '%abc%' - (alles was 'abc' enthält. ACHTUNG: Bei dieser Variante kann kein Datenbank-Index verwendet werden und die Suche wird ggf langsam.
IN Enthät einen Wert aus der Liste
a IN (1,2) - (wenn a den Wert 1 oder 2 hat)
x IN ('a', 'c')
parent IN (100010100000001128-2000,100010100000001129-2000)
parent IN (!{my.parent1.anchor},!{my.parent2.anchor})

Werte sind:

Boolean true oder false
a = true
Number Ganzzahlen und Dezimalzahlen
a = 1
a = 1.2
Text Texte werden in einfache Anführungszeichen 'abc' oder doppelte Anführungszeichen gefasst "abc". Im Text enthaltenen Anführungszeichen müssten mit einem Backslash escapte werden.
sp_title = 'Toms\'s Hütte'
ID Die ID eines Objekts. Siehe (ID)
parent = 100010100000001128-2000
mylink->parent = 100010100000001128-2000
Anchor Alternativ zu der ID kann auch ein Anchor angegeben werden. Diese wird in !{...} gefasst und bei der Ausführung der Suche aufgelöst.
parent = !{my.parent.anchor}
mylink->parent = !{my.parent.anchor}
Anchor können auch direkt gesucht werden, wenn mit dem Feld anchor gesucht wird. In diesem Fall ist der Anchor ein textuelles Suchkriterium und wird mit Anführungszeichen angegeben.
anchor = 'my.parent.anchor'
mylink->anchor = 'my.parent.anchor'
Funktionen

Funktionen stellen spezielle Filterkriterien bereit. Funktionen im WHERE-Teil liefern keine Rückgabewerte sondern schränken das Suchergebnis direkt ein.

Verfügbare Funkionen sind:

luceneSearch()
spmlSearch()

SORT

Sortierung eines Suchergebnisses. Hier können kommasepariert Feldnamen (mit Typen) angegeben werden um die Sortierkriterien zu definieren. Die Sortierrichtung kann mit ASC aufsteigend oder DESC absteigend angegeben werden. Wird keine Sortierrichtung angegeben wird aufsteigend sortiert.

SORT sp_date DESC, sp_title

Zu den Möglichkeiten Felder zu definieren siehe: Felddefinition


LIMIT

Um nur eine begrenzte Anzahl von Treffer zurück zu liefert, kann LIMIT verwendet werden. LIMIT kann mit ein oder zwei Argumenten verwendet werden. Wird LIMIT mit einem Argument verwendet wird die Anzahl der angegeben Treffer zurückgeliefert.

LIMIT 10

Liefert die ersten 10 Treffer zurück.

Wird LIMT mit zwei Argumenten verwendet, gibt das erste Argument den Offset der Treffer an. Der Offset beginnt mit 0. Das zweite Argument gibt die Anzahl der zurück zu liefernden Treffer an.

LIMIT 0,10

Liefert die ersten 10 Treffer zurück,

LIMIT 9,10

Liefert die Treffer 10 bis 19 zurück.

OPTIONS

Mit der Angabe von Optionen kann das verhalten der Suche noch weiter beeinflusst werden. Optionen werden kommasepariert, Name und Wert durch ein Gleich (=) getrennt.

OPTIONS number=1, boolean=true, text='abc', array=['a','b']

Folgende Optionen stehen zur Verfügung:

showHide=true|false
Eine Suche liefert immer nur die Objekte, auf die der angemeldete Nutzer lesende Rechte hat. Zusätzlich zu dem lese-Recht gibt es noch den Zusatz 'hide'. Damit können Objekte einem Nutzer vorenthalten werden, auch wenn dieser die nötigen Rechte besitzt. Mit Angabe dieser Option kann gesteuert werden, ob die 'versteckten' Objekte in dem Ergebnis enthalten sein sollen.
ignoreClassFields=Array (ab Version 1.4.10)
Bei Feldnamens-Konflikten zwischen Content-Feldern und Classen-Feldern kann die Auswertung der Classenfelder deaktiviert werden. Diese Option ist als Workarround gedacht, bis die Möglichkeit geschaffen wird, den Feld-Scope direkt anzugeben als z.B. SELECT Content:disabled, User:disabled. Der Option muss ein Array mit den Classen als Text übergeben werden: ignoreClassField=['User']. Gültige Werte sind 'User', 'Template', 'Directory'

Geplante Optionen:

locale='de'
Wird diese Option angegeben werden bei der Suche nur die Daten einer bestimmten Sprache berücksichtigt.
published='www|preview'
Wird diese Option angegeben werden bei der Suche nur die Daten berücksichtigt, die ein den angegebenen Publikationsbereichen publiziert sind. Es können mehrere Publikationsbereiche angegeben werden (Anchor oder ID). Werden die Publikationsbereiche mit (|) getrennt müssen die Objekte mindestens in einem der angegebenen Publikationsbereiche publiziert sein. Werden die Publikationsbereiche mit (&) getrennt müssen die Objekte in allen angegebenen Bereichen publiziert sein.
Hinweis zum IES-3
Für den IES-3 wird bei Angabe diese Option auch nur in den Daten gesucht, die für die angegebenen Publikationsbereiche publiziert sind.


Funktionen

Über Funktionen können komplexere Such-Anforderungen erfüllt werden

Funktion Beschreibung SELECT WHERE Countable
count(countable) Liefert die Anzahl einer Listen-Operation. Listen-Operationen sind z.B. Funktionen die Countable sind. Ja, Beispiel:
SELECT count(referrerLinks()) AS c WHERE ...
Nein Nein
date(),

date(milleseconds),
date(year, month, day [, hour [, minutes [, seconds [, milliseconds]]]])

Erzeugt ein Datum (Aktuelles Datum oder Angabe über Zeitstempel in Millisekunden bzw. Datumsangabe)

Mit erweiterten Funktionen können noch Datumsberechnungen vorgenommen werden.

Nein Ja, Beispiele:
SELECT ... WHERE sp_date > date()
SELECT ... WHERE sp_date > date(1427788800000)
SELECT ... WHERE sp_date > date(2015, 3, 10, 20, 30)

Um relative Zeitverschiebungen vorzunehmen stehen folgende Funktionen zur Verfügung

date().plusMinutes(3)
oder
date().plus(3, 'minutes')
Nein
dependenciesFrom(id|anchor) Liefert die Abhängigkeiten, die durch die Publikation entstehen. Geliefert werden die Objekte die Daten dieses Objektes verwenden. Ja, Beispiel:
{
    object: {
        id: "100220100000002155-1000",
        name: "Artikel A",
        anchor: "article.a"
    },
    template: {
        id: "100220100000073645-6000",
        name: "Template A",
        anchor: "template.a"
    },
    field: "sp_text"
}
Ja. Schränkt die Suche auf auf Objekte ein, auf die Daten des Artikels ${article.a} verwenden. Beispiel:
SELECT ... WHERE dependenciesFrom(${article.a})
Ja
dependenciesTo(id|anchor) Liefert die Abhängigkeiten, die durch die Publikation entstehen. Geliefert werden die Objekte dessen Daten von dieses Objektes verwenden werden. Ja, Beispiel:
{
    object: {
        id: "100220100000002155-1000",
        name: "Artikel A",
        anchor: "article.a"
    },
    template: {
        id: "100220100000073645-6000",
        name: "Template A",
        anchor: "template.a"
    },
    field: "sp_text"
}
Ja. Schränkt die Suche auf auf Objekte ein, dessen Daten vom Artikels ${article.a} verwenden werden. Beispiel:
SELECT ... WHERE dependenciesTo(${article.a})
Ja
list(field) Liefert die Liste von Werten für ein Content-Feld. Bei Felder die mehr als einen Wert besitzen (z.B. bei einer Multiselect-Box, Checkbox-Group, ...) wird im Normalfall nur der erste Wert zurück geliefert. Um die Liste aller Werte zu erhalten muss die Funktion list() verwendet werden. Ja, Beispiel:
["a", "b"]
Nein Nein
lock() Liefert die Lock-Informationen zu einem Objekt Ja, Beispiel:
{
   entity: {
      id : "100220100000001373-1015",
      name: "Artikel-Name",
      anchor: "article.anchor"
   },
   user: {
      id : "100220100000001452-3001",
      name : "Lustig, Peter",
      anchor : "user.lustig.peter",
   },
   created : 1395758658000,
   lastAccess : 1395774558000,
   ttl : 60000
}
Nein Nein
luceneSearch(root, luceneQuery, linkFields) Volltext-Suche Nein Ja Nein
media(field) Meta-Daten eines Mediums. Ja, Beispiel:
{
   id : "100220100000065452-11000",
   version : 1395758658000,
   contentType : "image/png",
   filesize : 782342,
   filename : "image.png",
   originalFilename : "image.png",
   width : 400,
   height : 700
}
Nein Nein
parentPath() Liefert den Gruppen-Pfad des Objektes (exklusive dem Object) Ja, Beispiel:
[
   {
       id: "100220100000002152-2000",
       name : "Root",
       anchor : "group.root"
   },{
       id: "100220100000002153-2000",
       name : "1",
       anchor : "group.1"
   },{
       id: "100220100000002154-2000",
       name : "1.1",
       anchor : "group.1.1"
   }
]
Nein Nein
path() Liefert den Gruppen-Pfad des Objektes (inklusive dem Object) Ja, Beispiel:
[
   {
       id: "100220100000002152-2000",
       name : "Root",
       anchor : "group.root"
   },{
       id: "100220100000002153-2000",
       name : "1",
       anchor : "group.1"
   },{
       id: "100220100000002154-2000",
       name : "1.1",
       anchor : "group.1.1"
   },{
       id: "100220100000002155-1000",
       name : "Artikel A",
       anchor : "article a"
   }
]
Nein Nein
privileges() liefert die Rechte eines Objektes für den aktuellen Nutzer Ja, Beispiel:
{
    object: {
        read: true,
        update: true,
        delete: true,
        copy: true
    },
    group: {
        createObjects: 0,
        createGroups: 0
    }
}
Nein Nein
publication(channel) Liefert den Publikations-Status eines Objektes für einen bestimmten Publikations-Kanal Ja, Beispiel:
{
    channel: 2,
    collision: {
        id: "100220100000002155-1000",
        name: "Artikel A"
    }
    filename: "a",
    suffix: "html",
    md5: "1012b1a8127893ed8388ed2b400863e4",
    path: "/a.html",
    publishable: true,
    depublishable: true,
    published: true,
    size: 46,
    timestamp: 1395740463000,
    version: 1395740463383
}
Nein Nein
publications([channel, channel, ...]) Liefert die Publikations-Stati eines Objektes für eine Liste bestimmter Publikations-Kanäle Ja, Beispiel:
[{
    channel: 1,
    collision: {
        id: "100220100000002155-1000",
        name: "Artikel A"
    },
    filename: "a"
    suffix: "html",
    md5: "1012b1a8127893ed8388ed2b400863e4",
    path: "/a.html",
    publishable: true,
    depublishable: true,
    published: true,
    size: 46,
    timestamp: 1395740463000,
    version: 1395740463383
},{
    channel: 2,
    collision: null,
    filename: "a",
    suffix: "html",
    path: "/a.html",
    publishable: true,
    depublishable: true,
    published: false
}]
Nein Nein
referrerLinks(field, objectclass, id) Liefert alle Links, die auf das Objekt verweisen. Die Parameter sind Optional. Ja, Beispiel:
{
    field: "sp_parent_iterate[0].sp_parent",
    origin: {
        id: "100220100000002155-1000",
        name: "Artikel A",
        anchor: "article.a"
    }
}
Ja. Schränkt die Suche auf auf Objekte ein, die auf den Artikel ${article.a} verlinken. Beispiel:
SELECT ... WHERE referrerLinks(null, "Publishable", ${article.a}) AND parent = !{parent.anchor.x}
Ja
referenceLinks(field, objectclass, id) Liefert alle Links, auf die das Objekt verweisen. Die Parameter sind Optional. Ja, Beispiel:
{
    field: "sp_parent_iterate[0].sp_parent",
    link: {
        id: "100220100000002155-1000",
        name: "Artikel A",
        anchor: "article.a"
    }
}
Ja. Schränkt die Suche auf auf Objekte ein, auf die der Artikel ${article.a} verlinken. Beispiel:
SELECT ... WHERE referenceLinks(null, "Publishable", ${article.a}) AND parent = !{parent.anchor.x}
Ja
spqlSearch(query) SPQL-Such-Syntax Nein Ja Nein
statistic(owner, [groups], type, from, to) Liefert Statistik-Werter aus der Statistik-Tabelle Ja, Beispiel:
{
   "totalValue":5,
   "totalMin":1,
   "totalMax":2,
   "totalAvg":1,
   "data":[
      {
         "samples":2,
         "group":"mygroup",
         "date":1391212800000,
         "value":2,
         "min":1,
         "max":1,
         "avg":1,
         "absolute":530
      }
   ]
}
Nein Nein