将数据导出到外部表

适用于:✅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 分布提示(singleper_nodeper_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=singledistributed=false(两者都是等效的)。 只有一个线程执行导出。 其缺点是,导出操作可能会变慢,因为并发性大幅减少。
减少导出持续时间 增加导出操作的并发性,以减少其持续时间。 在命令属性中设置 distribution=per_shard。 这意味着写入操作的并发性是按数据分片,而不是按节点。 只有当导出到未由字符串分区进行分区的外部表时,这才相关。 这可能会在存储上创建过多的负载,从而可能会产生限制。 请参阅存储失败
减少由字符串分区进行分区的外部表的导出持续时间 如果分区在节点之间未统一分布,则导出可能需要更长的时间才能运行。 例如,如果有一个分区比其他分区大得多,则大部分导出工作由分配给该分区的单节点完成,而其他节点大多处于空闲状态。 请参阅分布设置 可以更改多个设置:
* 如果有多个字符串分区,请首先定义分布最佳的字符串分区。

* 在命令属性中设置 distributionKind=uniform。 此设置会禁用字符串分区外部表的默认分布设置。 导出将使用 per-node 运行,每个节点将导出分配给该节点的数据。 单个分区可能由多个节点写入,文件数会相应地增加。 为了进一步提高并发性,请设置 distributionKind=uniform 以及 distribution=per_shard 以获得最高并发性(以可能写入更多文件为代价)

* 如果数据导出速度缓慢的原因不是离群值,请通过增加并发性来减少持续时间,而无需更改分区设置。 使用 hint.spreadhint.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.chinacloudapi.cn/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.chinacloudapi.cn/container1;secretKey'
)
.export to table PartitionedExternalBlob <| T
ExternalTableName `Path` NumRecords
ExternalBlob http://storageaccount.blob.core.chinacloudapi.cn/container1/CustomerName=customer1/2019/01/01/fa36f35c-c064-414d-b8e2-e75cf157ec35_1_58017c550b384c0db0fea61a8661333e.csv 10
ExternalBlob http://storageaccount.blob.core.chinacloudapi.cn/container1/CustomerName=customer2/2019/01/01/fa36f35c-c064-414d-b8e2-e75cf157ec35_2_b785beec2c004d93b7cd531208424dc9.csv 10

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