Compartilhar via

Agregações na API para GraphQL

Transforme seus dados do Microsoft Fabric em insights acionáveis com agregações do GraphQL. Em vez de recuperar milhares de registros individuais e processá-los em seu aplicativo, você pode pedir ao Fabric para agrupar seus dados e calcular resumos do lado do servidor, melhorando drasticamente o desempenho e reduzindo a transferência de dados.

As agregações do GraphQL funcionam como operações SQL GROUP BY, mas por meio da API do GraphQL. Você pode contar itens por categoria, calcular totais de receita, encontrar classificações médias ou determinar valores mínimos/máximos em suas tabelas lakehouse e warehouse, tudo em uma única consulta eficiente.

Principais benefícios:

  • Processamento do lado do servidor: aproveite os mecanismos de consulta otimizados do Fabric para cálculos
  • Transferência de dados reduzida: obter resumos em vez de registros brutos
  • Eficiência de consulta única: substituir várias operações do lado do cliente por uma agregação

Este guia mostra como criar consultas de agregação usando um exemplo prático de comércio eletrônico, abrangendo tudo, desde agrupamento básico até funções avançadas e limitações importantes.

Quem deve usar agregações

As agregações do GraphQL são valiosas para:

  • Desenvolvedores de aplicativos criando painéis personalizados e aplicativos de análise que precisam de dados resumidos do Fabric
  • Engenheiros de dados criando APIs de dados que atendem a métricas pré-computadas e KPIs de lakehouses e armazéns do Fabric
  • Desenvolvedores de BI criando soluções de análise personalizada que complementam o Power BI com dados agregados do Fabric
  • Desenvolvedores de integração criando aplicativos e fluxos de trabalho que precisam de estatísticas resumidas do Fabric
  • Analistas de dados criando soluções de análise de autoatendimento que exigem insights agrupados e agregados de dados do Fabric

Se você estiver recuperando dados para exibir gráficos, calcular totais, gerar relatórios ou analisar tendências, as agregações poderão melhorar significativamente o desempenho do aplicativo e reduzir a transferência de dados.

Perguntas comerciais comuns que você pode responder

As agregações do GraphQL se destacam em responder perguntas analíticas sobre seus dados do Fabric:

  • Contagem e agrupamento: "Quantos produtos estão em cada categoria?" ou "Quantos pedidos por mês?"
  • Cálculos financeiros: "Qual é a receita total por região?" ou "Valor médio do pedido por segmento do cliente?"
  • Métricas de desempenho: "Qual é o produto com classificação mais alta e mais baixa em cada categoria?"
  • Insights do cliente: "Quantos clientes exclusivos visitaram este mês?" ou "Quais cidades têm os usuários mais ativos?"

Essas consultas são ideais para criar dashboards, gerar relatórios e alimentar aplicativos de análise em que você precisa de dados resumidos em vez de registros individuais.

Pré-requisitos

Antes de usar agregações do GraphQL, verifique se você tem:

  • Um workspace do Microsoft Fabric com permissões apropriadas
  • Uma lakehouse ou um armazém com tabelas que contêm os dados que você deseja agregar
  • Um endpoint da API para GraphQL configurado para seus itens Fabric
  • Familiaridade básica com a sintaxe da consulta GraphQL

Onde executar essas consultas

Início rápido: use o editor de API para GraphQL no workspace do Fabric para testar todos os exemplos neste artigo. O editor fornece exploração de esquema, validação de consulta e resultados imediatos.

Para aplicativos: envie consultas como solicitações HTTP POST para o ponto de extremidade do GraphQL usando qualquer biblioteca de clientes do GraphQL para sua linguagem de programação.

Para desenvolvimento: ferramentas como GraphQL Playground, Insomnia ou Postman funcionam bem para desenvolvimento e teste de consulta.

Observação

Os exemplos neste artigo estão prontos para serem copiados e executados, uma vez que você tenha configurado sua API com o endpoint GraphQL. Alguns exemplos são reduzidos para fins de brevidade e podem precisar de adaptação para seu esquema específico.

Cenário de exemplo: dados de comércio eletrônico no Fabric

Para este guia, usamos um conjunto de dados de comércio eletrônico fictício armazenado em seu lakehouse ou data warehouse do Microsoft Fabric. Esse cenário demonstra como você pode analisar dados de varejo usando agregações do GraphQL.

Neste exemplo, os dados do produto pertencem a categorias, com cada Product um contendo campos como preço e classificação (valores numéricos perfeitos para agregação) e uma relação com Category. Quando você expõe essas tabelas por meio da API do Fabric para GraphQL, o esquema gerado pode ser semelhante a:

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

