Esportare i dati nell'archiviazione cloud

Articolo
03/05/2024

Esegue una query e scrive il primo set di risultati in un archivio cloud esterno, specificato da un stringa di connessione di archiviazione.

Autorizzazioni

Per eseguire questo comando, è necessario disporre almeno delle autorizzazioni del Visualizzatore di database .

Sintassi

.export[] [compressedasync] toOutputDataFormat(StorageConnectionString [, ...] ) [with(PropertyName=PropertyValue [, ...] )] <|Query

Altre informazioni sulle convenzioni di sintassi.

Parametri

Nome	Tipo	Obbligatoria	Descrizione
`async`	`string`		Se specificato, il comando viene eseguito in modalità asincrona. Vedere la modalità asincrona.
`compressed`	`string`		Se specificato, gli artefatti di archiviazione di output vengono compressi come `.gz` file. Vedere la `compressionType`proprietà supportata per la compressione dei file Parquet come snappy.
OutputDataFormat	`string`	✔️	Indica il formato dei dati degli artefatti di archiviazione scritti dal comando . I valori supportati sono: `csv`, `tsv`, `json`e `parquet`.
StorageConnectionString	`string`		Una o più stringhe di connessione di archiviazione che indicano la risorsa di archiviazione in cui scrivere i dati. È possibile specificare più stringa di connessione di archiviazione per le scritture scalabili. Ogni stringa di connessione deve indicare le credenziali da usare durante la scrittura nell'archiviazione. Ad esempio, quando si scrive in Archiviazione BLOB di Azure, le credenziali possono essere la chiave dell'account di archiviazione o una chiave di accesso condiviso con le autorizzazioni per leggere, scrivere ed elencare i BLOB.
PropertyName, PropertyValue	`string`		Elenco delimitato da virgole di coppie di proprietà chiave-valore. Vedere le proprietà supportate.

Nota

È consigliabile esportare i dati in una risorsa di archiviazione condivisa nella stessa area del cluster stesso. Sono inclusi i dati esportati in modo che possano essere trasferiti a un altro servizio cloud in altre aree. Le operazioni di scrittura devono essere eseguite in locale, mentre le letture possono essere eseguite in remoto.

Proprietà supportate

Proprietà	Type	Descrizione
`includeHeaders`	`string`	Per `csv`/`tsv` l'output, controlla la generazione di intestazioni di colonna. Può essere uno di (impostazione predefinita; nessuna riga di intestazione generata), `all` (generare una riga di intestazione in ogni artefatto di archiviazione) o `firstFile` (generare una riga di `none` intestazione solo nel primo artefatto di archiviazione).
`fileExtension`	`string`	Indica la parte "estensione" dell'artefatto di archiviazione (ad esempio, `.csv` o `.tsv`). Se viene usata la compressione, `.gz` viene aggiunta anche .
`namePrefix`	`string`	Indica un prefisso da aggiungere a ogni nome dell'artefatto di archiviazione generato. Se non specificato, viene usato un prefisso casuale.
`encoding`	`string`	Indica come codificare il testo: `UTF8NoBOM` (impostazione predefinita) o `UTF8BOM`.
`compressionType`	`string`	Indica il tipo di compressione da utilizzare. I possibili valori sono `gzip` o `snappy`. Il valore predefinito è `gzip`. `snappy` può (facoltativamente) essere utilizzato per `parquet` il formato.
`distribution`	`string`	Hint di distribuzione (`single`, `per_node`, `per_shard`). Se il valore è uguale a `single`, un singolo thread scrive nella risorsa di archiviazione. In caso contrario, esportare le scritture da tutti i nodi che eseguono la query in parallelo. Vedere l'operatore evaluate plugin. Il valore predefinito è `per_shard`.
`persistDetails`	`bool`	Indica che il comando deve rendere persistenti i risultati (vedere `async` flag). L'impostazione predefinita è `true` in esecuzione asincrona, ma può essere disattivata se il chiamante non richiede i risultati. Il valore predefinito è `false` in esecuzioni sincrone, ma può essere attivato anche in tali esecuzioni.
`sizeLimit`	`long`	Limite di dimensioni in byte di un singolo artefatto di archiviazione scritto (prima della compressione). Intervallo valido: da 100 MB (impostazione predefinita) a 4 GB.
`parquetRowGroupSize`	`int`	Rilevante solo quando il formato dati è Parquet. Controlla le dimensioni del gruppo di righe nei file esportati. La dimensione predefinita del gruppo di righe è 100.000 record.
`distributed`	`bool`	Disabilitare/abilitare l'esportazione distribuita. L'impostazione su false equivale all'hint di `single` distribuzione. Il valore predefinito è true.
`parquetDatetimePrecision`	`string`	Specifica la precisione da utilizzare per l'esportazione di `datetime` valori in Parquet. I valori possibili sono millisecondi e microsecondi. Il valore predefinito è millisecondo.

