Información general sobre la directiva de actualización

  • Artículo

Las directivas de actualización son mecanismos de automatización que se desencadenan cuando se escriben nuevos datos en una tabla. Eliminan la necesidad de orquestación especial ejecutando una consulta para transformar los datos ingeridos y guardar el resultado en una tabla de destino. Se pueden definir varias directivas de actualización en una sola tabla, lo que permite diferentes transformaciones y guardar datos en varias tablas simultáneamente. Las tablas de destino pueden 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. Para obtener más información, escenarios comunes.

En el diagrama siguiente se muestra una vista de alto nivel de una directiva de actualización. Muestra dos directivas de actualización que se desencadenan cuando los datos agregados a la segunda tabla de origen y dan lugar a que los datos transformados se agreguen a las dos tablas de destino.

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 quiere enriquecer los datos ingeridos, por ejemplo, uniendo 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 puede impedir la ingesta de datos en la tabla de origen. Es importante tener en cuenta que las limitaciones, así como 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 durante la creación y ejecución de la directiva, pero no cuando se actualizan las funciones almacenadas arbitrarias a las que podría hacer referencia la consulta. Por lo tanto, es fundamental realizar cualquier cambio con precaución para asegurarse de que la directiva de actualización permanece intacta.

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 la directiva es transaccional y se produce un error en la directiva 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 ejecuta 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, opcionalmente puede 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 Source propiedad , el nombre de la 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 ingieren 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 los 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 IsTransactional:trueen , 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 dos 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, a continuación, aumenta a 4 minutos, a 8 minutos, a 16 minutos, etc.

En cualquier otro caso, puede volver a intentar la ingesta manualmente.

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, carga (ETL).

En este ejemplo, use una directiva de actualización 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 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

Contenido relacionado