Aggregationen in DER API für GraphQL

Transformieren Sie Ihre Microsoft Fabric-Daten in umsetzbare Erkenntnisse mit GraphQL-Aggregationen. Anstatt Tausende einzelner Datensätze abzurufen und sie in Ihrer Anwendung zu verarbeiten, können Sie Fabric bitten, Ihre Daten zu gruppieren und serverseitige Zusammenfassungen zu berechnen– wodurch die Leistung erheblich verbessert und die Datenübertragung reduziert wird.

GraphQL-Aggregationen funktionieren wie SQL GROUP BY-Vorgänge, aber über die GraphQL-API. Sie können Elemente pro Kategorie zählen, Umsatzsummen berechnen, durchschnittliche Bewertungen finden oder Min/Max-Werte in Ihren Lakehouse- und Lagertabellen ermitteln – alles in einer einzigen, effizienten Abfrage.

Wichtige Vorteile:

  • Serverseitige Verarbeitung: Nutzen der optimierten Abfragemodule von Fabric für Berechnungen
  • Reduzierte Datenübertragung: Abrufen von Zusammenfassungen anstelle von Rohdatensätzen
  • Effizienz einzelner Abfragen: Ersetzen mehrerer clientseitiger Vorgänge durch eine Aggregation

In diesem Leitfaden erfahren Sie, wie Sie Aggregationsabfragen mithilfe eines praktischen E-Commerce-Beispiels erstellen, das alles von der einfachen Gruppierung bis hin zu erweiterten Funktionen und wichtigen Einschränkungen abdeckt.

Wer sollte Aggregationen verwenden?

GraphQL-Aggregationen sind nützlich für:

  • Anwendungsentwickler erstellen benutzerdefinierte Dashboards und Analyseanwendungen, die zusammengefasste Fabric-Daten benötigen
  • Dateningenieure erstellen Daten-APIs, die vorab berechnete Metriken und KPIs aus Fabric-Lakehouses und -Warehouses bereitstellen
  • BI-Entwickler erstellen benutzerdefinierte Analyselösungen, die Power BI mit aggregierten Fabric-Daten ergänzen
  • Integrationsentwickler erstellen Anwendungen und Workflows, die zusammenfassende Statistiken aus Fabric benötigen
  • Datenanalysten , die Self-Service Analytics-Lösungen erstellen, die gruppierte, aggregierte Erkenntnisse aus Fabric-Daten erfordern

Wenn Sie Daten abrufen, um Diagramme anzuzeigen, Summen zu berechnen, Berichte zu generieren oder Trends zu analysieren, können Aggregationen die Leistung Ihrer Anwendung erheblich verbessern und die Datenübertragung reduzieren.

Allgemeine Geschäftsfragen, die Sie beantworten können

GraphQL-Aggregationen zeichnen sich beim Beantworten analytischer Fragen zu Ihren Fabric-Daten aus.

  • Zählen und Gruppieren: "Wie viele Produkte befinden sich in jeder Kategorie?" oder "Wie viele Bestellungen pro Monat?"
  • Finanzberechnungen: "Was ist der Gesamtumsatz nach Region?" oder "Durchschnittlicher Auftragswert nach Kundensegment?"
  • Leistungsmetriken: "Was ist das höchste und niedrigste bewertete Produkt in jeder Kategorie?"
  • Kundeneinblicke: "Wie viele einzigartige Kunden haben diesen Monat besucht?" oder "Welche Städte haben die aktivsten Benutzer?"

Diese Abfragen eignen sich ideal für die Erstellung von Dashboards, das Generieren von Berichten und die Bereitstellung von Analyseanwendungen, bei denen Sie zusammengefasste Daten anstelle einzelner Datensätze benötigen.

Voraussetzungen

Stellen Sie vor der Verwendung von GraphQL-Aggregationen folgendes sicher:

  • Ein Microsoft Fabric-Arbeitsbereich mit entsprechenden Berechtigungen
  • Ein Seehaus oder Lager mit Tabellen, die die zu aggregierenden Daten enthalten
  • Eine API für den GraphQL-Endpunkt, der für Ihre Fabric-Elemente konfiguriert ist
  • Grundlegende Kenntnisse mit der GraphQL-Abfragesyntax

Wo diese Abfragen ausgeführt werden sollen

Schnellstart: Verwenden Sie die API für den GraphQL-Editor in Ihrem Fabric-Arbeitsbereich , um alle Beispiele in diesem Artikel zu testen. Der Editor bietet Schemasuche, Abfrageüberprüfung und sofortige Ergebnisse.

Für Anwendungen: Senden Sie Abfragen als HTTP POST-Anforderungen an Ihren GraphQL-Endpunkt, indem Sie eine beliebige GraphQL-Clientbibliothek für Ihre Programmiersprache verwenden.

