Información general sobre la directiva de actualización

Al desencadenar una directiva de actualización con un comando que agrega datos a una tabla de origen, los datos también se anexan a una tabla de destino. La tabla de destino puede tener un esquema, una directiva de retención y otras directivas de la tabla de origen. Por ejemplo, una tabla de origen de seguimiento de alta velocidad puede contener datos con formato de columna de texto libre. La tabla de destino puede incluir líneas de seguimiento específicas, con un esquema bien estructurado generado a partir de una transformación de los datos de texto libre de la tabla de origen mediante el operador de análisis.

Diagrama que muestra información general de la directiva de actualización.

Una directiva de actualización está sujeta a las mismas restricciones y procedimientos recomendados que la ingesta normal. La directiva se escala horizontalmente según el tamaño del clúster y es más eficaz al controlar la ingesta masiva.

Nota:

La tabla de origen y destino debe estar en la misma base de datos. El esquema de la función de directiva de actualización y el esquema de la tabla de destino deben coincidir en sus nombres de columna, tipos y orden.

La ingesta de datos con formato mejora el rendimiento y se prefiere CSV debido a que es un formato bien definido. A veces, sin embargo, no tiene ningún control sobre el formato de los datos, o puede que desee enriquecer los datos ingeridos, por ejemplo mediante la combinación de registros con una tabla de dimensiones estáticas en la base de datos.

Actualización de la consulta de directiva

Si la directiva de actualización se define en la tabla de destino, se pueden ejecutar varias consultas en los datos ingeridos en una tabla de origen. Si hay varias directivas de actualización, no se conoce necesariamente el orden de ejecución.

Limitaciones de las consultas

  • La consulta relacionada con la directiva puede invocar funciones almacenadas, pero:
    • No puede realizar consultas entre clústeres.
    • No puede acceder a datos externos ni tablas externas.
    • No puede realizar llamadas (mediante un complemento).
  • La consulta no tiene acceso de lectura a las tablas que tienen habilitada la directiva RestrictedViewAccess .
  • Para conocer las limitaciones de la directiva de actualización en la ingesta de streaming, consulte Limitaciones de ingesta de streaming.

Advertencia

Una consulta incorrecta podría impedir la ingesta de datos en la tabla de origen.

Las limitaciones anteriores y la "compatibilidad" entre los resultados de la consulta y el esquema de las tablas de origen y destino pueden provocar una consulta incorrecta para evitar la ingesta de datos en la tabla de origen.

Estas limitaciones se validan cuando se crea y ejecuta la directiva, pero no cuando se actualizan las funciones almacenadas arbitrarias a las que podría hacer referencia la consulta. Por lo tanto, es importante realizar estos cambios con un ojo para mantener intacta la directiva de actualización.

Al hacer referencia a la Source tabla en la Query parte de la directiva, o en funciones a las que hace referencia la Query parte:

  • No use el nombre completo de la tabla. En su lugar, use TableName.
  • No use database("DatabaseName").TableName o cluster("ClusterName").database("DatabaseName").TableName.

El objeto de directiva de actualización

Una tabla puede tener cero o más objetos de directiva de actualización asociados. Cada objeto de este tipo se representa como un contenedor de propiedades JSON, con las siguientes propiedades definidas.

Propiedad Tipo Descripción
IsEnabled bool Estados si la directiva de actualización es true , habilitada o false , deshabilitada
Source string Nombre de la tabla que desencadena la invocación de la directiva de actualización
Consultar string Consulta usada para generar datos para la actualización
IsTransactional bool Indica si la directiva de actualización es transaccional o no, el valor predeterminado es false. Si se produce un error en la directiva transaccional y de actualización, la tabla de origen no se actualiza.
PropagateIngestionProperties bool Indica si las propiedades especificadas durante la ingesta en la tabla de origen, como las etiquetas de extensión y el tiempo de creación, se aplican a la tabla de destino.
ManagedIdentity string La identidad administrada en nombre de la que se ejecutará la directiva de actualización. La identidad administrada puede ser un identificador de objeto o la system palabra reservada. La directiva de actualización debe configurarse con una identidad administrada cuando la consulta hace referencia a tablas de otras bases de datos o tablas con una directiva de seguridad de nivel de fila habilitada. Para más información, consulte Uso de una identidad administrada para ejecutar una directiva de actualización.

Nota:

En los sistemas de producción, establezca IsTransactional:true para asegurarse de que la tabla de destino no pierda datos en errores transitorios.

Nota

Se permiten actualizaciones en cascada, por ejemplo de la tabla A, a la tabla B, a la tabla C. Sin embargo, si las directivas de actualización se definen de forma circular, esto se detecta en tiempo de ejecución y se corta la cadena de actualizaciones. Los datos solo se ingieren una vez en cada tabla de la cadena.

Comandos de administración

Los comandos de administración de directivas de actualización incluyen:

La directiva de actualización se inicia después de la ingesta

Las directivas de actualización surten efecto cuando los datos se ingieren o se mueven a una tabla de origen, o las extensiones se crean en una tabla de origen mediante cualquiera de los siguientes comandos:

Advertencia

Cuando se invoca la directiva de actualización como parte de un .set-or-replace comando, los datos de las tablas derivadas se reemplazan de forma predeterminada de la misma manera que en la tabla de origen. Los datos se pueden perder en todas las tablas con una relación de directiva de actualización si se invoca el replace comando . Considere usar .set-or-append en su lugar.

Eliminación de datos de la tabla de origen

