外部テーブルへのデータのエクスポート

  • [アーティクル]

外部テーブルを定義し、データをエクスポートすることによって、データをエクスポートできます。 テーブルのプロパティは、 外部テーブルを作成するときに指定します。 エクスポート コマンドは、外部テーブルを名前で参照します。

アクセス許可

このコマンドを実行するには、少なくとも Table 管理 アクセス許可が必要です。

構文

.export [async] totableexternalTableName
[with(propertyName=propertyValue [, ...])] <|クエリ

構文規則について詳しく知る。

パラメーター

名前 型 必須 説明
externalTableName string ✔️ エクスポート先の外部テーブルの名前。
propertyName、 propertyValue string 省略可能な プロパティのコンマ区切りの一覧。
query string ✔️ エクスポート クエリ。

サポートされているプロパティ

外部テーブルへのエクスポート コマンドの一部として、次のプロパティがサポートされています。

プロパティ Type 説明 Default
sizeLimit long 書き込まれている 1 つのストレージ成果物の、バイト単位でのサイズ制限 (圧縮前)。 この行グループがサイズ parquetRowGroupSize 制限に達し、新しい成果物を開始する必要があるかどうかを確認する前に、サイズの完全な行グループが書き込まれます。 有効な範囲: 100 MB (既定値) から 1 GB。
distributed bool 分散エクスポートを無効/有効にします。 false に設定することは、single ディストリビューション ヒントと同じことを意味します。 既定値は true です。
distribution string ディストリビューション ヒント (single、per_node、per_shard)。 詳細については、「ディストリビューションの設定」を参照してください。 既定値は 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場合にのみ、1 つ以上になります。
外部テーブルは文字列列でパーティション分割されます エクスポートするデータは、各ノードがパーティション値のサブセットを書き込むよう、ノード間で移動されます。 1 つのパーティションは、常に 1 つのノードによって書き込まれます。 パーティションごとに書き込まれるファイルの数は、データが を超える場合にのみ 1 つを超える sizeLimit必要があります。 外部テーブルに複数の文字列パーティションが含まれている場合、データは最初のパーティションに基づいてノード間でパーティション分割されます。 そのため、最も均一な分散を持つパーティションを最初のパーティションとして定義することをお勧めします。

既定の配布設定を変更する

既定の配布設定を変更すると、次の場合に役立ちます。

ユース ケース 説明 推奨
エクスポートされたファイルの数を減らす エクスポートによって作成されるファイルの数が少なすぎるため、より小さなサイズのファイルを作成する必要があります。 コマンド プロパティで または distributed=false (両方とも同等です) を設定distribution=singleします。 エクスポートを実行するのは 1 つのスレッドだけです。 この欠点は、コンカレンシーが大幅に低下するため、エクスポート操作が遅くなる可能性があるということです。
エクスポート期間を短縮する エクスポート操作のコンカレンシーを増やして、その期間を短縮します。 コマンドのプロパティで を設定 distribution=per_shard します。 つまり、書き込み操作のコンカレンシーは、ノードごとではなく、データ シャードごとに行われます。 これは、文字列パーティションでパーティション分割されていない外部テーブルにエクスポートする場合にのみ関連します。 これによりストレージに負荷がかかりすぎるため、調整が発生する可能性があります。 「ストレージエラー」を参照してください。
文字列パーティションでパーティション分割された外部テーブルのエクスポート期間を短縮する パーティションがノード間で均等に分散されていない場合、エクスポートの実行に時間がかかる場合があります。 たとえば、他のパーティションよりもはるかに大きい 1 つのパーティションがある場合、エクスポート作業のほとんどは、そのパーティションに割り当てられた単一のノードによって実行されますが、他のノードはほとんどアイドル状態になります。 「ディストリビューションの設定」を参照してください。 変更できる設定がいくつかあります。
* 複数の文字列パーティションがある場合は、最初に最適な分布を持つパーティションを定義します。

