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. Los patrones que definen una asignación devuelven una expresión tabular cuando se invoca. Separe las dos instrucciones por punto y coma.

Los patrones vacíos son patrones declarados pero que no definen una asignación. When invoked, they return error SEM0036 along with the details of the missing pattern definitions in the HTTP header.

Las aplicaciones de nivel intermedio que proporcionan una experiencia de lenguaje de consulta kusto (KQL) pueden usar los detalles devueltos como parte de su proceso para enriquecer los resultados de la consulta KQL. Para obtener más información, consulte Trabajar con aplicaciones de nivel intermedio.

Syntax

• Declarar un patrón vacío:

  declare pattern PatternName;

• Declare y defina un patrón:

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

  {

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

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

  } ;

• Invoque un patrón:

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

Learn more about syntax conventions.

Parameters

Examples

Los ejemplos de esta sección muestran cómo usar la sintaxis para ayudarle a empezar.

Definición de un patrón simple

En este ejemplo se define un patrón que asigna estados a una expresión que devuelve su capital o ciudad principal.

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

Definición de un patrón con ámbito

En este ejemplo se define un patrón para definir el ámbito de los datos y las métricas de los datos de la aplicación. El patrón se invoca para devolver una unión de los datos.

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

Hay variaciones de sintaxis para invocar patrones. Por ejemplo, la unión siguiente devuelve una expresión de patrón única, ya que todas las invocaciones son del mismo patrón.

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

No hay ningún tratamiento especial dado a los caracteres comodín en un patrón. Por ejemplo, la consulta siguiente devuelve una única invocación de patrón que falta.

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

error semántico de salida

No se declararon una o más referencias de patrón. Referencias de patrón detectadas: ["app('ApplicationX').[' *']"]

Trabajar con aplicaciones de nivel intermedio

Una aplicación de nivel intermedio proporciona a sus usuarios la capacidad de usar KQL y quiere mejorar la experiencia enriqueciendo los resultados de la consulta con datos aumentados de su servicio interno.

Para ello, la aplicación proporciona a los usuarios una instrucción pattern que devuelve datos tabulares que sus usuarios pueden usar en sus consultas. Los argumentos del patrón son las claves que usará la aplicación para recuperar los datos de enriquecimiento.

Cuando el usuario ejecuta la consulta, la aplicación no analiza la propia consulta, sino que usa el error devuelto por un patrón vacío para recuperar las claves que requiere. Por lo tanto, antepone la consulta con la declaración de patrón vacía, la envía al clúster para su procesamiento y, a continuación, analiza el encabezado HTTP devuelto para recuperar los valores de los argumentos de patrón que faltan. La aplicación usa estos valores para buscar los datos de enriquecimiento y crea una nueva declaración que define la asignación de datos de enriquecimiento adecuada.

Por último, la aplicación antepone la nueva definición a la consulta, la reenvía para su procesamiento y devuelve el resultado que recibe al usuario.

Example

En los ejemplos, se declara, define un patrón y, a continuación, se invoca.

Declarar un patrón vacío

En este ejemplo, una aplicación de nivel intermedio enriquece las consultas con ubicaciones de longitud y latitud. La aplicación usa un servicio interno para asignar direcciones IP a ubicaciones de longitud y latitud y proporciona un patrón denominado map_ip_to_longlat. Cuando se ejecuta la consulta, devuelve un error con definiciones de patrón que faltan:

map_ip_to_longlat("10.10.10.10")

Declarar y definir un patrón

The application does not parse this query and hence does not know which IP address (10.10.10.10) was passed to the pattern. Por lo tanto, antepone la consulta de usuario con una declaración de patrón de map_ip_to_longlat vacía y la envía para su procesamiento:

declare pattern map_ip_to_longlat;
map_ip_to_longlat("10.10.10.10")

La aplicación recibe el siguiente error en respuesta.

No se declararon una o más referencias de patrón. Referencias de patrón detectadas: ["map_ip_to_longlat('10.10.10.10')"]

Invocación de un patrón

The application inspects the error, determines that the error indicates a missing pattern reference, and retrieves the missing IP address (10.10.10.10). Usa la dirección IP para buscar los datos de enriquecimiento en su servicio interno y crea un nuevo patrón que define la asignación de la dirección IP a los datos de longitud y latitud correspondientes. El nuevo patrón se antepone a la consulta del usuario y se vuelve a ejecutar.

Esta vez la consulta se realiza correctamente porque los datos de enriquecimiento ahora se declaran en la consulta y el resultado se envía al usuario.

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