Neste exemplo, a products consulta pode retornar uma lista normal de itens ou, se groupBy for usada, resultados agregados. Vamos nos concentrar no uso das funcionalidades de groupBy e de agregação dessa consulta.

Observação

Não é possível recuperar itens normais e resultados agrupados na mesma consulta. Para obter mais detalhes, consulte Agregação e itens brutos são mutuamente exclusivos.

Funções de agregação disponíveis

As funções exatas disponíveis dependem da implementação, mas as operações de agregação comuns incluem:

  • contagem – contagem de registros (ou valores não nulos de um campo) no grupo.
  • soma – soma de todos os valores em um campo numérico.
  • avg – média (média) de valores em um campo numérico.
  • min – valor mínimo em um campo.
  • max – valor máximo em um campo.

Nas agregações do GraphQL, especifique o nome da função e o campo de destino, conforme mostrado nos exemplos count(field: id), sum(field: price)etc. Cada função retorna um objeto que permite selecionar um ou mais campos aos quais ela foi aplicada.

Observação

Na API do Microsoft Fabric para GraphQL, operações de agregação comocount, sum, , avgmine max atualmente funcionam apenas em campos numéricos ou quantitativos (inteiros, floats). Você não pode usá-los diretamente em campos de texto ou data. Por exemplo, você não pode calcular a "média" de um campo de cadeia de caracteres. O suporte para executar agregações em outros tipos de dados (como concatenação de texto ou mínimo/máximo lexicográfico) pode ser adicionado em atualizações futuras ao Fabric.

Noções básicas de consulta de agregação

Para executar uma agregação na API graphQL do Fabric, especifique um groupBy argumento em sua consulta para definir como agrupar os dados e solicitar campos de agregação (como contagens ou somas) no resultado. O mecanismo GraphQL da Fabric processa essas consultas com eficiência em relação às tabelas subjacentes do seu sistema lakehouse ou warehouse, retornando uma lista de registros agrupados com seus valores-chave e métricas agregadas computadas.

Exemplo 1: Contar produtos por categoria

Vamos agrupar produtos por sua categoria e contar quantos produtos estão em cada grupo. A consulta pode ter a seguinte aparência:

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

Nesta consulta:

  • groupBy(fields: [category_id]) informa ao mecanismo GraphQL do Fabric para agrupar produtos pelo category_id campo.
  • Na seleção de resultados, você solicita group e uma agregação count no campo id. Contar id efetivamente contabiliza os produtos nesse grupo.

Como é o resultado: Cada item na resposta representa um grupo de categorias. O groupBy objeto contém a chave de agrupamento. Aqui ele inclui o category_id valor e count { id } fornece o número de produtos nessa categoria:

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

Essa saída informa que a categoria 1 tem três produtos, a categoria 2 tem 2 e assim por diante.

Exemplo 2: Soma e média

Podemos solicitar várias métricas de agregação em uma consulta. Suponha que queremos, para cada categoria, o preço total de todos os produtos e a classificação média:

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

Essa consulta retornaria os seguintes resultados:

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

Cada objeto de grupo inclui a categoria e as agregações computadas, como o número de produtos, a soma de seus preços e as classificações médias nessa categoria.

Exemplo 3: Agrupar por vários campos

Você pode agrupar por mais de um campo para obter um agrupamento de vários níveis. Por exemplo, se seu produto tiver um campo rating, você poderá agrupar tanto por category_id quanto por rating e calcular a média de price para o grupo.

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

Isso agruparia produtos pela combinação única de categoria e classificação, conforme mostrado abaixo.

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

E assim por diante para cada par de classificação de categoria nos dados.

Dica

Ao agrupar por vários campos, a classificação explícita torna-se especialmente importante para resultados previsíveis. Veja Classificação de resultados agrupados requer ordenação explícita.

Exemplo 4: Usando distinto

O recurso de agregação dá suporte a um modificador distinto para contar ou considerar valores exclusivos. Por exemplo, para descobrir quantas categorias distintas existem na coleção de produtos, você pode usar uma contagem distinta:

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

Essa consulta retorna um resultado com o número de produtos exclusivos para cada categoria. O resultado seria semelhante a:

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

Dica

Para obter mais diretrizes sobre quando e como usar distintamente, consulte Usar a agregação distinta adequadamente.

Exemplo 5: Usando aliases

Você pode criar aliases para agregações para fornecer nomes significativos e fáceis de entender para resultados agregados. Por exemplo, você pode nomear a agregação no exemplo anterior como distinctProductCategoryCount, pois ela está contando categorias de produtos distintas para entender melhor os resultados:

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

O resultado é semelhante, mas mais significativo com o alias personalizado:

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

Exemplo 6: Usando a having cláusula

