Sdílet prostřednictvím

Agregace v rozhraní API pro GraphQL

Transformujte data Microsoft Fabric na užitečné přehledy pomocí agregací GraphQL. Místo načítání tisíců jednotlivých záznamů a jejich zpracování ve vaší aplikaci můžete požádat Fabric, aby seskupila data a vypočítala souhrny na straně serveru – výrazně zlepšuje výkon a snižuje přenos dat.

Agregace GraphQL fungují jako operace SQL GROUP BY, ale prostřednictvím rozhraní GraphQL API. Můžete spočítat položky na kategorii, vypočítat celkové výnosy, najít průměrné hodnocení nebo určit minimální/maximální hodnoty v tabulkách lakehouse a skladu – to vše v jednom efektivním dotazu.

Klíčové výhody:

  • Zpracování na straně serveru: Využijte optimalizované dotazovací stroje Fabric pro výpočty
  • Zmenšený přenos dat: Získání souhrnů místo nezpracovaných záznamů
  • Efektivita jednoho dotazu: Nahrazení více operací na straně klienta jednou agregací

V této příručce se dozvíte, jak vytvářet agregační dotazy pomocí praktického příkladu elektronického obchodování, který pokrývá vše od základních seskupení až po pokročilé funkce a důležitá omezení.

Kdo by měl používat agregace

Agregace GraphQL jsou cenné pro:

  • Vývojáři aplikací vytvářející vlastní řídicí panely a analytické aplikace, které potřebují souhrnná data Fabric
  • Datoví inženýři vytvářející datová rozhraní API, která obsluhují předem vypočítané metriky a klíčové ukazatele výkonu z objektů Fabric Lakehouse a skladů
  • Vývojáři BI vytvářejí vlastní analytická řešení, která doplňují Power BI agregovanými daty Fabric
  • Vývojáři integračních řešení vytvářející aplikace a pracovní postupy, které potřebují souhrnné statistiky z Fabricu
  • Datoví analytici vytvářejí samoobslužná analytická řešení, která vyžadují seskupené a agregované přehledy z dat Fabric.

Pokud načítáte data pro zobrazení grafů, výpočtu součtů, generování sestav nebo analýzy trendů, můžou agregace výrazně zlepšit výkon vaší aplikace a snížit přenos dat.

Běžné obchodní otázky, na které můžete odpovědět

Agregace GraphQL excelují při odpovídání na analytické otázky týkající se dat Fabric:

  • Počítání a seskupení: "Kolik produktů je v každé kategorii?" nebo "Kolik objednávek za měsíc?"
  • Finanční výpočty: "Jaké jsou celkové výnosy podle oblasti?" nebo "Průměrná hodnota objednávky podle segmentu zákazníka?"
  • Metriky výkonu: "Co je nejvyšší a nejnižší hodnocení produktů v každé kategorii?"
  • Přehledy zákazníků: "Kolik jedinečných zákazníků tento měsíc navštívilo?" nebo "Která města mají nejaktivnější uživatele?"

Tyto dotazy jsou ideální pro vytváření řídicích panelů, generování sestav a napájení analytických aplikací, kde potřebujete souhrnná data spíše než jednotlivé záznamy.

Požadavky

Před použitím agregací GraphQL se ujistěte, že máte:

  • Pracovní prostor Microsoft Fabric s příslušnými oprávněními
  • Jezero nebo sklad s tabulkami obsahujícími data, která chcete agregovat
  • Rozhraní API pro koncový bod GraphQL nakonfigurovaný pro vaše položky fabric.
  • Základní znalost syntaxe dotazů GraphQL

Kde tyto dotazy spustit

Rychlý start: Pomocí editoru API pro GraphQL ve vašem pracovním prostoru Fabric otestujte všechny příklady v tomto článku. Editor poskytuje zkoumání schématu, ověřování dotazů a okamžité výsledky.

Pro aplikace: Odesílat dotazy jako požadavky HTTP POST do koncového bodu GraphQL pomocí libovolné klientské knihovny GraphQL pro váš programovací jazyk.

Pro vývoj: Nástroje jako GraphQL Playground, Insomnia nebo Postman fungují dobře pro vývoj a testování dotazů.

Poznámka:

Příklady v tomto článku jsou připravené ke zkopírování a spuštění, jakmile nakonfigurujete rozhraní API pro koncový bod GraphQL. Některé příklady jsou zkráceny pro stručnost a můžou potřebovat přizpůsobení pro vaše konkrétní schéma.

Ukázkový scénář: Data elektronického obchodování ve Fabric

Pro účely této příručky používáme fiktivní datovou sadu elektronického obchodování uloženou v Microsoft Fabric Lakehouse nebo skladu. Tento scénář ukazuje, jak můžete analyzovat maloobchodní data pomocí agregací GraphQL.

