クラウド ストレージにデータをエクスポートする

適用対象: ✅Microsoft Fabric✅Azure データ エクスプローラー

クエリを実行し、最初の結果セットを外部クラウド ストレージに書き込みます。これは、ストレージ 接続文字列によって指定されます。

アクセス許可

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

構文

.export [async] [compressed] to OutputDataFormat ( StorageConnectionString [, ...] ) [with ( PropertyName = PropertyValue [, ...] )] <| クエリ

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

パラメーター

件名	タイプ	Required	説明
async	string		指定した場合、コマンドは非同期モードで実行されます。 「 asynchronous モードを参照してください。
compressed	string		指定した場合、出力ストレージ成果物は .gz ファイルとして圧縮されます。 Parquet ファイルをスナップ形式で圧縮する場合は、 compressionType supported プロパティ を参照してください。
OutputDataFormat	string	✔️	コマンドによって書き込まれたストレージ 成果物のデータ形式を示します。 サポートされている値: csv、tsv、json、parquet。
StorageConnectionString	string		データを書き込むストレージを示す 1 つ以上のストレージ 接続文字列。 スケーラブルな書き込みには、複数のストレージ 接続文字列を指定できます。 このような接続文字列のそれぞれは、ストレージへの書き込み時に使用する資格情報を示している必要があります。 たとえば Azure Blob Storage に書き込む場合、資格情報には、ストレージ アカウント キー、または BLOB の読み取り、書き込み、および一覧表示を行うアクセス許可を持つ共有アクセス キー (SAS) を指定できます。
PropertyName、 PropertyValue	string		キーと値のプロパティのペアのコンマ区切りのリスト。 サポートされるプロパティを参照してください。

Note

データベース自体と同じリージョンに併置されているストレージにデータをエクスポートすることを強くお勧めします。 これには、他のリージョンの別のクラウド サービスに転送するためにエクスポートされるデータが含まれます。 読み取りはリモートでも可能ですが、書き込みはローカルで行う必要があります。

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

プロパティ	タイプ	説明
includeHeaders	string	csv/tsv の出力の場合、列ヘッダーの生成を制御します。 none (既定値、ヘッダー行を出力しない)、all (すべてのストレージ成果物にヘッダー行を出力します)、または firstFile (最初のストレージ成果物にのみヘッダー行を出力する) のいずれかを指定できます。
fileExtension	string	ストレージ成果物の "拡張子" の部分 (たとえば、.csv や .tsv) を示します。 圧縮を使用する場合は、 .gz も追加されます。
namePrefix	string	生成された各ストレージ成果物名に追加するプレフィックスを示します。 ランダム プレフィックスは、指定されていない場合に使用されます。
encoding	string	テキストをエンコードする方法を示します: UTF8NoBOM (既定値) または UTF8BOM。
compressionType	string	使用する圧縮の種類を示します。 指定できる値は gzip または snappy です。 既定値は gzip です。 snappy は、(必要に応じて) parquet 形式に使用できます。
distribution	string	ディストリビューション ヒント (single、per_node、per_shard)。 値が single と等しい場合、1 つのスレッドがストレージに書き込みます。 それ以外の場合は、クエリを並列で実行しているすべてのノードから書き込みをエクスポートします。 「evaluate プラグイン演算子」を参照してください。 既定値は per_shard です。
persistDetails	bool	コマンドが結果を保持する必要があることを示します (async フラグを参照)。 非同期実行では既定値は true に設定されますが、呼び出し元が結果を必要としない場合は無効にできます。 同期実行では既定値は false に設定されますが、同期実行でも有効にできます。
sizeLimit	long	書き込まれている 1 つのストレージ成果物の、バイト単位でのサイズ制限 (圧縮前)。 有効な範囲: 100 MB (既定値) から 4 GB。
parquetRowGroupSize	int	データ形式が Parquet の場合にのみ関連します。 エクスポート*されたファイル*内の行*グループ*のサイズを制御します。 既定の行グループ サイズは 100,000 レコードです。
distributed	bool	分散エクスポート*を無効/有効にします。 false に設定*することは、single distribution ヒント*と同じことを意味します。 既定値は True です。
parquetDatetimePrecision	string	datetime値を Parquet にエクスポートするときに使用する精度を指定します。 指定できる値はミリ秒とマイクロ秒です。 既定値はミリ秒です。

認証と権限承認

認証方法は指定された接続文字列に基づいており、必要なアクセス許可は認証方法によって異なります。

次の表に、サポートされている認証方法と、ストレージの種類別に外部ストレージにデータをエクスポートするために必要なアクセス許可を示します。

認証方法	Azure Blob Storage / Data Lake Storage Gen2	Data Lake Storage Gen1
偽装	ストレージ Blob データ共同作成者	Contributor
Shared Access (SAS) トークン	書き込み	書き込み
Microsoft Entra アクセス トークン	追加のアクセス許可は必要ありません	追加のアクセス許可は必要ありません
ストレージ アカウント アクセス キー	追加のアクセス許可は必要ありません	追加のアクセス許可は必要ありません

返品

このコマンドは、生成されたストレージ成果物を記述するテーブルを返します。 各レコードは、1 つの成果物を記述し、成果物へのストレージ パスと保持するレコードの数を含みます。

Path	NumRecords
http://storage1.blob.core.windows.net/containerName/export_1_d08afcae2f044c1092b279412dcb571b.csv	10
http://storage1.blob.core.windows.net/containerName/export_2_454c0f1359e24795b6529da8a0101330.csv	15

非同期モード

