Condividi tramite

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

  • Articolo

Si applica a: ✅Microsoft Fabric✅Azure Esplora dati

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 gestiscono tabelle e dati esistenti o inesistenti.

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

L'inserimento dalla query è un inserimento diretto. Di conseguenza, non include tentativi automatici. I tentativi automatici sono disponibili durante l'inserimento tramite il servizio di gestione dei dati. Usare il documento di panoramica dell'inserimento per decidere quale è l'opzione di inserimento più adatta per lo scenario in uso.

Autorizzazioni

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

  • Per aggiungere righe a una tabella esistente usando il .append comando , sono necessarie almeno le 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 , sono necessarie almeno le autorizzazioni di amministratore tabella.

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

Sintassi

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

Altre informazioni sulle convenzioni di sintassi.

Parametri

Nome Digita Obbligatorio Descrizione
async string Se specificato, il comando restituisce immediatamente e continua l'inserimento in background. Usare l'oggetto restituito OperationId con il .show operations comando per recuperare lo stato di completamento dell'inserimento 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 l'inserimento. Sono supportati solo .show i comandi di gestione.

Suggerimenti per incrementare le prestazioni

  • Impostare la distributed proprietà su true se la quantità di dati prodotti dalla query è grande, supera 1 GB e non richiede la serializzazione. Quindi, più nodi possono 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.
  • L'inserimento dati è un'operazione a elevato utilizzo di risorse che potrebbe influire sulle attività simultanee nel database, incluse le query in esecuzione. Evitare di eseguire troppi comandi di inserimento contemporaneamente.
  • Limitare i dati per l'inserimento a meno di 1 GB per operazione di inserimento. Se necessario, usare più comandi di inserimento.

Proprietà di inserimento supportate

Proprietà Type Descrizione
distributed 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.
creationTime string Valore datetime, formattato come stringa ISO8601, da usare come ora di creazione degli extent dei dati inseriti. Se non specificato, now() viene utilizzato . Se specificato, assicurarsi che la proprietà Lookback nel criterio di unione degli extent effettivi 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 amministratore 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 amministratore 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 contiene già dati contrassegnati con un ingest-by: tag con lo stesso valore. Per altre informazioni, vedere Tag ingest-by.
policy_ingestiontime bool Se true, i criteri relativi all'ora 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 utilizzata per documentare la tabella.
persistDetails Valore booleano che, se specificato, indica che il comando deve rendere persistenti i risultati dettagliati per il recupero tramite il comando .show operation details . 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 non sia impostata su true.
  • .set-or-append i comandi e .append 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 siano nello stesso ordine della tabella, altrimenti i dati verranno inseriti nelle colonne errate.

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.

Limitazione dei caratteri

Il comando ha 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 affinché il comando di inserimento abbia esito positivo.

Nella query seguente, ad esempio, 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

Esempi

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)

Creare una nuova tabella denominata "OldExtents" nel database con una singola colonna, "ExtentId" e contiene gli ID extent di tutti gli extent nel database creati più di 30 giorni fa. 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 tabella "OldExtents" nel database corrente, impostando l'ora di creazione extent su un valore datetime specifico 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