Dotazovací jazyk REST API systému ABRA Gen

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

Základní informace

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:

Rozšířené dotazování - JSON dokument (v těle požadavku)

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.

Parametr /query provádí dotaz na základě práv uživatele v závislosti na třídě (class), nad kterou dotaz běží.

Třída s BO kontrolerem - Práva se vyhodnocují podle kontroleru spojeného s touto třídou (např. issuedinvoices).
Třída bez BO kontroleru - Práva se ověřují na základě zpřístupnění položek pro API. Pokud nelze nastavit oprávnění ke spuštění dotazu, dotaz nebude proveden.

Uživatelé mají právo spouštět dotazy (opRun) na vybrané položky. Přístup k dalším položkám se nastavuje v agendě Zpřístupnění položek pro API.

Výrazy

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ů:

Řetězcové a aritmetické - jejich popis naleznete v tabulce na konci této kapitoly.
Porovnávací - viz popis klauzule where v kapitole Příklady základního dotazování REST API ABRA Gen.
Logické - viz sekce o kombinování výrazů ve stejné kapitole.

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 sensitive 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 insensitive 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 sensitive 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..