Panoramica dei criteri di aggiornamento

  • Articolo

I criteri di aggiornamento sono meccanismi di automazione attivati quando i nuovi dati vengono scritti 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 salvare i dati in più tabelle contemporaneamente. Le tabelle di destinazione possono avere uno schema diverso, criteri di conservazione e altri criteri 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 di analisi. Per altre informazioni, scenari comuni.

Il diagramma seguente illustra una visualizzazione generale di un criterio di aggiornamento. Vengono visualizzati due criteri di aggiornamento attivati quando i dati aggiunti alla seconda tabella di origine e generano l'aggiunta di dati trasformati alle due tabelle di destinazione.

Il diagramma mostra una panoramica dei criteri di aggiornamento.

Un criterio di aggiornamento è soggetto alle stesse restrizioni e alle procedure consigliate dell'inserimento regolare. I criteri vengono ridimensionati 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 di colonna, ai tipi e all'ordine.

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

Query sui criteri di aggiornamento

Se i criteri di aggiornamento vengono definiti nella tabella di destinazione, più query possono essere eseguite 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

Avviso

Una query errata può impedire l'inserimento dei 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 le funzioni archiviate arbitrarie che la query potrebbe fare riferimento vengono aggiornate. Pertanto, è fondamentale apportare modifiche con cautela per garantire che i criteri di aggiornamento rimangano intatti.

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

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

Oggetto criteri di aggiornamento

Una tabella può avere zero o più oggetti criteri di aggiornamento associati. Ogni oggetto viene rappresentato come un contenitore di proprietà JSON, con le proprietà seguenti definite.

Proprietà Type Descrizione
IsEnabled bool Stati se il criterio di aggiornamento è true - abilitato o false - disabilitato
Source string Nome della tabella che attiva la chiamata dei criteri di aggiornamento
Query string Query usata per produrre dati per l'aggiornamento
IsTransactional bool Indica se il criterio di aggiornamento è transazionale o meno, il valore predefinito è false. Se il criterio è transazionale e il criterio di aggiornamento ha 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 tempo di creazione, si applicano alla tabella di destinazione.
ManagedIdentity string Identità gestita per conto del quale viene eseguito il criterio 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 alle tabelle in altri database o tabelle con criteri di sicurezza a livello di riga abilitati. 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 perde 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 interrotta. I dati vengono inseriti una sola volta a 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 hanno effetto quando i dati vengono inseriti o spostati in una tabella di origine o gli extent vengono creati in una tabella di origine usando uno dei comandi seguenti:

Avviso

Quando il criterio di aggiornamento viene richiamato 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 viene richiamato il replace comando. In alternativa, considerare l'utilizzo di .set-or-append.

Rimuovere i dati dalla tabella di origine

Dopo aver inseriti dati nella tabella di destinazione, è possibile rimuoverli facoltativamente 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. Si applicano le condizioni seguenti:

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

Nota

Quando la tabella di origine ha un periodo di eliminazione temporanea (o 00:00:00), qualsiasi criterio di 0sec aggiornamento che fa riferimento a questa tabella deve essere transazionale.

Impatto sulle prestazioni

I criteri di aggiornamento possono influire sulle prestazioni del cluster e l'inserimento per gli extent di dati viene moltiplicato in base al numero di tabelle di destinazione. È importante ottimizzare la query correlata ai criteri. È possibile testare l'impatto delle prestazioni di un criterio di aggiornamento richiamando i criteri su extent già esistenti, prima di creare o modificare i criteri oppure 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

Errori

Con l'impostazione predefinita di IsTransactional:false, i dati possono comunque essere inseriti nella tabella di origine anche se i criteri non vengono eseguiti.

L'impostazione IsTransactional:true garantisce la coerenza tra i dati nella tabella di origine e di destinazione. Tuttavia, se le condizioni dei criteri hanno esito negativo, i dati non vengono inseriti nella tabella di origine. In alternativa, a seconda delle condizioni, a volte i dati vengono inseriti nella tabella di origine, ma non nella tabella di destinazione. Tuttavia, se il criterio è definito in modo non corretto o si verifica una mancata corrispondenza dello schema, i dati non vengono inseriti nella tabella di origine o di destinazione. Ad esempio, una mancata corrispondenza tra lo schema di output della query e la tabella di destinazione potrebbe essere causata dall'eliminazione di una colonna dalla tabella di destinazione.

È possibile visualizzare gli errori usando il .show ingestion failures comando .

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

Trattamento degli errori

Criteri non transazionali

Se impostato su IsTransactional:false, qualsiasi errore di esecuzione del criterio viene ignorato. L'inserimento non viene ritentato automaticamente. È possibile ripetere manualmente l'inserimento.

Criteri transazionali

Se impostato su IsTransactional:true, se il metodo di inserimento è pull, il servizio Gestione dati è coinvolto e l'inserimento viene eseguito automaticamente in base alle condizioni seguenti:

  • I tentativi vengono eseguiti fino a quando non viene soddisfatta una delle impostazioni di limite configurabili seguenti: DataImporterMaximumRetryPeriod o DataImporterMaximumRetryAttempts
  • Per impostazione predefinita, l'impostazione DataImporterMaximumRetryPeriod è due giorni e DataImporterMaximumRetryAttemptsè 10
  • Il periodo di backoff inizia a 2 minuti e raddoppia. Quindi l'attesa inizia con 2 minuti, quindi aumenta a 4 min, a 8 min, a 16 minuti e così via.

In qualsiasi altro caso, è possibile ripetere manualmente l'inserimento.

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 funzione semplice 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

Contenuti correlati