Introducción a la directiva de actualización

Se aplica a: ✅Microsoft Fabric✅Azure Data Explorer

Las directivas de actualización son mecanismos de automatización desencadenados cuando se escriben nuevos datos en una tabla. Eliminan la necesidad de orquestación especial mediante la ejecución de 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 general de una directiva de actualización. Muestra dos directivas de actualización que se desencadenan cuando se agregan datos a la segunda tabla de origen. Una vez desencadenados, los datos transformados se agregan a las dos tablas de destino.

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 de Eventhouse 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 función de directiva de actualización puede hacer referencia a tablas de otras bases de datos. Para ello, la directiva de actualización debe definirse con una ManagedIdentity propiedad y la identidad administrada debe tener viewerel rol en las bases de datos a las que se hace referencia. 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 control sobre el formato de los datos o desea enriquecer los datos ingeridos, por ejemplo, mediante la combinación de registros con una tabla de dimensiones estática 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 centros de eventos.
  • 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.
• De forma predeterminada, la directiva de ingesta de streaming está habilitada para todas las tablas de Eventhouse. Para usar funciones con el operador join en una directiva de actualización, la directiva de ingesta de streaming debe estar deshabilitada. Use el comando .altertableTableNamepolicystreamingingestionPolicyObject para deshabilitarlo.

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 puede 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 uses database("<DatabaseName>").TableName o cluster("<EventhouseName>").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
Consulta	string	Una consulta que se usa 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.
Identidad administrada	string	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 obtener 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 pierde datos en errores transitorios.

Nota:

Las actualizaciones en cascada se permiten, 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, 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:

• .show table *TableName* policy update muestra la directiva de actualización actual de una tabla.
• .alter table *TableName* policy update define la directiva de actualización actual de una tabla.
• .alter-merge table *TableName* policy update anexa definiciones a la directiva de actualización actual de una tabla.
• .delete table *TableName* policy update elimina la directiva de actualización actual de una tabla.

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. Estas acciones se pueden realizar mediante cualquiera de los siguientes comandos:

• .ingest (extracción)
• .ingest (insertado)
• .set | .append | .set-or-append | .set-or-replace
• .move extents
• .replace extents
  • El PropagateIngestionProperties comando solo surte efecto en las operaciones de ingesta. Cuando la directiva de actualización se desencadena como parte de un .move extents comando o .replace extents , esta opción no tiene ningún efecto.

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 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, puede quitarlos de la tabla de origen. Establezca un período de eliminación temporal de (o 0sec) en la directiva de 00:00:00 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 (o 0sec), cualquier directiva de 00:00:00 actualización que haga referencia a esta tabla debe ser transaccional.

Impacto en el rendimiento

Las directivas de actualización pueden afectar al rendimiento 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

Configuración transaccional

La configuración de directiva IsTransactional de actualización define si la directiva de actualización es transaccional y puede afectar al comportamiento de la actualización de directiva, como se indica a continuación:

• IsTransactional:false: si el valor se establece en el valor predeterminado, false, la directiva de actualización no garantiza la coherencia entre los datos de la tabla de origen y de destino. Si se produce un error en una directiva de actualización, los datos solo se ingieren en la tabla de origen y no en la tabla de destino. En este escenario, la operación de ingesta se realiza correctamente.
• IsTransactional:true: si el valor se establece en true, la configuración garantiza la coherencia entre los datos de las tablas de origen y de destino. Si se produce un error en una directiva de actualización, los datos no se ingieren en la tabla de origen o de destino. En este escenario, la operación de ingesta no es correcta.

Administración de errores

Cuando se produce un error en las actualizaciones de directivas, se controlan de forma diferente en función de si la IsTransactional configuración es true o false. Los motivos comunes de los errores de directiva de actualización son:

• Un error de coincidencia entre el esquema de salida de la consulta y la tabla de destino.
• Cualquier error de consulta.

Puede ver los errores de actualización de directivas mediante el .show ingestion failures comando siguiente: En cualquier otro caso, puede volver a intentar la ingesta manualmente.

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

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 tener 0s como su SoftDeletePeriod.

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

Contenido relacionado

• Escenarios comunes para usar directivas de actualización de tablas
• Tutorial: Enrutamiento de datos mediante directivas de actualización de tablas