在复制活动中配置湖屋

本文概述了如何使用管道中的复制活动从 Fabric Lakehouse 复制数据。 默认情况下，数据以 V 顺序写入 Lakehouse 表，你可以转到 Delta Lake 表优化和 V 顺序来了解详细信息。

此连接器支持工作区中启用了专用链接的 Lakehouse。 有关配置的详细信息，请参阅 “设置和使用专用链接”。

若要支持本地数据网关（版本 3000.286.12 或更高版本）中的工作区级专用链接，需要添加到 *.dfs.fabric.microsoft.com 允许列表，以确保 Lakehouse 连接器可以通过网络访问 Onelake API。

支持的格式

Lakehouse 支持以下文件格式。 请参阅每一篇介绍基于格式的设置的文章。

• Avro 格式
• 二进制格式
• 带分隔符的文本格式
• Excel 格式
• JSON 格式
• ORC 格式
• Parquet 格式
• XML 格式

支持的配置

有关复制活动下每个选项卡的配置，请分别转到以下各部分。

• General
• Source
• Destination
• Mapping
• Settings

General

对于“常规”选项卡配置，请转到“常规”。

Source

Lakehouse 支持复制活动的“源”选项卡下的以下属性。

需要以下属性：

• 连接：从连接列表中选择一个 Lakehouse 连接。 如果不存在连接，请创建新的 Lakehouse 连接。 如果使用“使用动态内容”来指定湖屋，请添加参数，并将湖屋对象 ID 指定为参数值。 要获取湖屋对象 ID，请在工作区中打开湖屋，ID 位于 URL 中的 /lakehouses/ 后面。

  

• Lakehouse：选择要使用的现有 Lakehouse。

