Čo je to?

Poznámka pre administrátora: Toto je výkonný nástroj na získavanie dát, ktorý sa používa na získavanie, filtrovanie a sumarizáciu informácií z vášho e-shopu. Predstavte si ho ako spôsob, ako „klásť otázky“ o vašich dátach, aby ste získali presne tie odpovede, ktoré potrebujete.

Pre koho je to určené? Administrátor by si to mal prečítať, aby pochopil možnosti analýzy dát systému. Konkrétne pokyny a príklady kódu sú však určené pre vývojárov na implementáciu vo vašich integráciách alebo vlastných reportoch.

Kľúčové výhody pre e-shop:

• Flexibilné reportovanie: Získajte presne tie dáta, ktoré potrebujete pre vlastné tabuľky alebo dashboardy, bez zbytočného „šumu“.
• Analýza trendov: Automaticky zoskupujte údaje o predaji alebo produktoch podľa časových období, aby ste videli, ako vaše podnikanie rastie.
• Cestovanie v čase: Pozrite si, ako presne vyzerali vaše dáta v ktoromkoľvek bode v minulosti, aby ste vyriešili nezrovnalosti alebo skontrolovali zmeny.
• Inteligentné dopĺňanie dát: Zabezpečte, aby vaše grafy vyzerali profesionálne, automatickým dopĺňaním „medzier“ v dňoch, keď nedošlo k žiadnym predajom.

Prehľad

Náš dotazovací jazyk je inšpirovaný GraphQL, ale je navrhnutý pre SQL-založené backendy a adaptáciu REST API. Používa známu, vnorenú a expresívnu syntax, ktorá eliminuje problém N+1 prostredníctvom inteligentného dávkovania a optimalizácie dotazov.

card: Inšpirované GraphQL
Známa vnorená syntax s výberom entít, špecifikáciou polí a podporou parametrov
card: Kompatibilné s REST
Dokáže prekladať dotazy na REST koncové body pre kompatibilitu s existujúcimi službami
card: Optimalizované pre výkon
Eliminuje problémy N+1 SQL prostredníctvom automatického dávkovania a optimalizácie dotazov

Príklady dotazov

Základný dotaz

Získajte všetky polia z entity [badge:Basic|info|right]

products {
    id
    name
    price
    description
}

Dotaz s parametrami

Použite parametre pre filtrovanie a stránkovanie [badge:Parameters|info|right]

products(
    where: "status = 'active'",
    limit: 10,
    orderBy: [name@asc]
) {
    id
    name
    price
}

Vnorené vzťahy

Získajte súvisiace entity v jednom dotaze [badge:Relations|info|right]

products {
    id
    name
    category {
        id
        name
    }
    variants(limit: 10) {
        id
        price
    }
}

Dotaz s agregáciami

Zahrňte agregačné funkcie do vášho dotazu [badge:Aggregation|info|right]

products(
    where: "price > 100"
) {
    id
    name
    @count as total_products
    @sum(price) as total_price
}

Funkcie polí

Aplikujte funkcie na polia pre transformácie [badge:Functions|info|right]

categories() {
    name,
    length(name) as name_length,
    isnull(description) as has_no_description,
    upper(code) as code_upper
}

Funkcie dátumu

Extrahujte komponenty dátumu/času z polí [badge:Functions|info|right]

orders() {
    id,
    order_date,
    year(order_date) as order_year,
    month(order_date) as order_month,
    quarter(order_date) as order_quarter,
    dayofweek(order_date) as weekday
}

Funkcie rozsahu dátumov

Získajte presné hranice časového obdobia pre analýzy [badge:Functions|info|right]

analytics() {
    id,
    event_date,
    startOfYear(event_date) as year_start,
    endOfYear(event_date) as year_end,
    startOfMonth(event_date) as month_start,
    endOfMonth(event_date) as month_end,
    startOfHour(event_date) as hour_start,
    endOfHour(event_date) as hour_end
}

GROUP BY s funkciami

Použite funkcie v zoskupovaní agregácií [badge:Aggregation|info|right]

sales(
    @count as total_sales,
    @sum(amount) as total_revenue,
    @groupBy(year(sale_date), month(sale_date))
) { * }

Pomenujte zoskupenú funkciu s as, aby ste získali predvídateľný stĺpec vo výsledku, a skombinujte obdobie s iným poľom:

journalEntries(
    where: "isPosted = true",
    @groupBy(yearquarter(accountingDate) as period, debitAccountCode),
    @sum(amount) as amount
) { }

Každý riadok výsledku má period (napr. 2026-Q1), debitAccountCode a amount.