Después de ingerir datos en la tabla de destino, es posible que quiera quitarlos de la tabla de origen. Establezca un período de eliminación temporal de 0sec (o 00:00:00) en la directiva de retención de la tabla de origen y la directiva de actualización como transaccional. Se aplican las siguientes condiciones:

  • Los datos de origen no se pueden consultar desde la tabla de origen.
  • Los datos de origen no se conservan en el almacenamiento duradero como parte de la operación de ingesta.
  • Mejora el rendimiento operativo. Los recursos posteriores a la ingesta se reducen para las operaciones de limpieza en segundo plano en extensiones de la tabla de origen.

Nota

Cuando la tabla de origen tiene un período de eliminación temporal de 0sec (o 00:00:00), cualquier directiva de actualización que haga referencia a esta tabla debe ser transaccional.

Impacto en el rendimiento

Las directivas de actualización pueden afectar al rendimiento del clúster y la ingesta de extensiones de datos se multiplica por el número de tablas de destino. Es importante optimizar la consulta relacionada con la directiva. Puede probar el impacto en el rendimiento de una directiva de actualización invocando la directiva en extensiones ya existentes, antes de crear o modificar la directiva, o en la función usada con la consulta.

Evaluación del uso de recursos

Use .show queries, para evaluar el uso de recursos (CPU, memoria, etc.) con los parámetros siguientes:

  • Establezca la propiedad , el nombre de la Source tabla de origen, como MySourceTable
  • Establezca la Query propiedad para llamar a una función denominada MyFunction()
// '_extentId' is the ID of a recently created extent, that likely hasn't been merged yet.
let _extentId = toscalar(
    MySourceTable
    | project ExtentId = extent_id(), IngestionTime = ingestion_time()
    | where IngestionTime > ago(10m)
    | top 1 by IngestionTime desc
    | project ExtentId
);
// This scopes the source table to the single recent extent.
let MySourceTable = 
    MySourceTable
    | where ingestion_time() > ago(10m) and extent_id() == _extentId;
// This invokes the function in the update policy (that internally references `MySourceTable`).
MyFunction

Errores

Con la configuración predeterminada de IsTransactional:false, los datos todavía se pueden ingerir en la tabla de origen aunque la directiva no se ejecute.

Establecer IsTransactional:true garantiza la coherencia entre los datos de la tabla de origen y de destino. Sin embargo, si se produce un error en las condiciones de la directiva, los datos no se ingieren en la tabla de origen. Como alternativa, en función de las condiciones, a veces los datos se ingieren en la tabla de origen, pero no en la tabla de destino. Sin embargo, si la directiva se define incorrectamente o hay un error de coincidencia de esquema, los datos no se ingerirán en la tabla de origen o de destino. Por ejemplo, una discrepancia entre el esquema de salida de la consulta y la tabla de destino podría deberse a la eliminación de una columna de la tabla de destino.

Puede ver errores mediante el .show ingestion failures comando .

.show ingestion failures 
| where FailedOn > ago(1hr) and OriginatesFromUpdatePolicy == true

Tratamiento de errores

Directiva no transaccional

Cuando se establece en IsTransactional:false, se omite cualquier error al ejecutar la directiva. La ingesta no se reintenta automáticamente. Puede reintentar manualmente la ingesta.

Directiva transaccional

Cuando se establece IsTransactionalen :true, si el método de ingesta es pull, el servicio Administración de datos está implicado y la ingesta se reintenta automáticamente según las condiciones siguientes:

  • Los reintentos se realizan hasta que se cumple una de las siguientes opciones de límite configurables: DataImporterMaximumRetryPeriod o DataImporterMaximumRetryAttempts
  • De forma predeterminada, la DataImporterMaximumRetryPeriod configuración es de 2 días y DataImporterMaximumRetryAttemptses 10.
  • El período de retroceso comienza en 2 minutos y se duplica. Por lo tanto, la espera comienza con 2 minutos, y luego aumenta a 4 minutos, a 8 minutos, a 16 minutos, etc.

En cualquier otro caso, puede reintentar manualmente la ingesta.

Ejemplo de extracción, transformación, carga

Puede usar la configuración de la directiva de actualización para realizar la extracción, transformación y carga (ETL).

En este ejemplo, use una directiva de actualización junto con una función sencilla para realizar ETL. En primer lugar, creamos dos tablas:

  • La tabla de origen: contiene una sola columna con tipo de cadena en la que se ingieren los datos.
  • La tabla de destino: contiene el esquema deseado. La directiva de actualización se define en esta tabla.
  1. Vamos a crear la tabla de origen:

    .create table MySourceTable (OriginalRecord:string) 
    
  2. A continuación, cree la tabla de destino:

    .create table MyTargetTable (Timestamp:datetime, ThreadId:int, ProcessId:int, TimeSinceStartup:timespan, Message:string)
    
  3. A continuación, cree una función para extraer datos:

    .create function
     with (docstring = 'Parses raw records into strongly-typed columns', folder = 'UpdatePolicyFunctions')
         ExtractMyLogs()  
        {
        MySourceTable
        | parse OriginalRecord with "[" Timestamp:datetime "] [ThreadId:" ThreadId:int "] [ProcessId:" ProcessId:int "] TimeSinceStartup: " TimeSinceStartup:timespan " Message: " Message:string
        | project-away OriginalRecord
    }
    
  4. Ahora, establezca la directiva de actualización para invocar la función que hemos creado:

    .alter table MyTargetTable policy update 
    @'[{ "IsEnabled": true, "Source": "MySourceTable", "Query": "ExtractMyLogs()", "IsTransactional": true, "PropagateIngestionProperties": false}]'
    
  5. Para vaciar la tabla de origen después de ingerir los datos en la tabla de destino, defina la directiva de retención en la tabla de origen para que tenga 0s como su SoftDeletePeriod.

     .alter-merge table MySourceTable policy retention softdelete = 0s