Del via

Sammenlægninger i API til GraphQL

Omdann dine Microsoft Fabric-data til handlingsorienterede indsigter med GraphQL-aggregeringer. I stedet for at hente tusindvis af individuelle poster og behandle dem i din applikation, kan du bede Fabric om at gruppere dine data og beregne opsummeringer server-side – hvilket dramatisk forbedrer ydeevnen og reducerer dataoverførslen.

GraphQL-aggregationer fungerer som SQL GROUP BY-operationer, men gennem GraphQL API'en. Du kan tælle varer pr. kategori, beregne totalindtægter, finde gennemsnitlige vurderinger eller bestemme min/max-værdier på tværs af dine lakehouse- og lagertabeller – alt sammen i en enkelt, effektiv forespørgsel.

Vigtigste fordele:

  • Server-side behandling: Udnyt Fabrics optimerede forespørgselsmotorer til beregninger
  • Reduceret dataoverførsel: Få resuméer i stedet for rå poster
  • Enkelt forespørgselseffektivitet: Erstat flere klientoperationer med én aggregation

Denne guide viser dig, hvordan du bygger aggregationsforespørgsler ved hjælp af et praktisk e-handelseksempel, der dækker alt fra grundlæggende gruppering til avancerede funktioner og vigtige begrænsninger.

Hvem bør bruge aggregeringer

GraphQL-aggregeringer er værdifulde til:

  • Applikationsudviklere , der bygger brugerdefinerede dashboards og analyseapplikationer, der har brug for opsummerede Fabric-data
  • Dataingeniører , der skaber data-API'er, der leverer forudberegnede målinger og KPI'er fra Fabric-søhuse og lagre
  • BI-udviklere bygger skræddersyede analyseløsninger, der supplerer Power BI med aggregerede Fabric-data
  • Integrationsudviklere , der opretter applikationer og arbejdsgange, der har brug for oversigtsstatistikker fra Fabric
  • Dataanalytikere bygger selvbetjeningsanalyseløsninger, der kræver grupperede, aggregerede indsigter fra Fabric-data

Hvis du henter data for at vise diagrammer, beregne totaler, generere rapporter eller analysere tendenser, kan aggregeringer markant forbedre din applikations ydeevne og reducere dataoverførsel.

Almindelige forretningsspørgsmål, du kan besvare

GraphQL-aggregationer er fremragende til at besvare analytiske spørgsmål om dine Fabric-data:

  • Optælling og gruppering: "Hvor mange produkter er der i hver kategori?" eller "Hvor mange ordrer pr. måned?"
  • Finansielle beregninger: "Hvad er den samlede omsætning efter region?" eller "Gennemsnitlig ordreværdi efter kundesegment?"
  • Præstationsmålinger: "Hvad er det højest og lavest vurderede produkt i hver kategori?"
  • Kundeindsigter: "Hvor mange unikke kunder besøgte denne måned?" eller "Hvilke byer har flest aktive brugere?"

Disse forespørgsler er ideelle til at bygge dashboards, generere rapporter og drive analyseapplikationer, hvor du har brug for opsummerede data i stedet for individuelle poster.

Forudsætninger

Før du bruger GraphQL-aggregationer, skal du sikre dig, at du har:

  • Et Microsoft Fabric-arbejdsområde med de relevante tilladelser
  • Et lakehouse eller lager med tabeller, der indeholder de data, du ønsker at samle
  • Et API til GraphQL-endpoint konfigureret til dine Fabric-elementer
  • Grundlæggende kendskab til GraphQL-forespørgselssyntaks

Hvor skal disse forespørgsler køres

Hurtig start: Brug API'et til GraphQL-editoren i dit Fabric-arbejdsområde til at teste alle eksemplerne i denne artikel. Redaktøren leverer skemaudforskning, forespørgselsvalidering og øjeblikkelige resultater.