Dopĺňanie medzier pre grafy časových radov

Vyplňte chýbajúce obdobia vo zoskupených výsledkoch pre súvislé grafy [badge:Aggregation|info|right]

orders(
    @count as order_count,
    @sum(total) as monthly_revenue,
    @groupBy(yearmonth(created_at)),
    @fillGaps(yearmonth(created_at))
) { }

S explicitným rozsahom dátumov (rozšírenie za hranice dát):

orders(
    @count as order_count,
    @sum(total) as monthly_revenue,
    @groupBy(yearmonth(created_at)),
    @fillGaps(yearmonth(created_at), from: "2024-01", to: "2024-12")
) { }

Keď @groupBy má viac polí, každá kombinácia ostatných polí nájdených v dátach získa všetky obdobia. @fillGaps sa môže odkazovať na názov zadaný s as:

journalEntries(
    @groupBy(yearmonth(accountingDate) as period, debitAccountCode),
    @sum(amount) as amount,
    @fillGaps(period, from: "2026-01", to: "2026-12")
) { }

Komplexný dotaz

Skombinujte viacero funkcií v jednom dotaze [badge:Advanced|info|right]

orders(limit: 10) {
    id
    total
    user {
        id
        name
    }
    items {
        id
        quantity
        product {
            id
            name
            price
        }
    }
}

Preložiteľné polia

Dotazujte sa na viacjazyčné polia s výberom špecifickým pre jazyk [badge:Advanced|info|right]

products(limit: 10) {
    id
    code
    name              // Returns {"en": "English", "cs": "Czech"}
    name:cs           // Returns Czech translation only
    name:en           // Returns English translation only
    description:cs as czech_desc
    category {
        name:cs
        name:en
    }
}

Dotaz na historické dáta

Dotazujte sa na historické verzie z archívnych tabuliek v kombinácii s aktuálnym riadkom [badge:Advanced|info|right]

products(
    @history
    where: "id = 123"
) {
    id
    name
    price
    _deleted
    _deletedAt
    _archiveValidSince
    _archiveValidTo
}

Dotaz na históriu k určitému časovému bodu

Dotazujte sa na dáta, ako existovali v konkrétnom časovom bode, plus aktuálny riadok [badge:Advanced|info|right]

products(
    @history(from: "2025-01-01T00:00:00")
    where: "price > 100"
    limit: 10
) {
    id
    name
    price
    _archiveValidSince
    _archiveValidTo
}

Pravidlá syntaxe

Funkcie polí

Transformujte a analyzujte hodnoty polí priamo vo vašich dotazoch

Funkcie polí vám umožňujú aplikovať transformácie a kontroly na polia v klauzule select. Funkcie môžu byť použité samostatne alebo s aliasmi pomocou kľúčového slova as.

Reťazcové funkcie

Funkcie dátumu a času

Funkcie rozsahu dátumov

Príklady použitia

Funkcie transformácie reťazcov:

users() {
    name,
    lower(name) as name_lower,
    upper(code) as code_upper,
    length(description) as desc_length
}

Funkcie extrakcie dátumu/času:

orders() {
    id,
    order_date,
    year(order_date) as order_year,
    month(order_date) as order_month,
    dayofweek(order_date) as weekday
}

Použitie zmiešaných funkcií:

products() {
    name,
    isnull(description) as has_no_description,
    length(name) as name_length,
    yearmonth(created_at) as creation_month
}

Funkcie rozsahu dátumov pre analýzu časového obdobia:

analytics() {
    id,
    event_date,
    startOfYear(event_date) as year_start,
    endOfYear(event_date) as year_end,
    startOfMonth(event_date) as month_start,
    endOfMonth(event_date) as month_end,
    startOfDay(event_date) as day_start,
    endOfDay(event_date) as day_end,
    startOfHour(event_date) as hour_start,
    endOfHour(event_date) as hour_end
}

Funkcie v agregáciách GROUP BY:

orders(
    @count as order_count,
    @sum(total) as total_revenue,
    @groupBy(year(created_at), month(created_at))
) { * }

// Date range functions in GROUP BY
events(
    @count as event_count,
    @sum(value) as total_value,
    @groupBy(startOfYear(event_date), startOfMonth(event_date))
) { * }

