Co je to?

Poznámka pro administrátora: Jedná se o výkonný nástroj pro získávání dat, který slouží k načítání, filtrování a sumarizaci informací z vašeho e-shopu. Představte si ho jako způsob, jak “klást otázky” o vašich datech, abyste získali přesně ty odpovědi, které potřebujete.

Pro koho je to určeno? Administrátor by si to měl přečíst, aby pochopil možnosti analýzy dat systému. Konkrétní pokyny a příklady kódu jsou však určeny pro vývojáře k implementaci do vašich integrací nebo vlastních reportů.

Klíčové výhody pro e-shop:

• Flexibilní reportování: Získejte přesně ta data, která potřebujete pro vlastní tabulky nebo dashboardy, bez zbytečného “šumu.”
• Analýza trendů: Automaticky seskupujte prodejní nebo produktová data podle časových období, abyste viděli, jak vaše podnikání roste.
• Cestování časem: Zobrazte si přesně, jak vaše data vypadala v jakémkoli okamžiku v minulosti, abyste vyřešili nesrovnalosti nebo auditovali změny.
• Inteligentní doplňování dat: Zajistěte, aby vaše grafy vypadaly profesionálně, automatickým doplňováním “mezer” ve dnech, kdy nedošlo k žádným prodejům.

Přehled

Náš dotazovací jazyk je inspirován GraphQL, ale je navržen pro SQL-založené backendy a adaptaci REST API. Používá známou, vnořenou a expresivní syntaxi, která eliminuje problém N+1 prostřednictvím inteligentního dávkování a optimalizace dotazů.

card: Inspirováno GraphQL
Známá vnořená syntaxe s výběrem entit, specifikací polí a podporou parametrů
card: Kompatibilní s REST
Dokáže překládat dotazy na REST koncové body pro kompatibilitu s existujícími službami
card: Optimalizováno pro výkon
Eliminuje problémy N+1 SQL prostřednictvím automatického dávkování a optimalizace dotazů

Příklady dotazů

Základní dotaz

Načtení všech polí z entity [badge:Základní|info|right]

products {
    id
    name
    price
    description
}

Dotaz s parametry

Použití parametrů pro filtrování a stránkování [badge:Parametry|info|right]

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

Vnořené relace

Načtení souvisejících entit v jediném dotazu [badge:Relace|info|right]

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

Dotaz s agregacemi

Zahrnutí agregačních funkcí do dotazu [badge:Agregace|info|right]

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

Funkce polí

Aplikace funkcí na pole pro transformace [badge:Funkce|info|right]

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

Funkce data

Extrahování komponent data/času z polí [badge:Funkce|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
}

Funkce rozsahu dat

