Agregaciones en API para GraphQL

Transforme los datos de Microsoft Fabric en información procesable con agregaciones de GraphQL. En lugar de recuperar miles de registros individuales y procesarlos en la aplicación, puede pedir a Fabric que agrupe los datos y calcule resúmenes del lado servidor, lo que mejora considerablemente el rendimiento y reduce la transferencia de datos.

Las agregaciones de GraphQL funcionan como las operaciones de SQL GROUP BY, pero a través de la API de GraphQL. Puede contar elementos por categoría, calcular los totales de ingresos, buscar clasificaciones medias o determinar los valores mínimos y máximos en las tablas de lakehouse y warehouse, todo ello en una sola consulta eficaz.

Ventajas clave:

  • Procesamiento del lado servidor: aproveche los motores de consulta optimizados de Fabric para los cálculos
  • Transferencia de datos reducida: obtener resúmenes en lugar de registros sin procesar
  • Eficacia de una sola consulta: reemplace varias operaciones del lado cliente por una agregación.

En esta guía se muestra cómo crear consultas de agregación mediante un ejemplo práctico de comercio electrónico, que abarca todo, desde la agrupación básica hasta funciones avanzadas y limitaciones importantes.

¿Quiénes deberían usar agregaciones?

Las agregaciones de GraphQL son valiosas para:

  • Desarrolladores de aplicaciones que crean paneles personalizados y aplicaciones de análisis que necesitan datos resumidos de Fabric
  • Ingenieros de datos que crean APIs de datos que sirven métricas y KPIs (indicadores clave de rendimiento) calculados previamente desde los almacenes y viviendas de datos de Fabric.
  • Desarrolladores de BI que crean soluciones de análisis personalizadas que complementan Power BI con datos agregados de Fabric
  • Desarrolladores de integración que crean aplicaciones y flujos de trabajo que necesitan estadísticas de resumen de Fabric
  • Analistas de datos que crean soluciones de análisis de autoservicio que requieren información agrupada y agregada de datos de Fabric

Si va a recuperar datos para mostrar gráficos, calcular totales, generar informes o analizar tendencias, las agregaciones pueden mejorar significativamente el rendimiento de la aplicación y reducir la transferencia de datos.

Preguntas empresariales comunes que puede responder

Las agregaciones de GraphQL se destacan en la respuesta a preguntas analíticas sobre los datos de Fabric:

  • Recuento y agrupación: "¿Cuántos productos hay en cada categoría?" o "¿Cuántos pedidos al mes?"
  • Cálculos financieros: "¿Cuáles son los ingresos totales por región?" o "Valor medio del pedido por segmento de cliente?"
  • Métricas de rendimiento: "¿Cuál es el producto con clasificación más alta y más baja en cada categoría?"
  • Información del cliente: "¿Cuántos clientes únicos visitaron este mes?" o "¿Qué ciudades tienen los usuarios más activos?"

Estas consultas son ideales para crear paneles, generar informes y alimentar aplicaciones de análisis en las que necesita datos resumidos en lugar de registros individuales.

Prerrequisitos

Antes de usar agregaciones de GraphQL, asegúrese de que tiene:

  • Un área de trabajo de Microsoft Fabric con los permisos adecuados
  • Una instancia de Lakehouse o un almacén con tablas que contengan los datos que desea agregar
  • Una API para un endpoint de GraphQL configurado para elementos de Fabric
  • Conocimientos básicos de la sintaxis de consulta graphQL

Dónde ejecutar estas consultas

Inicio rápido: Use el editor de API para GraphQL en el área de trabajo de Fabric para probar todos los ejemplos de este artículo. El editor proporciona exploración de esquemas, validación de consultas y resultados inmediatos.

Para aplicaciones: envíe consultas como solicitudes HTTP POST al punto de conexión de GraphQL mediante cualquier biblioteca cliente de GraphQL para el lenguaje de programación.

Para el desarrollo: herramientas como GraphQL Playground, Insomnio o Postman funcionan bien para el desarrollo y las pruebas de consultas.

Nota:

Los ejemplos de este artículo están listos para copiar y ejecutarse una vez que haya configurado la API para el punto de conexión de GraphQL. Algunos ejemplos se acortan para mayor brevedad y pueden necesitar adaptación para su esquema específico.

Escenario de ejemplo: datos de comercio electrónico en Fabric

Para esta guía, usamos un conjunto de datos de comercio electrónico ficticio almacenado en el lago de datos o el repositorio de Microsoft Fabric. En este escenario se muestra cómo puede analizar los datos comerciales mediante agregaciones de GraphQL.

En este ejemplo, los datos del producto pertenecen a categorías, donde cada Product contiene campos como el precio y la clasificación (valores numéricos perfectos para la agregación) y tiene una relación con Category. Al exponer estas tablas a través de la API de Fabric para GraphQL, el esquema generado podría ser similar al siguiente:

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