**Poznámky**
- Funkcie môžu byť aliasované pomocou kľúčového slova `as`
- Všetky názvy funkcií nerozlišujú veľké a malé písmená
- Reťazcové funkcie fungujú s akýmkoľvek poľom, ktoré možno previesť na reťazec
- Funkcie dátumu/času fungujú s typmi polí DATE a DATETIME
- Funkcie rozsahu dátumov vracajú presné časové pečiatky pomocou operácií DATE_TRUNC a INTERVAL v PostgreSQL
- Funkcie možno použiť pri výbere polí aj v agregáciách @groupBy
- `dayofweek()` vracia 0-6, kde 0=Nedeľa, 6=Sobota
- `quarter()` vracia 1-4 pre Q1-Q4
- `yearmonth()` vracia formát 'RRRR-MM' (napr. '2023-12')
- `yearweek()` vracia formát 'RRRR-TT' (napr. '2023-52')
- `yearquarter()` vracia formát 'RRRR-ŠN' (napr. '2023-Q4')
- `yearhalf()` vracia formát 'RRRR-PN' (napr. '2023-H2')
- Funkcie rozsahu dátumov poskytujú presnosť mikrosekúnd pre presné hranice časového obdobia

Pokročilé funkcie

Funkcie polí

Aplikujte transformácie a kontroly priamo v dotazoch

lower(name), year(created_at), length(description)

Dotazy s viacerými ID

Načítanie podľa jedného alebo viacerých ID pomocou polí a zmiešaných typov

products(id: ['id1', "uuid", 123]) { * }

Hlboké vnorenie

Prístup k hlboko vnoreným vzťahom bez penalizácie výkonu

orders { user { profile { preferences } } }

Podpora komentárov

Pridajte komentáre k svojim dotazom pre dokumentáciu

// Single line comment
/* Multi-line comment */
products(limit: 10) {
    id
    name // inline comment
}

Preložiteľné polia

Preložiteľné (viacjazyčné) polia je možné dotazovať viacerými spôsobmi:

Bez prípony jazyka:

products { name, description }

Vráti všetky vyplnené jazyky ako objekt JSON: {"en": "English", "cs": "Czech"}

S príponou jazyka:

products {
    name:cs,    // Czech only
    name:en,    // English only
    name:de     // German only
}

Vráti iba konkrétny jazyk ako reťazec. Podporuje: cs, en, de, sk, pl, hu, fr, es

S aliasmi:

products {
    name:cs as czech_name,
    name:en as english_name
}

Použite aliasy na premenovanie polí s príponami jazyka

**Výber jazyka:**
- Jazyk sa vyberá pomocou hlavičky HTTP Accept-Language.
- Všetky preložiteľné polia vo výsledkoch dotazu vracajú predvolene všetky vyplnené jazyky (bez prípony jazyka).
- Použite syntax fieldName:languageCode na získanie iba konkrétneho jazyka.
- Prípona jazyka funguje vo filtroch WHERE aj v poliach SELECT.
- Ak požadovaný jazyk nie je k dispozícii, pole môže byť prázdne alebo null.
- Príklad: `Accept-Language: en-US, cs-CZ;q=0.9`

Vyhľadávania a externé ID

Entity môžete odkazovať pomocou vyhľadávacích identifikátorov namiesto numerických/UUID ID. To je obzvlášť užitočné pri práci s dátami z externých systémov, ako sú ABRA Flexi/FlexiBee.

Štandardné vyhľadávania

Použite identifikátory založené na poliach, ako sú code:, ean:, alebo guid:

Použitie vyhľadávania kódu:

products(id: "code:ABC123") { id, name, code }

Použitie vyhľadávania v klauzule WHERE:

products(where: "category = 'code:ELEC'") { id, name }

Viaceré ID s vyhľadávaním:

products(id: ["code:ABC", "ean:123456", "uuid-value"]) { * }

Vyhľadávania externých ID

Externé ID (ext:) vám umožňujú odkazovať na entity pomocou identifikátorov z externých systémov. Tieto ID sú uložené v špecializovanej tabuľke extIds a podporujú viacdielne kľúče s dvojbodkami.

Použitie externého ID v dotaze:

products(id: "ext:SYSTEM:PRODUCT:12345") { id, name, code }

Použitie externého ID v klauzule WHERE:

products(where: "category = 'ext:SYSTEM:CATEGORY:ELEC'") { id, name }

Zmiešané identifikátory (štandardné + externé):

products(id: ["code:ABC", "ext:SYSTEM:PRODUCT:789"]) { * }

Externé ID v relačných poliach:

orders(where: "customer = 'ext:CRM:CUSTOMER:C001'") {
    id
    customer {
        id
        name
    }
}

Viacdielne externé ID (s dvojbodkami):

products(id: "ext:SYSTEM:NAMESPACE:TYPE:ID:123") { id, name }