• 根文件夹：选择 “表 或 文件”，指示湖中托管或非托管区域的虚拟视图。 有关详细信息，请参阅 Lakehouse 介绍。

  • 如果选择“表”：

    • 使用查询：从 表 或 T-SQL 查询中进行选择。

      • 如果选择“表”：

        • 表：从表列表中选择现有表，或指定表名作为源。 或者，可以选择“新建”来创建新表。

          

          当你在连接中应用 Lakehouse 架构时，请从表列表中选择一个已有架构的表，或指定一个具有架构的表作为来源。 或者，可以选择“新建”来创建包含架构的新表。 如果未指定架构名称，服务将使用 dbo 作为默认架构。

          

        • 在“高级”下，可以指定以下字段：

          • 时间戳：指定以按时间戳查询较旧的快照。
          • 版本：指定以按版本查询较旧的快照。
          • 其他列：添加其他数据列以存储源文件的相对路径或静态值。 后者支持表达式。

      • 如果选择 T-SQL 查询：

        • T-SQL 查询：指定要通过 Lakehouse SQL 分析终结点读取数据的自定义 SQL 查询。 例如： SELECT * FROM MyTable。 请注意，Lakehouse 表查询模式不支持工作区级专用链接。

          

        • 在“高级”下，可以指定以下字段：

          • 查询超时（分钟）：指定查询命令执行的超时，默认值为 120 分钟。

          • 分区选项：指定用于从 Lakehouse 表查询模式加载数据的数据分区选项。 可以选择 “无 ”或 “动态范围”。

            如果选择无，则表示不使用分区。

            如果选择 “动态范围”，则使用启用了并行的查询时，需要区域分区参数（?DfDynamicRangePartitionCondition）。 示例查询： SELECT * FROM <TableName> WHERE ?DfDynamicRangePartitionCondition.

            • 分区列名称：以 整数 类型指定源列的名称，范围分区用于并行复制。 如果未指定，则会自动检测表的索引或主键，并将其用作分区列。 如果使用查询来检索源数据，请在 WHERE 子句中挂接 ?DfDynamicRangePartitionCondition。 有关示例，请参阅 通过 T-SQL 查询从 Lakehouse 表并行复制的部分。

            • 分区上限：指定分区范围拆分的分区列的最大值。 此值用于确定分区步幅，不用于筛选表中的行。 将对表或查询结果中的所有行进行分区和复制。 如果未指定，复制活动会自动检测该值。 有关示例，请参阅 使用 T-SQL 查询并行复制 Lakehouse 表 部分。

            • 分区下限：指定分区范围拆分的分区列的最小值。 此值用于确定分区步幅，不用于筛选表中的行。 将对表或查询结果中的所有行进行分区和复制。 如果未指定，复制活动会自动检测该值。 有关示例，请参阅 通过 T-SQL 查询从 Lakehouse 表并行复制 部分。

              

          • 其他列：添加其他数据列以存储源文件的相对路径或静态值。 后者支持表达式。

  • 如果选择“文件”：

    • 文件路径类型：可以选择“文件路径”、“通配符文件路径”或“文件列表”作为文件路径类型。 以下列表介绍了每个设置的配置：

      

      • 文件路径：选择“浏览”以选择要复制的文件，或手动填写路径。

      • 通配符文件路径：在给定 Lakehouse 非托管区域（在文件下）中，使用通配符字符指定文件夹或文件路径以过滤源文件夹或文件。 允许的通配符为：*（匹配零个或更多字符）和 ?（匹配零个或单个字符）。 如果文件夹或文件名内包含通配符或此转义字符，请使用 ^ 进行转义。

        • 通配符文件夹路径：给定容器下的文件夹的路径。 如果要使用通配符来筛选文件夹，请跳过此设置并在活动源设置中进行相应的信息指定。

        • 通配符文件名：给定 Lakehouse 未管理区（在“文件”下）和文件夹路径下的文件名。

          

      • 文件列表：指示复制给定文件集。

        • 文件夹路径：指向包含要复制的文件的文件夹。
        • 文件列表路径：指向包含要复制的文件列表的文本文件，每行一个文件，即已配置文件路径的相对路径。

        

    • 递归：指示是要从子文件夹中以递归方式读取数据，还是只从指定的文件夹中读取数据。 如果启用，则以递归方式处理输入文件夹及其子文件夹中的所有文件。 将文件路径类型配置为文件列表时，此属性不适用。

    • 文件格式：从下拉列表中选择文件格式。 选择“设置”按钮以配置文件格式。 有关不同文件格式的设置，请参阅支持格式的文章了解详细信息。

    • 在“高级”下，可以指定以下字段：

      • 按上次修改日期筛选：根据上次修改日期筛选文件。 将文件路径类型配置为文件列表时，此属性不适用。
        • 开始时间：如果文件的上次修改时间大于或等于配置时间，则会选择这些文件。
        • 结束时间：如果文件的上次修改时间小于配置的时间，则选择这些文件。
      • 启用分区发现：对于已分区的文件，请指定是否从文件路径分析分区，并将它们添加为附加源列。
        • 分区根路径：当启用了分区发现时，请指定绝对根路径，以便将已分区文件夹读取为数据列。
      • 最大并发连接：指示活动运行期间与数据存储建立的并发连接的上限。 仅在要限制并发连接时指定一个值。

Destination

Lakehouse 在复制活动的“目标”选项卡下支持以下属性。

需要以下属性：

• 连接：从连接列表中选择一个 Lakehouse 连接。 如果不存在连接，请创建新的 Lakehouse 连接。 如果使用“使用动态内容”来指定湖屋，请添加参数，并将湖屋对象 ID 指定为参数值。 要获取湖屋对象 ID，请在工作区中打开湖屋，ID 位于 URL 中的 /lakehouses/ 后面。

  