En este ejemplo, la products consulta puede devolver una lista normal de elementos o, si groupBy se usa, resultados agregados. Vamos a centrarnos en el uso de las características de esta consulta y en la agregación groupBy.

Nota:

No se pueden recuperar los elementos normales y los resultados agrupados en la misma consulta. Para obtener más información, consulte Agregación y elementos sin procesar son mutuamente excluyentes.

Funciones de agregación disponibles

Las funciones exactas disponibles dependen de la implementación, pero las operaciones de agregación comunes incluyen:

  • count : recuento de registros (o valores no NULL de un campo) en el grupo.
  • sum: suma de todos los valores de un campo numérico.
  • avg: promedio (media) de valores en un campo numérico.
  • min : valor mínimo en un campo.
  • max : valor máximo en un campo.

En agregaciones de GraphQL, especifique el nombre de la función y el campo de destino, como se muestra en los ejemplos count(field: id), sum(field: price), etc. Cada función devuelve un objeto que permite seleccionar uno o varios campos a los que se aplicó.

Nota:

En la API de Microsoft Fabric para GraphQL, las operaciones de agregación como count, sum, avg, min, y max actualmente solo funcionan en campos numéricos o cuantitativos (enteros, floats). No se pueden usar directamente en campos de texto o fecha. Por ejemplo, no se puede calcular el "promedio" de un campo de cadena. La compatibilidad con la realización de agregados en otros tipos de datos (como la concatenación de texto o min/max lexicográfico) podría agregarse en futuras actualizaciones de Fabric.

Conceptos básicos de la consulta de agregación

Para realizar una agregación en GraphQL API de Fabric, especifique un groupBy argumento en la consulta para definir cómo agrupar los datos y solicitar campos de agregación (como recuentos o sumas) en el resultado. El motor de GraphQL de Fabric procesa estas consultas de forma eficaz en las tablas de almacén o lakehouse subyacentes, devolviendo una lista de registros agrupados con sus valores clave y métricas agregadas calculadas.

Ejemplo 1: Recuento de productos por categoría

Vamos a agrupar los productos por su categoría y contar cuántos productos hay en cada grupo. La consulta podría ser similar a la siguiente:

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

En esta consulta:

  • groupBy(fields: [category_id]) indica al motor de Fabric GraphQL que agrupe los productos por el category_id campo.
  • En la selección de resultados, solicitas group y un agregado count en el campo id. Contar id cuenta eficazmente los productos de ese grupo.

Aspecto del resultado: Cada elemento de la respuesta representa un grupo de categorías. El groupBy objeto contiene la clave de agrupación. Aquí incluye el category_id valor y count { id } proporciona el número de productos de esa categoría:

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

Esta salida indica que la categoría 1 tiene tres productos, la categoría 2 tiene 2, etc.

Ejemplo 2: Suma y promedio

Podemos solicitar varias métricas de agregación en una consulta. Supongamos que queremos, para cada categoría, el precio total de todos los productos y la clasificación 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
     } 
   }
  }
}

Esta consulta devolvería los siguientes 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 incluye la categoría y los agregados calculados, como el número de productos, la suma de sus precios y las clasificaciones medias de esa categoría.

Ejemplo 3: Agrupar por varios campos

Puede agrupar por más de un campo para obtener una agrupación de varios niveles. Por ejemplo, si su producto tiene un campo de rating, puede agrupar por los campos category_id y rating, y a continuación calcular el promedio de price para el grupo.

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

Esto agruparía los productos por la combinación única de categoría y clasificación, como se muestra a continuación:

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

Y así sucesivamente para cada par de clasificación de categorías en los datos.

Sugerencia

Al agrupar por varios campos, la ordenación explícita se vuelve especialmente importante para los resultados predecibles. Consulte Ordenar los resultados agrupados requiere una ordenación explícita.

Ejemplo 4: Uso de 'distinct'

La característica de agregación admite un modificador distinto para contar o considerar valores únicos. Por ejemplo, para averiguar cuántas categorías distintas existen en la colección de productos, puede usar un recuento distinto:

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

Esta consulta devuelve un resultado con el número de productos únicos para cada categoría. El resultado tendría el siguiente aspecto:

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

Sugerencia

Para obtener más instrucciones sobre cuándo y cómo usar distinct adecuadamente, consulte Usar la agregación distinct de forma adecuada.

Ejemplo 5: Uso de alias

Puede crear alias para agregaciones para proporcionar nombres significativos y fáciles de entender para los resultados agregados. Por ejemplo, puede nombrar la agregación en el ejemplo anterior como distinctProductCategoryCount, ya que está contando categorías de productos distintas para comprender mejor los resultados.

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

El resultado es similar pero más significativo con el alias personalizado:

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

Ejemplo 6: Uso de la having cláusula

