Dotazovací jazyk REST API systému ABRA Gen

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

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

Dotaz lze specifikovat ve dvou formách:

V základní variantě se dotaz zapisuje ve formě query parametrů URL HTTP požadavku. Výběr je v základní variantě vždy uskutečňován nad kolekcí BO nebo importním manažerem.

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.

Při zadání SQL příkazu a použití podmínky, v níž je textový sloupec (memo), se jeho porovnání vyhodnocuje jako case case insensitiveClosed 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..

Příklad použití podmínky:
SELECT ID FROM RestrictionDefinitions T_1 WHERE T_1.Note COLLATE UNICODE_LOCALE_CI like '%inTer%'

Z důvodu, že databázový server Oracle nepodporuje možnost nastavení COLLATE na těchto sloupcích, je výsledek dotazování vyhodnocovaný jako 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..