Aggregációk az API for GraphQL-ben

A Microsoft Fabric-adatokat a GraphQL-aggregációkkal végrehajtható elemzésekká alakíthatja. Ahelyett, hogy több ezer rekordot kér le és dolgoz fel az alkalmazásban, megkérheti a Fabricet, hogy csoportosítsa az adatokat, és számítsa ki az összegzéseket kiszolgálóoldalon – jelentősen javítva a teljesítményt és csökkenti az adatátvitelt.

A GraphQL-aggregációk az SQL GROUP BY-műveletekhez hasonlóan működnek, de a GraphQL API-n keresztül. Kategóriánként megszámlálhatja az elemeket, kiszámíthatja a bevétel összegét, megkeresheti az átlagos értékeléseket, vagy meghatározhatja a minimális/maximális értékeket a lakehouse- és raktártáblákban – mindezt egyetlen, hatékony lekérdezésben.

Főbb előnyök:

  • Kiszolgálóoldali feldolgozás: Használja ki a Fabric optimalizált lekérdezési motorjait számításokhoz
  • Csökkentett adatátvitel: Összegzések lekérése nyers rekordok helyett
  • Egyetlen lekérdezés hatékonysága: Több ügyféloldali művelet lecserélése egy összesítésre

Ez az útmutató bemutatja, hogyan hozhat létre összesítő lekérdezéseket egy gyakorlati e-kereskedelmi példán keresztül, amely az alapszintű csoportosítástól a speciális függvényekig és a fontos korlátozásokig mindent lefed.

Kinek érdemes aggregációkat használnia?

A GraphQL-aggregációk értékesek a következőkhöz:

  • Az alkalmazásfejlesztők olyan egyéni irányítópultokat és elemzési alkalmazásokat készítenek, amelyek összesített Fabric-adatokat igényelnek.
  • Az adatmérnökök olyan adat API-kat hoznak létre, amelyek előre kiszámított metrikákat és KPI-ket szolgálnak ki Fabric lakehouse-okból és raktárakból
  • A BI-fejlesztők olyan egyéni elemzési megoldásokat készítenek, amelyek a Power BI-t összesített Háló-adatokkal egészítik ki
  • Integrációs fejlesztők olyan alkalmazásokat és munkafolyamatokat hoznak létre, amelyek összefoglaló statisztikákat igényelnek a Fabricből
  • Az adatelemzők olyan önkiszolgáló elemzési megoldásokat készítenek, amelyek csoportosított, összesített elemzéseket igényelnek a Fabric-adatokból

Ha adatokat kér le diagramok megjelenítéséhez, összeg kiszámításához, jelentések létrehozásához vagy trendek elemzéséhez, az összesítések jelentősen javíthatják az alkalmazás teljesítményét, és csökkenthetik az adatátvitelt.

Gyakori üzleti kérdések, amelyek megválaszolhatók

A GraphQL-aggregációk kiválóan válaszolnak a Fabric-adatokkal kapcsolatos elemzési kérdésekre:

  • Számlálás és csoportosítás: "Hány termék van az egyes kategóriákban?" vagy "Hány megrendelés havonta?"
  • Pénzügyi számítások: "Mi a teljes bevétel régiónként?" vagy "Átlagos rendelési érték ügyfélszegmens szerint?"
  • Teljesítménymetrikák: "Mi az egyes kategóriák legmagasabb és legalacsonyabb besorolású terméke?"
  • Ügyfélelemzések: "Hány egyedi ügyfél látogatott el ebben a hónapban?" vagy "Mely városokban vannak a legaktívabb felhasználók?"

Ezek a lekérdezések ideálisak irányítópultok létrehozásához, jelentések létrehozásához és elemzési alkalmazások bekapcsolásához, ahol az egyes rekordok helyett összegzett adatokra van szükség.

Előfeltételek

A GraphQL-aggregációk használata előtt győződjön meg arról, hogy a következőkkel rendelkezik:

  • Megfelelő engedélyekkel rendelkező Microsoft Fabric-munkaterület
  • Egy tóház vagy raktár az összesíteni kívánt adatokat tartalmazó táblákkal
  • A Fabric-elemekhez konfigurált GraphQL-végponthoz készült API
  • A GraphQL lekérdezési szintaxisának alapszintű ismerete

A lekérdezések futtatásának helye

