Pattern statement

Applies to: ✅Microsoft Fabric✅Azure Data Explorer✅Azure Monitor✅Microsoft Sentinel

A pattern is a construct that maps string tuples to tabular expressions.

Each pattern must declare a pattern name and optionally define a pattern mapping. Les modèles qui définissent un mappage retournent une expression tabulaire lorsqu’ils sont appelés. Séparez les deux instructions par un point-virgule.

Les modèles vides sont des modèles déclarés, mais qui ne définissent pas de mappage. When invoked, they return error SEM0036 along with the details of the missing pattern definitions in the HTTP header.

Les applications de niveau intermédiaire qui fournissent une expérience KQL (Kusto Query Language) peuvent utiliser les détails retournés dans le cadre de leur processus pour enrichir les résultats de requête KQL. Pour plus d’informations, consultez Utilisation d’applications de niveau intermédiaire.

Syntax

• Déclarez un modèle vide :

  declare pattern PatternName;

• Déclarez et définissez un modèle :

  declare pattern PatternName = (ArgName:ArgType [, ... ]) [[PathName:PathArgType]]

  {

         ( ArgValue1_1 [,ArgValue2_1, ... ] ) [ .[PathValue_1] ] ={expression1};

      [ (ArgValue1_2 [,ArgValue2_2, ... ] ) [ .[PathValue_2] ] ={expression2}; ... ]

  } ;

• Appeler un modèle :

  • PatternName(ArgValue1 [,ArgValue2 ...] ).PathValue
  • PatternName(ArgValue1 [,ArgValue2 ...] ).["PathValue"]

Learn more about syntax conventions.

Parameters

Examples

Les exemples de cette section montrent comment utiliser la syntaxe pour vous aider à commencer.

Définir un modèle simple

Cet exemple définit un modèle qui mappe les états à une expression qui retourne sa capitale/ville principale.

declare pattern country = (name:string)[state:string]
{
  ("USA").["New York"] = { print Capital = "Albany" };
  ("USA").["Washington"] = { print Capital = "Olympia" };
  ("Canada").["Alberta"] = { print Capital = "Edmonton" };
};
country("Canada").Alberta

Output

Définir un modèle délimité

Cet exemple définit un modèle pour étendre les données et les métriques des données d’application. Le modèle est appelé pour retourner une union des données.

declare pattern App = (applicationId:string)[scope:string]
{
    ('a1').['Data']    = { range x from 1 to 5 step 1 | project App = "App #1", Data    = x };
    ('a1').['Metrics'] = { range x from 1 to 5 step 1 | project App = "App #1", Metrics = rand() };
    ('a2').['Data']    = { range x from 1 to 5 step 1 | project App = "App #2", Data    = 10 - x };
    ('a3').['Metrics'] = { range x from 1 to 5 step 1 | project App = "App #3", Metrics = rand() };
};
union App('a2').Data, App('a1').Metrics

Output

Normalization

Il existe des variantes de syntaxe pour appeler des modèles. Par exemple, l’union suivante retourne une expression de modèle unique, car tous les appels sont du même modèle.

declare pattern app = (applicationId:string)[eventType:string]
{
    ("ApplicationX").["StopEvents"] = { database("AppX").Events | where EventType == "StopEvent" };
    ("ApplicationX").["StartEvents"] = { database("AppX").Events | where EventType == "StartEvent" };
};
union
  app("ApplicationX").StartEvents,
  app('ApplicationX').StartEvents,
  app("ApplicationX").['StartEvents'],
  app("ApplicationX").["StartEvents"]

No wildcards

Il n’y a pas de traitement spécial donné aux caractères génériques dans un modèle. Par exemple, la requête suivante retourne un appel de modèle manquant unique.

declare pattern app = (applicationId:string)[eventType:string]
{
    ("ApplicationX").["StopEvents"] = { database("AppX").Events | where EventType == "StopEvent" };
    ("ApplicationX").["StartEvents"] = { database("AppX").Events | where EventType == "StartEvent" };
};
union app("ApplicationX").["*"]
| count

erreur sémantique de sortie

Une ou plusieurs références de modèle n’ont pas été déclarées. Références de modèle détectées : ["app('ApplicationX').[' *']"]

Utiliser des applications de niveau intermédiaire

Une application de niveau intermédiaire fournit à ses utilisateurs la possibilité d’utiliser KQL et souhaite améliorer l’expérience en enrichissant les résultats de la requête avec des données augmentées à partir de son service interne.

À cette fin, l’application fournit aux utilisateurs une instruction pattern qui retourne des données tabulaires que leurs utilisateurs peuvent utiliser dans leurs requêtes. Les arguments du modèle sont les clés que l’application utilisera pour récupérer les données d’enrichissement.

Lorsque l’utilisateur exécute la requête, l’application n’analyse pas la requête elle-même, mais utilise plutôt l’erreur retournée par un modèle vide pour récupérer les clés dont elle a besoin. Ainsi, il précède la requête avec la déclaration de modèle vide, l’envoie au cluster pour traitement, puis analyse l’en-tête HTTP retourné pour récupérer les valeurs des arguments de modèle manquants. L’application utilise ces valeurs pour rechercher les données d’enrichissement et générer une nouvelle déclaration qui définit le mappage approprié des données d’enrichissement.

Enfin, l’application ajoute la nouvelle définition à la requête, la renvoie pour traitement et retourne le résultat qu’elle reçoit à l’utilisateur.

Example

Dans les exemples, un modèle est déclaré, défini, puis appelé.

Déclarer un modèle vide

Dans cet exemple, une application de niveau intermédiaire enrichit les requêtes avec des emplacements longitude/latitude. L’application utilise un service interne pour mapper les adresses IP aux emplacements longitude/latitude, et fournit un modèle appelé map_ip_to_longlat. Lorsque la requête est exécutée, elle retourne une erreur avec des définitions de modèle manquantes :

map_ip_to_longlat("10.10.10.10")

Déclarer et définir un modèle

The application does not parse this query and hence does not know which IP address (10.10.10.10) was passed to the pattern. Ainsi, il précède la requête utilisateur avec une déclaration de modèle map_ip_to_longlat vide et l’envoie pour le traitement :

declare pattern map_ip_to_longlat;
map_ip_to_longlat("10.10.10.10")

L’application reçoit l’erreur suivante en réponse.

Une ou plusieurs références de modèle n’ont pas été déclarées. Références de modèle détectées : ["map_ip_to_longlat('10.10.10.10')"]

Appeler un modèle

The application inspects the error, determines that the error indicates a missing pattern reference, and retrieves the missing IP address (10.10.10.10). Il utilise l’adresse IP pour rechercher les données d’enrichissement dans son service interne et crée un nouveau modèle définissant le mappage de l’adresse IP aux données de longitude et de latitude correspondantes. Le nouveau modèle est ajouté à la requête de l’utilisateur et réexécuter.

Cette fois,la requête réussit, car les données d’enrichissement sont désormais déclarées dans la requête, et le résultat est envoyé à l’utilisateur.

declare pattern map_ip_to_longlat = (address:string)
{
  ("10.10.10.10") = { print Lat=37.405992, Long=-122.078515 };
};
map_ip_to_longlat("10.10.10.10")

Output