Esportare i dati in una tabella esterna
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] 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. 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 esportano contemporaneamente. 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. 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__.
- 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
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 (o più, se
sizeLimitviene raggiunto). 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 sudistributedfalse. 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
sizeLimitviene raggiunto). Tutti i nodi partecipano ancora all'esportazione (operazione distribuita), ma ogni partizione viene assegnata a un nodo specifico. Se si impostadistributedsu 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.