materialize()

Capture la valeur d’une expression tabulaire pendant la durée de l’exécution de la requête afin qu’elle puisse être référencée plusieurs fois par la requête sans recalcul.

Syntax

materialize(expression)

Découvrez les conventions de syntaxe.

Paramètres

Nom	Type	Obligatoire	Description
expression	string	✔️	Expression tabulaire à évaluer et mettre en cache pendant l’exécution de la requête.

Remarques

La materialize() fonction est utile dans les scénarios suivants :

• Pour accélérer les requêtes qui effectuent des calculs lourds dont les résultats sont utilisés plusieurs fois dans la requête.
• Pour évaluer une expression tabulaire une seule fois et l’utiliser plusieurs fois dans une requête. Cela est généralement nécessaire si l’expression tabulaire n’est pas déterministe. Par exemple, si l’expression utilise les rand() fonctions ou .dcount()

Notes

Materialize a une limite de taille de cache de 5 Go. Cette limite est par nœud de cluster et est mutuelle pour toutes les requêtes exécutées simultanément. Si une requête utilise materialize() et que le cache ne peut plus contenir de données, la requête est abandonnée avec une erreur.

Conseil

Une autre façon d’effectuer la matérialisation d’une expression tabulaire consiste à utiliser l’indicateur hint.materialized de l’opérateur en tant qu’opérateur et de l’opérateur de partition. Ils partagent tous un seul cache de matérialisation.

Conseil

• Envoyer (push) tous les opérateurs possibles qui réduisent le jeu de données matérialisé et conservent la sémantique de la requête. Par exemple, utilisez des filtres courants au-dessus de la même expression matérialisée.
• Utilisez materialize avec une jointure ou une union lorsque leurs opérandes ont des sous-requêtes mutuelles qui peuvent être exécutées une seule fois. Par exemple, des jambes de jointure/union. Consultez l’exemple d’utilisation de l’opérateur de jointure.
• Materialize ne peut être utilisé dans les instructions let que si vous donnez un nom au résultat mis en cache. Consultez l’exemple d’utilisation d’instructions let).

Exemples d’amélioration des performances des requêtes

L’exemple suivant montre comment materialize() peut être utilisé pour améliorer les performances de la requête. L’expression _detailed_data est définie à l’aide de materialize() la fonction et n’est donc calculée qu’une seule fois.

Exécuter la requête

let _detailed_data = materialize(StormEvents | summarize Events=count() by State, EventType);
_detailed_data
| summarize TotalStateEvents=sum(Events) by State
| join (_detailed_data) on State
| extend EventPercentage = Events*100.0 / TotalStateEvents
| project State, EventType, EventPercentage, Events
| top 10 by EventPercentage

Sortie

State	Type d’événement	EventPercentage	Événements
EAUX HAWAÏ	Trombe marine	100	2
LAC ONTARIO	Vent d’orage marin	100	8
GOLFE DE L’ALASKA	Trombe marine	100	4
ATLANTIQUE NORD	Vent d’orage marin	95.2127659574468	179
LAC ERIE	Vent d’orage marin	92.5925925925926	25
E PACIFIC	Trombe marine	90	9
LAC MICHIGAN	Vent d’orage marin	85.1648351648352	155
LAC HURON	Vent d’orage marin	79.3650793650794	50
GOLFE DU MEXIQUE	Vent d’orage marin	71.7504332755633	414
HAWAII	High Surf	70.0218818380744	320

L’exemple suivant génère un ensemble de nombres aléatoires et calcule :

• Nombre de valeurs distinctes dans le jeu (Dcount)
• Les trois premières valeurs de l’ensemble
• Somme de toutes ces valeurs dans l’ensemble

Cette opération peut être effectuée à l’aide de lots et matérialiser :

Exécuter la requête

let randomSet = 
    materialize(
        range x from 1 to 3000000 step 1
        | project value = rand(10000000));
randomSet | summarize Dcount=dcount(value);
randomSet | top 3 by value;
randomSet | summarize Sum=sum(value)

Jeu de résultats 1 :

Dcount
2578351

Jeu de résultats 2 :

value
9999998
9999998
9999997

Jeu de résultats 3 :

Sum
15002960543563

Exemples d’utilisation de materialize()

Conseil

Matérialisez votre colonne au moment de l’ingestion si la plupart de vos requêtes extraient des champs d’objets dynamiques dans des millions de lignes.

Pour utiliser l’instruction let avec une valeur que vous utilisez plusieurs fois, utilisez la fonction materialize(). Essayez d’envoyer (push) tous les opérateurs possibles qui réduisent le jeu de données matérialisé tout en conservant la sémantique de la requête. Par exemple, utilisez des filtres ou projetez uniquement les colonnes requises.

    let materializedData = materialize(Table
    | where Timestamp > ago(1d));
    union (materializedData
    | where Text !has "somestring"
    | summarize dcount(Resource1)), (materializedData
    | where Text !has "somestring"
    | summarize dcount(Resource2))

Le filtre sur Text est mutuel et peut être poussé vers l’expression matérialiser. La requête a uniquement besoin de colonnes Timestamp, Text, Resource1et Resource2. Projetez ces colonnes à l’intérieur de l’expression matérialisée.

    let materializedData = materialize(Table
    | where Timestamp > ago(1d)
    | where Text !has "somestring"
    | project Timestamp, Resource1, Resource2, Text);
    union (materializedData
    | summarize dcount(Resource1)), (materializedData
    | summarize dcount(Resource2))

Si les filtres ne sont pas identiques, comme dans la requête suivante :

    let materializedData = materialize(Table
    | where Timestamp > ago(1d));
    union (materializedData
    | where Text has "String1"
    | summarize dcount(Resource1)), (materializedData
    | where Text has "String2"
    | summarize dcount(Resource2))

Lorsque le filtre combiné réduit considérablement le résultat matérialisé, combinez les deux filtres sur le résultat matérialisé par une expression logique or , comme dans la requête suivante. Toutefois, conservez les filtres dans chaque étape union pour conserver la sémantique de la requête.

    let materializedData = materialize(Table
    | where Timestamp > ago(1d)
    | where Text has "String1" or Text has "String2"
    | project Timestamp, Resource1, Resource2, Text);
    union (materializedData
    | where Text has "String1"
    | summarize dcount(Resource1)), (materializedData
    | where Text has "String2"
    | summarize dcount(Resource2))