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

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

アクセス許可

このコマンドを実行するには、少なくとも データベース ビューアー のアクセス許可が必要です。

構文

.export [async] [compressed] toOutputDataFormat(StorageConnectionString [, ...] ) [with(PropertyName=PropertyValue [, ...] )] <|Query

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

パラメーター

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

注意

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

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

プロパティ	Type	説明
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)。 値が と等しい場合、 single1 つのスレッドがストレージに書き込みます。 それ以外の場合は、クエリを並列で実行しているすべてのノードから書き込みをエクスポートします。 「evaluate プラグイン演算子」を参照してください。 既定値は per_shard です。
persistDetails	bool	コマンドが結果を保持する必要があることを示します (async フラグを参照)。 非同期実行では既定値は true に設定されますが、呼び出し元が結果を必要としない場合は無効にできます。 同期実行では既定値は false に設定されますが、同期実行でも有効にできます。
sizeLimit	long	書き込まれている 1 つのストレージ成果物の、バイト単位でのサイズ制限 (圧縮前)。 有効な範囲: 100 MB (既定値) から 4 GB。
parquetRowGroupSize	int	データ形式が Parquet の場合にのみ関連します。 エクスポートされたファイルの行グループのサイズを制御します。 既定の行グループ サイズは 100,000 レコードです。
distributed	bool	分散エクスポートを無効/有効にします。 false に設定することは、single ディストリビューション ヒントと同じことを意味します。 既定値は true です。
parquetDatetimePrecision	string	値を Parquet にエクスポート datetime するときに使用する精度を指定します。 指定できる値はミリ秒とマイクロ秒です。 既定値はミリ秒です。

認証と承認

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

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

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

戻り値

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

パス	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 つ以上の圧縮された CSV BLOB (圧縮前に最大 1 GB) にエクスポートします。 列名ラベルは、各 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 です。これは、書き込みをストレージに同時にエクスポートするデータを含むすべてのエクステントを意味します。
• 外部テーブルへのエクスポート コマンドの既定のディストリビューションは per_node です。これは、コンカレンシーがクラスター内のノード数であることを意味します。

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

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

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

• クライアント要求プロパティ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
  

• クライアント要求プロパティ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 プロパティを設定するとコンカレンシーが減る可能性があります (コマンドのプロパティの詳細を参照)。

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

認可エラー

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

データ型のマッピング

Parquet データ型のマッピング

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

Kusto データ型	Parquet データ型	Parquet 注釈	コメント
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