Share via

mv-expand, opérateur

  • Article

Développe des tableaux dynamiques à valeurs multiples ou des conteneurs de propriétés en plusieurs enregistrements.

mv-expand peut être décrit comme l’opposé des opérateurs d’agrégation qui rassemblent plusieurs valeurs en un seul tableau ou un seul conteneur de propriétés de type dynamique, comme summarize ... make-list() et make-series. Chaque élément dans le tableau (scalaire) ou le conteneur de propriétés génère un nouvel enregistrement dans la sortie de l’opérateur. Toutes les colonnes de l’entrée qui ne sont pas développées sont dupliquées dans tous les enregistrements de la sortie.

Syntaxe

T|mv-expand [kind=(bagarray | )] [with_itemindex=IndexColumnName] ColumnName [to typeof(Typename)] [,ColumnName ...] [limitRowlimit]

T|mv-expand [kind=(bag | array)] [Name=] ArrayExpression [to typeof(Typename)] [, [Name=] ArrayExpression [to typeof(Typename)] ...] [limitRowlimit]

Découvrez les conventions de syntaxe.

Paramètres

Nom Type Obligatoire Description
ColumnName, ArrayExpression string ✔️ Référence de colonne ou expression scalaire avec une valeur de type dynamic qui contient un tableau ou un conteneur de propriétés. Les éléments individuels de plus haut niveau du tableau ou du conteneur de propriétés sont développés en plusieurs enregistrements.
Quand expression_tableau est utilisé et que nom n’est pas égal à un nom de colonne d’entrée, la valeur développée est étendue en une nouvelle colonne dans la sortie. Sinon, le nom_colonne existant est remplacé.
Nom string Nom de la nouvelle colonne.
Typename string ✔️ Indique le type sous-jacent des éléments du tableau, qui devient le type de la colonne produite par l’opérateur mv-expand . L’opération d’application de type est uniquement cast et n’inclut pas d’analyse ou de conversion de type. Les éléments de tableau qui ne sont pas conformes au type déclaré deviennent null des valeurs.
RowLimit int Nombre maximal de lignes générées à partir de chaque ligne d’origine. La valeur par défaut est 2147483647. mvexpand est une forme héritée et obsolète de l’opérateur mv-expand. La version héritée a une limite de lignes par défaut de 128.
IndexColumnName string Si with_itemindex est spécifié, la sortie inclut une autre colonne nommée IndexColumnName qui contient l’index commençant à 0 de l’élément dans la collection développée d’origine.

Retours

Pour chaque enregistrement de l’entrée, l’opérateur retourne zéro, un ou plusieurs enregistrements dans la sortie, comme déterminé de la façon suivante :

  1. Les colonnes d’entrée qui ne sont pas développées apparaissent dans la sortie avec leur valeur d’origine. Si un seul enregistrement d’entrée est développé en plusieurs enregistrements de sortie, la valeur est dupliquée dans tous les enregistrements.

  2. Pour chaque ColumnName ou ArrayExpression développé, le nombre d’enregistrements de sortie est déterminé pour chaque valeur, comme expliqué dans modes d’expansion. Pour chaque enregistrement d’entrée, le nombre maximal d’enregistrements de sortie est calculé. Tous les tableaux ou conteneurs de propriétés sont développés « en parallèle » afin que les valeurs manquantes (le cas échéant) soient remplacées par des valeurs Null. Les éléments sont développés en lignes dans l’ordre dans lequel ils apparaissent dans le tableau/conteneur d’origine.

  3. Si la valeur dynamique est Null, un seul enregistrement est produit pour cette valeur (Null). Si la valeur dynamique est un tableau ou un conteneur de propriétés vide, aucun enregistrement n’est produit pour cette valeur. Sinon, il est produit autant d’enregistrements qu’il y a d’éléments dans la valeur dynamique.

Les colonnes développées sont de type dynamic, sauf si elles sont typées explicitement avec la clause to typeof().

Modes d’expansion

