.export to storage

使用 “版本 ”下拉列表切换服务。了解有关导航的详细信息。
适用于：✅ Azure Data Explorer

执行查询并将第一个结果集写入外部云storage，由 storage connection string 指定。

权限

必须至少具有 Database Viewer 权限才能运行此命令。

语法

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

详细了解语法约定。

参数

客户	类型	必需	说明
异步	`string`		如果指定此参数，命令将以异步模式运行。请参阅异步模式。
压缩的	`bool`		如果指定，则输出storage artifacts采用由 `compressionType`supported 属性指定的格式进行压缩。
OutputDataFormat	`string`	✔️	命令编写的storage artifacts的数据格式。支持的值为 `csv`、`tsv`、`json` 和 `parquet`。
StorageConnectionString	`string`		一个或多个storage连接字符串指定要向其写入数据的storage。可以为可缩放写入指定多个storage connection string。每个此类connection string都必须指定要在写入storage时使用的凭据。例如，写入Azure Blob Storage时，凭据可以是storage帐户密钥，也可以是具有读取、写入和列出 blob 的权限的共享access密钥（SAS）。使用 DFS 终结点将数据导出到 CSV 文件时，数据将通过 DFS 托管专用终结点。将数据导出到 parquet 文件时，数据将通过 Blob 托管专用终结点。
PropertyName、PropertyValue	`string`		键值属性对的逗号分隔列表。请参阅支持的属性。

注意

强烈建议将数据导出到与数据库本身并置在同一区域中的storage。其中包括已导出的数据，这样，这些数据便可以传输到其他区域中的其他云服务。写入应在本地执行，而读取则可以远程进行。

支持的属性

属性	类型	说明
`includeHeaders`	`string`	对于 `csv`/`tsv` 输出，此属性控制列标题的生成。可以是 `none`（默认值;未发出标头行）、`all`（将标头行发出到每个storage项目），或`firstFile`（仅向第一个storage项目发出标头行）。
`fileExtension`	`string`	storage项目的“扩展”部分（例如，`.csv` 或 `.tsv`）。如果使用压缩，则还将追加 `.gz`。
`namePrefix`	`string`	要添加到每个生成的storage项目名称的前缀。如果未指定此项，将使用随机前缀。
`encoding`	`string`	文本的编码。可能的值包括：`UTF8NoBOM`（默认值）或 `UTF8BOM`。
`compressionType`	`string`	要使用的压缩类型。对于非 Parquet 文件，仅允许 `gzip`。对于 Parquet 文件，可能的值包括 `gzip`、`snappy`、`lz4_raw`、`brotli`和 `zstd`。默认值为 `gzip`。
`distribution`	`string`	分布提示（`single`、`per_node`、`per_shard`）。如果值等于 `single`，则单个线程写入storage。否则，导出会以并行方式从执行查询的所有节点进行写入。请参阅 evaluate 插件运算符。默认为 `per_shard`。
`persistDetails`	`bool`	如果 `true`，该命令将保留其结果（请参阅 `async` 标志）。在异步运行中默认为 `true`，但如果调用方不需要结果，则可将其关闭。在同步执行中默认为 `false`，但可以开启。
`sizeLimit`	`long`	压缩之前写入的单个storage项目的大小限制（以字节为单位）。有效范围：100 MB（默认）到 4 GB。
`parquetRowGroupSize`	`int`	只有数据格式为 Parquet 时才相关。控制已导出文件中的行组大小。默认的行组大小为 100,000 条记录。
`distributed`	`bool`	禁用或启用分布式导出。设置为 false 等效于 `single` 分布提示。默认值为 true。
`parquetDatetimePrecision`	`string`	将 `datetime` 值导出到 Parquet 时要使用的精度。可能的值为毫秒和微秒。默认值为毫秒。

身份验证和授权

身份验证方法基于提供的connection string，所需的权限因身份验证方法而异。

下表列出了支持的身份验证方法和storage类型将数据导出到外部storage所需的权限。

