opérateur summarize

Génère une table qui agrège le contenu de la table d’entrée.

Syntaxe

T| summarize [Paramètres_synthèse] [[Colonne=] Agrégation [, ...]] [by [Colonne=] Expression_groupe [, ...]]

Découvrez les conventions de syntaxe.

Paramètres

Nom	Type	Obligatoire	Description
Colonne	string		Le nom de la colonne de résultat. Prend par défaut un nom dérivé de l’expression.
Agrégation	string	✔️	appel d'une fonction d'agrégation telle que count() ou avg(), avec des noms de colonne comme arguments.
Expression_groupe	scalaire	✔️	expression scalaire qui peut faire référence aux données d’entrée. La sortie a autant d’enregistrements qu’il y a de valeurs distinctes pour toutes les expressions de groupe.
Paramètres_synthèse	string		Zéro ou plusieurs paramètres séparés par un espace, sous la forme Nom=Valeur, qui contrôlent le comportement. Consultez Paramètres pris en charge.

Notes

Lorsque la table d’entrée est vide, la sortie varie selon que GroupExpression est utilisé :

• Si GroupExpression n’est pas fourni, la sortie est une ligne unique (vide).
• Si GroupExpression est fourni, la sortie n’a pas de ligne.

Paramètres pris en charge

Name	Description
hint.num_partitions	Spécifie le nombre de partitions utilisées pour partager la charge de requête sur les nœuds de cluster. Voir requête de lecture aléatoire
hint.shufflekey=<key>	La requête shufflekey partage la charge de requête sur les nœuds de cluster à l’aide d’une clé pour partitionner les données. Voir requête de lecture aléatoire
hint.strategy=shuffle	La requête de stratégie shuffle partage la charge de requête sur les nœuds de cluster, où chaque nœud traitera une partition des données. Voir requête de lecture aléatoire

Retours

Les lignes d’entrée sont organisées en groupes ayant les mêmes valeurs que les expressions by . Ensuite, les fonctions d’agrégation spécifiées sont calculées sur chaque groupe, générant une ligne pour chaque groupe. Le résultat contient les colonnes by et au moins une colonne pour chaque agrégation calculée. (Certaines fonctions d’agrégation retournent plusieurs colonnes.)

Le résultat contient autant de lignes qu’il existe de combinaisons de valeurs by (et peut être égal à zéro). Si aucune clé de groupe n’est fournie, le résultat comporte un seul enregistrement.

Pour générer une synthèse sur des plages de valeurs numériques, utilisez bin() pour limiter les plages aux valeurs discrètes.

Notes

• Bien que vous puissiez fournir des expressions arbitraires pour les expressions d’agrégation et de regroupement, il est plus efficace d’utiliser des noms de colonne simples ou d’appliquer bin() à une colonne numérique.
• Les emplacements horaires automatiques pour les colonnes DateTime ne sont plus pris en charge. Utilisez à la place le binning explicite. Par exemple : summarize by bin(timestamp, 1h).

Valeurs par défaut des agrégations

Le tableau suivant récapitule les valeurs par défaut des agrégations :

Opérateur	Valeur par défaut
count(), countif(), dcount(), dcountif(), count_distinct(), sum(), sumif(), variance(), varianceif(), stdev(), stdevif()	0
make_bag(), make_bag_if(), make_list(), make_list_if(), make_set(), make_set_if()	tableau dynamique vide ([])
Tous les autres	null

Notes

Lorsque vous appliquez ces agrégats à des entités qui incluent des valeurs null, les valeurs null sont ignorées et ne sont pas prises en compte dans le calcul. Pour obtenir des exemples, consultez Valeurs par défaut des agrégations.

Exemples

Combinaison unique

La requête suivante détermine quelles combinaisons uniques de State et EventType il existe pour les tempêtes qui sont la cause directe de blessures. Il n’existe aucune fonction d’agrégation, mais uniquement des clés de regroupement. La sortie montre juste les colonnes de ces résultats.

Exécuter la requête

StormEvents
| where InjuriesDirect > 0
| summarize by State, EventType

Sortie

Le tableau suivant montre uniquement les 5 premières lignes. Pour voir la sortie complète, exécutez la requête.