- Externé ID sa automaticky vytvárajú pri importe dát s identifikátormi `ext:`
- Rovnaká entita môže mať viacero externých ID z rôznych systémov
- Externé ID fungujú všade, kde fungujú bežné ID (dotazy, klauzuly WHERE, relačné polia)
- Všetko za `ext:` sa považuje za externý identifikátor
- Externé ID nerozlišujú veľkosť písmen pri porovnávaní
- Uložené v špecializovanej tabuľke `extIds` s poľami: code, related_id, related_entity

Koncový bod API: /api/query

Koncový bod /api/query prijíma požiadavky POST s poľami dotazov a vracia streamované JSON odpovede pre optimálny výkon. Viacero dotazov sa spracováva paralelne a výsledky sa odosielajú hneď, ako sú k dispozícii.

Požadované hlavičky

[navigate:/apiKeys|Spravovať kľúče API|key]

Formát požiadavky

POST /api/query
Content-Type: application/json

[
  {
    "requestId": "products",
    "query": "products(where: \"category.name = ${categoryName}\", limit: 5) { id, name, price }",
    "params": {"categoryName": "Electronics"}
  },
  {
    "requestId": "categories",
    "query": "categories { id, name }",
    "params": {}
  }
]

Úspešná odpoveď

[
  {
    "requestId": "products",
    "success": true,
    "data": [
      {"id": 1, "name": "Product 1", "price": 100},
      {"id": 2, "name": "Product 2", "price": 150}
    ]
  }
]

Chybová odpoveď

[
  {
    "requestId": "products",
    "success": false,
    "error": "Invalid where clause syntax",
    "errorCode": "QUERY_ERROR"
  }
]

Odpovede sú streamované po častiach pre optimálny výkon. Viacero dotazov sa spracováva paralelne a výsledky môžu prísť v inom poradí, než boli požadované. Pri spracovaní streamu odpovedí použite čiastočný JSON parser, ktorý dokáže spracovať neúplný JSON.

Dopĺňanie medzier pre časové rady (@fillGaps)

Doplňte chýbajúce obdobia v zoskupených výsledkoch pre plynulé, súvislé grafy

Pri vytváraní grafov alebo reportov v priebehu času majú zoskupené výsledky často medzery – mesiace, týždne alebo roky, pre ktoré neexistujú žiadne dáta. @fillGaps automaticky vloží riadky pre tieto chýbajúce hodnoty, aby bola výsledná sada súvislá.

Použite @fillGaps spolu s @groupBy na rovnakom poli. Spúšťa sa ako krok po spracovaní a nemodifikuje vaše dáta.

Ako to funguje

• Chýbajúce intervaly sú detekované porovnaním zoskupených hodnôt poľa s očakávaným rozsahom.
• Automatická detekcia rozsahu: štandardne sa rozsah rozprestiera od najmenšej po najväčšiu hodnotu v aktuálnych dátach.
• Explicitný rozsah: použite from a/alebo to na rozšírenie rozsahu nad rámec toho, čo dáta obsahujú.
• Viaceré zoskupené polia: medzery sa vyplnia pre každú kombináciu ostatných zoskupených polí, ktorá sa vyskytuje v dátach.
• Pomenované polia: @fillGaps sa môže odkazovať na funkciu pomenovanú pomocou as v @groupBy, napr. @fillGaps(period).
• Agregácie @count a @sum sú pre chýbajúce riadky vyplnené 0.
• Agregácie @avg, @min, @max sú pre chýbajúce riadky vyplnené null.

Podporované typy polí

Mesačný trend s automaticky detekovaným rozsahom

orders(
    @count as order_count,
    @sum(total) as monthly_revenue,
    @groupBy(yearmonth(created_at)),
    @fillGaps(yearmonth(created_at))
) { }

Mesiace bez objednávok dostanú order_count=0 a monthly_revenue=0

Celoročný prehľad (explicitný rozsah)

orders(
    @count as order_count,
    @avg(total) as avg_order_value,
    @groupBy(yearmonth(created_at)),
    @fillGaps(yearmonth(created_at), from: "2024-01", to: "2024-12")
) { }

Vždy vráti presne 12 riadkov, január – december 2024

Týždenná aktivita s nulovými metrikami pre prázdne týždne

events(
    @count as event_count,
    @avg(duration) as avg_duration,
    @groupBy(yearweek(event_date)),
    @fillGaps(yearweek(event_date))
) { }

Prázdne týždne dostanú event_count=0 a avg_duration=null

Zoskupovanie celočíselných polí

products(
    @count as product_count,
    @groupBy(month),
    @fillGaps(month, from: 1, to: 12)
) { }

