Condividi tramite

Aggregazioni nell'API per GraphQL

Trasformare i dati di Microsoft Fabric in informazioni dettagliate interattive con le aggregazioni GraphQL. Invece di recuperare migliaia di singoli record ed elaborarli nell'applicazione, è possibile chiedere a Fabric di raggruppare i dati e calcolare riepiloghi sul lato server, migliorando notevolmente le prestazioni e riducendo il trasferimento dei dati.

Le aggregazioni GraphQL funzionano come le operazioni SQL GROUP BY, ma tramite l'API GraphQL. È possibile contare gli elementi per categoria, calcolare i totali dei ricavi, trovare valutazioni medie o determinare i valori min/max nelle tabelle lakehouse e warehouse, tutti in una singola query efficiente.

Vantaggi principali:

  • Elaborazione lato server: sfruttare i motori di query ottimizzati di Fabric per i calcoli
  • Trasferimento dei dati ridotto: ottenere riepiloghi anziché record non elaborati
  • Efficienza di una singola query: sostituire più operazioni lato client con un'aggregazione

Questa guida illustra come creare query di aggregazione usando un esempio pratico di e-commerce, che illustra tutto, dal raggruppamento di base alle funzioni avanzate e alle limitazioni importanti.

Chi deve usare le aggregazioni

Le aggregazioni GraphQL sono utili per:

  • Sviluppatori di applicazioni che creano dashboard personalizzati e applicazioni di analisi che necessitano di dati di Fabric riepilogati
  • Gli ingegneri dei dati che creano API di dati per fornire metriche e KPI pre-computati dai data lakehouse e data warehouse di Fabric.
  • Sviluppatori di business intelligence che creano soluzioni di analisi personalizzate che integrano Power BI con i dati aggregati di Fabric
  • Sviluppatori di integrazione che creano applicazioni e flussi di lavoro che necessitano di statistiche di riepilogo da Fabric
  • Analisti dei dati che creano soluzioni di analisi self-service che richiedono informazioni dettagliate raggruppate e aggregate dai dati di Fabric

Se si recuperano dati per visualizzare grafici, calcolare i totali, generare report o analizzare le tendenze, le aggregazioni possono migliorare significativamente le prestazioni dell'applicazione e ridurre il trasferimento dei dati.

Domande aziendali comuni a cui è possibile rispondere

Le aggregazioni GraphQL sono eccellenti per rispondere alle domande analitiche sui dati di Fabric:

  • Conteggio e raggruppamento: "Quanti prodotti si trovano in ogni categoria?" o "Quanti ordini al mese?"
  • Calcoli finanziari: "Qual è il fatturato totale per area?" o "Valore medio dell'ordine per segmento di clienti?"
  • Metriche delle prestazioni: "Qual è il prodotto più alto e più basso in ogni categoria?"
  • Informazioni dettagliate suiclienti: "Quanti clienti univoci hanno visitato questo mese?" o "Quali città hanno gli utenti più attivi?"

Queste query sono ideali per la creazione di dashboard, la generazione di report e l'alimentazione delle applicazioni di analisi in cui sono necessari dati riepilogati anziché singoli record.

Prerequisiti

Prima di usare le aggregazioni GraphQL, assicurarsi di disporre di:

  • Un'area di lavoro di Microsoft Fabric con autorizzazioni appropriate
  • Una lakehouse o un magazzino con tabelle contenenti i dati da aggregare
  • UN'API per l'endpoint GraphQL configurato per gli elementi di Fabric
  • Conoscenza di base della sintassi delle query GraphQL

Dove eseguire queste query

Guida introduttiva: Usare l'editor API per GraphQL nell'area di lavoro Fabric per testare tutti gli esempi in questo articolo. L'editor fornisce l'esplorazione dello schema, la convalida delle query e i risultati immediati.

Per le applicazioni: inviare query come richieste HTTP POST all'endpoint GraphQL usando qualsiasi libreria client GraphQL per il linguaggio di programmazione.

Per lo sviluppo: strumenti come GraphQL Playground, Insonnia o Postman funzionano bene per lo sviluppo e il test delle query.

Annotazioni

Gli esempi in questo articolo sono pronti per la copia e l'esecuzione dopo aver configurato l'API per l'endpoint GraphQL. Alcuni esempi sono abbreviati per brevità e potrebbero richiedere l'adattamento per lo schema specifico.

Scenario di esempio: dati di e-commerce in Fabric

Per questa guida viene usato un set di dati fittizio di e-commerce archiviato in Microsoft Fabric lakehouse o warehouse. Questo scenario illustra come analizzare i dati delle vendite al dettaglio usando le aggregazioni GraphQL.