Für die Entwicklung: Tools wie GraphQL Playground, Insomnia oder Postman funktionieren gut für die Abfragenentwicklung und -test.

Hinweis

Beispiele in diesem Artikel können sofort kopiert und ausgeführt werden, sobald Sie Ihre API für den GraphQL-Endpunkt konfiguriert haben. Einige Beispiele werden aus Platzgründen gekürzt und benötigen möglicherweise Anpassungen für Ihr spezifisches Schema.

Beispielszenario: E-Commerce-Daten in Fabric

Für diesen Leitfaden verwenden wir ein fiktives E-Commerce-Dataset, das in Ihrem Microsoft Fabric Lakehouse oder Warehouse gespeichert ist. In diesem Szenario wird veranschaulicht, wie Sie Einzelhandelsdaten mithilfe von GraphQL-Aggregationen analysieren können.

In diesem Beispiel gehören Produktdaten zu Kategorien, wobei jedes Product Felder wie Preis und Bewertung enthält (numerische Werte, die sich perfekt zur Aggregation eignen), und eine Beziehung zu Category. Wenn Sie diese Tabellen über die Fabric-API für GraphQL verfügbar machen, könnte das generierte Schema wie folgt aussehen:

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

In diesem Beispiel kann die products Abfrage entweder eine normale Liste von Elementen oder, falls groupBy verwendet, aggregierte Ergebnisse zurückgeben. Konzentrieren wir uns auf die Verwendung der groupBy Features und Aggregationen dieser Abfrage.

Hinweis

Sie können sowohl normale Elemente als auch gruppierte Ergebnisse in derselben Abfrage nicht abrufen. Weitere Informationen finden Sie unter Aggregation und Unformatierte Elemente schließen sich gegenseitig aus.

Verfügbare Aggregationsfunktionen

Die genau verfügbaren Funktionen hängen von der Implementierung ab, aber zu den allgemeinen Aggregationsvorgängen gehören:

  • count – Anzahl von Datensätzen (oder Nicht-Null-Werten eines Felds) in der Gruppe.
  • summe – Summe aller Werte in einem numerischen Feld.
  • Durchschn . – Mittelwert (Mittelwert) von Werten in einem numerischen Feld.
  • min – Minimalwert in einem Feld.
  • max – Maximalwert in einem Feld.

In GraphQL-Aggregationen geben Sie den Funktionsnamen und das Zielfeld an, wie in den Beispielen count(field: id), usw sum(field: price). gezeigt. Jede Funktion gibt ein Objekt zurück, mit dem Sie ein oder mehrere Felder auswählen können, auf die sie angewendet wurde.

Hinweis

In Microsoft Fabrics API für GraphQL funktionieren Aggregationen wie count, sum, avg, min und max aktuell nur für numerische oder quantitative Felder (ganze Zahlen, Floats). Sie können sie nicht direkt in Text- oder Datumsfeldern verwenden. Beispielsweise können Sie den "Mittelwert" eines Zeichenfolgenfelds nicht berechnen. Unterstützung für die Durchführung von Aggregaten für andere Datentypen (z. B. Textverkettung oder lexikographische Min/Max) kann in zukünftigen Updates von Fabric hinzugefügt werden.

Grundlagen der Aggregationsabfrage

Um eine Aggregation in der GraphQL-API von Fabric durchzuführen, geben Sie ein groupBy Argument in Ihrer Abfrage an, um zu definieren, wie die Daten gruppiert werden sollen, und Anfordern von Aggregationsfeldern (z. B. Anzahlen oder Summen) im Ergebnis. Das GraphQL-Modul von Fabric verarbeitet diese Abfragen effizient anhand Ihrer zugrunde liegenden Lakehouse- oder Warehouse-Tabellen, gibt eine Liste gruppierter Datensätze mit ihren Schlüsselwerten und berechneten aggregierten Metriken zurück.

Beispiel 1: Zählen von Produkten pro Kategorie

Gruppieren wir Produkte nach ihrer Kategorie und zählen, wie viele Produkte in jeder Gruppe enthalten sind. Die Abfrage sieht möglicherweise wie folgt aus:

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

Parameter dieser Abfrage:

  • groupBy(fields: [category_id]) weist das Fabric GraphQL-Modul an, Produkte nach dem category_id Feld zu gruppieren.
  • In der Ergebnisauswahl fordern Sie group und ein count Aggregat für das id-Feld an. Durch das Zählen id werden die Produkte in dieser Gruppe effektiv gezählt.

Wie das Ergebnis aussieht: Jedes Element in der Antwort stellt eine Kategoriegruppe dar. Das groupBy Objekt enthält den Gruppierungsschlüssel. Hier enthält er den category_id Wert und count { id } gibt die Anzahl der Produkte in dieser Kategorie an:

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