Rövid útmutató: A Cikk összes példájának teszteléséhez használja a GraphQL-szerkesztő API-t a Fabric-munkaterületen. A szerkesztő sémafeltárást, lekérdezésérvényesítést és azonnali eredményeket biztosít.

Alkalmazások esetén: Lekérdezések küldése HTTP POST-kérésekként a GraphQL-végpontra, bármely GraphQL-ügyfélkódtár használatával a programozási nyelvhez.

Fejlesztéshez: Az olyan eszközök, mint a GraphQL Playground, az Insomnia vagy a Postman jól használhatók a lekérdezések fejlesztéséhez és teszteléséhez.

Megjegyzés:

A cikkben szereplő példák a GraphQL-végpont API-jának konfigurálását követően másolhatók és futtathatók. Néhány példa rövidítve van a rövidítéshez, és szükség lehet az adott sémához való alkalmazkodásra.

Példaforgatókönyv: E-kereskedelmi adatok a Fabricben

Ebben az útmutatóban a Microsoft Fabric lakehouse-ban vagy -raktárban tárolt fiktív e-kereskedelmi adatkészletet használjuk. Ez a forgatókönyv bemutatja, hogyan elemezheti a kiskereskedelmi adatokat GraphQL-aggregációk használatával.

Ebben a példában a termékadatok kategóriákhoz tartoznak, amelyek mindegyike Product olyan mezőket tartalmaz, mint az ár és az értékelés (az összesítéshez tökéletes numerikus értékek), valamint egy kapcsolattal Category. Ha ezeket a táblákat a Fabric GRAPHQL-hez készült API-ján keresztül teszi elérhetővé, a létrehozott séma a következőképpen nézhet ki:

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!
}

Ebben a példában a products lekérdezés visszaadhatja az elemek normál listáját, vagy ha groupBy használják, összesített eredményeket. Koncentráljunk a groupBy lekérdezés összesítési funkcióinak használatára.

Megjegyzés:

Nem lehet beolvasni a normál elemeket és a csoportosított eredményeket ugyanabban a lekérdezésben. További részletekért lásd: Az összesítés és a nyers elemek kölcsönösen kizárják egymást.

Elérhető összesítési függvények

A pontos elérhető függvények a megvalósítástól függenek, de a gyakori összesítési műveletek a következők:

  • count – A csoport rekordjainak száma (vagy egy mező nem null értékű értékei).
  • sum – Egy numerikus mező összes értékének összege.
  • avg – Egy numerikus mező értékeinek átlaga (középértéke).
  • min – Minimális érték egy mezőben.
  • max – Maximális érték egy mezőben.

A GraphQL-aggregációkban meg kell adnia a függvény nevét és a célmezőt, ahogy a példákban count(field: id), sum(field: price) stb. látható. Minden függvény egy objektumot ad vissza, amely lehetővé teszi egy vagy több mező kiválasztását.

Megjegyzés:

A Microsoft Fabric GraphQL-hez készült API-jában az aggregációs műveletek, például counta , sum, avgminés max jelenleg csak numerikus vagy mennyiségi mezőkön (egész számok, lebegőpontos értékek) működnek. Közvetlenül nem használhatja őket szöveg- vagy dátummezőkön. Például egy sztringmező "átlagát" nem lehet kiszámítani. Más adattípusok (például szövegösszefűzés vagy lexikográfiai min/max) összesítéseinek támogatása a Fabric későbbi frissítéseiben is lehetséges.

Az aggregációs lekérdezés alapjai

Ha a Fabric GraphQL API-jában szeretne összesítést végezni, a lekérdezésben meg kell adnia egy groupBy argumentumot, amely meghatározza az adatok csoportosításának módját, és összeadási mezőket (például darabszámokat vagy összegeket) kér az eredményben. A Fabric GraphQL-motorja hatékonyan dolgozza fel ezeket a lekérdezéseket az alapul szolgáló lakehouse- vagy raktártáblákon, és visszaadja a csoportosított rekordok listáját a fő értékekkel és a kiszámított összesített metrikákkal.

1. példa: Termékek száma kategóriánként

Csoportosítsuk a termékeket a kategóriájuk szerint, és számoljuk meg, hogy hány termék van az egyes csoportokban. A lekérdezés a következőképpen nézhet ki:

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")
     } 
   }
  }
}