État	Type d’événement
TEXAS	Vent d’orage
TEXAS	Crue soudaine
TEXAS	Météo hivernale
TEXAS	Vent fort
TEXAS	Crue
...	...

Horodatage minimal et maximal

Trouve les tempêtes de pluie les moins fortes et les plus fortes à Hawaii. Comme il n’y a pas de clause group-by, la sortie contient une seule ligne.

Exécuter la requête

StormEvents
| where State == "HAWAII" and EventType == "Heavy Rain"
| project Duration = EndTime - StartTime
| summarize Min = min(Duration), Max = max(Duration)

Sortie

Min	Max
01:08:00	11:55:00

Nombre distinct

Créez une ligne pour chaque continent, en indiquant le nombre de villes dans lesquelles les activités se produisent. Comme il y a peu de valeurs pour « continent », aucune fonction de regroupement n’est nécessaire dans la clause « by » :

Exécuter la requête

StormEvents
| summarize TypesOfStorms=dcount(EventType) by State
| sort by TypesOfStorms

Sortie

Le tableau suivant montre uniquement les 5 premières lignes. Pour voir la sortie complète, exécutez la requête.

State	TypesOfStorms
TEXAS	27
CALIFORNIE	26
PENNSYLVANIA	25
GEORGIE	24
ILLINOIS	23
...	...

Histogramme

L’exemple suivant calcule un histogramme des types d’événements orageux qui ont enregistré des tempêtes de plus de 1 jour. Étant donné que Duration a de nombreuses valeurs, utilisez bin() pour regrouper ses valeurs par intervalles de 1 jour.

Exécuter la requête

StormEvents
| project EventType, Duration = EndTime - StartTime
| where Duration > 1d
| summarize EventCount=count() by EventType, Length=bin(Duration, 1d)
| sort by Length

Sortie

Type d’événement	Longueur	EventCount
Sécheresse	30.00:00:00	1646
Feu de forêt	30.00:00:00	11
Chauffage	30.00:00:00	14
Crue	30.00:00:00	20
Fortes précipitations	29.00:00:00	42
...	...	...

Agrège les valeurs par défaut

Lorsque l’entrée de l’opérateur summarize a au moins une clé de regroupement vide, le résultat est également vide.

Lorsque l’entrée de l’opérateur summarize n’a pas de clé de regroupement vide, le résultat inclut les valeurs par défaut des agrégations utilisés dans summarize Pour plus d’informations, consultez Valeurs par défaut des agrégations.

Exécuter la requête

datatable(x:long)[]
| summarize any_x=take_any(x), arg_max_x=arg_max(x, *), arg_min_x=arg_min(x, *), avg(x), buildschema(todynamic(tostring(x))), max(x), min(x), percentile(x, 55), hll(x) ,stdev(x), sum(x), sumif(x, x > 0), tdigest(x), variance(x)

Sortie

any_x	arg_max_x	arg_min_x	avg_x	schema_x	max_x	min_x	percentile_x_55	hll_x	stdev_x	sum_x	sumif_x	tdigest_x	variance_x
			NaN						0	0	0		0

Le résultat de avg_x(x) est NaN dû à la division par 0.

Exécuter la requête

datatable(x:long)[]
| summarize  count(x), countif(x > 0) , dcount(x), dcountif(x, x > 0)

Sortie

count_x	countif_	dcount_x	dcountif_x
0	0	0	0

Exécuter la requête

datatable(x:long)[]
| summarize  make_set(x), make_list(x)

Sortie

set_x	list_x
[]	[]

La moyenne des agrégations calcule la somme de toutes les valeurs non null et compte uniquement celles qui ont participé au calcul (sans les valeurs null).

Exécuter la requête

range x from 1 to 4 step 1
| extend y = iff(x == 1, real(null), real(5))
| summarize sum(y), avg(y)

Sortie

sum_y	avg_y
15	5

Le nombre régulier compte les valeurs null :

Exécuter la requête

range x from 1 to 2 step 1
| extend y = iff(x == 1, real(null), real(5))
| summarize count(y)

Sortie

count_y
2

Exécuter la requête

range x from 1 to 2 step 1
| extend y = iff(x == 1, real(null), real(5))
| summarize make_set(y), make_set(y)

Sortie

set_y	set_y1
[5.0]	[5.0]