Diese Ausgabe teilt uns mit, dass die Kategorie 1 drei Produkte hat, Kategorie 2 hat 2 usw.

Beispiel 2: Summe und Mittelwert

Wir können mehrere Aggregationsmetriken in einer Abfrage anfordern. Angenommen, wir möchten für jede Kategorie den Gesamtpreis aller Produkte und die durchschnittliche Bewertung:

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

Diese Abfrage würde die folgenden Ergebnisse zurückgeben:

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

Jedes Gruppenobjekt enthält die Kategorie und die berechneten Aggregate, z. B. die Anzahl der Produkte, die Summe ihrer Preise und die durchschnittlichen Bewertungen in dieser Kategorie.

Beispiel 3: Gruppieren nach mehreren Feldern

Sie können nach mehreren Feldern gruppieren, um eine mehrstufige Gruppierung zu erhalten. Wenn Ihr Produkt beispielsweise über ein rating Feld verfügt, können Sie sowohl nach category_id als auch nach rating gruppieren und dann den Mittelwert price für die Gruppe berechnen.

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

Dies würde Produkte nach der eindeutigen Kombination aus Kategorie und Bewertung gruppieren, wie unten dargestellt:

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

Und so weiter für jedes Kategoriebewertungspaar in den Daten.

Tipp

Bei der Gruppierung nach mehreren Feldern wird die explizite Sortierung für vorhersagbare Ergebnisse besonders wichtig. Siehe Sortieren gruppierter Ergebnisse erfordert eine explizite Sortierung.

Beispiel 4: Verwenden von "Distinct"

Das Aggregationsfeature unterstützt einen eindeutigen Modifizierer, um eindeutige Werte zu zählen oder zu berücksichtigen. Um beispielsweise herauszufinden, wie viele verschiedene Kategorien in der Produktsammlung vorhanden sind, können Sie eine unterschiedliche Anzahl verwenden:

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

Diese Abfrage gibt ein Ergebnis mit der Anzahl eindeutiger Produkte für jede Kategorie zurück. Das Ergebnis würde wie folgt aussehen:

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

Tipp

Weitere Anleitungen dazu, wann und wie sie angemessen verwendet werden können, finden Sie unter "Geeignete Verwendung einer eindeutigen Aggregation".

Beispiel 5: Verwenden von Aliasen

Sie können Aliase für Aggregationen erstellen, um aussagekräftige und leicht verständliche Namen für aggregierte Ergebnisse bereitzustellen. Beispielsweise können Sie die Aggregation im vorherigen Beispiel als distinctProductCategoryCount bezeichnen, da sie unterschiedliche Produktkategorien zählt, um die Ergebnisse besser zu verstehen.

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

Das Ergebnis ist ähnlich, aber aussagekräftiger mit dem benutzerdefinierten Alias:

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

Beispiel 6: Verwenden der having Klausel

Es ist möglich, die aggregierten Ergebnisse mit der having Klausel zu filtern. Sie können z. B. das vorherige Beispiel so ändern, dass nur Ergebnisse zurückgegeben werden, die größer als zwei sind:

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

Das Ergebnis gibt einen einzelnen Wert mit der einzigen Kategorie mit mehr als zwei Produkten zurück:

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

Einschränkungen und bewährte Methoden

Wenn Sie Aggregationen in der Microsoft Fabric-API für GraphQL verwenden, müssen wichtige Regeln und Einschränkungen berücksichtigt werden. Indem Sie diese bewährten Methoden befolgen und diese Einschränkungen verstehen, können Sie effektive GraphQL-Aggregationsabfragen erstellen, die leistungsstarke Erkenntnisse liefern und gleichzeitig vorhersagbare Ergebnisse sicherstellen, insbesondere beim Arbeiten mit großen Datasets oder beim Implementieren der Paginierung.

Das Aggregationsfeature ist nützlich für Berichte und Analyse-Anwendungsfälle, erfordert jedoch eine sorgfältige Strukturierung von Abfragen. Überprüfen Sie immer, ob Ihre groupBy Felder mit den ausgewählten Ausgabefeldern übereinstimmen, fügen Sie eine Sortierung für eine vorhersagbare Reihenfolge hinzu, insbesondere bei der Seitennummerierung, und verwenden Sie Distinct- und Aggregatfunktionen passend zu den Datentypen.

In den folgenden Abschnitten werden drei wichtige Bereiche behandelt, die Sie verstehen müssen: Aggregation und Rohelemente schließen sich gegenseitig aus, Die Sortierung gruppierter Ergebnisse erfordert eine explizite Sortierung und die geeignete Verwendung einer eindeutigen Aggregation.

Aggregation und Rohelemente schließen sich gegenseitig aus