V tomto příkladu patří údaje o produktech do kategorií, přičemž každá Product obsahuje pole, jako je cena a hodnocení (číselné hodnoty ideální pro agregaci) a vztah k Category. Když tyto tabulky zveřejníte prostřednictvím rozhraní API Fabric pro GraphQL, vygenerované schéma může vypadat takto:

type Category {
  id: ID!
  name: String!
  products: [Product!]!  # one-to-many relationship
}

type Product {
  id: Int!
  name: String!
  price: Float!
  rating: Int!
  category_id: Int!
  category: Category!  # many-to-one relationship
}

type ProductResult { # automatically generated, adding groupBy capabilities
  items: [Product!]!
  endCursor: String
  hasNextPage: Boolean!
  groupBy(fields: [ProductScalarFields!]): [ProductGroupBy!]!
}

type Query {
  products(
    first: Int
    after: String
    filter: ProductFilterInput
    orderBy: ProductOrderByInput
  ): ProductResult!
}

V tomto příkladu products může dotaz vrátit buď normální seznam položek, nebo pokud groupBy se používá agregované výsledky. Pojďme se zaměřit na používání groupBy funkcí a agregace tohoto dotazu.

Poznámka:

Ve stejném dotazu nemůžete načíst normální i seskupené výsledky. Další podrobnosti najdete v tématu Agregace a nezpracované položky se vzájemně vylučují.

Dostupné agregační funkce

Přesné dostupné funkce závisí na implementaci, ale mezi běžné agregační operace patří:

  • count – Počet záznamů (nebo nenulových hodnot pole) ve skupině.
  • sum – součet všech hodnot v číselném poli
  • avg – Průměr (průměr) hodnot v číselném poli.
  • min – Minimální hodnota v poli.
  • max – Maximální hodnota v poli.

V agregacích GraphQL zadáte název funkce a cílové pole, jak je znázorněno v příkladech count(field: id)atd sum(field: price). Každá funkce vrátí objekt, který umožňuje vybrat jedno nebo více polí, na která byla použita.

Poznámka:

V rozhraní API Microsoft Fabric pro GraphQL fungují agregační operace jako count, sum, avgmina max v současné době pracují pouze na číselných nebo kvantitativních polích (celá čísla, float). Nemůžete je použít přímo u textových polí nebo polí kalendářních dat. Nemůžete například vypočítat "průměr" pole řetězce. Podpora provádění agregací u jiných datových typů (například zřetězení textu nebo lexikální min/max) může být přidána v budoucích aktualizacích Fabric.

Základy agregačních dotazů

Pokud chcete provést agregaci v rozhraní GraphQL API Fabric, zadáte v dotazu argument groupBy, který definuje, jak seskupit data, a ve výsledku zahrnout agregační pole (například počty nebo součty). Modul GraphQL Fabric tyto dotazy efektivně zpracovává vůči podkladovým tabulkám lakehouse nebo datového skladu a vrací seznam seskupených záznamů s jejich klíčovými hodnotami a vypočítanými agregovanými metrikami.

Příklad 1: Počet produktů na kategorii

Pojďme produkty seskupit podle jejich kategorie a spočítat, kolik produktů je v každé skupině. Dotaz může vypadat takto:

query {
  products {
   groupBy(fields: [category_id]) 
   {
      fields {
         category_id # grouped key values
      }
      aggregations {
        count(field: id) # count of products in each group (count of "id")
     } 
   }
  }
}

V tomto dotazu:

  • groupBy(fields: [category_id]) říká modulu Fabric GraphQL, aby seskupil produkty podle category_id pole.
  • Ve výběru výsledků požadujete group a count agregát na poli id. Počítání id efektivně počítá produkty v dané skupině.

Jak výsledek vypadá: Každá položka v odpovědi představuje jednu skupinu kategorií. Objekt groupBy obsahuje klíč seskupení. Obsahuje hodnotu category_id a count { id } poskytuje počet produktů v dané kategorii:

{
  "data": {
    "products": {
      "groupBy": [
        {
          "fields": {
            "category_id": 1
          },
          "aggregations": {
            "count": 3
          }
        },
        {
          "fields": {
            "category_id": 2
          },
          "aggregations": {
            "count": 2
          }
        },
        // Sample shortened for brevity
      ]
    }
  }
}

Tento výstup nám říká, že kategorie 1 má tři produkty, kategorie 2 má 2 atd.

Příklad 2: Součet a průměr

V jednom dotazu můžeme požádat o více metrik agregace. Předpokládejme, že chceme pro každou kategorii, celkovou cenu všech produktů a průměrné hodnocení:

query {
  products {
   groupBy(fields: [category_id]) 
   {
      fields {
         category_id
      }
     aggregations {
        count(field: id)   # number of products in the category
        sum(field: price)  # sum of all product prices in the category
        avg(field: rating) # average rating of products in the category
     } 
   }
  }
}