For applikationer: Send forespørgsler som HTTP POST-forespørgsler til dit GraphQL-endpoint, ved at bruge et hvilket som helst GraphQL-klientbibliotek til dit programmeringssprog.

Til udvikling: Værktøjer som GraphQL Playground, Insomnia eller Postman fungerer godt til udvikling og testning af forespørgsler.

Bemærk

Eksemplerne i denne artikel er klar til at kopieres og køres, når du har konfigureret dit API til GraphQL-endpoint. Nogle eksempler er forkortet for korthedens skyld og kan kræve tilpasning til dit specifikke skema.

Eksempelscenarie: E-handelsdata i Fabric

Til denne guide bruger vi et fiktivt e-handelsdatasæt, der er gemt i dit Microsoft Fabric-lakehouse eller lager. Dette scenarie demonstrerer, hvordan du kan analysere detaildata ved hjælp af GraphQL-aggregationer.

I dette eksempel tilhører produktdata kategorier, hvor hver Product indeholder felter som pris og vurdering (numeriske værdier perfekte til aggregering), og en relation til Category. Når du eksponerer disse tabeller gennem Fabrics API for GraphQL, kan det genererede skema se sådan ud:

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

I dette eksempel kan forespørgslen products enten returnere en normal liste over elementer eller aggregerede resultater, hvis groupBy de bruges. Lad os fokusere på at bruge funktionerne og sammenlægningsfunktionerne groupBy i denne forespørgsel.

Bemærk

Du kan ikke hente både normale elementer og grupperede resultater i samme forespørgsel. For flere detaljer, se Aggregering, og rå elementer udelukker hinanden.

Tilgængelige sammenlægningsfunktioner

De nøjagtige funktioner, der er tilgængelige, afhænger af implementeringen, men almindelige sammenlægningshandlinger omfatter:

  • count – antallet af poster (eller værdier, der ikke er null for et felt) i gruppen.
  • sum – summen af alle værdier i et numerisk felt.
  • avg – middelværdi for værdier i et numerisk felt.
  • min – minimumværdi i et felt.
  • max – Maksimumværdi i et felt.

I GraphQL-aggregationer angiver du funktionsnavnet og målfeltet, som vist i eksemplerne count(field: id), sum(field: price), osv. Hver funktion returnerer et objekt, der tillader dig at vælge et eller flere felter, det er anvendt på.

Bemærk

I Microsoft Fabrics API for GraphQL fungerer aggregeringsoperationer som count, sum, avg, min, og max arbejder i øjeblikket kun på numeriske eller kvantitative felter (heltal, flydende tal). Du kan ikke bruge dem direkte på tekst- eller datofelter. For eksempel kan du ikke beregne "gennemsnittet" af et strengfelt. Understøttelse af at udføre aggregater på andre datatyper (såsom tekstkonkatenering eller leksikografisk min/max) kan blive tilføjet i fremtidige opdateringer til Fabric.

Grundlæggende oplysninger om sammenlægningsforespørgsler

For at udføre en aggregering i Fabrics GraphQL API specificerer du et groupBy argument i din forespørgsel for at definere, hvordan dataene skal grupperes, og anmoder om aggregeringsfelter (som tællinger eller summer) i resultatet. Fabrics GraphQL-motor behandler disse forespørgsler effektivt mod dine underliggende lakehouse- eller lagertabeller og returnerer en liste over grupperede poster med deres nøgleværdier og beregnede aggregerede målinger.

Eksempel 1: Tæl produkter pr. kategori

Lad os gruppere produkter efter deres kategori og tælle, hvor mange produkter der er i hver gruppe. Forespørgslen kan se ud som følger:

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

I denne forespørgsel:

  • groupBy(fields: [category_id]) fortæller Fabric GraphQL-programmet at gruppere produkter efter feltet category_id .
  • I resultatvalget anmoder du om group og en count aggregering i feltet id . Optælling id tæller effektivt produkterne i den pågældende gruppe.