Deux modes d’expansion de conteneur de propriétés sont pris en charge :

  • kind=bag ou bagexpansion=bag : Les conteneurs de propriétés sont développés en conteneurs de propriétés à entrée unique. Il s'agit du mode par défaut.
  • kind=array ou bagexpansion=array : Les conteneurs de propriétés sont développés en structures de tableau à deux éléments [clé,valeur], permettant un accès uniforme aux clés et aux valeurs. Ce mode permet aussi par exemple d’effectuer une agrégation avec comptage distinct sur les noms de propriété.

Exemples

Colonne unique - extension de tableau

Exécuter la requête

datatable (a: int, b: dynamic)
[
    1, dynamic([10, 20]),
    2, dynamic(['a', 'b'])
]
| mv-expand b

Sortie

a b
1 10
1 20
2 a
2 b

Colonne unique - extension de conteneur

Développement simple d’une colonne unique :

Exécuter la requête

datatable (a: int, b: dynamic)
[
    1, dynamic({"prop1": "a1", "prop2": "b1"}),
    2, dynamic({"prop1": "a2", "prop2": "b2"})
]
| mv-expand b

Sortie

a b
1 {"prop1 » : « a1"}
1 {"prop2 » : « b1"}
2 {"prop1 » : « a2"}
2 {"prop2 » : « b2"}

Colonne unique - Extension de conteneur aux paires clé-valeur

Une extension de sac simple aux paires clé-valeur :

Exécuter la requête

datatable (a: int, b: dynamic)
[
    1, dynamic({"prop1": "a1", "prop2": "b1"}),
    2, dynamic({"prop1": "a2", "prop2": "b2"})
]
| mv-expand kind=array b 
| extend key = b[0], val=b[1]

Sortie

a b key Val
1 ["prop1 »,"a1"] prop1 a1
1 ["prop2 »,"b1"] prop2 b1
2 ["prop1 »,"a2"] prop1 a2
2 ["prop2 »,"b2"] prop2 b2

Deux colonnes zippées

Si vous développez deux colonnes, vous devez d’abord « zipper » les colonnes applicables, puis les développer :

Exécuter la requête

datatable (a: int, b: dynamic, c: dynamic)[
    1, dynamic({"prop1": "a", "prop2": "b"}), dynamic([5, 4, 3])
]
| mv-expand b, c

Sortie

a b c
1 {"prop1":"a"} 5
1 {"prop2":"b"} 4
1 3

Produit cartésien de deux colonnes

Si vous souhaitez obtenir un produit cartésien du développement de deux colonnes, développez l’une après l’autre :

Exécuter la requête

datatable (a: int, b: dynamic, c: dynamic)
[
    1, dynamic({"prop1": "a", "prop2": "b"}), dynamic([5, 6])
]
| mv-expand b
| mv-expand c

Sortie

a b c
1 { « prop1 » : « a"} 5
1 { « prop1 » : « a"} 6
1 { « prop2 » : « b"} 5
1 { « prop2 » : « b"} 6

Convertir la sortie

Pour forcer la sortie d’un opérateur mv-expand avec un certain type (le type par défaut est « dynamic »), utilisez to typeof :

Exécuter la requête

datatable (a: string, b: dynamic, c: dynamic)[
    "Constant", dynamic([1, 2, 3, 4]), dynamic([6, 7, 8, 9])
]
| mv-expand b, c to typeof(int)
| getschema

Sortie

ColumnName ColumnOrdinal DateType ColumnType
a 0 System.String string
b 1 System.Object dynamic
c 2 System.Int32 int

Notez que la colonne b est retournée avec le type dynamic, tandis que c est retournée avec le type int.

Utilisation de with_itemindex

Développement d’un tableau avec with_itemindex :

Exécuter la requête

range x from 1 to 4 step 1
| summarize x = make_list(x)
| mv-expand with_itemindex=Index x

Sortie

x Index
1 0
2 1
3 2
4 3

Contenu connexe