Tento dotaz by vrátil následující výsledky:

{
  "data": {
    "products": {
      "groupBy": [
        {
          "fields": {
            "category_id": 1
          },
          "aggregations": {
            "count": 3,
            "sum": 2058.98,
            "avg": 4
          }
        },
        {
          "fields": {
            "category_id": 2
          },
          "aggregations": {
            "count": 2,
            "sum": 109.94,
            "avg": 4
          }
        },
        ...
      ]
    }
  }
}

Každý objekt skupiny zahrnuje kategorii a vypočítané agregace, jako je počet produktů, součet jejich cen a průměrné hodnocení v dané kategorii.

Příklad 3: Seskupení podle více polí

Seskupení můžete seskupit podle více než jednoho pole, abyste získali seskupení na více úrovních. Pokud má váš produkt například pole rating, můžete seskupit podle category_id a rating a poté vypočítat průměr price pro skupinu.

query {
  products {
   groupBy(fields: [category_id, rating])
   {
      fields {
         category_id
         rating
      }
     aggregations {
        avg(field: price)
     }
   }
  }
}

To by seskupilo produkty podle jedinečné kombinace kategorií a hodnocení, jak je znázorněno níže:

 {
    "fields": {
        "category_id": 10,
        "rating": 4
    },
    "aggregations": {
        "avg": 6.99
    }
}

A tak dále pro každou dvojici hodnocení kategorií v datech.

Návod

Při seskupování podle více polí se explicitní řazení stává zvlášť důležité pro předvídatelné výsledky. Viz Řazení seskupených výsledků vyžaduje explicitní řazení.

Příklad 4: Použití odlišných hodnot

Funkce agregace podporuje jedinečný modifikátor pro počítání nebo zvažování jedinečných hodnot. Pokud například chcete zjistit, kolik různých kategorií existuje v kolekci produktů, můžete použít odlišný počet:

query {
  products {
   groupBy(fields: [category_id]) 
   {
      fields {
         category_id
      }
     aggregations {
        count(field: id, distinct: true) 
     } 
   }
  }
}

Tento dotaz vrátí výsledek s počtem jedinečných produktů pro každou kategorii. Výsledek by vypadal takto:

{
  "data": {
    "products": {
      "groupBy": [
        {
          "fields": {
            "category_id": 1
          },
          "aggregations": {
            "count": 3
          }
        },
        {
          "fields": {
            "category_id": 2
          },
          "aggregations": {
            "count": 2
          }
        },
        ...
      ]
    }
  }
}

Návod

Další pokyny k tomu, kdy a jak se správně používají, najdete v tématu Vhodné použití jedinečné agregace.

Příklad 5: Použití aliasů

Můžete vytvořit aliasy pro agregace, které poskytují smysluplné a snadno pochopitelné názvy agregovaných výsledků. Agregaci můžete například pojmenovat v předchozím příkladu, protože distinctProductCategoryCount počítá různé kategorie produktů, abyste lépe porozuměli výsledkům:

query {
  products {
   groupBy(fields: [category_id]) 
   {
      fields {
         category_id
      }
     aggregations {
        distinctProductCategoryCount: count(field: id, distinct: true) 
     } 
   }
  }
}

Výsledek je podobný, ale smysluplnější s vlastním aliasem:

{
  "data": {
    "products": {
      "groupBy": [
        {
          "fields": {
            "category_id": 1
          },
          "aggregations": {
            "distinctProductCategoryCount": 3
          }
        },
        {
          "fields": {
            "category_id": 2
          },
          "aggregations": {
            "distinctProductCategoryCount": 2
          }
        },
        ...
      ]
    }
  }
}

Příklad 6: Použití having klauzule

Agregované výsledky je možné filtrovat pomocí having klauzule. Předchozí příklad můžete například upravit tak, aby vracely jenom výsledky větší než dvě:

query {
  products {
   groupBy(fields: [category_id]) 
   {
      fields {
         category_id
      }
     aggregations {
        distinctProductCategoryCount: count(field: id, distinct: true, having:  {
           gt: 2
        }) 
     } 
   }
  }
}

Výsledek vrátí jednu hodnotu s jedinou kategorií s více než dvěma produkty:

{
  "data": {
    "products": {
      "groupBy": [
        {
          "fields": {
            "category_id": 1
          },
          "aggregations": {
            "distinctProductCategoryCount": 3
          }
        }
      ]
    }
  }
}

Omezení a osvědčené postupy