Autenticazione e autorizzazione

Il metodo di autenticazione si basa sul stringa di connessione fornito e le autorizzazioni necessarie variano a seconda del metodo di autenticazione.

Nella tabella seguente sono elencati i metodi di autenticazione supportati e le autorizzazioni necessarie per l'esportazione dei dati nell'archiviazione esterna in base al tipo di archiviazione.

Metodo di autenticazione	Archiviazione BLOB di Azure/Data Lake Storage Gen2	Data Lake Storage Gen1
Rappresentazione	Collaboratore ai dati del BLOB di archiviazione	Autore di contributi
Token di accesso condiviso	Scrittura	Scrittura
token di accesso Microsoft Entra	Nessuna autorizzazione aggiuntiva necessaria	Nessuna autorizzazione aggiuntiva necessaria
Chiave di accesso dell'account di archiviazione	Nessuna autorizzazione aggiuntiva necessaria	Nessuna autorizzazione aggiuntiva necessaria

Restituisce

I comandi restituiscono una tabella che descrive gli artefatti di archiviazione generati. Ogni record descrive un singolo artefatto e include il percorso di archiviazione dell'artefatto e il numero di record che contiene.

Percorso	NumRecords
http://storage1.blob.core.windows.net/containerName/export_1_d08afcae2f044c1092b279412dcb571b.csv	10
http://storage1.blob.core.windows.net/containerName/export_2_454c0f1359e24795b6529da8a0101330.csv	15

Modalità asincrona

Se il async flag viene specificato, il comando viene eseguito in modalità asincrona. In questa modalità, il comando restituisce immediatamente con un ID operazione e l'esportazione dei dati continua in background fino al completamento. L'ID operazione restituito dal comando può essere usato per tenere traccia dello stato di avanzamento e infine i risultati tramite i comandi seguenti:

.show operations: tenere traccia dello stato di avanzamento.
.show operation details: ottiene i risultati di completamento.

Ad esempio, dopo il completamento, è possibile recuperare i risultati usando:

.show operation f008dc1e-2710-47d8-8d34-0d562f5f8615 details

Esempio

In questo esempio Kusto esegue la query e quindi esporta il primo recordset prodotto dalla query in uno o più BLOB CSV compressi, fino a 1 GB prima della compressione. Le etichette dei nomi di colonna vengono aggiunte come prima riga per ogni BLOB.

.export
  async compressed
  to csv (
    h@"https://storage1.blob.core.windows.net/containerName;secretKey",
    h@"https://storage1.blob.core.windows.net/containerName2;secretKey"
  ) with (
    sizeLimit=1000000000,
    namePrefix="export",
    includeHeaders="all",
    encoding="UTF8NoBOM"
  )
  <| 
  Logs | where id == "1234"

Errori durante i comandi di esportazione

