Esportare i dati in una tabella esterna

È 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] to table externalTableName
[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à	Type	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 ha raggiunto il limite di dimensioni, verrà scritto un gruppo di righe parquetRowGroupSize completo e deve iniziare un nuovo artefatto. Intervallo valido: da 100 MB (impostazione predefinita) a 1 GB.
distributed	bool	Disabilitare/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 del cluster. 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 ha raggiunto 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 del cluster vengono esportati simultaneamente. Ogni nodo scrive i dati assegnati a tale nodo. Il numero di file esportati da un nodo sarà 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. Ciò significa che la concorrenza delle operazioni di scrittura è per 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. Ad esempio, se è presente una singola partizione molto più grande di altre, la maggior parte del lavoro di esportazione viene eseguita dal nodo singolo assegnato a tale partizione, mentre altri nodi saranno principalmente inattive. Vedere Impostazioni di distribuzione.	È possibile modificare diverse impostazioni: * Se è presente 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 verrà eseguita con per-node la distribuzione e ogni nodo esporterà 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 contemporaneamente () spreadsarà il valore minimo compreso tra 64 e il numero di nodi del cluster. 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	Tipo	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, come illustrato nell'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 partizioni datetime o nessuna partizione, il numero di file scritti (per ogni partizione, se esistente) deve essere simile al numero di nodi nel cluster (o più, se sizeLimit viene raggiunto). Quando l'operazione di esportazione viene distribuita, tutti i nodi del cluster 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 ridurrà 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. Se si imposta distributed su false, verrà eseguito solo un singolo nodo per l'esportazione, ma il comportamento rimarrà invariato (un singolo file scritto per partizione).

Esempi

Esempio di tabella esterna non partizionata

ExternalBlob è una tabella esterna non partizionata.

.export to table ExternalBlob <| T

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

Esempio di tabella esterna partizionata

PartitionedExternalBlob è una tabella esterna, definita come segue:

.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'
)

.export to table PartitionedExternalBlob <| T

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 async parola chiave ), l'output è disponibile usando il comando mostra dettagli operazione.