Jak používat AQL

AQL je dotazovací jazyk, který umožňuje zkoumat data v sítí reality a získávat tato data z grafu pomocí přirozených konceptů. Podrobněji se jeho princip popisuje v předchozí části (Co je to AQL).

Na této stránce se vám pokusíme vysvětlit, jak v AQL zadávat konkrétní dotazy. Podíváme se na to krok po kroku na to, kam vás která klauzule zavede a jaký výsledek uvidíte na konci dotazu. Dozvíte se také, jak pracovat s různými typy kroků - s generátory, jejichž výsledek vás zajímá, nebo s kroky, které jsou nutné jen pro přeskočení na jiná aktiva. Také vás upozorníme na to, čeho se při zadávání dotazu vyvarovat, aby zůstal dotaz platný a použitelný.

Pro ilustraci použijeme následující síť reality:

Údaje pro tuto mapu aktiv (síť reality) se skládají ze dvou serverů: 1 a 2, čtyř senzorů: a až d a jedné místnosti X.

Na server 1 jsou navázány senzory a a b, na server 2 senzory c a d.

Oba senzory jsou umístěny v jedné místnosti X.

Vztahy mezi aktivy jsou určeny hranami.

AQL je účinný nástroj, který vám pomůže projít vaši síť reality, aniž byste museli otvírat v prohlížeči každou bublinu zvlášť a načítat souvislost za souvislostí. Tento jazyk je mnohem přesnější a rychlejší. Každý dotaz, který budete formulovat, začne počátečním krokem, na který budou navazovat další kroky.

Počáteční krok

Jedná se o krok, který nevychází z žádného předcházejícího kroku. Tím je tento krok v rámci celého dotazu unikátní. Zpravidla začíná klauzulí FROM a ID maskou, která definuje výchozí místo pro prozkoumávání sítě reality nebo nastavování widgetů.

FROM '/assets/servers/*'

FROM odpovídá anglickému překladu “z/od”. Používá se jako klauzule pro určení výchozího místa na počátku dotazu. Za ní následuje ID maska aktiva nebo aktiv uvedená v uvozovkách. Chcete-li jako ID masku zadat všechna aktiva určitého typu, výběr všech aktiv nahradí symbol hvězdičky *. V dotazu můžete specifikovat i více ID masek současně, stačí je zabalit do hranatých závorek [ ] a mezi sebou oddělit čárkou ,.

TYPY_KROKŮ
1. Generátor

