Condividi tramite

Esportare i dati in una tabella esterna

  • Articolo

Si applica a: ✅Microsoft Fabric✅Azure Esplora dati

È possibile esportare i dati definendo una tabella esterna ed esportando i dati. Le proprietà della tabella vengono specificate durante la creazione della tabella esterna. Il comando di esportazione fa riferimento alla tabella esterna in base al nome.

Autorizzazioni

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

Sintassi

.export [async] totableexternalTableName
[with(propertyName=propertyValue [, ...]] )<|quesito

Altre informazioni sulle convenzioni di sintassi.

Parametri

Nome Digita Obbligatorio Descrizione
externalTableName string ✔️ Nome della tabella esterna in cui esportare.
propertyName, propertyValue string Elenco delimitato da virgole di proprietà facoltative.
query string ✔️ Query di esportazione.

Proprietà supportate

Le proprietà seguenti sono supportate come parte del comando esporta in una tabella esterna.

Proprietà Digita Descrizione Default
sizeLimit long Limite di dimensioni in byte di un singolo artefatto di archiviazione scritto prima della compressione. Prima di verificare se questo gruppo di righe raggiunge il limite di dimensioni e deve avviare un nuovo artefatto, viene scritto un gruppo di righe completo di dimensioni parquetRowGroupSize. Intervallo valido: da 100 MB (impostazione predefinita) a 1 GB.
distributed bool Disabilitare o abilitare l'esportazione distribuita. L'impostazione su false equivale all'hint di single distribuzione. Il valore predefinito è true.
distribution string Hint di distribuzione (single, per_node, per_shard). Per altri dettagli, vedere Impostazioni di distribuzione Il valore predefinito è per_node.
distributionKind string Facoltativamente, passa alla distribuzione uniforme quando la tabella esterna viene partizionata per partizione di stringa. I valori validi sono uniform o default. Per altri dettagli, vedere Impostazioni di distribuzione
concurrency Numero Suggerisce al sistema il numero di partizioni da eseguire in parallelo. Per altri dettagli, vedere Impostazioni di distribuzione Il valore predefinito è 16.
spread Numero Suggerisce al sistema come distribuire le partizioni tra i nodi. Per altri dettagli, vedere Impostazioni di distribuzione Il valore predefinito è Min(64, number-of-nodes).
parquetRowGroupSize int Rilevante solo quando il formato dati è Parquet. Controlla le dimensioni del gruppo di righe nei file esportati. Questo valore ha la precedenza su sizeLimit, ovvero un gruppo di righe completo verrà esportato prima di verificare se questo gruppo di righe raggiunge il limite di dimensioni e deve avviare un nuovo artefatto. La dimensione predefinita del gruppo di righe è 100.000 record.

Impostazioni distribuzione

La distribuzione di un'esportazione in un'operazione di tabella esterna indica il numero di nodi e thread che scrivono nello spazio di archiviazione contemporaneamente. La distribuzione predefinita dipende dal partizionamento delle tabelle esterne:

Partizionamento di tabelle esterne Distribuzione predefinita
La tabella esterna non è partizionata o partizionata solo per datetime colonna L'esportazione è distribuita per_node : tutti i nodi esportano contemporaneamente. Ogni nodo scrive i dati assegnati a tale nodo. Il numero di file esportati da un nodo è maggiore di uno, solo se le dimensioni dei dati di tale nodo superano sizeLimit.
La tabella esterna è partizionata da una colonna stringa I dati da esportare vengono spostati tra i nodi, in modo che ogni nodo scriva un subset dei valori della partizione. Una singola partizione viene sempre scritta da un singolo nodo. Il numero di file scritti per partizione deve essere maggiore di uno solo se i dati superano sizeLimit. Se la tabella esterna include diverse partizioni di stringa, i dati vengono partizionati tra il nodo in base alla prima partizione. Pertanto, è consigliabile definire la partizione con la distribuzione più uniforme come prima.

