Condividi tramite

Comando tabella .update

  • Articolo

Il .update table comando esegue gli aggiornamenti dei dati in una tabella specificata eliminando e accodando i record in modo atomico.

Avviso

Questo comando non è irreversibile.

Nota

Quando si esegue il .update table comando in una tabella che rappresenta l'origine di un criterio di aggiornamento, il .update table comando attiva questi criteri di aggiornamento per cui la tabella da modificare è l'origine dei criteri di aggiornamento.

È possibile eliminare fino a 5 milioni di record in un singolo comando.

Autorizzazioni

Per eseguire questo comando, è necessario disporre almeno delle autorizzazioni di amministratore tabella .

Sintassi

Nota

La sintassi semplificata , disponibile durante l'anteprima, è stata deprecata.

Altre informazioni sulle convenzioni di sintassi.

.update[async] table TableName delete DeleteIdentifier AppendIdentifier append [with ( propertyName = propertyValue ] )<|
letDeleteIdentifier= DeletePredicate;
letAppendIdentifier= AppendPredicate;

Parametri

Nome Digita Obbligatorio Descrizione
async string Se specificato, indica che il comando viene eseguito in modalità asincrona.
TableName string ✔️ Nome della tabella da aggiornare.
DeleteIdentifier string ✔️ Nome dell'identificatore utilizzato per specificare il predicato di eliminazione applicato alla tabella aggiornata.
DeletePredicate string ✔️ Testo di una query i cui risultati vengono usati come dati da eliminare. Il predicato presenta le stesse limitazioni del predicato di eliminazione temporanea.
AppendIdentifier string ✔️ Nome dell'identificatore utilizzato per specificare il predicato di accodamento applicato alla tabella aggiornata.
AppendPredicate string ✔️ Testo di una query i cui risultati vengono utilizzati come dati da accodare.

Importante

  • Sia i predicati di eliminazione che di accodamento non possono usare entità remote, cross-db ed entità tra cluster. I predicati non possono fare riferimento a una tabella esterna o usare l'operatore externaldata .
  • Le query di accodamento ed eliminazione dovrebbero produrre risultati deterministici. Le query non deterministiche possono causare risultati imprevisti. Una query è deterministica se e solo se restituisce gli stessi dati se eseguiti più volte.
  • Le query possono essere eseguite più volte all'interno dell'esecuzione update . Se i risultati intermedi della query sono incoerenti, il comando update può produrre risultati imprevisti.

Proprietà supportate

Nome Tipo Descrizione
whatif bool Se true, restituisce il numero di record che verranno accodati/eliminati in ogni partizione, senza accodare/eliminare record. Il valore predefinito è false.
distribuito bool Se true, il comando inserisce da tutti i nodi che eseguono la query in parallelo. Il valore predefinito è false. Vedere i suggerimenti sulle prestazioni.

Importante

È consigliabile eseguire in whatif modalità prima di eseguire l'aggiornamento per convalidare i predicati prima di eliminare o aggiungere dati.

Valori restituiti

Il risultato del comando è una tabella in cui ogni record rappresenta un extent creato con nuovi dati o record eliminati.

Nome Tipo Descrizione
Table string Tabella in cui è stato creato o eliminato l'extent.
Azione string Creare o eliminare a seconda dell'azione eseguita nell'extent.
ExtentId guid Identificatore univoco per l'extent creato o eliminato dal comando.
RowCount long Numero di righe create o eliminate nell'extent specificato dal comando.

Scegliere tra .update table e viste materializzate

Esistono scenari in cui è possibile usare il .update table comando o una vista materializzata per raggiungere lo stesso obiettivo in una tabella. Ad esempio, è possibile usare una vista materializzata per mantenere la versione più recente di ogni record o un aggiornamento per aggiornare i record quando è disponibile una nuova versione.

Usare le linee guida seguenti per decidere quale metodo usare:

  • Se il modello di aggiornamento non è supportato dalle viste materializzate, usare il comando update.
  • Se la tabella di origine ha un volume di inserimento elevato, ma solo pochi aggiornamenti, l'uso del comando di aggiornamento può essere più efficiente e utilizzare meno cache o archiviazione rispetto alle viste materializzate. Ciò è dovuto al fatto che le viste materializzate devono rielaborare tutti i dati inseriti, operazione meno efficiente rispetto all'identificazione dei singoli record da aggiornare in base ai predicati di accodamento o eliminazione.
  • Le viste materializzate sono una soluzione completamente gestita. La vista materializzata viene definita una volta e la materializzazione avviene in background dal sistema. Il comando di aggiornamento richiede un processo orchestrato ,ad esempio Azure Data Factory, App per la logica, Power Automate e altri, che esegue in modo esplicito il comando di aggiornamento ogni volta che sono presenti aggiornamenti. Se le viste materializzate funzionano abbastanza bene per il caso d'uso, l'uso di viste materializzate richiede meno gestione e manutenzione.

