將數據匯出至外部數據表

適用於： ✅Microsoft網狀架構✅Azure 數據總管

您可以定義 外部數據表 並將數據匯出至數據，以匯出數據。 建立外部數據表時會指定資料表屬性。 匯出命令會依名稱參考外部數據表。

權限

您必須至少有 資料表管理員 許可權才能執行此命令。

語法

.export [async] to table externalTableName
[with (propertyName = propertyValue [, ...]] <| )查詢

深入瞭解 語法慣例。

參數

姓名	類型​​	必要	描述
externalTableName	string	✔️	要匯出之外部數據表的名稱。
propertyName、 propertyValue	string		選擇性 屬性的逗號分隔清單。
query	string	✔️	匯出查詢。

支援的屬性

匯出至外部資料表命令時，支援下列屬性。

屬性	類型​	描述	預設
sizeLimit	long	要寫入之單一記憶體成品的大小限制 ，以位元組為單位（在壓縮之前）。 在檢查此數據列群組是否已達到大小限制，而且應該啟動新的成品之前，會先寫入大小的完整數據列群組 parquetRowGroupSize 。 有效範圍：100 MB（預設值） 到 1 GB。
distributed	bool	停用/啟用分散式匯出。 將 設定為 false 相當於 single 散發提示。	預設值為 true。
distribution	string	散發提示 （single、 、 per_shardper_node 請參閱散發設定中的 更多詳細數據	預設值為 per_node。
distributionKind	string	當外部數據表依字串分割分割時，選擇性地切換為統一散發。 有效值為 uniform 或 default。 請參閱散發設定中的 更多詳細數據
concurrency	Number	提示系統要平行執行的分割區數目。 請參閱散發設定中的 更多詳細數據	預設值為 16。
spread	Number	提示系統如何在節點之間散發分割區。 請參閱散發設定中的 更多詳細數據	預設值是 Min(64, number-of-nodes)。
parquetRowGroupSize	int	只有在數據格式為 Parquet 時才相關。 控制匯出檔案中的數據列群組大小。 此值的優先順序高於 sizeLimit，這表示在檢查此數據列群組是否達到大小限制且應該啟動新的成品之前，將會匯出完整的數據列群組。	默認數據列群組大小為100,000筆記錄。

發佈設定

匯出至外部數據表作業的散發表示同時寫入記憶體的節點和線程數目。 預設散發取決於外部資料表分割：

外部數據表數據分割	默認散發
外部數據表未分割或僅依 datetime 數據行分割	匯出是分散式的 per_node - 所有節點都會同時匯出。 每個節點都會寫入指派給該節點的數據。 節點所導出的檔案數目將大於一個，只有當來自該節點的數據大小超過 sizeLimit時。
外部數據表是由字串數據行分割	要匯出的數據會在節點之間移動，讓每個節點寫入分割區值的子集。 單一分割區一律由單一節點寫入。 只有在數據超過 sizeLimit時，每個分割區寫入的檔案數目應該大於一個。 如果外部數據表包含數個字串分割，則數據會根據第一個數據分割在節點之間分割。 因此，建議將最統一分佈的分割區定義為第一個數據分割。

變更預設散發設定

在下列情況下，變更預設散發設定可能會很有用：

