次の方法で共有

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

  • [アーティクル]

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

アクセス許可

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

構文

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

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

パラメーター

件名 タイプ Required 説明
externalTableName string ✔️ エクスポート先の外部テーブルの名前。
propertyName, propertyValue string 省略可能な プロパティのコンマ区切りリスト。
クエリ string ✔️ エクスポート クエリ。

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

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

プロパティ タイプ 説明 Default
sizeLimit long 書き込まれている 1 つのストレージ成果物の、バイト単位でのサイズ制限 (圧縮前)。 この行グループがサイズ制限に達し、新しい成果物を開始する必要があるかどうかを確認する前に、サイズ parquetRowGroupSize の完全な行グループが書き込まれます。 有効な範囲: 100 MB (既定値) から 1 GB。
distributed bool 分散エクスポート*を無効/有効にします。 false に設定*することは、single distribution ヒント*と同じことを意味します。 既定値は true です。
distribution string ディストリビューション ヒント (single、per_node、per_shard)。 詳細については、 Distribution の設定を参照してください。 既定値は per_node です。
distributionKind string 必要に応じて、外部テーブルが文字列パーティションでパーティション分割されている場合に、均一分散に切り替えます。 有効な値は uniform または defaultです。 詳細については、 Distribution の設定を参照してください。
concurrency 番号 システムに対して並列実行するパーティションの数をヒントします。 詳細については、 Distribution の設定を参照してください。 既定値は 16 です。
spread 番号 クラスターノード間でパーティションを分散する方法をシステムに対してヒントします。 詳細については、 Distribution の設定を参照してください。 既定値は Min(64, number-of-nodes) です。
parquetRowGroupSize int データ形式が Parquet の場合にのみ関連します。 エクスポート*されたファイル*内の行*グループ*のサイズを制御します。 この値は sizeLimitよりも優先されます。つまり、この行グループがサイズ制限に達し、新しい成果物を開始する必要があるかどうかを確認する前に、完全な行グループがエクスポートされます。 既定の行グループ サイズは 100,000 レコードです。

配布の設定

外部テーブルへのエクスポート操作の分散は、ストレージに同時に書き込むノードとスレッドの数を示します。 既定のディストリビューションは、外部テーブルのパーティション分割によって異なります。

外部テーブルのパーティション分割 既定のディストリビューション
外部テーブルがパーティション分割されていないか、列によってのみパーティション分割datetime エクスポートは per_node 分散されます。クラスター内のすべてのノードが同時にエクスポートされます。 各ノードは、そのノードに割り当てられたデータを書き込みます。 ノードによってエクスポートされるファイルの数は、そのノードのデータのサイズが sizeLimitを超えた場合にのみ、1 つ以上になります。
外部テーブルが文字列列によってパーティション分割される 各ノードがパーティション値のサブセットを書き込むよう、エクスポートするデータがノード間で移動されます。 1 つのパーティションは、常に 1 つのノードによって書き込まれます。 パーティションごとに書き込まれるファイルの数は、データが sizeLimitを超える場合にのみ 1 つを超える必要があります。 外部テーブルに複数の文字列パーティションが含まれている場合、データは最初のパーティションに基づいてノード間でパーティション分割されます。 そのため、最も均一な分散を持つパーティションを最初のパーティションとして定義することをお勧めします。

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

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

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

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

* 低速エクスポートの原因がデータの外れ値でない場合は、パーティション設定を変更せずにコンカレンシーを増やすことで期間を短縮します。 パーティション分割のコンカレンシーを決定する 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 Path 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 Path 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 オペレーションの詳細コマンドを使用して利用可能です。