Dopytovací jazyk REST API systému ABRA Gen

Tu sú uvedené možnosti dopytovania v ABRA API.

Základné informácie

Dopytovanie (tiež dopytovací jazyk alebo BO Query) v REST API ABRA Gen slúži k efektívnemu výberu dát zo systému ABRA Gen.

Dopyt je možné špecifikovať v dvoch formách:

Rozšírené dopytovanie - JSON dokument (v tele požiadavky)

V rozšírenom variante sa dopyt zapisuje vo forme JSON dokumentu, ktorý je zasielaný v tele HTTP požiadavky (používa sa HTTP metóda POST).

Výber je v rozšírenom variante uskutočňovaný:

nad resourcom query podradeným kolekcii BO (napr. /{spojenie}/{kolekcia BO}/query) - potom sa v JSON dopyte neuvádza vlastnosť class
nad všeobecným resourcom pre rozšírené dopytovanie s názvom query (/{spojenie}/query) - potom sa v JSON dopyte uvádza vlastnosť class

Pri výbere dát z kolekcie BO nie sú vo východiskovom stave zahrnuté užívateľské ani neperzistentné položky.

Parameter /query vykonáva dopyt na základe práv užívateľa v závislosti na triede (class), nad ktorou dopyt beží.

Trieda s BO kontrolerom - Práva sa vyhodnocujú podľa kontrolera spojeného s touto triedou (napr. issuedinvoices).
Trieda bez BO kontrolera - Práva sa overujú na základe sprístupnenia položiek pre API. Pokiaľ nie je možné nastaviť oprávnenie k spusteniu dopytu, dopyt nebude realizovaný.

Užívatelia majú právo spúšťať dopyty (opRun) na vybrané položky. Prístup k ďalším položkám sa nastavuje v agende Sprístupnenie položiek pre API.

Výrazy

Výraz je v dopytovacom jazyku sekvencie jedného alebo viacerých operandov (operandom je field BO alebo výraz), v prípadnej kombinácii s operátormi (spojovanie reťazcov, matematické operácie atď.), ktorý je možné vyhodnotiť ako jednu hodnotu.

Príklad výrazu pre spojenie polí Code a Name: Code || Name

Pri použití výrazu v klauzule SELECT dopytu je do názvu výsledného fieldu dosadený celý výraz. Na jeho premenovanie slúži v základnom variante dopytovania operátor as, v rozšírenom variante je nutné field špecifikovať ako výrazový objekt (JSON objekt obsahujúci alias fieldu a výraz dosadzovaný do jeho hodnoty).

Vo výrazoch je možné používať niekoľko druhov operátorov:

Reťazcové a aritmetické - ich popis nájdete v tabuľke na konci tejto kapitoly.
Porovnávacie - viď popis klauzuly where v kapitole Příklady základního dotazování REST API ABRA Gen.
Logické - viď sekcie o kombinovaní výrazov v rovnakej kapitole.

Operátory je možné reťaziť, vyhodnocované sú vždy zľava doprava, v prípade aritmetických operátorov je patrične aplikovaná prednosť. Poradie vykonávania výrazov je možné ovplyvňovať pomocou zátvoriek.

Okrem operátorov je vo výrazoch možné používať tiež všeobecné funkcie.

Operátory
Operátor	Názov	Význam	Príklad použitia	Popis príkladu
Reťazcové operátory
\|\| +	Spojenie reťazcov	Spojí dva reťazce do jedného	`Code \|\| Name` alebo `Code + Name`	Spojí fieldy Code a Name. Na mieste fieldov je možné použiť i literál (konkrétny reťazec) alebo výraz.
Aritmetické operátory
+	Plus	Sčíta dve čísla	`LocalAmountWithoutVAT + VATAmount`	Sčíta fieldy LocalAmountWithoutVAT a VATAmount. Na mieste fieldov je možné použiť i literál (konkrétne číslo) alebo výraz.
-	Mínus	Odčíta dve čísla	`Amount - VATAmount`	Odčíta hodnotu fieldu VATAmount od hodnoty vo fielde Amount. Na mieste fieldov je možné použiť i literál (konkrétne číslo) alebo výraz.
* mul	Krát	Vynásobí dve čísla	`UnitPrice * Quantity` alebo `UnitPrice mul Quantity`	Vynásobí hodnoty fieldov UnitPrice a Quantity. Na mieste fieldov je možné použiť i literál (konkrétne číslo) alebo výraz.
/ div	Delené	Vydelí dve čísla	`TotalPrice / Quantity` alebo `TotalPrice div Quantity`	Vydelí hodnotu fieldu TotalPrice hodnotou fieldu Quantity. Na mieste fieldov je možné použiť i literál (konkrétne číslo) alebo výraz. L-hodnota = delenec, r-hodnota = deliteľ
% mod	Zvyšok po delení (modulo)	Vypočíta zvyšok po delení l-hodnoty r-hodnotou	`TotalPrice % 3` alebo `TotalPrice mod 3`	Vypočíta zvyšok po delení fieldu TotalPrice hodnotou číslom 3. Na mieste fieldov je možné použiť i literál (konkrétne číslo) alebo výraz.

Funkcie
Funkcie	Význam	Príklad použitia	Popis príkladu
Reťazcové funkcie
upper()	Prevedie reťazec na veľké písmená	`where=upper(name)+like+'ABRA'`	Obmedzí výber na objekty, ktorých názov (Name) po prevedení na veľké písmená obsahuje reťazec ABRA. Túto funkciu, rovnako ako jej obdobu lower(), je možné používať i na iných miestach, napr. v klauzule orderby: `GET http://localhost/data/firms?select=upper(name)&orderby=upper(name)` Bez použitia funkcií upper() alebo lower() zohľadňuje dopytovanie na reťazce a ich časti prostredníctvom Web API veľkosť písmen (je case sensitive Ak je nejaká položka case insensitive, znamená to, že nie je citlivá na veľké a malé písmená, inými slovami, že nerozlišuje veľké a malé písmená. Tzn., že nie je rozdiel, ak je napísané napr. "Abc" alebo "abc". Opak je case sensitive.), tzn. pokiaľ je v databáze firma uložená pod názvom "ABRA Software", nasledujúci dopyt vráti prázdnu odpoveď: `GET http://localhost/data/firms?select=name&where=name+eq+'abra software'` Je potrebné sa dopýtať takto: `GET http://localhost/data/firms?select=name&where=lower(name)+eq+'abra software'`
lower()	Prevedie reťazec na malé písmená	`where=lower(name)+like+'abra'`	Obmedzí výber na objekty, ktorých názov (Name) po prevedení na malé písmená obsahuje reťazec abra.

Pri zadaní SQL príkazu a použití podmienky, v ktorej je textový stĺpec (memo), sa jeho porovnanie vyhodnocuje ako case case insensitive Ak je nejaká položka case insensitive, znamená to, že nie je citlivá na veľké a malé písmená, inými slovami, že nerozlišuje veľké a malé písmená. Tzn., že nie je rozdiel, ak je napísané napr. "Abc" alebo "abc". Opak je case sensitive..

Príklad použitia podmienky:
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žnosť nastavenia COLLATE na týchto stĺpcoch, je výsledok dopytovania vyhodnocovaný ako case sensitive Ak je nejaká položka case insensitive, znamená to, že nie je citlivá na veľké a malé písmená, inými slovami, že nerozlišuje veľké a malé písmená. Tzn., že nie je rozdiel, ak je napísané napr. "Abc" alebo "abc". Opak je case sensitive..