- `@fillGaps` sa musí používať spolu s `@groupBy` na rovnakom poli
- Automatická detekcia vyplní od minimálnej po maximálnu hodnotu prítomnú v dátach
- Môžete zadať iba `from`, iba `to` alebo oboje pre podrobné ovládanie
- Číselné hodnoty `from`/`to` sa píšu bez úvodzoviek; reťazcové hodnoty (yearmonth, yearweek) používajú dvojité úvodzovky
- Direktíva ovplyvňuje iba výslednú sadu; nemodifikuje dáta ani nespúšťa ďalšie SQL dotazy

Dotazy histórie (@history)

Dotazovanie historických dát z archívnych tabuliek v kombinácii s aktuálnym riadkom

Direktíva @history vám umožňuje dotazovať historické dáta z archívnych tabuliek. Keď entity podporujú archiváciu, všetky zmeny záznamov sú uchovávané v špeciálnych archívnych tabuľkách, ktoré udržiavajú kompletnú históriu modifikácií a vymazaní. Dotaz vráti historické verzie aj aktuálny stav záznamov.

Ako to funguje

Direktíva @history používa SQL UNION ALL na kombinovanie:

• Riadky archívnej tabuľky — historické verzie z {entity}_archive
• Aktuálny riadok tabuľky — aktuálny stav z {entity}

Výsledky sú zoradené podľa _archiveValidTo DESC NULLS LAST, čo znamená, že historické verzie sa zobrazujú ako prvé (od najnovších po najstaršie) a aktuálny riadok sa zobrazuje ako posledný.

Polia špecifické pre archív

Dotazovanie všetkých historických verzií plus aktuálny riadok

products(@history) {
    id
    name
    price
    _deleted
    _deletedAt
    _archiveValidSince
    _archiveValidTo
}

Dotaz k určitému časovému bodu (dáta k špecifickému dátumu)

products(
    @history(from: "2025-01-01T00:00:00")
    where: "price > 100"
) {
    id
    name
    price
    _archiveValidSince
    _archiveValidTo
}

Nájsť všetky zmeny konkrétneho produktu

products(
    @history
    where: "id = 123"
) {
    id
    name
    price
    _archiveValidSince
    _archiveValidTo
}

Nájsť vymazané záznamy

products(
    @history
    where: "_deleted = true"
) {
    id
    name
    _deletedAt
    _archiveValidSince
    _archiveValidTo
}

Bežné prípady použitia

card: Auditná stopa
Sledujte všetky zmeny citlivých dát pre dodržiavanie súladu
card: Cestovanie v čase
Zobrazte dáta tak, ako existovali v ktoromkoľvek bode v minulosti
card: Analýza zmien
Analyzujte vzory v modifikáciách dát v priebehu času
card: Obnova vymazaných záznamov
Nájdite a skontrolujte vymazané záznamy spolu s aktuálnymi záznamami

- Nie všetky entity podporujú archiváciu. Ak použijete @history na nepodporovanej entite, dostanete chybu
- Dopyt vždy zahŕňa aktuálny stav záznamov ako posledný riadok (riadky) vo výslednej sade
- Archívne tabuľky môžu obsahovať mnoho verzií, preto používajte vhodné klauzuly where a parametre limit
- Časové pečiatky by mali byť poskytnuté vo formáte ISO 8601 (napr. "2025-01-01T12:00:00")
- Pre aktuálny riadok je _archiveValidTo NULL a _deleted je vždy false

Filtrovanie pomocou klauzúl WHERE

Parameter where používa náš výkonný systém filtrovania, ktorý podporuje rôzne operátory, logické podmienky a filtrovanie vzťahov. Zistite viac o všetkých dostupných operátoroch a pozrite si praktické príklady.

products(where: "price > 100 and category.name = 'Electronics'") { id, name, price }

[navigate:where.md|Zobraziť dokumentáciu klauzuly WHERE|filter]

Komplexný sprievodca možnosťami filtrovania a vyhľadávania

Výkon a osvedčené postupy

card: Eliminácia problému N+1
Systém automaticky zoskupuje a optimalizuje vnorené dopyty, aby zabránil problémom N+1 SQL
card: Selektívne načítavanie polí
Vyžiadajte si len polia, ktoré potrebujete, aby ste minimalizovali prenos a spracovanie dát
card: Používanie stránkovania
Vždy používajte limit a offset pre veľké súbory dát na zlepšenie doby odozvy. Predvolený limit je 1000 riadkov — použite limit: 0 pre neobmedzené výsledky (používajte opatrne).
card: Streamovanie výsledkov
Viaceré dopyty môžu vrátiť výsledky v optimalizovanom poradí pre lepšiu priepustnosť