身份验证方法	Azure Blob Storage/Data Lake Storage Gen2	Data Lake Storage Gen1
Impersonation	Storage Blob 数据参与者	参与者
Managed Identity	Storage Blob 数据参与者	参与者
共享Access令牌	写入	写入
Microsoft Entra access token	不需要额外的权限	不需要额外的权限
Storage帐户access密钥	不需要额外的权限	不需要额外的权限

这些命令返回描述生成的storage artifacts的表。每个记录描述单个项目，并包括项目的storage路径及其保存的记录数。

路径	NumRecords
http://storage1.blob.core.chinacloudapi.cn/containerName/export_1_d08afcae2f044c1092b279412dcb571b.csv	10
http://storage1.blob.core.chinacloudapi.cn/containerName/export_2_454c0f1359e24795b6529da8a0101330.csv	15

异步模式

如果指定了 async 标志，则命令将以异步模式执行。在此模式下，命令会立即返回一个操作 ID，而数据导出则在后台继续进行，直到完成。可以使用此命令返回的操作 ID 通过以下命令跟踪其进度并最终跟踪其结果：

.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.chinacloudapi.cn/containerName;secretKey",
    h@"https://storage1.blob.core.chinacloudapi.cn/containerName2;secretKey"
  ) with (
    sizeLimit=1000000000,
    namePrefix="export",
    includeHeaders="all",
    encoding="UTF8NoBOM"
  )
  <| 
  Logs | where id == "1234"

执行 export 命令期间发生故障

export 命令在执行期间可能会暂时失败。连续导出会自动重试命令。常规导出命令（export 到 storage，export 到外部表）不执行任何重试。

导出命令失败时，不会删除已写入storage artifacts。这些artifacts保留在storage中。如果命令失败，则假定导出不完整，即使写入了某些artifacts也是如此。
跟踪命令的完成和成功完成时导出的artifacts的最佳方式是使用 .show operations 和 .show operation details 命令。

Storage失败

默认情况下，导出命令是分布式的，因此可能会有许多并发写入storage。分配级别取决于 export 命令的类型：

常规 .export 命令的默认分布为 per_shard，这意味着包含要同时导出到storage的数据的所有 extents。
导出到外部表命令的默认分布是 per_node，这意味着并发度是节点数。

当盘区/节点数较大时，这可能会导致storage负载过高，导致storage限制或暂时性storage错误。以下建议可能会解决这些错误（按优先级顺序）：

将提供给导出命令或 external 表定义的storage帐户数增加。负载会在帐户之间均匀分配。
通过将分配提示设置为 per_node 来降低并发度（请参阅命令属性）。
通过将客户端请求属性query_fanout_nodes_percent 设置为所需的并发度（节点百分比）来降低进行导出的节点的并发度。可以在导出查询中设置此属性。例如，以下命令将写入到storage的节点数限制为 50 个节点%：
```
.export async  to csv
    ( h@"https://storage1.blob.core.chinacloudapi.cn/containerName;secretKey" ) 
    with
    (
        distribution="per_node"
    ) 
    <| 
    set query_fanout_nodes_percent = 50;
    ExportQuery
```
使用按分片导出时，通过将客户端请求属性query_fanout_threads_percent 设置为所需的并发度（线程数的百分比），降低每个节点中导出的线程数的并发度。可以在导出查询中设置此属性。例如，以下命令将写入storage的线程数限制为每个节点上的 50 个%：
```
.export async  to csv
    ( h@"https://storage1.blob.core.chinacloudapi.cn/containerName;secretKey" ) 
    with
    (
        distribution="per_shard"
    ) 
    <| 
    set query_fanout_threads_percent = 50;
    ExportQuery
```
如果要导出到分区的外部表，则设置 spread/concurrency 属性可以降低并发度（请参阅spread中的详细信息）。
如果上述建议都不起作用，则可以通过将 distributed 属性设置为 false 来完全禁用分配。但我们不建议这样做，因为这可能会显著影响命令性能。

授权失败

当不允许在storage connection string中提供的凭据写入storage时，可能会发生身份验证或授权失败。如果对导出命令使用 impersonate 或用户委托的 SAS 令牌，则需要Storage Blob 数据参与者角色才能写入storage帐户。有关详细信息，请参阅Storage连接字符串。

数据类型映射

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`	十进制

Last updated on 2026-03-10

通过