Získání přesných hranic časového období pro analýzy [badge:Funkce|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 funkcemi

Použití funkcí při seskupování agregací [badge:Agregace|info|right]

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

Pojmenujte seskupenou funkci pomocí as, abyste získali předvídatelný sloupec ve výsledku, a zkombinujte období s jiným polem:

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

Každý řádek výsledku obsahuje period (např. 2026-Q1), debitAccountCode a amount.

Doplnění mezer pro grafy časových řad

Doplnění chybějících období ve seskupených výsledcích pro souvislé grafy [badge:Agregace|info|right]

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

S explicitním rozsahem dat (rozšíření za hranice dat):

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

Když @groupBy obsahuje více polí, každá kombinace ostatních polí nalezených v datech získává všechna období. @fillGaps se může odkazovat na název uvedený pomocí as:

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

Složitý dotaz

Kombinace více funkcí v jednom dotazu [badge:Pokročilé|info|right]

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

Přeložitelná pole

Dotazování vícejazyčných polí s výběrem specifickým pro jazyk [badge:Pokročilé|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á data

Dotazování historických verzí z archivních tabulek v kombinaci s aktuálním řádkem [badge:Pokročilé|info|right]

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

Dotaz na historii k určitému okamžiku

Dotazování dat, jak existovala v konkrétním časovém razítku, plus aktuální řádek [badge:Pokročilé|info|right]

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

Pravidla syntaxe

Funkce polí

Transformujte a analyzujte hodnoty polí přímo ve svých dotazech

Funkce polí vám umožňují aplikovat transformace a kontroly na pole v klauzuli select. Funkce lze použít samostatně nebo s aliasy pomocí klíčového slova as.

Řetězcové funkce

Funkce pro datum a čas

Funkce pro rozsahy dat

Příklady použití

Funkce pro transformaci řetězců:

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

Funkce pro extrakci data/času:

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

Použití smíšených funkcí:

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

Funkce pro rozsahy dat pro analýzu časových období:

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
}

Funkce v agregací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**
- Funkce lze aliasovat pomocí klíčového slova `as`
- Všechny názvy funkcí nerozlišují velká a malá písmena
- Řetězcové funkce fungují s jakýmkoli polem, které lze převést na řetězec
- Funkce pro datum/čas fungují s typy polí DATE a DATETIME
- Funkce pro rozsahy dat vracejí přesná časová razítka pomocí operací DATE_TRUNC a INTERVAL v PostgreSQL
- Funkce lze použít jak ve výběru polí, tak v agregacích @groupBy
- `dayofweek()` vrací 0-6, kde 0=neděle, 6=sobota
- `quarter()` vrací 1-4 pro Q1-Q4
- `yearmonth()` vrací formát 'RRRR-MM' (např. '2023-12')
- `yearweek()` vrací formát 'RRRR-TT' (např. '2023-52')
- `yearquarter()` vrací formát 'RRRR-ČN' (např. '2023-Q4')
- `yearhalf()` vrací formát 'RRRR-PN' (např. '2023-P2')
- Funkce pro rozsahy dat poskytují přesnost na mikrosekundy pro přesné hranice časových období

Pokročilé funkce

Funkce polí

Aplikujte transformace a kontroly přímo v dotazech

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

Dotazy s více ID

Načítání podle jednoho nebo více ID pomocí polí a smíšených typů

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

Hluboké vnořování

Přístup k hluboce vnořeným relacím bez dopadu na výkon

orders { user { profile { preferences } } }

Podpora komentářů

Přidejte komentáře k dotazům pro dokumentaci

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

Přeložitelná pole

Přeložitelná (vícejazyčná) pole lze dotazovat několika způsoby:

Bez jazykové přípony:

products { name, description }

Vrací všechny vyplněné jazyky jako objekt JSON: {"en": "English", "cs": "Czech"}

S jazykovou příponou:

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

Vrací pouze konkrétní jazyk jako řetězec. Podporuje: cs, en, de, sk, pl, hu, fr, es

S aliasy:

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

Použijte aliasy k přejmenování polí s jazykovými příponami

**Výběr jazyka:**
- Jazyk se vybírá pomocí HTTP hlavičky Accept-Language. 
- Všechna přeložitelná pole ve výsledcích dotazu ve výchozím nastavení vracejí všechny vyplněné jazyky (bez jazykové přípony). 
- Použijte syntaxi fieldName:languageCode pro získání pouze konkrétního jazyka. 
- Jazyková přípona funguje jak ve filtrech WHERE, tak v polích SELECT. 
- Pokud požadovaný jazyk není k dispozici, pole může být prázdné nebo null. 
- Příklad: `Accept-Language: en-US, cs-CZ;q=0.9`

Vyhledávání a externí ID

Entity můžete odkazovat pomocí vyhledávacích identifikátorů namísto číselných/UUID ID. To je obzvláště užitečné při práci s daty z externích systémů, jako je ABRA Flexi/FlexiBee.

Standardní vyhledávání

Použijte identifikátory založené na polích, jako jsou code:, ean: nebo guid:

Použití vyhledávání podle kódu:

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

Použití vyhledávání v klauzuli WHERE:

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

Více ID s vyhledáváním:

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

Vyhledávání externích ID

Externí ID (ext:) vám umožňují odkazovat na entity pomocí identifikátorů z externích systémů. Tato ID jsou uložena ve vyhrazené tabulce extIds a podporují vícedílné klíče s dvojtečkami.

Použití externího ID v dotazu:

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

Použití externího ID v klauzuli WHERE:

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

Smíšené identifikátory (standardní + externí):

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

Externí ID v relačních polích:

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

Vícedílná externí ID (s dvojtečkami):

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

- Externí ID jsou automaticky vytvářena při importu dat s identifikátory `ext:`
- Stejná entita může mít více externích ID z různých systémů
- Externí ID fungují všude tam, kde fungují běžná ID (dotazy, klauzule WHERE, relační pole)
- Vše za `ext:` je považováno za externí identifikátor
- Externí ID nerozlišují velká a malá písmena při porovnávání
- Uloženo ve vyhrazené tabulce `extIds` s poli: code, related_id, related_entity

Koncový bod API: /api/query

Koncový bod /api/query přijímá požadavky POST s poli dotazů a vrací streamované odpovědi JSON pro optimální výkon. Více dotazů je zpracováváno paralelně a výsledky jsou odesílány, jakmile jsou k dispozici.

Požadované hlavičky

[navigate:/apiKeys|Spravovat klíče API|key]

Formát požadavku

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": {}
  }
]

Úspěšná odpověď

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

Chybová odpověď

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

Odpovědi jsou streamovány po částech pro optimální výkon. Více dotazů je zpracováváno paralelně a výsledky mohou dorazit v jiném pořadí, než bylo požadováno. Při zpracování streamu odpovědi použijte částečný JSON parser, který dokáže zpracovat neúplný JSON.

Vyplňování mezer pro časové řady (@fillGaps)

Vyplňte chybějící období ve skupinových výsledcích pro plynulé, nepřerušované grafy

Při vytváření grafů nebo sestav v průběhu času mají seskupené výsledky často mezery – měsíce, týdny nebo roky, pro které neexistují žádná data. @fillGaps automaticky vkládá řádky pro tyto chybějící hodnoty, takže výsledná sada je souvislá.

