Condividi tramite

Panoramica dei criteri di aggiornamento

  • Articolo

I criteri di aggiornamento sono meccanismi di automazione attivati quando vengono scritti nuovi dati in una tabella. Eliminano la necessità di orchestrazione speciale eseguendo una query per trasformare i dati inseriti e salvare il risultato in una tabella di destinazione. È possibile definire più criteri di aggiornamento in una singola tabella, consentendo trasformazioni diverse e salvando i dati in più tabelle contemporaneamente. Le tabelle di destinazione possono avere uno schema, criteri di conservazione e altri criteri diversi dalla tabella di origine.

Ad esempio, una tabella di origine di traccia ad alta frequenza può contenere dati formattati come colonna free-text. La tabella di destinazione può includere righe di traccia specifiche, con uno schema ben strutturato generato da una trasformazione dei dati free-text della tabella di origine usando l'operatore parse. Per altre informazioni, scenari comuni.

Il diagramma seguente illustra una visualizzazione generale di un criterio di aggiornamento. Mostra due criteri di aggiornamento attivati quando i dati vengono aggiunti alla seconda tabella di origine. Dopo l'attivazione, i dati trasformati vengono aggiunti alle due tabelle di destinazione.

Diagramma che mostra una panoramica dei criteri di aggiornamento.

Un criterio di aggiornamento è soggetto alle stesse restrizioni e procedure consigliate dell'inserimento regolare. Il criterio viene ridimensionato in base alle dimensioni del cluster ed è più efficiente quando si gestisce l'inserimento bulk.

Nota

  • La tabella di origine e di destinazione deve trovarsi nello stesso database.
  • Lo schema della funzione dei criteri di aggiornamento e lo schema della tabella di destinazione devono corrispondere ai nomi, ai tipi e all'ordine delle colonne.
  • La funzione dei criteri di aggiornamento può fare riferimento a tabelle in altri database. A tale scopo, i criteri di aggiornamento devono essere definiti con una ManagedIdentity proprietà e l'identità gestita deve avere viewer il ruolo nei database a cui si fa riferimento.

L'inserimento di dati formattati migliora le prestazioni e csv è preferibile a causa di un formato ben definito. In alcuni casi, tuttavia, non si ha alcun controllo sul formato dei dati o si desidera arricchire i dati inseriti, ad esempio aggiungendo record con una tabella delle dimensioni statiche nel database.

Aggiornare la query dei criteri

Se i criteri di aggiornamento sono definiti nella tabella di destinazione, è possibile eseguire più query sui dati inseriti in una tabella di origine. Se sono presenti più criteri di aggiornamento, l'ordine di esecuzione non è necessariamente noto.

Limitazioni delle query

  • La query correlata ai criteri può richiamare funzioni archiviate, ma:
    • Non può eseguire query tra cluster.
    • Non può accedere a dati esterni o tabelle esterne.
    • Non può creare callout (usando un plug-in).
  • La query non ha accesso in lettura alle tabelle con i criteri RestrictedViewAccess abilitati.
  • Per le limitazioni dei criteri di aggiornamento nell'inserimento in streaming, vedere Limitazioni per l'inserimento in streaming.

Avviso

Una query non corretta può impedire l'inserimento di dati nella tabella di origine. È importante notare che le limitazioni, nonché la compatibilità tra i risultati della query e lo schema delle tabelle di origine e di destinazione, possono causare una query errata per impedire l'inserimento dei dati nella tabella di origine.

Queste limitazioni vengono convalidate durante la creazione e l'esecuzione dei criteri, ma non quando vengono aggiornate funzioni archiviate arbitrarie a cui potrebbe fare riferimento la query. Pertanto, è fondamentale apportare eventuali modifiche con cautela per garantire che i criteri di aggiornamento rimangano intatti.

Quando si fa riferimento alla Source tabella nella Query parte del criterio o nelle funzioni a cui fa riferimento la Query parte:

  • Non usare il nome completo della tabella. Usare invece TableName.
  • Non utilizzare database("DatabaseName").TableName o cluster("ClusterName").database("DatabaseName").TableName.

Oggetto criteri di aggiornamento

A una tabella possono essere associati zero o più oggetti criteri di aggiornamento. Ogni oggetto di questo tipo è rappresentato come contenitore di proprietà JSON, con le proprietà seguenti definite.

Proprietà Type Descrizione
IsEnabled bool Indica se i criteri di aggiornamento sono true , abilitati o false , disabilitati
Origine string Nome della tabella che attiva la chiamata dei criteri di aggiornamento
Query string Query utilizzata per produrre dati per l'aggiornamento
IsTransactional bool Se il criterio di aggiornamento è transazionale o meno, il valore predefinito è false. Se il criterio è transazionale e i criteri di aggiornamento hanno esito negativo, la tabella di origine non viene aggiornata.
PropagateIngestionProperties bool Indica se le proprietà specificate durante l'inserimento nella tabella di origine, ad esempio tag extent e ora di creazione, si applicano alla tabella di destinazione.
ManagedIdentity string Identità gestita per conto della quale vengono eseguiti i criteri di aggiornamento. L'identità gestita può essere un ID oggetto o la system parola riservata. I criteri di aggiornamento devono essere configurati con un'identità gestita quando la query fa riferimento a tabelle in altri database o tabelle con un criterio di sicurezza a livello di riga abilitato. Per altre informazioni, vedere Usare un'identità gestita per eseguire un criterio di aggiornamento.

Nota

Nei sistemi di produzione impostare IsTransactional:true per assicurarsi che la tabella di destinazione non perda i dati in errori temporanei.

Nota