É possível filtrar os resultados agregados com a having cláusula. Por exemplo, você pode modificar o exemplo anterior para retornar apenas resultados maiores que dois:

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

O resultado retorna um único valor com a única categoria com mais de dois produtos:

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

Restrições e práticas recomendadas

Quando você usa agregações na API do Microsoft Fabric para GraphQL, há regras e limitações importantes a serem consideradas. Seguindo essas práticas recomendadas e entendendo essas restrições, você pode criar consultas de agregação do GraphQL eficazes que geram insights poderosos, garantindo resultados previsíveis, especialmente ao trabalhar com grandes conjuntos de dados ou implementar paginação.

O recurso de agregação é útil para casos de uso de relatórios e análises, mas requer estruturação cuidadosa de consultas. Sempre verifique se os groupBy campos estão alinhados com os campos de saída selecionados, adicione classificação para ordem previsível especialmente ao paginar e use funções distintas e agregadas adequadamente para os tipos de dados.

As seções a seguir abrangem três áreas principais que você precisa entender: agregação e itens brutos são mutuamente exclusivos, classificar resultados agrupados requer ordenação explícita e Usar agregação distinta adequadamente.

Agregação e itens brutos são mutuamente exclusivos

Atualmente, você não pode recuperar dados de resumo agrupados e a lista bruta de itens na mesma consulta simultaneamente. Quando você usa groupBy em sua consulta, a API alterna para "modo de agregação" e retorna apenas os resultados agrupados. Esse design mantém a estrutura de resposta inequívoca - cada consulta está no "modo de agregação" ou no "modo de itens de lista", mas nunca ambas.

Como isso funciona na prática:

A consulta products(...) retorna uma das seguintes opções:

  • Uma lista de produtos individuais (quando groupBy não é usada)
  • Uma lista de resultados agrupados com dados agregados (quando groupBy é usado)

Observe nos exemplos agregados acima que a resposta contém groupBy e agrega campos, mas a lista usual items de produtos está ausente.

O que acontece se você tentar ambos:

Se você tentar solicitar itens normais e grupos na mesma consulta, o mecanismo graphQL retornará um erro ou não permitirá essa seleção.

Solução alternativa:

Se você precisar de dados brutos e dados agregados, execute duas consultas separadas: uma para dados brutos e outra para dados agregados. Essa abordagem fornece controle total sobre ambos os conjuntos de dados e pode ser otimizada com base em seus requisitos específicos de cache e desempenho.

Classificar resultados agrupados requer ordenação explícita

Os grupos agregados são retornados em ordem imprevisível, a menos que você especifique a classificação explícita. Sempre use os argumentos orderBy ou sort para garantir resultados consistentes e significativos.

Por que a ordenação explícita importa:

  • Ordem padrão imprevisível: sem orderBygrupos podem retornar em ordem arbitrária determinada pelo banco de dados
  • Requisitos de paginação: a ordem de classificação estável é essencial para um comportamento de paginação consistente
  • Experiência do usuário: a ordenação previsível melhora a interpretação de dados e a confiabilidade do aplicativo

Quando você deve especificar a ordenação:

  • Nenhuma chave primária nos campos groupBy: se os campos de agrupamento não incluirem uma chave primária, você deverá adicionar orderBy
  • Chaves de agrupamento não exclusivas: ao agrupar por campos como nomes de categoria ou datas
  • Cenários de paginação: Sempre que você planeja usar limite/deslocamento ou paginação por cursor

Práticas recomendadas:

  • Classificar por valores agregados (como a contagem mais alta em ordem decrescente) para obter análises.
  • Usar classificação alfabética para agrupamentos baseados em categoria
  • Combinar vários critérios de classificação para necessidades complexas de ordenação

Use agregação distinta de forma apropriada

O distinct modificador elimina valores duplicados antes de executar agregações, garantindo cálculos precisos quando seus dados contêm duplicatas.

Casos de uso comuns:

  • Contagens exclusivas: count(field: category_id, distinct: true) conta o número de categorias diferentes que existem em cada grupo
  • Somas desduplicadas: sum(field: price, distinct: true) adiciona cada valor de preço único apenas uma vez por grupo
  • Cenários de junção: quando os produtos aparecem várias vezes devido a junções de tabela, DISTINCT garante que cada item seja contado uma vez

Quando usar DISTINCT:

  • Seus dados contêm duplicatas legítimas que distorceriam os cálculos
  • Você está trabalhando com tabelas unidas que criam linhas duplicadas
  • Você precisa contar valores exclusivos em vez do total de ocorrências

Consideração de desempenho:

Operações distintas exigem mais processamento. Use somente quando necessário para precisão de dados.

Conteúdo relacionado

  • Last updated on