Dotazovací jazyk REST API systému IS FLORES

Zde jsou uvedeny možnosti dotazování v FLORES API.

Dotazování (také dotazovací jazyk nebo BO Query) v REST API IS FLORES slouží k efektivnímu výběru dat ze systému IS FLORES.

Dotaz lze specifikovat ve dvou formách:

V základní variantě se dotaz zapisuje ve formě query parametrů URL HTTP požadavku. Query parametry se zapisují tak, že za adresou následuje otazník a za ním zapsané páry ve formátu klíč=hodnota. Klíč i hodnota musí být tzv. URL-zakódované (např. se v nich nesmí vyskytovat mezery a další znaky napřímo; např. mezera se dá zapsat jako + nebo %20). Výběr je v základní variantě vždy uskutečňován nad kolekcí BO. Páry jsou odděleny znakem &.

Pro url zakódování/dekódování řetězců lze využít různé on-line nástroje typu URL decoder/encoder. (Zdroj pro download si naleznete na webu.)

V rozšířené variantě se dotaz zapisuje ve formě JSON dokumentu, který je zasílán v těle HTTP požadavku (je používána HTTP metoda POST).

Výběr je v rozšířené variantě uskutečňován:

  • nad resourcem query podřízeným kolekci BO (např. /{spojení}/{kolekce BO}/query) - pak se v JSON dotazu neuvádí vlastnost class
  • nad obecným resourcem pro rozšířené dotazování s názvem query (/{spojení}/query) - pak se v JSON dotazu uvádí vlastnost class

Při výběru dat z kolekce BO nejsou ve výchozím stavu zahrnuty uživatelské ani nepersistentní položky.

Výraz je v dotazovacím jazyce sekvence jednoho nebo více operandů (operandem je field BO nebo výraz), v případné kombinaci s operátory (spojování řetězců, matematické operace atd.), který je možné vyhodnotit jako jednu hodnotu.

Příklad výrazu pro spojení polí Code a Name: Code || Name

Při použití výrazu v klauzuli SELECT dotazu je do názvu výsledného fieldu dosazen celý výraz. K jeho přejmenování slouží v základní variantě dotazování operátor as, v rozšířené variantě je nutné field specifikovat jako výrazový objekt (JSON objekt obsahující alias fieldu a výraz dosazovaný do jeho hodnoty).

Ve výrazech lze používat několik druhů operátorů:

Operátory lze řetězit, vyhodnocovány jsou vždy zleva doprava, v případě aritmetických operátorů je patřičně aplikována přednost. Pořadí vykonávání výrazů lze ovlivňovat pomocí závorek.

Kromě operátorů je ve výrazech možné používat také obecné funkce.

Operátory
Operátor Název Význam Příklad použití Popis příkladu
Řetězcové operátory  

||

+

 Spojení řetězců Spojí dva řetězce do jednoho

Code || Name nebo Code + Name

Spojí fieldy Code a Name. Na místě fieldů lze použít i literál (konkrétní řetězec) nebo výraz.
Aritmetické operátory  
+ Plus Sečte dvě čísla

LocalAmountWithoutVAT + VATAmount

Sečte fieldy LocalAmountWithoutVAT a VATAmount. Na místě fieldů lze použít i literál (konkrétní číslo) nebo výraz.
- Minus Odečte dvě čísla

Amount - VATAmount

Odečte hodnotu fieldu VATAmount od hodnoty ve fieldu Amount. Na místě fieldů lze použít i literál (konkrétní číslo) nebo výraz.

*

mul

 Krát Vynásobí dvě čísla

UnitPrice * Quantity nebo UnitPrice mul Quantity

Vynásobí hodnoty fieldů UnitPrice a Quantity. Na místě fieldů lze použít i literál (konkrétní číslo) nebo výraz.

/

div

 Děleno Vydělí dvě čísla

TotalPrice / Quantity nebo TotalPrice div Quantity

Vydělí hodnotu fieldu TotalPrice hodnotou fieldu Quantity. Na místě fieldů lze použít i literál (konkrétní číslo) nebo výraz.
L-hodnota = dělenec, r-hodnota = dělitel

%

mod

 Zbytek po dělení (modulo) Vypočte zbytek po dělení l-hodnoty r-hodnotou

TotalPrice % 3 nebo TotalPrice mod 3

Vypočte zbytek po dělení fieldu TotalPrice hodnotou číslem 3. Na místě fieldů lze použít i literál (konkrétní číslo) nebo výraz.

Funkce
Funkce Význam Příklad použití Popis příkladu
Řetězcové funkce

upper()

 Převede řetězec na velká písmena

where=upper(name)+like+'*ABRA*'

Omezí výběr na objekty, jejichž název (Name) po převedení na velká písmena obsahuje řetězec ABRA.

Tuto funkci, stejně jako její obdobu lower(), je možné používat i na jiných místech, např. v klauzuli orderby:

GET http://localhost/data/firms?select=upper(name)&orderby=upper(name)

Bez použití funkcí upper() nebo lower() zohledňuje dotazování na řetězce a jejich části prostřednictvím Web API velikost písmen (je case sensitiveClosed Je-li nějaká položka case insensitive, znamená to, že není citlivá na velká a malá písmena, neboli nerozlišuje velká a malá písmena. Tzn., že není rozdíl, je-li napsáno např. "Abc" nebo "abc". Opak je case sensitive.), tj. pokud je v databázi firma uložená pod názvem "ABRA Software", následující dotaz vrátí prázdnou odpověď:

GET http://localhost/data/firms?select=name&where=name+eq+'abra software'

Je zapotřebí se dotázat takto:

GET http://localhost/data/firms?select=name&where=lower(name)+eq+'abra software'

lower()

 Převede řetězec na malá písmena

where=lower(name)+like+'*abra*'

Omezí výběr na objekty, jejichž název (Name) po převedení na malá písmena obsahuje řetězec abra.