• 根文件夹：选择 “表 或 文件”，指示湖中托管或非托管区域的虚拟视图。 有关详细信息，请参阅 Lakehouse 介绍。

  • 如果选择“表”：

    • 表：从表列表中选择现有表，或指定表名作为目标。 或者，可以选择“新建”来创建新表。

      

      在连接中使用架构应用 Lakehouse 时，请从表列表中选择具有架构的现有表，或指定具有架构的表作为目标。 或者，可以选择“新建”来创建包含架构的新表。 如果未指定架构名称，服务将使用 dbo 作为默认架构。

      

    Note

    表名必须至少包含一个字符，不带“/”或“\”，无尾随点，且没有前导或尾随空格。

    • 表操作：指定针对所选表的操作。

      • 追加：将新值追加到现有表。 在 “高级”下，可以在目标表上启用分区：

        • 启用分区：此选择允许基于一列或多列在文件夹结构中创建分区。 每个不同的列值（对）都是一个新分区。 例如，“year=2000/month=01/file”。
          • 分区列名称：将数据追加到新表时，从架构映射中的目标列中进行选择。 将数据追加到已有分区的现有表时，系统将根据现有表自动派生分区列。 支持的数据类型为 string、integer、boolean 和 datetime。 格式遵循“映射”选项卡下的类型转换设置。

      • 覆盖：使用新值来覆盖表中的现有数据和架构 在 “高级”下，可以在目标表上启用分区：

        • 启用分区：此选择允许基于一列或多列在文件夹结构中创建分区。 每个不同的列值（对）都是一个新分区。 例如，“year=2000/month=01/file”。
          • 分区列名称：从架构映射中的目标列中进行选择。 支持的数据类型为 string、integer、boolean 和 datetime。 格式遵循“映射”选项卡下的类型转换设置。

        它支持 Delta Lake 时空穿越。 覆盖的表具有以前版本的增量日志，可以在 Lakehouse 中访问这些日志。 还可以通过在复制活动源中指定“版本”，从 Lakehouse 复制以前的版本表。

      • Upsert （预览版）：将新值插入现有表并更新现有值。 使用分区的 Lakehouse 表时不支持 Upsert。 选择此作时，无法启用分区。

        • 键列：选择用于确定源中的行是否与目标中的行匹配的列。 列出所有目标列的下拉列表。 可以在写入 Lakehouse 表时，将一个或多个列选择为键列。

    • 在“高级”下，可以指定以下字段：

      • 应用 V 顺序：指定通过复制操作来应用 V 顺序。 禁用它会保留原始 parquet 文件，而无需应用额外的 V-Order 优化。 有关详细信息，请参阅 Delta Lake 表优化和 V-Order。

  • 如果选择“文件”：

    • 文件路径：选择“浏览”以选择要复制的文件，或手动填写路径。

      

    • 文件格式：从下拉列表中选择文件格式。 选择“设置”以配置文件格式。 有关不同文件格式的设置，请参阅支持格式的文章了解详细信息。

    • 在“高级”下，可以指定以下字段：

      • 复制活动：定义以基于文件的数据存储中的文件为源时的复制行为。 可以选择“平展层次结构”、“合并文件”、“保留层次结构”或“添加动态内容”作为复制行为。 每个设置的配置为：

        • 平展层次结构：源文件夹中的所有文件都位于目标文件夹的第一级别。 目标文件具有自动生成的名称。

        • 合并文件：将源文件夹中的所有文件合并到一个文件中。 如果指定了文件名，则合并文件的名称为指定名称。 否则，它是自动生成的文件名。

        • 保留层次结构：将文件层次结构保留到目标文件夹中。 指向源文件夹的源文件相对路径与指向目标文件夹的目标文件相对路径相同。

        • 添加动态内容：若要指定属性值的表达式，请选择“添加动态内容”。 这字段会打开“表达式生成器”，在其中可以通过支持的系统变量、活动输出、函数和用户指定的变量或参数来生成表达式。 若要了解表达式语言详细信息，请参阅表达式和函数。

          

      • 最大并发连接：活动运行期间与数据存储建立的并发连接的上限。 仅在要限制并发连接时指定一个值。

      • 块大小 (MB)：将数据写入 Lakehouse 时指定块大小（以 MB 为单位）。 允许的值介于 4 MB 到 100 MB 之间。

      • 元数据：在复制到目标数据存储时设置自定义元数据。 metadata 数组下的每个对象都表示一个额外的列。 name 定义元数据键名称，value 表示该键的数据值。 如果使用了保留属性功能，则指定的元数据会与源文件元数据联合，或者会被其覆盖。 允许的数据值为：

        • $$LASTMODIFIED：保留变量指示存储源文件的上次修改时间。 仅适用于二进制格式的基于文件的源。

        • Expression

        • 静态值

          

