Inserimento da query (.set, .append, .set-or-append, .set-or-replace)

  • Articolo

Questi comandi eseguono una query o un comando di gestione e inseriscono i risultati della query in una tabella. La differenza tra questi comandi è il modo in cui trattano tabelle e dati esistenti o inesistente.

Comando Se la tabella esiste Se la tabella non esiste
.set Il comando non riesce La tabella viene creata e i dati vengono inseriti
.append I dati vengono aggiunti alla fine della tabella Il comando non riesce
.set-or-append I dati vengono aggiunti alla fine della tabella La tabella viene creata e i dati vengono inseriti
.set-or-replace I dati sostituiscono i dati nella tabella La tabella viene creata e i dati vengono inseriti

Per annullare un inserimento dal comando di query, vedere cancel operation.

Nota

Questo metodo di inserimento è destinato all'esplorazione e alla prototipazione. Non usarlo negli scenari di produzione o di volumi elevati.

Autorizzazioni

Per eseguire azioni diverse in una tabella, sono necessarie autorizzazioni specifiche:

  • Per aggiungere righe a una tabella esistente usando il .append comando, è necessario un minimo di autorizzazioni Table Ingestor.
  • Per creare una nuova tabella usando i vari .set comandi, sono necessarie almeno le autorizzazioni utente del database.
  • Per sostituire le righe in una tabella esistente usando il .set-or-replace comando, è necessario un minimo di autorizzazioni di Amministrazione tabella.

Per altre informazioni sulle autorizzazioni, vedere Controllo degli accessi in base al ruolo kusto.

Sintassi

(.set.append.set-or-append | .set-or-replace | | ) [async] tableName [with(propertyName=propertyValue [, ...])] <|queryOrCommand

Altre informazioni sulle convenzioni di sintassi.

Parametri

Nome Tipo Obbligatoria Descrizione
Async string Se specificato, il comando restituirà e continuerà l'inserimento in background. Usare il comando restituito con il comando per recuperare lo stato di completamento dell'inserimento OperationId.show operations e i risultati.
tableName string ✔️ Nome della tabella in cui inserire i dati. TableName è sempre correlato al database nel contesto.
propertyName, propertyValue string Una o più proprietà di inserimento supportate usate per controllare il processo di inserimento.
queryOrCommand string ✔️ Testo di una query o di un comando di gestione i cui risultati vengono usati come dati per inserire.

Nota

Sono supportati solo .show i comandi di gestione.

Proprietà di inserimento supportate

Proprietà Type Descrizione
creationTime string Valore datetime, formattato come stringa ISO8601, da usare come ora di creazione degli extent dei dati inseriti. Se non specificato, now() viene usato. Se specificato, assicurarsi che la Lookback proprietà nel criterio di unione Extents della tabella di destinazione sia allineata al valore specificato.
extend_schema bool Se true, il comando può estendere lo schema della tabella. Il valore predefinito è false. Questa opzione è valida solo per i comandi .append, .set-or-append e set-or-replace. Questa opzione richiede almeno autorizzazioni di Amministrazione tabella.
recreate_schema bool Se true, il comando può ricreare lo schema della tabella. Il valore predefinito è false. Questa opzione è valida solo per il comando .set-or-replace. Questa opzione ha la precedenza sulla extend_schema proprietà se entrambi sono impostati. Questa opzione richiede almeno autorizzazioni di Amministrazione tabella.
folder string Cartella da assegnare alla tabella. Se la tabella esiste già, questa proprietà sovrascrive la cartella della tabella.
ingestIfNotExists string Se specificato, l'inserimento ha esito negativo se la tabella ha già i dati contrassegnati con un ingest-by: tag con lo stesso valore. Per altre informazioni, vedere inserimento-by: tag.
policy_ingestiontime bool Se true, i criteri di inserimento verranno abilitati nella tabella. Il valore predefinito è true.
tags string Stringa JSON che rappresenta un elenco di tag da associare all'extent creato.
docstring string Descrizione usata per documentare la tabella.
distributed bool Se true, il comando inserisce da tutti i nodi che eseguono la query in parallelo. Il valore predefinito è false. Vedere Suggerimenti sulle prestazioni.
persistDetails Valore booleano che, se specificato, indica che il comando deve rendere persistenti i risultati dettagliati per il recupero dal comando dettagli operazione .show . Il valore predefinito è false. with (persistDetails=true)

