将数据导出到云存储空间

项目
03/17/2024

执行查询，将第一个结果集写入到通过存储连接字符串指定的云存储空间。

权限

你必须至少具有数据库查看者权限才能运行此命令。

语法

.export [async] [compressed] to.export(async [, ...] ) [with(compressed=to [, ...] )] <|(

参数

客户	类型	必需	说明
`async`	`string`		如果指定此参数，命令将以异步模式运行。请参阅异步模式。
`compressed`	`string`		如果指定了此项，则输出存储项目将压缩为 `.gz` 文件。请参阅用于将 Parquet 文件压缩为 snappy 的 `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`	表示要使用的压缩类型。可能的值为 `gzip` 或 `snappy`。默认值为 `gzip`。 `snappy` 可以（选择性地）用于 `parquet` 格式。
`distribution`	`string`	分布提示（`single`、`per_node`、`per_shard`）。如果值等于 `single`，则由单个线程将数据写入存储。否则，导出会以并行方式从执行查询的所有节点进行写入。请参阅 evaluate 插件运算符。默认为 `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.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，压缩前最大可达 1GB。列名标签添加为每个 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 命令（导出到存储、导出到外部表）不执行任何重试操作。

如果 export 命令失败，不会删除已写入到存储的项目。这些项目将保留在存储中。如果该命令失败，应假定导出不完整（即使已写入了一些项目）。
若要跟踪命令完成情况和成功完成时导出的项目，最好使用 .show operations 和 .show operation details 命令。

存储故障

默认情况下会对 export 命令进行分配，从而可能会有许多针对存储的并发写入。分配级别取决于 export 命令的类型：

常规 .export 命令的默认分配为 per_shard，这意味着所有包含要导出数据的.export都以并发方式写入到存储。
导出到外部表命令的默认分配为 per_node，这意味着并发度是指群集中的节点数。

当区/节点的数量很大时，可能会导致存储中的负载过高，从而导致发生存储限制或出现暂时性存储错误。以下建议可能会解决这些错误（按优先级顺序）：

增加为 export 命令或外部表定义提供的存储帐户数（负载会在帐户之间均匀分配）。
通过将分配提示设置为 per_node 来降低并发度（请参阅命令属性）。
通过将客户端请求属性query_fanout_nodes_percent 设置为所需的并发度（节点百分比）来减少导出节点数的并发性。可以在导出查询中设置此属性。例如，以下命令会将以并发方式写入到存储的节点的数目限制为群集节点的 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 设置为所需的并发度（线程数的百分比），降低每个节点中导出的线程数的并发度。可以在导出查询中设置此属性。例如，以下命令会将每个群集节点上以并发方式向存储中写入数据的线程数限制为 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 来完全禁用分发。但我们不建议这样做，因为这可能会显著影响命令性能。

授权失败

当存储连接字符串中提供的凭据无权写入存储时，身份验证或授权可能会在导出命令期间失败。如果使用 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