Mapping

对于“映射”选项卡配置，如果不将 Lakehouse 表作为目标数据存储，请转到“映射”。

如果将 Lakehouse 表应用为目标数据存储，则除了“映射”中的配置外，可以编辑目标列的类型。 选择“导入架构”后，可以在目标中指定列类型。

例如，源中 PersonID 列的类型为 int，当映射到目标列时，你可以将其更改为字符串类型。

如果选择“二进制”作为文件格式，则不支持映射。

Settings

对于“设置”选项卡配置，请转到“设置”。

Lakehouse 数据库表数据类型映射

以下部分介绍从 Lakehouse 表复制数据时的数据类型映射。 有关详细信息，请参阅对应于源模式的子节。

Table

在 Table 模式下从 Lakehouse 表复制数据时，以下映射用于将 Lakehouse 表数据类型转换为服务内部使用的过渡数据类型。

在表模式下将数据复制到 Lakehouse 表时，服务内部使用的临时数据类型与所支持的 delta 目标数据类型之间会进行以下映射。

T-SQL 查询

在 T-SQL 查询模式下从 Lakehouse 表复制数据时，以下映射用于从 Lakehouse 表数据类型到服务内部使用的临时数据类型。

使用 T-SQL 查询从 Lakehouse 表并行复制

在复制活动中使用 T-SQL 查询的 Lakehouse 表连接器提供内置的数据分区来并行复制数据。 可以在复制活动的 源 选项卡上找到数据分区选项。

启用分区复制时，复制活动使用 T-SQL 查询源针对 Lakehouse 表运行并行查询，以便按分区加载数据。 并行度由复制活动的设置选项卡中的 复制并行度 控制。例如，如果将 复制并行度 设置为 4，服务会根据指定的分区选项和设置并发生成并运行四个查询，每个查询使用 T-SQL 从 Lakehouse 表检索部分数据。

建议使用数据分区启用并行复制，尤其是在使用 T-SQL 查询从 Lakehouse 表加载大量数据时。 下面是适用于不同方案的建议配置。 将数据复制到基于文件的数据存储中时，建议将数据作为多个文件写入文件夹（仅指定文件夹名称），在这种情况下，性能优于写入单个文件。

Delta Lake 表支持

以下部分介绍了有关源和目标的 Delta Lake 表支持的详细信息。

Source

在 Lakehouse 表的 中使用 columnMapping 来应用阅读器版本 2 或阅读器版本 3 时，支持 readerFeatures。

Delta 表的列映射功能允许更灵活的架构演变，确保表结构中的更改不会中断数据工作流。 使用列映射，可以从现有的 Delta Lake 表中读取数据，并将 delta.columnMapping.mode 设置为 name 或 id。

在 Lakehouse 表的 中将阅读器版本 3 与 deletionVectors 一起应用时，支持readerFeatures。 被软删除的行会在删除向量文件中被标记，在读取 Delta Lake 表时会被跳过。

支持变更数据流。

Destination

支持 Delta 列映射。 此功能允许更灵活的架构演变，确保表结构中的更改不会中断数据工作流。 使用列映射，你可以：

• 将数据写入到设置为delta.columnMapping.mode的现有 Delta Lake 表，使用name。
• 当目标表不存在且源列包含特殊字符和空格时，自动创建 delta.columnMapping.mode 设置为 name 的表。
• 当“表操作”为“覆盖”且源数据集列包含特殊字符和空格时，自动创建一个表，并将 delta.columnMapping.mode 设置为 name。

支持删除向量。

支持变更数据流。

表摘要

下表包含有关 Lakehouse 中复制活动的详细信息。

源信息

目的地信息

相关内容

• Lakehouse 连接器概述