Sådan ser resultatet ud: Hvert element i svaret repræsenterer én kategorigruppe. Objektet groupBy indeholder grupperingsnøglen. Her inkluderer den værdien category_id og count { id } giver antallet af produkter i den pågældende kategori:

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

Dette output fortæller os, at kategori 1 har tre produkter, kategori 2 har 2 osv.

Eksempel 2: Sum og gennemsnit

Vi kan anmode om flere sammenlægningsmålepunkter i én forespørgsel. Lad os antage, at vi for hver kategori vil have den samlede pris for alle produkter og den gennemsnitlige bedømmelse:

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

Denne forespørgsel returnerer følgende resultater:

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

Hvert gruppeobjekt indeholder kategorien og de beregnede aggregeringer, f.eks. antallet af produkter, summen af deres priser og de gennemsnitlige bedømmelser i den pågældende kategori.

Eksempel 3: Gruppér efter flere felter

Du kan gruppere efter mere end ét felt for at få en gruppering på flere niveauer. Hvis dit produkt f.eks. har et rating felt, kan du gruppere efter begge category_id og rating derefter beregne gennemsnittet price for gruppen:

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

Dette grupperer produkter efter den entydige kombination af kategori og bedømmelse som vist nedenfor:

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

Og så videre for hvert kategoriklassificeringspar i dataene.

Tips

Når man grupperer efter flere felter, bliver eksplicit sortering særligt vigtig for forudsigelige resultater. Se Sortering af grupperede resultater kræver eksplicit rækkefølge.

Eksempel 4: Brug af distinkt

Sammenlægningsfunktionen understøtter en særskilt modifikator til at tælle eller overveje entydige værdier. Hvis du f.eks. vil finde ud af, hvor mange forskellige kategorier der findes i produktsamlingen, kan du bruge et specifikt antal:

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

Denne forespørgsel returnerer et resultat med antallet af entydige produkter for hver kategori. Resultatet ser ud som følger:

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

Tips

For mere vejledning om, hvornår og hvordan man bruger forskellige korrekt, se Brug forskellig aggregering korrekt.

Eksempel 5: Brug af aliasser

Du kan oprette aliasser for sammenlægninger for at give meningsfulde og nemme at forstå navne på aggregerede resultater. Du kan f.eks. navngive sammenlægningen i det forrige eksempel, da distinctProductCategoryCount den tæller særskilte produktkategorier for bedre at forstå resultaterne:

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

Resultatet er det samme, men mere meningsfuldt med det brugerdefinerede alias:

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

Eksempel 6: Brug af delsætningen having

Det er muligt at filtrere de samlede resultater med delsætningen having . Du kan f.eks. ændre det forrige eksempel, så der kun returneres resultater, der er større end to:

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

Resultatet returnerer en enkelt værdi med den eneste kategori med mere end to produkter:

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

Begrænsninger og bedste fremgangsmåder

Når du bruger aggregeringer i Microsoft Fabrics API til GraphQL, er der vigtige regler og begrænsninger at tage højde for. Ved at følge disse bedste praksisser og forstå disse begrænsninger kan du opbygge effektive GraphQL-aggregeringsforespørgsler, der giver stærke indsigter, samtidig med at de sikrer forudsigelige resultater, især når du arbejder med store datasæt eller implementerer paginering.

Sammenlægningsfunktionen er nyttig til brug i forbindelse med rapportering og analyse, men den kræver omhyggelig strukturering af forespørgsler. Dobbelttjek altid, at felterne groupBy er i overensstemmelse med de valgte outputfelter, tilføj sortering efter forudsigelig rækkefølge, især når du sideinddelte, og brug særskilte og aggregerede funktioner korrekt til datatyperne.

Følgende afsnit dækker tre nøgleområder, du skal forstå: Aggregation og rå elementer udelukker hinanden, sortering af grupperede resultater kræver eksplicit rækkefølge, og brug adskilt aggregation passende.

