Dotazovací jazyk Web API systému ABRA Flores

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

Základní informace

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

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).

Dotazový objekt může obsahovat také vlastnost having pro omezení agregovaných výsledků. Hodnotou může být řetězec nebo pole řetězců, přičemž více podmínek se spojí pomocí and.

Příklady použití jsou uvedeny v kapitole Příklady rozšířeného dotazování.

Klauzuli having lze použít také ve vnořených dotazech v where a v klauzulích expand(...).

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

V rozšířeném dotazování je možné v těle požadavku použít také vlastnost view. Pomocí ní lze na dotaz aplikovat stejné předpřipravené omezení dat, jaké používají běžné endpointy s cestou views/{view}.

To je užitečné zejména v případech, kdy má obecný endpoint /query vracet stejnou množinu záznamů jako odpovídající kolekce BO nebo její konkrétní pohled.

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.

Pokud je /query použito pro tisk nebo export (parametr report, export nebo exportb2b), vyhodnocuje se odpovídající právo k funkci nad tímto endpointem. U tisku přes obecný endpoint /query se navíc kontroluje také právo tisknout objekt odpovídající třídě class uvedené v dotazu.

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 Typové příklady základního dotazování Web API (Query String).
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..