Pokud používáte agregace v rozhraní API Microsoft Fabric pro GraphQL, je potřeba zvážit důležitá pravidla a omezení. Pomocí těchto osvědčených postupů a porozumění těmto omezením můžete vytvářet efektivní agregační dotazy GraphQL, které poskytují výkonné přehledy a zároveň zajišťují předvídatelné výsledky, zejména při práci s velkými datovými sadami nebo implementací stránkování.

Funkce agregace je užitečná pro případy použití sestav a analýz, ale vyžaduje pečlivé strukturování dotazů. Vždy pečlivě zkontrolujte, jestli jsou pole groupBy v souladu s vybranými výstupními poli, přidejte řazení pro předvídatelné pořadí, zejména při stránkování, a pro datové typy používejte jedinečné a agregační funkce.

Následující části obsahují tři klíčové oblasti, které je potřeba pochopit: Agregace a nezpracované položky se vzájemně vylučují, seskupené výsledky řazení vyžadují explicitní řazení a vhodné použití jedinečné agregace.

Agregace a nezpracované položky se vzájemně vylučují

V současné době nemůžete načíst souhrnná data seskupená i nezpracovaný seznam položek ve stejném dotazu současně. Při použití groupBy v dotazu se rozhraní API přepne do "režimu agregace" a vrátí pouze seskupené výsledky. Tento návrh zachovává jednoznačnou strukturu odpovědí – každý dotaz je buď v "režimu agregace", nebo "režim položek seznamu", ale nikdy obojí.

Jak to funguje v praxi:

Dotaz products(...) vrátí jednu ze dvou možností:

  • Seznam jednotlivých produktů (pokud groupBy se nepoužívá)
  • Seznam seskupených výsledků s agregovanými daty (při použití groupBy)

Všimněte si v agregovaných příkladech výše, že odpověď obsahuje groupBy a agreguje pole, ale chybí obvyklý items seznam produktů.

Co se stane, když zkusíte obojí:

Pokud se pokusíte požádat o normální položky i skupiny ve stejném dotazu, modul GraphQL vrátí chybu nebo tento výběr nepovolí.

Alternativní řešení:

Pokud potřebujete nezpracovaná i agregovaná data, spusťte dva samostatné dotazy: jeden pro nezpracovaná data a jeden pro agregovaná data. Tento přístup poskytuje úplnou kontrolu nad datovými sadami a dá se optimalizovat na základě konkrétních požadavků na ukládání do mezipaměti a výkon.

Řazení seskupených výsledků vyžaduje explicitní řazení.

Agregované skupiny se vrátí nepředvídatelným pořadím, pokud nezadáte explicitní řazení. Vždy používejte orderBy nebo sort argumenty, abyste zajistili konzistentní a smysluplné výsledky.

Proč je důležité explicitní řazení:

  • Nepředvídatelné výchozí pořadí: Bez orderBy, mohou se skupiny vrátit v libovolném pořadí určeném databází.
  • Požadavky na stránkování: Stabilní pořadí řazení je nezbytné pro konzistentní chování stránkování.
  • Uživatelské prostředí: Předvídatelné řazení zlepšuje interpretaci dat a spolehlivost aplikací.

Pokud je nutné zadat řazení:

  • V polích groupBy není žádný primární klíč: Pokud pole seskupení neobsahují primární klíč, musíte přidat orderBy
  • Ne jedinečné klíče seskupení: Při seskupování podle polí, jako jsou názvy kategorií nebo kalendářní data
  • Scénáře stránkování: Kdykoli plánujete použít stránkování pomocí limitu/offsetu nebo kurzoru

Osvědčené postupy:

  • Seřazení podle agregačních hodnot (např. nejvyššího počtu jako první) pro analytické přehledy
  • Použití abecedního řazení pro seskupování podle kategorií
  • Kombinování více kritérií řazení pro komplexní potřeby řazení

Vhodné použití jedinečné agregace

distinct Modifikátor eliminuje duplicitní hodnoty před provedením agregací a zajišťuje přesné výpočty, když data obsahují duplicity.

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

  • Počet jedinečných položek: count(field: category_id, distinct: true) spočítá, kolik různých kategorií existuje v každé skupině.
  • Deduplikované součty: sum(field: price, distinct: true) přidá každou jedinečnou cenovou hodnotu pouze jednou na skupinu.
  • Scénáře spojení: Když se produkty zobrazují vícekrát kvůli spojení tabulek, použití 'distinct' zajistí, že se každá položka počítá pouze jednou.

Kdy použít jedinečné:

  • Vaše data obsahují legitimní duplicity, které by zkreslily výpočty.
  • Pracujete s připojenými tabulkami, které vytvářejí duplicitní řádky.
  • Potřebujete spočítat jedinečné hodnoty místo celkového počtu výskytů.

Důležité informace o výkonu:

Odlišné operace vyžadují další zpracování. Používejte pouze v případě potřeby přesnosti dat.

Související obsah

  • Last updated on