將數據匯出至雲端記憶體

發行項
07/04/2024

執行查詢，並將第一個結果集寫入至由記憶體連接字串指定的外部雲端記憶體。

權限

您必須至少有資料庫檢視器許可權才能執行此命令。

語法

.export[] [compressedasync] to OutputDataFormat ( StorageConnectionString [, ...] )[with ( PropertyName = PropertyValue [, ...] ] <| )查詢

深入瞭解語法慣例。

參數

姓名	類型	必要	描述
`async`	`string`		如果指定，命令會以異步模式執行。請參閱異步模式。
`compressed`	`string`		如果指定，輸出記憶體成品會壓縮為 `.gz` 檔案。 `compressionType` 請參閱將 Parquet 檔案壓縮為 snappy 的支持屬性。
OutputDataFormat	`string`	✔️	指出命令所寫入之記憶體成品的數據格式。支援的值為： `csv`、 `tsv`、 `json`、和 `parquet`。
StorageConnectionString	`string`		一或多個記憶體連接字串，指出要寫入數據的記憶體。可以針對可調整的寫入指定多個記憶體連接字串。每個這類連接字串都必須指出寫入記憶體時要使用的認證。例如，寫入至 Azure Blob 儲存體時，認證可以是記憶體帳戶密鑰，或具有讀取、寫入和列出 Blob 許可權的共用存取密鑰（SAS）。
PropertyName、 PropertyValue	`string`		索引鍵/值屬性組的逗號分隔清單。請參閱支持的屬性。

注意

強烈建議將數據匯出至與叢集本身位於相同區域中的記憶體。這包括導出的數據，以便傳輸至其他區域中的另一個雲端服務。寫入應該在本機完成，而讀取可能會從遠程進行。

支援的屬性

屬性	類型	描述
`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_shardper_node` 如果值等於 `single`，則單一線程會寫入記憶體。否則，從所有平行執行查詢的節點匯出寫入。請參閱評估外掛程式運算元。預設為 `per_shard`。
`persistDetails`	`bool`	表示命令應該保存其結果（請參閱 `async` 旗標）。默認為 `true` 在異步執行中，但如果呼叫端不需要結果，則可以關閉。在同步執行中預設為 `false` ，但也可以在這些執行中開啟。
`sizeLimit`	`long`	要寫入之單一記憶體成品的大小限制，以位元組為單位（在壓縮之前）。有效範圍：100 MB（預設值）到 4 GB。
`parquetRowGroupSize`	`int`	只有在數據格式為 Parquet 時才相關。控制匯出檔案中的數據列群組大小。默認數據列群組大小為100,000筆記錄。
`distributed`	`bool`	停用/啟用分散式匯出。將設定為 false 相當於 `single` 散發提示。預設為 true。
`parquetDatetimePrecision`	`string`	指定將值匯出 `datetime` 至 Parquet 時要使用的有效位數。可能的值為毫秒和微秒。預設值為毫秒。

驗證和授權

驗證方法是以所提供的連接字串為基礎，所需的許可權會根據驗證方法而有所不同。

下表列出支持的驗證方法，以及依記憶體類型將數據匯出至外部記憶體所需的許可權。

驗證方法	Azure Blob 儲存體 / Data Lake Storage Gen2	Data Lake Storage Gen1
模仿	儲存體 Blob 資料參與者	參與者
共用存取權（SAS）令牌	寫入	寫入
Microsoft Entra 存取令牌	不需要額外的許可權	不需要額外的許可權
儲存體帳戶存取金鑰	不需要額外的許可權	不需要額外的許可權

傳回

命令會傳回描述所產生記憶體成品的數據表。每個記錄都會描述單一成品，並包含成品的記憶體路徑及其保存的記錄數目。

路徑	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如果指定旗標，命令會以異步模式執行。在此模式中，命令會立即傳回作業標識符，且數據匯出會在背景繼續執行，直到完成為止。命令傳回的作業標識碼可用來追蹤其進度，最後透過下列命令來追蹤其結果：

.show operations：追蹤進度。
.show operation details：取得完成結果。

例如，成功完成之後，您可以使用下列項目來擷取結果：

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

範例

在此範例中，Kusto 會執行查詢，然後將查詢所產生的第一個記錄集匯出至一或多個壓縮的 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屬性可以減少並行性（請參閱命令屬性中的詳細數據。
如果上述兩項都無法運作，您可以將屬性設定 distributed 為 false，以完全停用散發。不過，我們不建議您這麼做，因為它可能會影響命令效能。

授權失敗

當記憶體中提供的認證連接字串不允許寫入記憶體時，可能會發生匯出命令期間的驗證或授權失敗。如果您使用 impersonate 或匯出命令的使用者委派 SAS 令牌，則需要記憶體 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

共用方式為