Ebben a lekérdezésben:

  • groupBy(fields: [category_id])A Fabric GraphQL-motor a termékek mező szerinti csoportosítását kéri.category_id
  • Az eredménykiválasztásban kérje a group és a count összesítést a id mezőn. A számlálás id hatékonyan megszámolja az adott csoportban lévő termékeket.

Az eredmény a következőképpen néz ki: A válasz minden eleme egy kategóriacsoportot jelöl. Az groupBy objektum tartalmazza a csoportosítási kulcsot. Itt szerepel az category_id érték, és count { id } megadja az adott kategóriába tartozó termékek számát:

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

Ez a kimenet azt jelzi, hogy az 1. kategóriának három terméke van, a 2. kategóriának 2 és így tovább.

2. példa: Összeg és átlag

Egy lekérdezésben több aggregációs metrikát is lekérhetünk. Tegyük fel, hogy minden kategóriához az összes termék teljes árát és az átlagos minősítést szeretnénk:

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
     } 
   }
  }
}

Ez a lekérdezés a következő eredményeket adja vissza:

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

Minden csoportobjektum tartalmazza a kategóriát és a kiszámított összesítéseket, például a termékek számát, az árak összegét és az adott kategória átlagos minősítéseit.

3. példa: Csoportosítás több mező szerint

Több mező szerint csoportosítva többszintű csoportosítást kaphat. Ha például a terméknek van egy rating mezője, akkor csoportosíthat mind category_id, mind rating szerint, majd kiszámíthatja a csoport átlagát price alapján.

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

Ez a kategóriák és minősítések egyedi kombinációja alapján csoportosítaná a termékeket az alábbiak szerint:

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

És így tovább az összes kategória-minősítési pár esetében az adatokban.

Jótanács

Ha több mező szerint csoportosít, a explicit rendezés különösen fontos lesz a kiszámítható eredmények szempontjából. Lásd : A csoportosított eredmények rendezése explicit rendezést igényel.

4. példa: Különböző adatok használata

Az aggregációs funkció egy különálló módosító használatát támogatja az egyedi értékek megszámlálásához vagy figyelembe véveéhez. Ha például meg szeretné tudni, hogy hány különböző kategória létezik a termékgyűjteményben, használhatja a különböző darabszámokat:

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

Ez a lekérdezés egy eredményt ad vissza az egyes kategóriákhoz tartozó egyedi termékek számával. Az eredmény a következőképpen nézne ki:

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

Jótanács

Ha további útmutatást szeretne a különböző aggregációk megfelelő használatáról, olvassa el a különböző összesítések megfelelő használatát ismertető témakört.

5. példa: Aliasok használata

Létrehozhat aliasokat az összesítésekhez, hogy érthető és könnyen érthető neveket biztosítson az összesített eredményekhez. Például az előző példában elnevezheti az összesítést distinctProductCategoryCount-nek, mivel az eltérő termékkategóriák darabszámát számolja, hogy jobban megértse az eredményeket.

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

Az eredmény az egyéni aliashoz hasonló, de érthetőbb:

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

6. példa: A having záradék használata

Az összesített eredményeket a záradékkal having is szűrheti. Módosíthatja például az előző példát úgy, hogy csak kettőnél nagyobb eredményeket adjon vissza:

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

Az eredmény egyetlen értéket ad vissza, amelynek egyetlen kategóriája kétnál több terméket tartalmaz:

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

Korlátozások és ajánlott eljárások

Ha aggregációkat használ a Microsoft Fabric GraphQL API-jában, fontos szabályokat és korlátozásokat kell figyelembe vennie. Az ajánlott eljárások követésével és a korlátozások megértésével hatékony GraphQL-összesítő lekérdezéseket hozhat létre, amelyek hatékony elemzéseket nyújtanak, és kiszámítható eredményeket nyújtanak, különösen nagy adatkészletek használata vagy lapszámozás megvalósításakor.

Az összesítési funkció hasznos jelentéskészítési és elemzési használati esetekhez, de a lekérdezések gondos strukturálását igényli. Mindig ellenőrizze, hogy a groupBy mezők igazodnak-e a kiválasztott kimeneti mezőkhöz, rendezést ad-e a kiszámítható sorrendhez, különösen lapszámozáskor, és az adattípusokhoz megfelelő különböző és összesítő függvényeket használjon.

A következő szakaszok három fontos területet fednek le: Az összesítés és a nyers elemek kölcsönösen kizárják egymást, a csoportosított eredmények rendezése explicit rendezést igényel, és a különböző összesítések megfelelő használata.