Použijte @fillGaps společně s @groupBy na stejném poli. Spouští se jako krok po zpracování a nemění vaše data.

Jak to funguje

• Chybějící intervaly jsou detekovány porovnáním hodnot seskupených polí s očekávaným rozsahem.
• Automatická detekce rozsahu: ve výchozím nastavení se rozsah rozprostírá od nejmenší po největší hodnotu ve skutečných datech.
• Explicitní rozsah: použijte from a/nebo to k rozšíření rozsahu nad rámec toho, co data obsahují.
• Několik seskupených polí: mezery jsou vyplněny pro každou kombinaci ostatních seskupených polí, která se vyskytuje v datech.
• Pojmenovaná pole: @fillGaps může odkazovat na funkci pojmenovanou pomocí as v @groupBy, např. @fillGaps(period).
• Agregace @count a @sum jsou pro chybějící řádky vyplněny 0.
• Agregace @avg, @min, @max jsou pro chybějící řádky vyplněny null.

Podporované typy polí

Měsíční trend s automaticky detekovaným rozsahem

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

Měsíce bez objednávek získají order_count=0 a monthly_revenue=0

Celoroční dashboard (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átí přesně 12 řádků, leden–prosinec 2024

Týdenní aktivita s nulovými metrikami pro prázdné týdny

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

Prázdné týdny získají event_count=0 a avg_duration=null

Seskupování celočíselného pole

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

- `@fillGaps` musí být použito společně s `@groupBy` na stejném poli
- Automatická detekce vyplňuje od minimální po maximální hodnotu přítomnou v datech
- Můžete zadat pouze `from`, pouze `to`, nebo obojí pro jemné ovládání
- Číselné hodnoty `from`/`to` se píší bez uvozovek; řetězcové hodnoty (yearmonth, yearweek) používají dvojité uvozovky
- Direktiva ovlivňuje pouze výslednou sadu; nemění data ani nespouští další SQL dotazy

Dotazy historie (@history)

Dotazování historických dat z archivních tabulek v kombinaci s aktuálním řádkem

Direktiva @history umožňuje dotazovat se na historická data z archivních tabulek. Pokud entity podporují archivaci, všechny změny záznamů jsou uchovávány ve speciálních archivních tabulkách, které udržují kompletní historii úprav a smazání. Dotaz vrací jak historické verze, tak aktuální stav záznamů.

Jak to funguje

Direktiva @history používá SQL UNION ALL ke kombinování:

• Řádky archivní tabulky — historické verze z {entity}_archive
• Aktuální řádek tabulky — aktuální stav z {entity}

Výsledky jsou seřazeny podle _archiveValidTo DESC NULLS LAST, což znamená, že historické verze se zobrazují nejprve (od nejnovější po nejstarší) a aktuální řádek se zobrazuje jako poslední.

Pole specifická pro archiv

Dotaz na všechny historické verze plus aktuální řádek

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

Dotaz k určitému časovému bodu (data k určitému datu)

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

Najít všechny změny konkrétního produktu

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

Najít smazané záznamy

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

Běžné případy použití

card: Auditní záznamy
Sledujte všechny změny citlivých dat pro dodržení souladu
card: Cestování časem
Zobrazte data tak, jak existovala v kterémkoli okamžiku v minulosti
card: Analýza změn
Analyzujte vzorce v úpravách dat v průběhu času
card: Obnova smazaných záznamů
Najděte a zkontrolujte smazané záznamy vedle aktuálních záznamů

- Ne všechny entity podporují archivaci. Pokud použijete @history na nepodporované entitě, obdržíte chybu
- Dotaz vždy zahrnuje aktuální stav záznamů jako poslední řádek (řádky) ve výsledné sadě
- Archivní tabulky mohou obsahovat mnoho verzí, proto používejte vhodné klauzule where a parametry limit
- Časová razítka by měla být poskytnuta ve formátu ISO 8601 (např. „2025-01-01T12:00:00“)
- Pro aktuální řádek je _archiveValidTo NULL a _deleted je vždy false

Filtrování pomocí klauzulí WHERE

Parametr where používá náš výkonný systém filtrů, který podporuje různé operátory, logické podmínky a filtrování vztahů. Přečtěte si o všech dostupných operátorech a podívejte se na praktické příklady.

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

[navigate:where.md|Zobrazit dokumentaci klauzule WHERE|filter]

Komplexní průvodce možnostmi filtrování a vyhledávání

Výkon a osvědčené postupy

card: Eliminace problému N+1
Systém automaticky dávkuje a optimalizuje vnořené dotazy, aby zabránil problémům N+1 SQL
card: Selektivní načítání polí
Vyžádejte si pouze pole, která potřebujete, abyste minimalizovali přenos a zpracování dat
card: Použijte stránkování
Pro velké datové sady vždy používejte limit a offset pro zlepšení doby odezvy. Výchozí limit je 1000 řádků – pro neomezené výsledky použijte limit: 0 (používejte s opatrností).
card: Streamování výsledků
Více dotazů může vracet výsledky v optimalizovaném pořadí pro lepší propustnost