通过

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

将数据导出到外部表

  • 项目

适用于：✅Microsoft Fabric✅Azure 数据资源管理器

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

权限

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

语法

.export [async] to table externalTableName
[with (propertyName = propertyValue [, ...])] <| query

详细了解语法约定。

参数

客户 类型​​ 必需 说明
externalTableName string ✔️ 要导出到的外部表的名称。
propertyName、propertyValue string 可选属性的逗号分隔列表。
查询 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 运行，每个节点将导出分配给该节点的数据。 单个分区可能由多个节点写入，文件数会相应地增加。 为了进一步提高并发性，请设置 distributionKind=uniform 以及 distribution=per_shard 以获得最高并发性（以可能写入更多文件为代价）

* 如果数据导出速度缓慢的原因不是离群值，请通过增加并发性来减少持续时间，而无需更改分区设置。 使用 hint.spread 和 hint.concurrency 属性来确定分区的并发性。 请参阅分区运算符。 默认情况下，并发导出的节点数 (spread) 将是 64 与节点数之间的最小值。 将 spread 设置为大于节点数的数量会增加每个节点的并发性（spread 的最大值为 64）。

身份验证和授权

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

输出

输出参数 类型 说明
ExternalTableName string 外部表的名称。
路径 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 命令获得输出。