你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

将数据导出到外部表

项目
02/12/2024

可以通过定义外部表并将数据导出到其中来导出数据。表属性在创建外部表时指定。 export 命令按名称引用外部表。

权限

你必须至少具有表管理员权限才能运行此命令。

语法

.export [async] totableexternalTableName
[with(propertyName=propertyValue [, ...])] <|query

详细了解语法约定。

参数

名称	类型	必需	说明
externalTableName	`string`	✔️	要导出到的外部表的名称。
propertyName、propertyValue	`string`		可选属性的逗号分隔列表。
query	`string`	✔️	导出查询。

支持的属性

支持将以下属性作为“导出到外部表”命令的一部分。

属性	类型	说明	默认
`sizeLimit`	`long`	在压缩之前要写入的单个存储项目的大小限制（字节）。在检查此行组是否已达到大小限制之前，将写入大小为 `parquetRowGroupSize` 的完整行组，并应启动新项目。有效范围：100 MB (默认) 为 1 GB。
`distributed`	`bool`	禁用/启用分布式导出。设置为 false 等效于 `single` 分布提示。	默认为 `true`。
`distribution`	`string`	分布提示（`single`、`per_node`、`per_shard`）。在分发设置中查看更多详细信息	默认为 `per_node`。
`distributionKind`	`string`	（可选）在按字符串分区对外部表进行分区时切换到统一分布。有效值为 `uniform` or `default`进行求值的基于 SQL 语言的筛选器表达式。在分发设置中查看更多详细信息
`concurrency`	数字	提示系统要并行运行的分区数量。在分发设置中查看更多详细信息	默认值为 16。
`spread`	数字	提示系统如何在群集节点之间分配分区。在分发设置中查看更多详细信息	默认值为 `Min(64, number-of-nodes)`。
`parquetRowGroupSize`	`int`	只有数据格式为 Parquet 时才相关。控制已导出文件中的行组大小。此值优先于 `sizeLimit`，这意味着在检查此行组是否已达到大小限制并应启动新项目之前，将导出完整的行组。	默认的行组大小为 100,000 条记录。

分发设置

导出到外部表操作的分布指示同时写入存储的节点和线程数。默认分布取决于外部表分区：

外部表分区	默认分布
外部表未分区或仅按列分区`datetime`	导出是分布式的 `per_node` - 群集中的所有节点都在并发导出。每个节点写入分配给该节点的数据。仅当来自该节点的数据大小超过 `sizeLimit`时，节点导出的文件数将大于 1。
外部表按字符串列进行分区	要导出的数据在节点之间移动，以便每个节点写入分区值的子集。单个分区始终由单个节点写入。仅当数据超过 `sizeLimit`时，每个分区写入的文件数应大于 1。如果外部表包含多个字符串分区，则会基于第一个分区在节点之间对数据进行分区。因此，建议将分布最均匀的分区定义为第一个分区。

更改默认分发设置

在以下情况下，更改默认分发设置很有用：

用例	说明	建议
减少导出的文件数	导出会创建过多的小文件，你希望它创建少量的大型文件。	设置 `distribution`=`single` 或 `distributed`=`false` (两者在命令属性中是等效) 。只有单个线程执行导出。这样做的缺点是导出操作可能会变慢，因为并发性大大降低。
缩短导出持续时间	增加导出操作的并发性，以缩短其持续时间。	在命令属性中设置 `distribution`=`per_shard` 。这意味着写入操作的并发性是每个数据分片，而不是每个节点。仅当导出到未按字符串分区的外部表时，这才相关。这可能会对存储造成过多的负载，从而导致限制。请参阅存储故障。
减少按字符串分区进行分区的外部表的导出持续时间	如果分区在节点之间分布不统一，则导出可能需要更长的时间才能运行。例如，如果有一个分区比其他分区大得多，则大多数导出工作由分配给该分区的单个节点完成，而其他节点将大多处于空闲状态。请参阅分发设置。	可以更改多个设置： * 如果有多个字符串分区，请先定义分布最佳的字符串分区。 * 在命令属性中设置 `distributionKind`=`uniform` 。此设置禁用字符串分区外部表的默认分布设置。导出将随分发一起 `per-node` 运行，每个节点将导出分配给该节点的数据。单个分区可能由多个节点写入，文件数相应地增加。若要进一步提高并发性，请将与一`distribution`=`per_shard`起设置为`distributionKind`=`uniform`最高并发 (，代价是可能写入更多文件) * 如果导出速度缓慢的原因不是数据中的离群值，请通过增加并发性来缩短持续时间，而无需更改分区设置。 `hint.spread`使用和 `hint.concurrency` 属性，用于确定分区的并发性。请参阅分区运算符。默认情况下， () 同时导出的 `spread` 节点数将是 64 和群集节点数之间的最小值。如果设置为 `spread` 大于节点数，则每个节点的并发性 (最大值为 `spread` 64) 。