I comandi di esportazione possono avere esito negativo temporaneo durante l'esecuzione. L'esportazione continua ritenta automaticamente il comando. I normali comandi di esportazione (esportazione nell'archiviazione, esportazione in tabella esterna) non eseguono tentativi.

Quando il comando di esportazione ha esito negativo, gli artefatti già scritti nella risorsa di archiviazione non vengono eliminati. Questi artefatti rimangono nello spazio di archiviazione. Se il comando ha esito negativo, si supponga che l'esportazione sia incompleta, anche se sono stati scritti alcuni artefatti.
Il modo migliore per tenere traccia sia del completamento del comando che degli artefatti esportati al completamento corretto consiste nell'usare i .show operations comandi e .show operation details .

Errori di archiviazione

Per impostazione predefinita, i comandi di esportazione vengono distribuiti in modo che ci siano molte scritture simultanee nella risorsa di archiviazione. Il livello di distribuzione dipende dal tipo di comando di esportazione:

La distribuzione predefinita per il comando normale .export è per_shard, ovvero tutti gli extent che contengono dati da esportare nella risorsa di archiviazione simultaneamente.
La distribuzione predefinita per l'esportazione nei comandi di tabella esterna è per_node, ovvero la concorrenza è il numero di nodi nel cluster.

Quando il numero di extent/nodi è elevato, ciò può causare un carico elevato nell'archiviazione che comporta la limitazione dell'archiviazione o errori di archiviazione temporanei. I suggerimenti seguenti possono superare questi errori (in base all'ordine di priorità):

Aumentare il numero di account di archiviazione forniti al comando di esportazione o alla definizione di tabella esterna (il carico verrà distribuito uniformemente tra gli account).
Ridurre la concorrenza impostando l'hint di distribuzione su per_node (vedere le proprietà del comando).
Ridurre la concorrenza del numero di nodi da esportare impostando la proprietà query_fanout_nodes_percentdella richiesta client sulla concorrenza desiderata (percentuale di nodi). La proprietà può essere impostata come parte della query di esportazione. Ad esempio, il comando seguente limita il numero di nodi che scrivono nella risorsa di archiviazione simultaneamente al 50% dei nodi del cluster:
```
.export async  to csv
    ( h@"https://storage1.blob.core.windows.net/containerName;secretKey" ) 
    with
    (
        distribution="per_node"
    ) 
    <| 
    set query_fanout_nodes_percent = 50;
    ExportQuery
```
Ridurre la concorrenza del numero di thread che esportano in ogni nodo quando si usa l'esportazione di partizioni impostando la proprietà query_fanout_threads_percentdella richiesta client sulla concorrenza desiderata (percentuale di thread). La proprietà può essere impostata come parte della query di esportazione. Ad esempio, il comando seguente limita il numero di thread scritti nella risorsa di archiviazione contemporaneamente al 50% in ognuno dei nodi del cluster:
```
.export async  to csv
    ( h@"https://storage1.blob.core.windows.net/containerName;secretKey" ) 
    with
    (
        distribution="per_shard"
    ) 
    <| 
    set query_fanout_threads_percent = 50;
    ExportQuery
```
Se si esegue l'esportazione in una tabella esterna partizionata, l'impostazione delle proprietà può ridurre la spread/concurrency concorrenza . Vedere i dettagli nelle proprietà del comando.
Se nessuna delle operazioni precedenti è possibile disabilitare completamente la distribuzione impostando la distributed proprietà su false. Tuttavia, non è consigliabile farlo, perché può influire in modo significativo sulle prestazioni del comando.

Errori di autorizzazione

Gli errori di autenticazione o autorizzazione durante i comandi di esportazione possono verificarsi quando le credenziali fornite nella stringa di connessione di archiviazione non sono autorizzate a scrivere nell'archiviazione. Se si usa impersonate o un token di firma di accesso condiviso delegato dall'utente per il comando di esportazione, è necessario il ruolo Collaboratore ai dati del BLOB di archiviazione per scrivere nell'account di archiviazione. Per altre informazioni, vedere Stringhe di connessione di archiviazione.

Mapping dei tipi di dati

Mapping dei tipi di dati Parquet

Durante l'esportazione, i tipi di dati Kusto vengono mappati ai tipi di dati Parquet usando le regole seguenti:

Tipo di dati Kusto	Tipo di dati Parquet	Annotazione Parquet	Commenti
`bool`	`BOOLEAN`
`datetime`	`INT64`	TIMESTAMP_MICROS
`dynamic`	`BYTE_ARRAY`	UTF-8	Serializzato come stringa JSON
`guid`	`BYTE_ARRAY`	UTF-8
`int`	`INT32`
`long`	`INT64`
`real`	`DOUBLE`
`string`	`BYTE_ARRAY`	UTF-8
`timespan`	`INT64`		Archiviato come tick (unità di 100 nanosecondi)
`decimal`	`FIXED_LENGTH_BYTE_ARRAY`	DECIMAL