Considerazioni sullo schema

  • .set-or-replace mantiene lo schema a meno che una delle proprietà di extend_schema inserimento o recreate_schema sia impostata su true.
  • .set-or-append e .append i comandi mantengono lo schema a meno che la extend_schema proprietà di inserimento non sia impostata su true.
  • La corrispondenza dello schema del set di risultati a quella della tabella di destinazione è basata sui tipi di colonna. Non viene cercata alcuna corrispondenza tra i nomi delle colonne. Assicurarsi che le colonne dello schema dei risultati della query si trovino nello stesso ordine della tabella, altri dati verranno inseriti nelle colonne sbagliate.

Attenzione

Se lo schema viene modificato, si verifica in una transazione separata prima dell'inserimento effettivo dei dati. Ciò significa che lo schema può essere modificato anche quando si verifica un errore di inserimento dei dati.

Suggerimenti per incrementare 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. Evitare di eseguire troppi comandi di inserimento contemporaneamente.
  • Limitare i dati per l'inserimento a meno di 1 GB per ogni operazione di inserimento. Se necessario, usare più comandi di inserimento.
  • Impostare il flag su true se la distributed quantità di dati generati dalla query è di grandi dimensioni, supera 1 GB e non richiede la serializzazione. Quindi, più nodi possono produrre output in parallelo. Non usare questo flag quando i risultati delle query sono piccoli, poiché potrebbe generare senza necessità molte partizioni di dati di piccole dimensioni.

Limitazione dei caratteri

Il comando avrà esito negativo se la query genera un nome di entità con il $ carattere. I nomi delle entità devono essere conformi alle regole di denominazione, pertanto il $ carattere deve essere rimosso per il comando di inserimento.

Ad esempio, nella query seguente l'operatore search genera una colonna $table. Per archiviare i risultati della query, usare project-rename per rinominare la colonna.

.set Texas <| search State has 'Texas' | project-rename tableName=$table

Esempio

Nel database creare una nuova tabella denominata RecentErrors che ha lo stesso schema di LogsTable e contiene tutti i record degli errori dell'ultima ora.

.set RecentErrors <|
   LogsTable
   | where Level == "Error" and Timestamp > now() - time(1h)

Nel database creare una nuova tabella denominata "OldExtents" che ha una sola colonna, "ExtentId", e contiene gli ID extent di tutti gli extent nel database creati più di 30 giorni prima. Il database contiene una tabella denominata "MyExtents". Poiché si prevede che il set di dati sia maggiore di 1 GB (più di circa 1 milione di righe) usare il flag distribuito

.set async OldExtents with(distributed=true) <|
   MyExtents 
   | where CreatedOn < now() - time(30d)
   | project ExtentId

Nel database corrente aggiungere dati a una tabella esistente denominata "OldExtents" che ha una sola colonna, "ExtentId", e contiene gli ID extent di tutti gli extent nel database creati più di 30 giorni prima. Contrassegnare il nuovo extent con i tag tagA e tagB, in base a una tabella esistente denominata "MyExtents".

.append OldExtents with(tags='["TagA","TagB"]') <| 
   MyExtents 
   | where CreatedOn < now() - time(30d) 
   | project ExtentId

Aggiungere i dati alla fine della tabella "OldExtents" nel database corrente oppure creare la tabella se non esiste già. Contrassegnare il nuovo extent con il tag ingest-by:myTag. Eseguire questa operazione solo se la tabella non contiene già un extent con il tag ingest-by:myTag, in base a una tabella esistente denominata "MyExtents".

.set-or-append async OldExtents with(tags='["ingest-by:myTag"]', ingestIfNotExists='["myTag"]') <|
   MyExtents
   | where CreatedOn < now() - time(30d)
   | project ExtentId

Sostituire i dati nella tabella "OldExtents" nel database corrente oppure creare la tabella se non esiste già. Contrassegnare il nuovo extent con il tag ingest-by:myTag.

.set-or-replace async OldExtents with(tags='["ingest-by:myTag"]', ingestIfNotExists='["myTag"]') <| 
   MyExtents 
   | where CreatedOn < now() - time(30d) 
   | project ExtentId

Aggiungere dati alla fine della tabella "OldExtents" nel database corrente, impostando l'ora di creazione degli extent creati su una data e ora specifiche nel passato.

.append async OldExtents with(creationTime='2017-02-13T11:09:36.7992775Z') <| 
   MyExtents 
   | where CreatedOn < now() - time(30d) 
   | project ExtentId

Restituire l'output

Restituisce informazioni sugli extent creati a causa del comando .set o .append.

Output di esempio

ExtentId OriginalSize ExtentSize CompressedSize IndexSize RowCount
23a05ed6-376d-4119-b1fc-6493bcb05563 1291 5882 1568 4314 10