async フラグが指定されている場合、コマンドは非同期モードで実行されます。 このモードでは、コマンドは操作 ID ですぐに返し、データのエクスポートは完了するまでバックグラウンドで続行されます。 コマンドによって返される操作 ID を使用すると、次のコマンドによって進行状況と、最後にはその結果を追跡できます:

• .show operations: 進捗状況の追跡。
• .show operation details: 完了結果の取得。

たとえば、正常に完了した後は、次を使用して結果を取得できます:

.show operation f008dc1e-2710-47d8-8d34-0d562f5f8615 details

例

この例では、Kusto はクエリを実行し、クエリによって生成された最初のレコードセットを、圧縮前に最大 1 GB の 1 つ以上の圧縮された CSV BLOB にエクスポートします。 列名ラベルは、各 BLOB の最初の行として追加されます。

.export
  async compressed
  to csv (
    h@"https://storage1.blob.core.windows.net/containerName;secretKey",
    h@"https://storage1.blob.core.windows.net/containerName2;secretKey"
  ) with (
    sizeLimit=1000000000,
    namePrefix="export",
    includeHeaders="all",
    encoding="UTF8NoBOM"
  )
  <| 
  Logs | where id == "1234" 

エクスポート コマンド中のエラー

エクスポート コマンドは、実行中に一時的に失敗する可能性があります。 連続エクスポートでは、コマンドが自動的に再試行されます。 通常のエクスポート コマンド (ストレージへのエクスポート、外部テーブルへのエクスポート) は再試行を実行しません。

• エクスポート コマンドが失敗した場合、ストレージに既に書き込まれた成果物は削除されません。 これらの成果物はストレージに残ります。 コマンドが失敗した場合は、一部の成果物が書き込まれた場合でも、エクスポートが不完全だと想定します。
• コマンドの完了と、正常完了時にエクスポートされた成果物の両方を追跡する最善の方法は、.show operations コマンドと .show operation details コマンドを使用する方法です。

ストレージの障害

既定では、エクスポート コマンドが配布され、ストレージへの同時書き込みの数が多い場合があります。 ディストリビューションのレベルは、エクスポート コマンドの種類によって異なります:

• 通常の .export コマンドの既定のディストリビューションは per_shard です。これは、書き込みをストレージに同時にエクスポートするデータを含むすべてのエクステントを意味します。

• export to external table コマンドの既定の分布はper_node。つまり、コンカレンシーはノードの数です。

エクステントやノードの数が多い場合、ストレージの負荷が高くなり、ストレージの調整や一時的なストレージ エラーが発生する可能性があります。 次の提案では、これらのエラーを (優先順位順に) 克服できます:

• エクスポート コマンドまたは外部テーブル定義に提供されるストレージ アカウントの数を増やします (負荷はアカウント間で均等に分散されます)。

• ディストリビューション ヒントを per_node に設定して、コンカレンシーを減らします (コマンドのプロパティを参照)。

• client 要求プロパティを query_fanout_nodes_percent目的のコンカレンシー (ノードの割合) に設定することで、エクスポートするノードの数のコンカレンシーを減らします。 プロパティは、エクスポート クエリの一部として設定できます。 たとえば、次のコマンドを実行すると、ストレージに同時に書き込むノードの数がノードの 50% に制限されます。

  .export async  to csv
      ( h@"https://storage1.blob.core.windows.net/containerName;secretKey" ) 
      with
      (
          distribution="per_node"
      ) 
      <| 
      set query_fanout_nodes_percent = 50;
      ExportQuery
  

• client 要求プロパティを query_fanout_threads_percent目的のコンカレンシー (スレッドの割合) に設定することで、シャードごとのエクスポートを使用する場合に、各ノードでエクスポートするスレッドの数のコンカレンシーを減らします。 プロパティは、エクスポート クエリの一部として設定できます。 たとえば、次のコマンドでは、ストレージに同時に書き込むスレッドの数を各ノードで 50% に制限します。

  .export async  to csv
      ( h@"https://storage1.blob.core.windows.net/containerName;secretKey" ) 
      with
      (
          distribution="per_shard"
      ) 
      <| 
      set query_fanout_threads_percent = 50;
      ExportQuery
  

• パーティション分割された外部テーブルにエクスポートする場合、spread/concurrency プロパティを設定するとコンカレンシーが減る可能性があります (コマンドのプロパティの詳細を参照)。

• 上記のどちらも機能しない場合は、 distributed プロパティを false に設定することで、ディストリビューションを完全に無効にすることができます。 ただし、コマンドのパフォーマンスに大きな影響を与える可能性があるため、これを行うことはお勧めしません。

認可エラー

ストレージ接続文字列で指定された資格情報に、ストレージへの書き込み許可が与えられていない場合、エクスポート コマンド中の認証または認可エラーが発生する可能性があります。 エクスポート コマンドに impersonate またはユーザー委任 SAS トークンを使用している場合、ストレージ アカウントに書き込むには、 Storage BLOB データ共同作成者 ロールが必要です。 詳細については、「ストレージの接続文字列」を参照してください。

データ型のマッピング

Parquet データ型のマッピング

エクスポート時に、Kusto データ型は次の規則を使用して Parquet データ型にマップされます:

Kusto データ型	Parquet データ型	Parquet 注釈	Comments
bool	BOOLEAN
datetime	INT64	TIMESTAMP_MICROS
dynamic	BYTE_ARRAY	UTF-8	JSON 文字列としてシリアル化されています
guid	BYTE_ARRAY	UTF-8
int	INT32
long	INT64
real	DOUBLE
string	BYTE_ARRAY	UTF-8
timespan	INT64		ティック (100 ナノ秒単位) の数として格納されます
decimal	FIXED_LENGTH_BYTE_ARRAY	DECIMAL