Az összesítés és a nyers elemek kölcsönösen kizárják egymást

Jelenleg nem lehet egyszerre lekérni a csoportosított összesítő adatokat és az ugyanabban a lekérdezésben lévő elemek nyers listáját. Amikor a lekérdezésben használja groupBy , az API "aggregációs módra" vált, és csak csoportosított eredményeket ad vissza. Ez a kialakítás egyértelműen tartja a válaszstruktúrát – minden lekérdezés vagy "összesítési módban" van, vagy "listaelemek módban", de soha sincs mindkettőben.

Hogyan működik ez a gyakorlatban:

A products(...) lekérdezés a következőt adja vissza:

  • Az egyes termékek listája (ha groupBy nincs használatban)
  • Csoportosított eredmények listája összesítő adatokkal (használat esetén groupBy )

Figyelje meg a fenti összesített példákban, hogy a válasz tartalmazza a groupBy és az összesített mezőket, de a szokásos items terméklista hiányzik.

Mi történik, ha mindkettőt kipróbálja:

Ha ugyanabban a lekérdezésben a normál elemeket és csoportokat is megkísérli kérni, a GraphQL-motor hibát ad vissza, vagy nem engedélyezi a kijelölést.

Átmeneti megoldás:

Ha nyers és összesített adatokra is szüksége van, futtasson két külön lekérdezést: egyet a nyers adatokhoz, egyet pedig az összesített adatokhoz. Ez a megközelítés teljes körű vezérlést biztosít mindkét adathalmaz felett, és az adott gyorsítótárazási és teljesítménykövetelmények alapján optimalizálható.

A csoportosított eredmények rendezése explicit rendezést igényel

Az összesített csoportok kiszámíthatatlan sorrendben jelennek meg, hacsak nem ad meg explicit rendezést. Mindig használjon orderBy vagy sort argumentumokat a konzisztens, értelmes eredmények biztosításához.

Miért fontos a explicit megrendelés:

  • Előre nem látható alapértelmezett sorrend: Nélküle orderBya csoportok tetszőleges adatbázis által meghatározott sorrendben térhetnek vissza
  • Lapozási követelmények: A stabil rendezési sorrend elengedhetetlen a folyamatos lapozási viselkedéshez
  • Felhasználói élmény: A kiszámítható rendezés javítja az adatértelmezést és az alkalmazások megbízhatóságát

Amikor meg kell adnia a rendelést:

  • Nincs elsődleges kulcs a GroupBy mezőkben: Ha a csoportosítási mezők nem tartalmaznak elsődleges kulcsot, hozzá kell adnia orderBy
  • Nem egyedi csoportosítási kulcsok: Ha mezők, például kategórianevek vagy dátumok szerint csoportosít
  • Lapozási forgatókönyvek: Bármikor, amikor korlátozást,eltolást vagy kurzort szeretne lapozást használni

Ajánlott eljárások:

  • Rendezés összesítési értékek (például a legmagasabb szám első) alapján az elemzési elemzésekhez
  • Betűrendes rendezés használata kategóriaalapú csoportosításokhoz
  • Több rendezési feltétel kombinálása az összetett rendezési igényekhez

A különböző összesítések megfelelő használata

A distinct módosító az összesítések végrehajtása előtt kiküszöböli az ismétlődő értékeket, így pontos számításokat végezhet, ha az adatok ismétlődő adatokat tartalmaznak.

Gyakori használati esetek:

  • Egyedi számok: count(field: category_id, distinct: true) megszámolja, hogy hány különböző kategória létezik az egyes csoportokban
  • Deduplikált összegek: sum(field: price, distinct: true) minden egyedi árértéket csoportonként csak egyszer ad hozzá
  • Összekapcsolási forgatókönyvek: Ha a termékek többször is megjelennek a táblabeillesztések miatt, a különböző elemek egyszer lesznek megszámolva

Mikor érdemes különbözőeket használni:

  • Az adatok olyan hiteles duplikációkat tartalmaznak, amelyek eltúlznák a számításokat
  • Ismétlődő sorokat létrehozó összekapcsolt táblákkal dolgozik
  • Az összes előfordulás helyett egyedi értékeket kell megszámolnia

Teljesítménnyel kapcsolatos szempont:

A különböző műveletek további feldolgozást igényelnek. Csak akkor használja, ha az adat pontosságához szükséges.

Kapcsolódó tartalom

  • Last updated on