Modificare le impostazioni di distribuzione predefinite

La modifica delle impostazioni di distribuzione predefinite può essere utile nei casi seguenti:

Caso d'uso Descrizione Elemento consigliato
Ridurre il numero di file esportati L'esportazione crea troppi file di piccole dimensioni e si vuole creare un numero inferiore di file più grandi. Impostare distribution=single o distributed=false (entrambi sono equivalenti) nelle proprietà del comando. Solo un singolo thread esegue l'esportazione. Lo svantaggio è che l'operazione di esportazione può essere più lenta, poiché la concorrenza è notevolmente ridotta.
Ridurre la durata dell'esportazione Aumento della concorrenza dell'operazione di esportazione per ridurne la durata. Impostare distribution=per_shard nelle proprietà del comando. In questo modo si intende la concorrenza delle operazioni di scrittura per ogni partizione di dati, anziché per nodo. Questo è rilevante solo quando si esporta in una tabella esterna che non è partizionata per partizione di stringa. Questo potrebbe creare un carico eccessivo nell'archiviazione, causando potenzialmente una limitazione. Vedere Errori di archiviazione.
Ridurre la durata di esportazione per le tabelle esterne partizionate da una partizione di stringa Se le partizioni non vengono distribuite in modo uniforme tra i nodi, l'esportazione potrebbe richiedere più tempo per l'esecuzione. Se una partizione è molto più grande delle altre, il nodo assegnato a tale partizione esegue la maggior parte del lavoro di esportazione, mentre gli altri nodi rimangono per lo più inattive. Per altre informazioni, vedere impostazioni di distribuzione . È possibile modificare diverse impostazioni:
* Se sono presenti più di una partizione di stringa, definire prima di tutto quella con la distribuzione migliore.

* Impostare distributionKind=uniform nelle proprietà del comando. Questa impostazione disabilita le impostazioni di distribuzione predefinite per le tabelle esterne partizionate da stringhe. L'esportazione viene eseguita con per-node distribuzione e ogni nodo esporta i dati assegnati al nodo. Una singola partizione può essere scritta da diversi nodi e il numero di file aumenta di conseguenza. Per aumentare ulteriormente la concorrenza, impostare distributionKind=uniform insieme distribution=per_shard a per ottenere la concorrenza più elevata (a costo di molti altri file scritti)

* Se la causa dell'esportazione lenta non è outlier nei dati, ridurre la durata aumentando la concorrenza, senza modificare le impostazioni di partizionamento. Usare le hint.spread proprietà e hint.concurrency che determinano la concorrenza del partizionamento. Vedere Operatore di partizione. Per impostazione predefinita, il numero di nodi che esportano simultaneamente (il spread) è il valore minimo compreso tra 64 e il numero di nodi. L'impostazione su spread un numero maggiore rispetto al numero di nodi aumenta la concorrenza in ogni nodo (il valore massimo per spread è 64).

Autenticazione e autorizzazione

Per esportare in una tabella esterna, è necessario configurare le autorizzazioni di scrittura. Per altre informazioni, vedere Autorizzazioni di scrittura per Archiviazione di Azure tabella esterna o tabella esterna di SQL Server.

Output

Parametro di output Digita Descrizione
ExternalTableName string Nome della tabella esterna.
Percorso string Percorso di output.
NumRecords string Numero di record esportati nel percorso.