身份验证和授权

若要导出到外部表，必须设置写入权限。有关详细信息，请参阅适用于 Azure 存储外部表或 SQL Server 外部表的写入权限。

输出

输出参数	类型	说明
ExternalTableName	`string`	外部表的名称。
`Path`	`string`	输出路径。
NumRecords	`string`	导出到路径的记录数。

注释

导出查询输出架构必须与外部表的架构（包括分区定义的所有列）匹配。例如，如果表按 DateTime 分区，则查询输出架构必须具有与 TimestampColumnName 匹配的 Timestamp 列。此列名在外部表分区定义中定义。
不能使用 export 命令重写外部表属性。例如，不能将 Parquet 格式的数据导出到数据格式为 CSV 的外部表。
如果外部表已分区，则导出的项目将根据分区定义写入到各自的目录，如已分区外部表示例中所示。
- 如果分区值为 NULL 或为空，或者是无效的目录值，则根据目标存储的定义，分区值将替换为默认值 __DEFAULT_PARTITION__。
有关解决导出命令过程中出现的存储错误的建议，请参阅导出命令过程中的失败。
根据数据类型映射规则，将外部表列映射到合适的目标格式数据类型。
Parquet 本机导出是一种性能更高的资源轻型导出机制。导出的“datetime”列当前不受 Synapse SQL“COPY”支持。

文件的数目

每个分区写入的文件数取决于导出操作的分发设置：

如果外部表只包含日期/时间分区或者根本不包含分区，则每个分区（如果存在）写入的文件数应该与群集中的节点数相似（如果达到 sizeLimit，则需增加该数目）。分发导出操作后，群集中的所有节点将同时导出。若要禁用分发，以便仅单个节点执行写操作，请将 distributed 设为 false。此过程会创建较少的文件，但会降低导出性能。
如果外部表通过一个字符串列包含一个分区，则导出的文件数应为每个分区一个文件（如果达到 sizeLimit，则需增加该数目）。所有节点仍参与导出（操作已分发），但每个分区将分配给特定节点。将 distributed 设为 false 会导致只有单个节点进行导出，但行为将保持不变（每个分区写入一个文件）。

示例

未分区外部表示例

ExternalBlob 是未分区外部表。

.export to table ExternalBlob <| T

ExternalTableName	`Path`	NumRecords
ExternalBlob	http://storage1.blob.core.windows.net/externaltable1cont1/1_58017c550b384c0db0fea61a8661333e.csv	10

已分区外部表示例

PartitionedExternalBlob 是一个外部表，定义如下：

.create external table PartitionedExternalBlob (Timestamp:datetime, CustomerName:string) 
kind=blob
partition by (CustomerName:string=CustomerName, Date:datetime=startofday(Timestamp))   
pathformat = ("CustomerName=" CustomerName "/" datetime_pattern("yyyy/MM/dd", Date))   
dataformat=csv
( 
   h@'http://storageaccount.blob.core.windows.net/container1;secretKey'
)

.export to table PartitionedExternalBlob <| T

ExternalTableName	`Path`	NumRecords
ExternalBlob	http://storageaccount.blob.core.windows.net/container1/CustomerName=customer1/2019/01/01/fa36f35c-c064-414d-b8e2-e75cf157ec35_1_58017c550b384c0db0fea61a8661333e.csv	10
ExternalBlob	http://storageaccount.blob.core.windows.net/container1/CustomerName=customer2/2019/01/01/fa36f35c-c064-414d-b8e2-e75cf157ec35_2_b785beec2c004d93b7cd531208424dc9.csv	10

如果命令是异步执行的（通过使用 async 关键字），则可以使用 async 命令获得输出。