* コマンドプロパティで設定 distributionKind=uniform します。 この設定により、文字列パーティション分割された外部テーブルの既定の分散設定が無効になります。 エクスポートはディストリビューションで per-node 実行され、各ノードはノードに割り当てられたデータをエクスポートします。 1 つのパーティションが複数のノードによって書き込まれる場合があり、それに応じてファイルの数が増えます。 コンカレンシーをさらに高めるために、 を とper_shard=distribution共に設定distributionKind=uniformして、最も高いコンカレンシーを実現します (書き込まれるファイルの数が多くなる可能性があります)

* 低速エクスポートの原因がデータの外れ値ではない場合は、パーティション分割の設定を変更せずにコンカレンシーを増やすことで期間を短縮します。 パーティション分割の hint.spread コンカレンシーを決定する プロパティと hint.concurrency プロパティを使用します。 パーティション演算子に関するページを参照してください。 既定では、同時にエクスポートするノードの数 () spreadは、64 からクラスター ノードの数までの最小値になります。 ノード数よりも大きい値に設定 spread すると、各ノードのコンカレンシーが増加します (の spread 最大値は 64)。

認証と承認

外部テーブルにエクスポートするには、書き込みアクセス許可を設定する必要があります。 詳細については、「Azure Storage 外部テーブルの書き込みアクセス許可」または「外部テーブルSQL Server」を参照してください。

出力

出力パラメーター 型 説明
ExternalTableName string 外部テーブルの名前。
Path string 出力パス。
NumRecords string パスにエクスポートされたレコード数。

メモ

  • エクスポート クエリの出力スキーマは、パーティションで定義されているすべての列を含め、外部テーブルのスキーマと一致する必要があります。 たとえば、テーブルが DateTime でパーティション分割されている場合、クエリ出力スキーマには、タイムスタンプ columnname と一致する Timestamp 列が必要です。 この列名は、外部テーブルのパーティション分割定義で定義されています。

  • エクスポート コマンドを使用して外部テーブルのプロパティを上書きすることはできません。 たとえば、Parquet 形式のデータを、データ形式が CSV である外部テーブルにエクスポートすることはできません。

  • 外部テーブルがパーティション分割されている場合、エクスポートされた成果物は、パーティション 外部テーブルの例に示されているように、パーティション定義に従ってそれぞれのディレクトリに書き込まれます。

    • パーティション値が null または空であるか、または無効なディレクトリ値の場合、ターゲットストレージの定義に従って、パーティション値は既定値の __DEFAULT_PARTITION__ に置き換えられます。

  • エクスポート コマンドの実行中にストレージ エラーを解決するための推奨事項については、「エクスポート コマンドのエラー」を参照してください。

  • 外部テーブルの列は、 データ型のマッピング 規則に従って、適切なターゲット形式のデータ型にマップされます。

  • Parquet ネイティブ エクスポートは、よりパフォーマンスが高く、リソースの軽いエクスポート メカニズムです。 エクスポートされた 'datetime' 列は現在、Synapse SQL 'COPY' ではサポートされていません。

ファイルの数

パーティションごとに書き込まれるファイルの数は、エクスポート操作の 配布設定 によって異なります。

  • 外部テーブルに datetime パーティションだけが含まれている場合、またはパーティションがまったく存在しない場合は、書き込まれたファイルの数 (パーティションが存在する場合) は、クラスター内のノードの数に似ている必要があります (または、sizeLimit に達した場合)。 エクスポート操作が分散されると、クラスター内のすべてのノードが同時にエクスポートされます。 単一のノードのみが書き込みを行うようにディストリビューションを無効にするには、distributed を false に設定します。 このプロセスでは、作成されるファイルは少なくなりますが、エクスポートのパフォーマンスは低下します。

  • 外部テーブルに文字列型の列によってパーティションが含まれている場合、エクスポートされるファイルの数は、パーティションごとに1つのファイルである必要があります (または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 キーワードを使用して) 非同期的に実行された場合、出力は、show オペレーションの詳細コマンドを使用して利用可能です。