Note

  • Lo schema di output della query di esportazione deve corrispondere allo schema della tabella esterna, incluse tutte le colonne definite dalle partizioni. Ad esempio, se la tabella è partizionata da DateTime, lo schema di output della query deve avere una colonna Timestamp corrispondente a TimestampColumnName. Questo nome di colonna è definito nella definizione di partizionamento della tabella esterna.

  • Non è possibile eseguire l'override delle proprietà della tabella esterna usando il comando di esportazione. Ad esempio, non è possibile esportare i dati in formato Parquet in una tabella esterna il cui formato di dati è CSV.

  • Se la tabella esterna è partizionata, gli artefatti esportati vengono scritti nelle rispettive directory in base alle definizioni di partizione. Per un esempio, vedere esempio di tabella esterna partizionata.

    • Se un valore di partizione è null/empty o è un valore di directory non valido, in base alle definizioni dell'archiviazione di destinazione, il valore della partizione viene sostituito con un valore predefinito di __DEFAULT_PARTITION__.

  • Per suggerimenti per risolvere gli errori di archiviazione durante i comandi di esportazione, vedere Errori durante i comandi di esportazione.

  • Le colonne della tabella esterna vengono mappate ai tipi di dati di formato di destinazione appropriati, in base alle regole di mapping dei tipi di dati.

  • L'esportazione nativa Parquet è un meccanismo di esportazione della luce delle risorse più efficiente. Una colonna datetime esportata non è attualmente supportata da Synapse SQL COPY.

Numero di file

Il numero di file scritti per partizione dipende dalle impostazioni di distribuzione dell'operazione di esportazione:

  • Se la tabella esterna include solo datetime partizioni o nessuna partizione, il numero di file scritti per ogni partizione esistente dovrebbe essere simile al numero di nodi (o più, se viene raggiunto sizeLimit). Quando l'operazione di esportazione viene distribuita, tutti i nodi esportano simultaneamente. Per disabilitare la distribuzione, in modo che solo un singolo nodo ese segue le scritture, impostare su distributed false. Questo processo crea meno file, ma riduce le prestazioni di esportazione.

  • Se la tabella esterna include una partizione in base a una colonna stringa, il numero di file esportati deve essere un singolo file per partizione (o più, se sizeLimit viene raggiunto). Tutti i nodi partecipano ancora all'esportazione (operazione distribuita), ma ogni partizione viene assegnata a un nodo specifico. L'impostazione di distributed su false determina solo l'esportazione di un singolo nodo, ma il comportamento rimane invariato (un singolo file scritto per partizione).

Esempi

Esempio di tabella esterna non partizionata

Nell'esempio seguente i dati della tabella T nella tabella ExternalBlob. ExternalBlob è una tabella esterna non partizionata.

.export to table ExternalBlob <| T

output

ExternalTableName Percorso NumRecords
ExternalBlob http://storage1.blob.core.windows.net/externaltable1cont1/1_58017c550b384c0db0fea61a8661333e.csv 10

Esempio di tabella esterna partizionata

Nell'esempio seguente viene prima creata una tabella esterna partizionata, PartitionedExternalBlob con un percorso di archiviazione BLOB specificato. I dati vengono archiviati in formato CSV con un formato di percorso che organizza i dati in base al nome e alla data del cliente.

.create external table PartitionedExternalBlob (Timestamp:datetime, CustomerName:string) 
kind=blob
partition by (CustomerName:string=CustomerName, Date:datetime=startofday(Timestamp))   
pathformat = ("CustomerName=" CustomerName "/" datetime_pattern("yyyy/MM/dd", Date))   
dataformat=csv
( 
   h@'http://storageaccount.blob.core.windows.net/container1;secretKey'
)

Esporta quindi i dati dalla tabella T alla tabella esterna PartitionedExternalBlob.

.export to table PartitionedExternalBlob <| T

output

ExternalTableName Percorso NumRecords
ExternalBlob http://storageaccount.blob.core.windows.net/container1/CustomerName=customer1/2019/01/01/fa36f35c-c064-414d-b8e2-e75cf157ec35_1_58017c550b384c0db0fea61a8661333e.csv 10
ExternalBlob http://storageaccount.blob.core.windows.net/container1/CustomerName=customer2/2019/01/01/fa36f35c-c064-414d-b8e2-e75cf157ec35_2_b785beec2c004d93b7cd531208424dc9.csv 10

Se il comando viene eseguito in modo asincrono usando la parola chiave async, l'output è disponibile usando il visualizzare i dettagli dell'operazione comando.

Contenuto correlato