Suggerimenti per le prestazioni

  • L'inserimento dati è un'operazione a elevato utilizzo di risorse che potrebbe influire sulle attività simultanee nel cluster, inclusa l'esecuzione di query. È consigliabile evitare le azioni a elevato utilizzo di risorse seguenti: esecuzione di molti .update comandi contemporaneamente e uso intensivo della proprietà distribuita .
  • Limitare i dati di accodamento a meno di 1 GB per operazione. Se necessario, usare più comandi di aggiornamento.
  • Impostare il distributed flag su true solo se la quantità di dati prodotti dalla query è grande, supera 1 GB e non richiede la serializzazione: più nodi possono quindi produrre output in parallelo. Non usare questo flag quando i risultati della query sono di piccole dimensioni, perché potrebbe generare inutilmente molte piccole partizioni di dati.

Esempi

Per gli esempi si userà la tabella seguente:

.set-or-replace Employees <|
  range i from 1 to 100 step 1
  | project Id=i
  | extend Code = tostring(dynamic(["Customer", "Employee"])[Id %2])
  | extend Color = tostring(dynamic(["Red", "Blue", "Gray"])[Id %3])

Questo comando crea una tabella con 100 record a partire da:

ID Codice Color
1 Dipendente Blu
2 Customer Grigio
3 Dipendente Rosso
4 Customer Blu
5 Dipendente Grigio
6 Customer Rosso
6 Dipendente Blu

Aggiornare una singola colonna in una riga

Nell'esempio seguente viene aggiornata una singola colonna in una singola riga:

.update table Employees delete D append A with(whatif=true) <|
    let D = Employees
      | where Id==3;
    let A = Employees
      | where Id==3
      | extend Color="Orange";

Si noti che whatif è impostato su true. Dopo questa query, la tabella rimane invariata, ma il comando restituisce che esiste un extent con una riga eliminata e un nuovo extent con una riga.

Il comando seguente esegue effettivamente l'aggiornamento:

.update table Employees delete D append A <|
    let D = Employees
      | where Id==3;
    let A = Employees
      | where Id==3
      | extend Color="Orange";

Aggiornare una singola colonna in più righe

Nell'esempio seguente viene aggiornato in una singola colonna Color il valore di Verde in tali righe con il valore blu.

.update table Employees delete D append A <|
    let D = Employees
        | where Code=="Employee"
        | where Color=="Blue";
    let A = D
      | extend Color="Green";

In questo caso è stato riutilizzato l'identificatore di eliminazione nella definizione nel predicato di accodamento.

Aggiornare più colonne in più righe

Nell'esempio seguente vengono aggiornate più colonne in tutte le righe con colore grigio.

.update table Employees delete D append A <|
    let D = Employees
      | where Color=="Gray";
    let A = D
      | extend Code=strcat("ex-", Code)
      | extend Color="";

Aggiornare le righe usando un'altra tabella

In questo esempio, il primo passaggio consiste nel creare la tabella di mapping seguente:

.set-or-replace ColorMapping <|
  datatable(OldColor:string, NewColor:string)[
    "Red", "Pink",
    "Blue", "Purple",
    "Gray", "LightGray",
    "Orange", "Yellow",
    "Green", "AppleGreen"
  ]

Questa tabella di mapping viene quindi usata per aggiornare alcuni colori nella tabella originale:

.update table Employees delete D append A <|
  let D = Employees
    | where Code=="Customer";
  let A = D
    | lookup ColorMapping on $left.Color==$right.OldColor
    | project Id, Code, Color=NewColor

Aggiornare le righe con una tabella di staging

Un modello comune consiste nel trasferire i dati in una tabella di staging prima di aggiornare la tabella principale.

Il primo comando crea una tabella di staging:

.set-or-replace MyStagingTable <|
    range i from 70 to 130 step 5
    | project Id=i
    | extend Code = tostring(dynamic(["Customer", "Employee"])[Id %2])
    | extend Color = tostring(dynamic(["Red", "Blue", "Gray"])[Id %3])

Il comando successivo aggiorna la tabella principale con i dati nella tabella di staging:

.update table Employees delete D append A <|
    let A = MyStagingTable;
    let D = Employees
        | join kind=leftsemi MyStagingTable on Id
        | where true;

Alcuni record nella tabella di staging non esistevano nella tabella principale (ovvero, avevano Id>100) ma sono stati ancora inseriti nella tabella principale (comportamento upsert).

Chiave composta

Il primo comando crea una tabella con chiavi composte:

.set-or-replace VersionedArticle <|
  datatable(ArticleId:string, Version:int, Detail:string)[
    "A", 1, "Early version",
    "B", 1, "News about mobiles",
    "C", 1, "Opinion article",
    "B", 2, "Revision about brand X",
    "B", 3, "Revision about brand Y",
    "C", 2, "Fact check"
  ]

Il comando successivo aggiorna un record specifico usando la sintassi espansa:

.update table VersionedArticle delete D append A <|
  let D = VersionedArticle
    | where ArticleId=="B"
    | where Version==3;
  let A = VersionedArticle
    | where ArticleId=="B"
    | where Version==3
    | extend Detail = "Revision about brand Z";

Contenuto correlato