Jedná se o krok, jehož výsledek je pro vás relevantní. Na začátku kroku tohoto typu použijte v případě počátečního kroku klauzuli FROM.
FROM ['/assets/servers/*', '/assets/sensors/*' , '....' ]
Další užitečnou klauzulí na začátku dotazu může být FROM NOT, která označuje místa, odkud počáteční krok nebude vycházet.
FROM NOT '/assets/servers/*'
Tento dotaz nevrací výsledek /assets/servers/* , ale může vrátit /assets/sensors/* nebo jiné typy aktiv v síti, např. /assets/rooms/*.

2. Krok přeskočení

je oproti generátoru krokem, jehož výsledek vám slouží pouze jako mezikrok k výsledku, který požadujete. Vypadá podobně jako generátor, jen klauzuli FROM zaměňte za klauzuli SKIP.
SKIP ['/assets/servers/*', '/assets/sensors/*']

Upozornění

Ve výše uvedeném případě by krok přeskočení nedával příliš velký smysl. Takovýto dotaz by totiž v úvodu vše přeskočil a nemohl tak vracet žádné výsledky. Proto v AQL není takový dotaz povolen.

Každý dotaz musí obsahovat alespoň jeden generátor.

Kroky následující po počátečním kroku

Tyto kroky vychází z prvního kroku a vedou po hranách k dalším výsledkům.

V případě jiných než počátečních kroků začíná generátor klauzulí DIRECT, která určuje další pohyb v prozkoumávání sítě. Za touto klauzulí bývá uveden směr hran, po kterých bude procházení sítí pokračovat. Mohou to být:

odchozí hrany (od zdroje k cíli) - klauzule FORWARD,
příchozí hrany (od cíle ke zdroji) - klauzule BACKWARD,
libovolné hrany bez ohledu na směr - klauzule ALL.

Pro ilustraci uvedeme pár příkladů kroku počátečního a kroku po něm následujícího:

FROM '/assets/servers/*' DIRECT FORWARD

Tento dotaz vychází z typu aktiv /assets/servers. Výsledkem prvního kroku jsou /assets/servers/1 a /assets/servers/2. Výsledkem druhého kroku jsou aktiva na druhém konci odchozích hran z výsledku prvního kroku (serverů), tedy: /assets/sensors/a, /assets/sensors/b, /assets/sensors/c, /assets/sensors/d. První i druhý krok jsou v tomto případě generátory. Ve výsledku dotazu tudíž budou zahrnuty výsledky obou kroků: /assets/servers/1, /assets/servers/2 a /assets/sensors/a, /assets/sensors/b, /assets/sensors/c, /assets/sensors/d.

FROM '/assets/servers/*' DIRECT BACKWARD

Další dotaz vychází také z aktiv typu /assets/servers. Výsledkem prvního kroku jsou také všechna aktiva typu server: /assets/servers/1 a /assets/servers/2. Výsledek druhého kroku se však liší tím, že se jedná o aktivum na druhém konci příchozích hran do výsledků prvního kroku (serverů) : /assets/rooms/X. Oba kroky jsou rovněž generátory. Ve výsledku dotazu tudíž budou zahrnuty výsledky obou kroků: /assets/servers/1, /assets/servers/2 a /assets/room/X.

FROM '/assets/servers/*' DIRECT ALL

Vycházejí bod dotazu je stejný jako u předchozích dotazů - aktiva typu /assets/servers. Výsledkem prvního kroku jsou i tentokrát všechna aktiva typu server: /assets/servers/1 a /assets/servers/2. Ale výsledkem druhého kroku budou všechna aktiva v okolí: /assets/sensors/a, /assets/sensors/b, /assets/sensors/c, /assets/sensors/d, /assets/rooms/X. I v tomto případě jsou oba kroky generátory a tak do celkového výsledku dotazu budou zahrnuty výsledky obou kroků: /assets/servers/1, /assets/servers/2 i /assets/sensors/a, /assets/sensors/b, /assets/sensors/c, /assets/sensors/d, /assets/rooms/X. Jedná se o všechna aktiva ilustrativní sítě reality uvedené výše.

Můžete používat i kroky přeskočení s pomocí klauzule SKIP, avšak každý zadaný dotaz musí končit generátorem.

Upozornění
Např. zadáte-li následující dotaz:
FROM '/assets/servers/*' SKIP ALL
nedává krok přeskočení příliš velký smysl. Krok tohoto typu má totiž jediný účel, a to že slouží jako výchozí bod pro další krok. Pokud je ale přeskočení krokem posledním, nemá takové přeskočení žádný účel. Tyto dotazy jsou proto v AQL zakázané.

Pro ukázku je zde uvedeno několik dalších neplatných příkladů:
SKIP '/assets/*'
FROM '/assets/*' SKIP FORWARD
FROM '/assets/*' DIRECT ALL SKIP ALL

Ve všech nepočátečních krocích je jako výchozí bod použit výsledek předchozího kroku. I když z tohoto výsledku nový krok vychází, jeho vlastní výsledek už výsledek předchozího kroku neobsahuje!

Vezměme např. dotaz s tímto zadáním:

FROM '/a/*' DIRECT FORWARD WHERE TO ID LIKE '/b/*' DIRECT FORWARD WHERE TO ID LIKE '/c/*'.

Lze jej rozdělit do 3 kroků a sledovat jejich výsledky:

krok je FROM '/a/*', jeho výsledkem jsou aktiva typu /a.
krok je DIRECT FORWARD WHERE TO ID LIKE '/b/*', odchozí hrana jde k aktivům typu /b, výsledkem jsou pouze aktiva typu /b. I přesto, že tento krok navazuje na výsledek prvního kroku, nejsou aktiva typu /a v jeho výsledku zahrnuta.
krok je DIRECT FORWARD WHERE TO ID LIKE '/c/*', odchozí hrana jde k aktivům typu /c, výsledkem třetího kroku jsou jen aktiva typu /c. Ve výsledku nejsou ani aktiva typu /a ani /b.

Příklady dotazů KROK po KROKU

      SKIP '/assets/servers/1' SKIP BACKWARD SKIP FORWARD DIRECT ALL
      \_____________________/  \__________/ \___________/ \________/
                1                  2            3            4

Podívejte se nyní na dotaz, který by měl v ukázkové síti reality v úvodu vrátit veškerá okolní aktiva všech serverů, které jsou ve stejné místnosti jako server 1. Podíváme se podrobně na výsledek každého kroku.

SKIP '/assets/servers/1' SKIP BACKWARD SKIP FORWARD DIRECT ALL

1. krok SKIP '/assets/servers/1' zvolí ze serverů pouze jeden konkrétní - server s názvem 1. Dotaz totiž obsahuje pouze jednu ID masku a to přímo ID tohoto aktiva. V tomto případě se jedná o krok přeskočení. Tudíž výsledek tohoto kroku nebude na konci započítán do výsledku dotazu. Výsledkem 1. kroku je:

/assets/servers/1

2. krok SKIP BACKWARD sleduje odchozí hrany ze serveru 1, tedy příchozí hranu do místnosti. Opět se jedná o krok přeskočení. Výsledkem tohoto kroku je:

/assets/rooms/X

Poznámka: tomuto výsledku nerozumím. Myslela jsem si, že ze serveru 1 vychází hrany kromě místnosti X i k k senzorům a i b.

3. krok SKIP FORWARD sleduje všechny přicházející hrany k místnosti, to jsou hrany odchozí od serverů, tentokrát jsou do výsledku zahrnuty již oba servery. I v tomto případě se jedná o krok přeskočení. Výsledkem 3. kroku je:

/assets/servers/1
/assets/servers/2

4. krok DIRECT ALL sbírá okolí serverů, sleduje jak hrany jdoucí do senzorů tak i do místnosti. Pouze tento krok je generátorem, proto je výsledek tohoto kroku i výsledkem dotazu:

/assets/sensors/a
/assets/sensors/b
/assets/sensors/c
/assets/sensors/d
/assets/rooms/X

Jiný příklad ve zkratce

SKIP '/assets/servers/1' DIRECT FORWARD DIRECT ALL SKIP BACKWARD DIRECT FORWARD

1. krok SKIP '/assets/servers/1' vybere server 1, jeho výsledek není započítán.

2. krok DIRECT FORWARD - jeho výsledkem budou aktiva na druhém konci odchozích hran jdoucích ze serveru 1 –> senzory a a b, výsledek kroku je započítán.

3. krok DIRECT ALL - výsledkem budou aktiva na druhém konci hran vycházejících či přicházejících z výsledných aktiv 2. kroku –> server 1, výsledek kroku je započítán.

4. krok SKIP BACKWARD - tento krok vrátí aktiva, z nichž přichází hrana do aktiv, které jsou výsledkem 3. kroku –> místnost X, výsledek kroku není započítán.

5. krok DIRECT FORWARD - výsledkem kroku budou aktiva na druhém konci hran vycházejících z aktiv, jež byly výsledkem 4. kroku –> servery 1 a 2.