Aggregation og rå varer udelukker hinanden

I øjeblikket kan du ikke hente både grupperede oversigtsdata og den rå liste over elementer i den samme forespørgsel samtidig. Når du bruger groupBy i din forespørgsel, skifter API'en til "aggregationstilstand" og returnerer kun grupperede resultater. Dette design holder svarstrukturen entydig – hver forespørgsel er enten i "aggregeringstilstand" eller "listeelementer-tilstand", men aldrig begge dele.

Sådan fungerer dette i praksis:

Forespørgslen products(...) returnerer enten:

  • En liste over individuelle produkter (når groupBy de ikke bruges)
  • En liste over grupperede resultater med aggregerede data (når groupBy den bruges)

Bemærk i de aggregerede eksempler ovenfor, at svaret indeholder groupBy og aggregerede felter, men den sædvanlige items liste over produkter mangler.

Hvad sker der, hvis du prøver begge dele:

Hvis du forsøger at anmoder om både normale elementer og grupper i samme forespørgsel, returnerer GraphQL-motoren en fejl eller tillader ikke det valg.

Løsning:

Hvis du har brug for både rådata og aggregerede data, skal du køre to separate forespørgsler: én for rådata og én for aggregerede data. Denne tilgang giver dig fuld kontrol over begge datasæt og kan optimeres baseret på dine specifikke caching- og ydelseskrav.

Sortering af grupperede resultater kræver eksplicit rækkefølge

Aggregerede grupper returneres i uforudsigelig rækkefølge, medmindre du specificerer eksplicit sortering. Brug altid orderBy argumenter sort for at sikre konsistente, meningsfulde resultater.

Hvorfor eksplicit rækkefølge betyder noget:

  • Uforudsigelig standardrækkefølge: Uden orderBy, kan grupper returnere i vilkårlig databasebestemt rækkefølge
  • Krav til paginering: Stabil sorteringsrækkefølge er afgørende for konsistent pagineringsadfærd
  • Brugeroplevelse: Forudsigelig rækkefølge forbedrer datafortolkning og applikationspålidelighed

Når du skal angive rækkefølgen:

  • Ingen primærnøgle i groupBy-felter: Hvis dine grupperingsfelter ikke indeholder en primærnøgle, skal du tilføje orderBy
  • Ikke-unikke grupperingsnøgler: Når man grupperer efter felter som kategorinavne eller datoer
  • Pagineringsscenarier: Når som helst du planlægger at bruge limit/offset eller cursor-paginering

Anbefalede fremgangsmåder:

  • Sorter efter samlede værdier (såsom højeste antal først) for analytiske indsigter
  • Brug alfabetisk sortering til kategoribaserede grupperinger
  • Kombiner flere sorteringskriterier for komplekse ordningsbehov

Brug forskellig aggregering passende

Modifikatoren distinct eliminerer duplikerede værdier før aggregeringer udføres, hvilket sikrer nøjagtige beregninger, når dine data indeholder dubletter.

Almindelige brugssager:

  • Unik optælling: tæller, count(field: category_id, distinct: true) hvor mange forskellige kategorier der findes i hver gruppe
  • Deduplikerede summer:sum(field: price, distinct: true) tilføjer hver unik prisværdi kun én gang pr. gruppe
  • Join-scenarier: Når produkter vises flere gange på grund af tabeljoins, sikrer distinkt, at hvert element tælles én gang

Hvornår skal man bruge distinkt:

  • Dine data indeholder legitime dubletter, som ville forvride beregningerne
  • Du arbejder med joinede tabeller, der skaber dubletter rækker
  • Du skal tælle unikke værdier i stedet for det samlede antal forekomster

Præstationsovervejelse:

Forskellige operationer kræver mere behandling. Brug kun, når det er nødvendigt for datanøjagtigheden.

Relateret indhold

  • Last updated on