Derzeit können Sie sowohl gruppierte Zusammenfassungsdaten als auch die unformatierte Liste der Elemente in derselben Abfrage nicht gleichzeitig abrufen. Wenn Sie in Ihrer Abfrage verwenden groupBy , wechselt die API in den "Aggregationsmodus" und gibt nur gruppierte Ergebnisse zurück. Dieser Entwurf behält die Antwortstruktur eindeutig bei – jede Abfrage befindet sich entweder im "Aggregationsmodus" oder im "Listenelementemodus", aber nie beides.

Funktionsweise in der Praxis:

Die products(...) Abfrage gibt eine der folgenden Elemente zurück:

  • Eine Liste einzelner Produkte (wenn groupBy nicht verwendet wird)
  • Eine Liste der gruppierten Ergebnisse mit aggregierten Daten (bei groupBy Verwendung)

Beachten Sie in den oben zusammengefassten Beispielen, dass die Antwort groupBy und aggregierte Felder enthält, aber die übliche Produktliste items fehlt.

Was passiert, wenn Sie beide versuchen:

Wenn Sie versuchen, sowohl normale Elemente als auch Gruppen in derselben Abfrage anzufordern, gibt das GraphQL-Modul einen Fehler zurück oder lässt diese Auswahl nicht zu.

Workaround:

Wenn Sie sowohl Rohdaten als auch aggregierte Daten benötigen, führen Sie zwei separate Abfragen aus: eine für Rohdaten und eine für aggregierte Daten. Dieser Ansatz bietet Ihnen die vollständige Kontrolle über beide Datasets und kann basierend auf Ihren spezifischen Zwischenspeicherungs- und Leistungsanforderungen optimiert werden.

Das Sortieren gruppierter Ergebnisse erfordert eine explizite Sortierung

Aggregierte Gruppen werden in unvorhersehbarer Reihenfolge zurückgegeben, es sei denn, Sie geben eine explizite Sortierung an. Verwenden Sie immer orderBy oder sort Argumente, um konsistente, aussagekräftige Ergebnisse sicherzustellen.

Warum die explizite Anordnung wichtig ist:

  • Unvorhersehbare Standardreihenfolge: Ohne orderBy, Gruppen können in beliebiger datenbankbestimmter Reihenfolge zurückgegeben werden
  • Paginierungsanforderungen: Stabile Sortierreihenfolge ist für ein konsistentes Paginierungsverhalten unerlässlich.
  • Benutzererfahrung: Vorhersehbare Sortierung verbessert die Dateninterpretation und Anwendungssicherheit

Wenn Sie die Sortierung angeben müssen:

  • Kein Primärschlüssel in "groupBy"-Feldern: Wenn Die Gruppierungsfelder keinen Primärschlüssel enthalten, müssen Sie hinzufügen orderBy
  • Nicht eindeutige Gruppierungsschlüssel: Beim Gruppieren nach Feldern wie Kategorienamen oder Datumsangaben
  • Paginierungsszenarien: Jederzeit, wenn Sie die Limit-/Offset- oder Cursor-Paginierung verwenden möchten

Bewährte Methoden:

  • Sortieren nach Aggregatwerten (z. B. die höchste Anzahl zuerst) für analytische Erkenntnisse
  • Alphabetische Sortierung für kategoriebasierte Gruppierungen verwenden
  • Kombinieren mehrerer Sortierkriterien für komplexe Sortieranforderungen

Unterschiedliche Aggregation entsprechend verwenden

Der distinct Modifizierer entfernt doppelte Werte, bevor Aggregationen ausgeführt werden, wodurch genaue Berechnungen sichergestellt werden, wenn Ihre Daten Duplikate enthalten.

Häufige Anwendungsfälle:

  • Eindeutige Anzahl: Zählt, wie viele verschiedene Kategorien in jeder Gruppe vorhanden sind. count(field: category_id, distinct: true)
  • Deduplizierte Summen: sum(field: price, distinct: true) Addiert jeden eindeutigen Preiswert nur einmal pro Gruppe.
  • Join-Szenarien: Wenn Produkte aufgrund von Tabellen-Joins mehrmals angezeigt werden, stellt die Nutzung von 'distinct' sicher, dass jedes Element nur einmal gezählt wird.

Wann sollte "distinct" verwendet werden:

  • Ihre Daten enthalten legitime Duplikate, die die Berechnungen verzerren würden.
  • Sie arbeiten mit verknüpften Tabellen, die doppelte Zeilen erstellen
  • Sie müssen eindeutige Werte anstelle von Gesamtvorkommnissen zählen

Leistungsüberlegung:

Für unterschiedliche Vorgänge ist eine weitere Verarbeitung erforderlich. Verwenden Sie nur, wenn dies für die Datengenauigkeit erforderlich ist.

Verwandte Inhalte

  • Last updated on