使用案例	描述	建議
減少導出的檔案數目	匯出會建立太多小型檔案，而且您想要建立較小的檔案數目。	在命令屬性中設定 distribution=single 或 distributed=false （兩者都相等）。 只有單一線程會執行匯出。 缺點是導出作業可能會變慢，因為並行處理會大幅降低。
減少匯出持續時間	增加導出作業的並行性，以減少其持續時間。	在命令屬性中設定 distribution=per_shard 。 這表示寫入作業的並行存取是每個數據分區，而不是每個節點。 只有在匯出至未依字串分割分割的外部數據表時，才會相關。 這可能會在記憶體上建立太多負載，可能會導致節流。 請參閱 記憶體失敗。
減少字串分割所分割之外部數據表的導出持續時間	如果分割區未在節點之間統一散發，導出可能需要較長的時間才能執行。 例如，如果單一分割區遠大於其他分割區，則大部分的匯出工作是由指派給該數據分割的單一節點完成，而其他節點則大部分會閑置。 請參閱 散發設定。	您可以變更數個設定： * 如果有一個以上的字串分割，請先定義具有最佳散發的字串分割。 * 在命令屬性中設定 distributionKind=uniform 。 此設定會停用字串分割外部數據表的預設散發設定。 匯出會以散發方式 per-node 執行，而且每個節點都會匯出指派給節點的數據。 單一分割區可能會由數個節點寫入，而且檔案數目會隨之增加。 若要進一步增加並行存取，請 distributionKind=uniform 設定為 distribution=per_shard 最高的並行存取 （代價是可能寫入更多檔案） * 如果數據匯出速度緩慢的原因不是極端值，請藉由增加並行存取來減少持續時間，而不需要變更數據分割設定。 使用 和 hint.spread hint.concurrency 屬性，判斷數據分割的並行性。 請參閱 數據分割運算元。 根據預設，同時導出的節點數目會 spread是介於 64 和節點數目之間的最小值。 將 設定 spread 為大於節點數目的數位，會增加每個節點上的並行性（最大值 spread 為 64）。

驗證與授權

若要匯出至外部資料表，您必須設定寫入許可權。 如需詳細資訊，請參閱 Azure 儲存體 外部數據表或 SQL Server 外部數據表的寫入許可權。

輸出

輸出參數	類型	描述
ExternalTableName	string	外部數據表的名稱。
路徑	string	輸出路徑。
NumRecords	string	匯出至路徑的記錄數目。

備註

• 匯出查詢輸出架構必須符合外部數據表的架構，包括數據分割所定義的所有數據行。 例如，如果數據表是由 DateTime 分割，則查詢輸出架構必須具有符合 TimestampColumnName 的 Timestamp 數據行。 這個數據行名稱是在外部數據表數據分割定義中定義的。

• 您無法使用 export 命令覆寫外部資料表屬性。 例如，您無法將 Parquet 格式的數據匯出至數據格式為 CSV 的外部資料表。

• 如果外部數據表已分割，導出的成品會根據分割區定義寫入其各自的目錄，如數據分割外部數據表範例所示。

  • 如果分割區值是 Null/空白，或是無效的目錄值，則根據目標記憶體的定義，分割區值會取代為 預設值 __DEFAULT_PARTITION__。

• 如需在匯出命令期間克服記憶體錯誤的建議，請參閱 匯出命令期間失敗。

• 根據數據類型對應規則，外部數據表數據行會對應至適當的目標格式數據類型。

• Parquet 原生匯出是效能較良好的資源輕導出機制。 Synapse SQL 'COPY' 目前不支持導出的 'datetime' 數據行。

檔案數目

每個分割區寫入的檔案數目取決於 匯出作業的散發設定 ：

• 如果外部數據表只包含datetime資料分割，或完全沒有分割區，則寫入的檔案數目（如果存在則為每個分割區，如果有的話）應該類似於節點數目（如果已達到，則 sizeLimit 為更多）。 當匯出作業散發時，所有節點都會同時導出。 若要停用散發，因此只有單一節點才會進行寫入，並將 設定 distributed 為 false。 此程式會建立較少的檔案，但會降低導出效能。

• 如果外部數據表依字串數據行包含分割區，導出的檔案數目應該是每個分割區的單一檔案（如果已達到，則 sizeLimit 為更多檔案）。 所有節點仍會參與匯出（作業已散發），但每個分割區都會指派給特定節點。 將 設定 distributed 為 false 只會造成單一節點執行匯出，但行為會維持不變（每個分割區寫入的單一檔案）。

範例

非分割外部數據表範例

ExternalBlob 是非分割的外部數據表。

.export to table ExternalBlob <| T

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

分割的外部數據表範例

PartitionedExternalBlob 是外部數據表，定義如下：

.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	路徑	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

如果命令是以異步方式執行（使用 async 關鍵詞），則會使用 顯示作業詳細 數據命令來取得輸出。