共用方式為

.export to storage

  • 發行項

適用於： ✅Microsoft網狀架構✅Azure 數據總管

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

權限

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

語法

.export[] [asynccompressed] toOutputDataFormat( StorageConnectionString [, ...] )[with(PropertyName=PropertyValue [, ...] ] )<|查詢

深入瞭解 語法慣例。

參數

姓名 類型​​ 必要 描述
異步 string 如果指定，命令會以異步模式執行。 請參閱 異步模式。
壓縮 bool 如果指定，輸出記憶體成品會以 compressionType支援的屬性所指定的格式壓縮。
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 要使用的壓縮類型。 針對非 Parquet 檔案，只允許 gzip。 對於 Parquet 檔案，可能的值包括 gzip、snappy、lz4_raw、brotli和 zstd。 預設值為 gzip。
distribution string 散發提示 （single、 、 per_nodeper_shard 如果值等於 single，則單一線程會寫入記憶體。 否則，從所有平行執行查詢的節點匯出寫入。 請參閱 評估外掛程式運算元。 預設為 per_shard。
persistDetails bool 如果 true，命令會保存其結果（請參閱 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 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 ，以減少並行存取（請參閱命令屬性）。

  • 將用戶端要求屬性為所需的並行存取（節點百分比），以減少導出的節點數目並行。 屬性可以設定為匯出查詢的一部分。 例如，下列命令會將寫入記憶體的節點數目限制為 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

  • 使用每個分區匯出時，減少每個節點中導出線程數目的並行，方法是將用戶端要求屬性為所需的並行存取 （線程百分比）。 屬性可以設定為匯出查詢的一部分。 例如，下列命令會將寫入記憶體的線程數目限制為每個節點上的 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

相關內容