In questo esempio i dati del prodotto appartengono a categorie, ognuno Product dei quali contiene campi come prezzo e classificazione (valori numerici perfetti per l'aggregazione) e una relazione con Category. Quando si espongono queste tabelle tramite l'API di Fabric per GraphQL, lo schema generato potrebbe essere simile al seguente:

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 questo esempio la products query può restituire un normale elenco di elementi oppure, se groupBy viene usato, risultati aggregati. Concentriamoci sull'uso delle groupBy e delle caratteristiche di aggregazione di questa query.

Annotazioni

Non è possibile recuperare sia gli elementi normali che i risultati raggruppati nella stessa query. Per ulteriori dettagli, vedere Aggregazione ed elementi grezzi si escludono a vicenda.

Funzioni di aggregazione disponibili

Le funzioni esatte disponibili dipendono dall'implementazione, ma le operazioni di aggregazione comuni includono:

  • count : numero di record (o valori non Null di un campo) nel gruppo.
  • sum : somma di tutti i valori in un campo numerico.
  • avg : media (media) di valori in un campo numerico.
  • min : valore minimo in un campo.
  • max : valore massimo in un campo.

Nelle aggregazioni GraphQL si specificano il nome della funzione e il campo di destinazione, come illustrato negli esempi count(field: id), sum(field: price)e così via. Ogni funzione restituisce un oggetto che consente di selezionare uno o più campi a cui è stato applicato.

Annotazioni

Nell'API di Microsoft Fabric per GraphQL, le operazioni di aggregazione come count, sum, avgmin, e max attualmente funzionano solo su campi numerici o quantitativi (numeri interi, float). Non è possibile usarli direttamente nei campi di testo o data. Ad esempio, non è possibile calcolare la "media" di un campo stringa. Il supporto per l'esecuzione di aggregazioni in altri tipi di dati, ad esempio la concatenazione del testo o il valore lessicografico min/max, potrebbe essere aggiunto negli aggiornamenti futuri di Fabric.

Nozioni di base sulle query di aggregazione

Per eseguire un'aggregazione nell'API GraphQL di Fabric, specificare un groupBy argomento nella query per definire come raggruppare i dati e richiedere campi di aggregazione (ad esempio conteggi o somme) nel risultato. Il motore GraphQL di Fabric elabora queste query in modo efficiente sulle tabelle lakehouse o warehouse sottostanti, restituendo un elenco di record raggruppati con i relativi valori chiave e le metriche aggregate calcolate.

Esempio 1: Contare i prodotti per categoria

Raggruppare i prodotti in base alla categoria e contare il numero di prodotti in ogni gruppo. La query potrebbe essere simile alla seguente:

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

In questa query:

  • groupBy(fields: [category_id]) indica al motore GraphQL di Fabric di raggruppare i prodotti in base al category_id campo.
  • Nella selezione dei risultati, richiedi group e un'aggregazione count nel campo id. Il conteggio id conta efficacemente i prodotti in tale gruppo.

L'aspetto del risultato è simile al seguente: Ogni elemento nella risposta rappresenta un gruppo di categorie. L'oggetto groupBy contiene la chiave di raggruppamento. Qui include il category_id valore e count { id } assegna il numero di prodotti in tale categoria:

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

Questo output indica che la categoria 1 ha tre prodotti, la categoria 2 ha 2 e così via.

Esempio 2: somma e media

È possibile richiedere più metriche di aggregazione in una query. Si supponga di volere, per ogni categoria, il prezzo totale di tutti i prodotti e la valutazione media:

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

Questa query restituirà i risultati seguenti:

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

Ogni oggetto gruppo include la categoria e le aggregazioni calcolate, ad esempio il numero di prodotti, la somma dei relativi prezzi e le valutazioni medie in tale categoria.

Esempio 3: Raggruppare per più campi

È possibile raggruppare per più campi per ottenere un raggruppamento a più livelli. Ad esempio, se il prodotto ha un rating campo, è possibile raggruppare entrambi category_id e rating quindi calcolare la media price per il gruppo:

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

In questo modo i prodotti vengono raggruppati in base alla combinazione univoca di categoria e classificazione, come illustrato di seguito:

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

E così via per ogni coppia di classificazione di categoria nei dati.

Suggerimento

Quando si raggruppano in base a più campi, l'ordinamento esplicito diventa particolarmente importante per i risultati prevedibili. Vedi Per ordinare i risultati raggruppati è necessario un ordinamento esplicito.

Esempio 4: Uso di distinct

La funzionalità di aggregazione supporta un modificatore distinto per contare o considerare valori univoci. Ad esempio, per scoprire il numero di categorie distinte presenti nella raccolta prodotti, è possibile usare un conteggio distinto:

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

Questa query restituisce un risultato con il numero di prodotti univoci per ogni categoria. Il risultato sarà simile al seguente:

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

Suggerimento

Per altre indicazioni su quando e su come usare in modo appropriato, vedere Usare un'aggregazione distinta in modo appropriato.

Esempio 5: Uso di alias

È possibile creare alias per le aggregazioni per fornire nomi significativi e facili da comprendere per i risultati aggregati. Ad esempio, è possibile denominare l'aggregazione nell'esempio precedente come distinctProductCategoryCount poiché conta le categorie di prodotti distinte per comprendere meglio i risultati.

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

Il risultato è simile ma più significativo con l'alias personalizzato:

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

Esempio 6: Uso della having clausola

È possibile filtrare i risultati aggregati con la having clausola . Ad esempio, è possibile modificare l'esempio precedente in modo da restituire solo risultati maggiori di due:

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

Il risultato restituisce un singolo valore con l'unica categoria con più di due prodotti:

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

Restrizioni e procedure consigliate

Quando si usano le aggregazioni nell'API di Microsoft Fabric per GraphQL, esistono regole e limitazioni importanti da considerare. Seguendo queste procedure consigliate e comprendendo queste restrizioni, è possibile creare query di aggregazione GraphQL efficaci che producono informazioni dettagliate avanzate garantendo risultati prevedibili, in particolare quando si lavora con set di dati di grandi dimensioni o implementando la paginazione.

La funzionalità di aggregazione è utile per i casi d'uso di report e analisi, ma richiede un'attenta strutturazione delle query. Verificare sempre che i groupBy campi siano allineati ai campi di output selezionati, aggiungere l'ordinamento per un ordine prevedibile soprattutto durante la paginazione e usare funzioni distinte e aggregate in modo appropriato per i tipi di dati.

Le sezioni seguenti illustrano tre aree chiave da comprendere: l'aggregazione e gli elementi non elaborati si escludono a vicenda, l'ordinamento dei risultati raggruppati richiede l'ordinamento esplicito e l'uso di aggregazioni distinte in modo appropriato.

Le aggregazioni e gli elementi non elaborati si escludono a vicenda

Attualmente, non è possibile recuperare contemporaneamente i dati di riepilogo raggruppati e l'elenco non elaborato di elementi nella stessa query. Quando si usa groupBy nella query, l'API passa alla modalità di aggregazione e restituisce solo i risultati raggruppati. Questa progettazione mantiene la struttura di risposta non ambigua: ogni query è in modalità di aggregazione o modalità di elementi elenco, ma non entrambe.

Come funziona in pratica:

La products(...) query restituisce una delle due operazioni seguenti:

  • Elenco di singoli prodotti (quando groupBy non viene usato)
  • Elenco di risultati raggruppati con dati aggregati (quando groupBy viene usato)

Si noti negli esempi aggregati precedenti che la risposta contiene groupBy e aggrega campi, ma manca l'elenco consueto items di prodotti.

Cosa accade se si prova entrambi:

Se si tenta di richiedere sia gli elementi normali che i gruppi nella stessa query, il motore GraphQL restituisce un errore o non consente tale selezione.

Soluzione alternativa:

Se sono necessari dati non elaborati e dati aggregati, eseguire due query separate: una per i dati non elaborati e una per i dati aggregati. Questo approccio offre il controllo completo su entrambi i set di dati e può essere ottimizzato in base ai requisiti specifici di memorizzazione nella cache e prestazioni.

L'ordinamento dei risultati raggruppati richiede l'ordinamento esplicito

I gruppi aggregati vengono restituiti in ordine imprevedibile, a meno che non si specifichi l'ordinamento esplicito. Usare sempre argomenti orderBy o sort per garantire risultati coerenti e significativi.

Perché l'ordinamento esplicito è importante:

  • Ordine predefinito imprevedibile: senza orderBy, i gruppi potrebbero restituire in ordine arbitrario determinato dal database
  • Requisiti di paginazione: l'ordinamento stabile è essenziale per un comportamento di paginazione coerente
  • Esperienza utente: l'ordinamento prevedibile migliora l'interpretazione dei dati e l'affidabilità delle applicazioni

Quando è necessario specificare l'ordinamento:

  • Nessuna chiave primaria nei campi groupBy: se i campi di raggruppamento non includono una chiave primaria, è necessario aggiungere orderBy
  • Chiavi di raggruppamento non univoco: quando si raggruppano in base a campi come nomi di categoria o date
  • Scenari di paginazione: ogni volta che si prevede di utilizzare la paginazione con limite/offset o cursore

Procedure consigliate:

  • Ordinare in base ai valori aggregati (ad esempio il conteggio più alto per primo) per informazioni analitiche
  • Usare l'ordinamento alfabetico per i raggruppamenti basati su categorie
  • Combinare più criteri di ordinamento per esigenze di ordinamento complesse

Usare l'aggregazione distinta in modo appropriato

Il distinct modificatore elimina i valori duplicati prima di eseguire aggregazioni, assicurando calcoli accurati quando i dati contengono duplicati.

Casi d'uso comuni:

  • Conteggi univoci: count(field: category_id, distinct: true) conta quante categorie diverse esistono in ogni gruppo
  • Somme deduplicate: sum(field: price, distinct: true) aggiunge ogni valore di prezzo univoco una sola volta per gruppo
  • Scenari di join: quando i prodotti vengono visualizzati più volte a causa di join di tabelle, distinct assicura che ogni elemento venga conteggiato una sola volta

Quando usare distinto:

  • I dati contengono duplicati legittimi che asimmetrierebbero i calcoli
  • Stai lavorando con tabelle collegate che creano righe duplicate
  • È necessario contare valori univoci anziché occorrenze totali

Considerazioni sulle prestazioni:

Le operazioni distinte richiedono un'elaborazione maggiore. Usare solo se necessario per l'accuratezza dei dati.

Contenuti correlati

  • Last updated on