Gli aggiornamenti a catena sono consentiti, ad esempio dalla tabella A, alla tabella B, alla tabella C. Tuttavia, se i criteri di aggiornamento vengono definiti in modo circolare, questo viene rilevato in fase di esecuzione e la catena di aggiornamenti viene tagliata. I dati vengono inseriti una sola volta in ogni tabella della catena.

Comandi di gestione

I comandi di gestione dei criteri di aggiornamento includono:

I criteri di aggiornamento vengono avviati dopo l'inserimento

I criteri di aggiornamento diventano effettivi quando i dati vengono inseriti o spostati in una tabella di origine o gli extent vengono creati in una tabella di origine. Queste azioni possono essere eseguite usando uno dei comandi seguenti:

Avviso

Quando i criteri di aggiornamento vengono richiamati come parte di un .set-or-replace comando, per impostazione predefinita i dati nelle tabelle derivate vengono sostituiti nello stesso modo della tabella di origine. I dati possono essere persi in tutte le tabelle con una relazione di criteri di aggiornamento se il replace comando viene richiamato. In alternativa, considerare l'utilizzo di .set-or-append.

Rimuovere dati dalla tabella di origine

Dopo aver inserito i dati nella tabella di destinazione, è possibile rimuoverli dalla tabella di origine. Impostare un periodo di eliminazione temporanea di 0sec (o 00:00:00) nei criteri di conservazione della tabella di origine e i criteri di aggiornamento come transazionali. Vengono applicate le seguenti condizioni:

  • I dati di origine non sono queryabili dalla tabella di origine
  • I dati di origine non vengono mantenuti nell'archiviazione durevole come parte dell'operazione di inserimento
  • Le prestazioni operative migliorano. Le risorse post-inserimento vengono ridotte per le operazioni di pulitura in background sugli extent nella tabella di origine.

Nota

Quando la tabella di origine ha un periodo di eliminazione temporanea di (o 00:00:00), tutti i criteri di 0sec aggiornamento che fanno riferimento a questa tabella devono essere transazionali.

Impatto sulle prestazioni

I criteri di aggiornamento possono influire sulle prestazioni del cluster e l'inserimento per gli extent di dati viene moltiplicato per il numero di tabelle di destinazione. È importante ottimizzare la query correlata ai criteri. È possibile testare l'impatto sulle prestazioni di un criterio di aggiornamento richiamando i criteri in extent già esistenti, prima di creare o modificare i criteri o sulla funzione usata con la query.

Valutare l'utilizzo delle risorse

Usare .show queries, per valutare l'utilizzo delle risorse (CPU, memoria e così via) con i parametri seguenti:

  • Impostare la Source proprietà, il nome della tabella di origine, come MySourceTable
  • Impostare la Query proprietà per chiamare una funzione denominata 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

Impostazioni transazionali

L'impostazione dei criteri di aggiornamento IsTransactional definisce se i criteri di aggiornamento sono transazionali e possono influire sul comportamento dell'aggiornamento dei criteri, come indicato di seguito:

  • IsTransactional:false: se il valore è impostato sul valore predefinito, false, i criteri di aggiornamento non garantiscono la coerenza tra i dati nella tabella di origine e di destinazione. Se un criterio di aggiornamento ha esito negativo, i dati vengono inseriti solo nella tabella di origine e non nella tabella di destinazione. In questo scenario l'operazione di inserimento ha esito positivo.

  • IsTransactional:true: se il valore è impostato su true, l'impostazione garantisce la coerenza tra i dati nelle tabelle di origine e di destinazione. Se un criterio di aggiornamento non riesce, i dati non vengono inseriti nella tabella di origine o di destinazione. In questo scenario, l'operazione di inserimento non riesce.

Gestione degli errori

Quando gli aggiornamenti dei criteri hanno esito negativo, vengono gestiti in modo diverso in base al fatto che l'impostazione IsTransactional sia true o false. I motivi comuni per gli errori dei criteri di aggiornamento sono:

  • Mancata corrispondenza tra lo schema di output della query e la tabella di destinazione.
  • Qualsiasi errore di query.

È possibile visualizzare gli errori di aggiornamento dei criteri usando il .show ingestion failures comando con il comando seguente:

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

Esempio di estrazione, trasformazione, caricamento

È possibile usare le impostazioni dei criteri di aggiornamento per eseguire estrazione, trasformazione, caricamento (ETL).

In questo esempio usare un criterio di aggiornamento con una semplice funzione per eseguire ETL. Prima di tutto, vengono create due tabelle:

  • Tabella di origine: contiene una singola colonna tipizzata di stringa in cui vengono inseriti i dati.
  • Tabella di destinazione: contiene lo schema desiderato. I criteri di aggiornamento sono definiti in questa tabella.

  1. Creare la tabella di origine:

    .create table MySourceTable (OriginalRecord:string)

  2. Creare quindi la tabella di destinazione:

    .create table MyTargetTable (Timestamp:datetime, ThreadId:int, ProcessId:int, TimeSinceStartup:timespan, Message:string)

  3. Creare quindi una funzione per estrarre i dati:

    .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. Impostare ora i criteri di aggiornamento per richiamare la funzione creata:

    .alter table MyTargetTable policy update
@'[{ "IsEnabled": true, "Source": "MySourceTable", "Query": "ExtractMyLogs()", "IsTransactional": true, "PropagateIngestionProperties": false}]'

  5. Per svuotare la tabella di origine dopo l'inserimento dei dati nella tabella di destinazione, definire i criteri di conservazione nella tabella di origine in modo da avere 0 come .SoftDeletePeriod

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

Contenuto correlato