Es posible filtrar los resultados agregados con la having cláusula . Por ejemplo, puede modificar el ejemplo anterior para devolver solo resultados mayores que dos:

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

El resultado devuelve un valor único con la única categoría con más de dos productos:

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

Restricciones y procedimientos recomendados

Cuando se usan agregaciones en la API de Microsoft Fabric para GraphQL, hay reglas y limitaciones importantes que se deben tener en cuenta. Al seguir estos procedimientos recomendados y comprender estas restricciones, puede crear consultas de agregación de GraphQL eficaces que produzcan información eficaz al tiempo que garantizan resultados predecibles, especialmente cuando se trabaja con grandes conjuntos de datos o implementación de paginación.

La característica de agregación es útil para los casos de uso de informes y análisis, pero requiere una estructuración cuidadosa de las consultas. Compruebe siempre que los groupBy campos se alinean con los campos de salida seleccionados, agregue una ordenación para un orden predecible, especialmente cuando se paginan y usen funciones distintas y agregadas apropiadamente para los tipos de datos.

En las secciones siguientes se tratan tres áreas clave que debe comprender: La agregación y los elementos sin procesar son mutuamente excluyentes, la ordenación agrupada requiere una ordenación explícita y usar una agregación distinta correctamente.

La agregación y los elementos sin procesar son mutuamente excluyentes

Actualmente, no se pueden recuperar los datos de resumen agrupados y la lista sin procesar de elementos de la misma consulta simultáneamente. Cuando se usa groupBy en la consulta, la API cambia al "modo de agregación" y devuelve solo los resultados agrupados. Este diseño mantiene la estructura de respuesta inequívoca: cada consulta está en "modo de agregación" o "modo de elementos de lista", pero nunca ambas.

Cómo funciona en la práctica:

La products(...) consulta devuelve:

  • Una lista de productos individuales (cuando groupBy no se usa)
  • Una lista de resultados agrupados con datos agregados (cuando groupBy se usa)

Observe en los ejemplos agregados anteriores que la respuesta contiene groupBy y agrega campos, pero falta la lista habitual items de productos.

¿Qué ocurre si prueba ambos:

Si intenta solicitar elementos y grupos normales en la misma consulta, el motor de GraphQL devuelve un error o no permitirá esa selección.

Solución alternativa:

Si necesita datos sin procesar y datos agregados, ejecute dos consultas independientes: una para los datos sin procesar y otra para los datos agregados. Este enfoque proporciona un control completo sobre ambos conjuntos de datos y se puede optimizar en función de los requisitos específicos de almacenamiento en caché y rendimiento.

La ordenación de los resultados agrupados requiere una ordenación explícita

Los grupos agregados se devuelven en orden impredecible a menos que especifique la ordenación explícita. Siempre use argumentos orderBy o sort para garantizar resultados coherentes y significativos.

Por qué importa la ordenación explícita:

  • Orden predeterminado imprevisible: sin orderBy, los grupos pueden devolver en orden arbitrario determinado por la base de datos
  • Requisitos de paginación: el criterio de ordenación estable es esencial para el comportamiento coherente de la paginación.
  • Experiencia del usuario: la ordenación predecible mejora la interpretación de los datos y la confiabilidad de las aplicaciones

Cuando debe especificar la ordenación:

  • Sin clave principal en los campos groupBy: si los campos de agrupación no incluyen una clave principal, debe agregar. orderBy
  • Claves de agrupación no únicas: al agrupar por campos como nombres de categoría o fechas
  • Escenarios de paginación: cada vez que planee usar un límite/desplazamiento o paginación mediante cursores

Procedimiento recomendado:

  • Ordenar por valores agregados (como el recuento más alto primero) para obtener información analítica
  • Usar la ordenación alfabética para las agrupaciones basadas en categorías
  • Combinar varios criterios de ordenación para necesidades de ordenación complejas

Usar la agregación distinta de forma adecuada

El distinct modificador elimina los valores duplicados antes de realizar agregaciones, lo que garantiza cálculos precisos cuando los datos contienen duplicados.

Casos de uso comunes:

  • Recuentos únicos: count(field: category_id, distinct: true) cuenta cuántas categorías existen en cada grupo
  • Sumas desduplicadas: sum(field: price, distinct: true) agrega cada valor de precio único solo una vez por grupo
  • Escenarios de combinación: cuando los productos aparecen varias veces debido a combinaciones de tabla, distinct garantiza que cada elemento se cuente una vez.

Cuándo usar "distinct":

  • Sus datos contienen duplicados válidos que sesgarían los cálculos
  • Está trabajando con tablas combinadas que crean filas duplicadas
  • Debe contar valores únicos en lugar del total de ocurrencias.

Consideración del rendimiento:

Las operaciones distintas requieren más procesamiento. Use solo cuando sea necesario para la precisión de los datos.

Contenido relacionado

  • Last updated on