打开镜像登陆区域要求和格式

本文详细介绍了在 Microsoft Fabric 中打开镜像的登陆区域和表/列作要求。

在 Fabric 工作区中通过 Fabric 门户或公共 API 创建打开的镜像数据库后，可以在镜像数据库项 主页 的 OneLake 中获取登陆区域 URL。 此登陆区域是应用程序在 Parquet 或带分隔符的文本格式（包括 CSV）中创建元数据文件和登陆数据的位置。 可以使用 Snappy、GZIP 或 ZSTD 解压缩或压缩文件。 有关详细信息，请参阅 支持的数据文件和格式。

登陆区域

对于每个镜像数据库，OneLake 中都有一个用于元数据和增量表的唯一存储位置。 打开镜像为应用程序提供了一个登陆区域文件夹，用于创建元数据文件并将数据推送到 OneLake。 镜像监视登陆区域中的这些文件，并读取新表和数据添加的文件夹。

例如，如果要在登陆区域中创建表（Table A、 Table B、 Table C），请创建文件夹，如下所示的 URL：

• https://onelake.dfs.fabric.microsoft.com/<workspace id>/<mirrored database id>/Files/LandingZone/TableA
• https://onelake.dfs.fabric.microsoft.com/<workspace id>/<mirrored database id>/Files/LandingZone/TableB
• https://onelake.dfs.fabric.microsoft.com/<workspace id>/<mirrored database id>/Files/LandingZone/TableC

登陆区域中的元数据文件

每个表文件夹都必须包含一个 _metadata.json 文件。

此表元数据文件包含 JSON 记录，当前仅指定唯一键列。keyColumns

例如，若要声明列 C1 ，并 C2 作为表的复合唯一键：

{
   "keyColumns" : ["C1", "C2"]
}

如果 keyColumns 或 _metadata.json 未指定，则无法更新/删除。 可以随时添加此文件，但添加后 keyColumns 无法更改。

登陆区域中的事件文件

如果你是实施开放镜像解决方案的合作伙伴，或者想要向我们提供有关要镜像到 OneLake 的源类型的更多详细信息的客户，我们已添加了一个新的 _partnerEvents.json 文件。 这不是必需的，但强烈建议这样做。

示例：

{
  "partnerName": "testPartner",
  "sourceInfo": {
    "sourceType": "SQL",
    "sourceVersion": "2019",
    "additionalInformation": {
      "testKey": "testValue"
    }
  }
}

_partnerEvents.json文件的要求：

• 该文件 _partnerEvents.json 应放置在登陆区域中的镜像数据库级别，而不是每个表。
• sourceType可以是表示源的任何描述性字符串。 此值没有约束，例如：“SQL”、“Oracle”、“Salesforce”等。
• partnerName可以设置为所选的任何名称，并且可以代表组织的名称。 在所有镜像数据库中保持名称一致。

登陆区域中的数据文件和格式

打开镜像支持 Parquet 或带分隔符的文本格式的数据引入。 可以使用 Snappy、GZIP 或 ZSTD 解压缩或压缩文件。

Parquet 要求

带分隔符的文本要求

• 对于带分隔符的文本格式，文件必须在第一行中具有标题行。

• 对于带分隔符的文本，请在 _metadata.json 文件中提供其他信息。 属性 FileExtension 是必需的。 带分隔符的文本文件具有以下属性和默认值：

  资产	Description	注释
  FirstRowAsHeader	第一行标题的 True/false。	true必须为带分隔符的文本文件。
  RowSeparator	用于分隔行的字符。	默认值为 \r\n。 也支持 \n 和 \r。
  ColumnSeparator	用于分隔列的字符。	默认值为 ,。 此外还支持 ;、 |和 \t。
  QuoteCharacter	用于引用包含分隔符的值的字符。	默认值为 "。 也可以为 ' 空字符串。
  EscapeCharacter	用于转义带引号内的引号。	默认值为 \。 也可以为 /空 "。
  NullValue	null 值的字符串表示形式。	可以是 ""、 "N/A"， "null"等等。
  Encoding	文件的字符编码。	默认值为 UTF-8。 支持各种编码，包括 ascii、 utf-16等等 windows-1252。
  SchemaDefinition	定义列名、类型和可为 null 性。	不支持架构演变。
  FileFormat	数据文件的格式。	默认为 CSV 未指定。 必须为 "DelimitedText" CSV 以外的格式。
  FileExtension	指定文件扩展名，例如 .tsv， .psv。	使用 DelimitedText时必需 。

  例如， _metadata.json 包含四列的数据文件的文件 .tsv ：

  {
  "KeyColumns": [ "id" ],
  "SchemaDefinition": {
      "Columns": [
                    {
                    "Name": "id",
                    "DataType": "Int32"
                    },
                    {
                    "Name": "name",
                    "DataType": "String",
                    "IsNullable": true
                    },
                    {
                    "Name": "age",
                    "DataType": "Int32",
                    "IsNullable": true
                    },
                    {
                    "Name": "seqNum",
                    "DataType": "Int64",
                    "IsNullable": false
                    }
                  ]
                },
  "FileFormat": "DelimitedText",
  "FileExtension": "tsv",
  "FileFormatTypeProperties": {
                              "FirstRowAsHeader": true,
                              "RowSeparator": "\r\n",
                              "ColumnSeparator": ",",
                              "QuoteCharacter": "'",
                              "EscapeCharacter": "\",
                              "NullValue": "N/A",
                              "Encoding": "UTF-8"
                           }
  }
  

• 只有带分隔符的文本格式才能在文件中 _metadata.json具有数据类型。 Parquet 文件不需要指定列类型信息。 当前支持的数据类型：

格式要求

写入登陆区域的所有文件具有以下格式：

<rowMarker><DataColumns>

• rowMarker：列名是 __rowMarker__ （包括前后 rowMarker的两个下划线）。 __rowMarker__ 值和行为：

  __rowMarker__ （场景）	如果目标中不存在具有相同键列的行	如果行存在于目标中具有相同键列
  0 （插入）	将行插入目标	将行插入目标，不验证 dup 键列检查。
  1 （更新）	将行插入目标，无需验证/异常来检查是否存在具有相同键列的行。	使用相同的键列更新行。
  2 （删除）	没有数据更改，没有验证/异常，用于检查是否存在具有相同键列的行。	删除具有相同键列的行。
  4 （Upsert）	将行插入目标，无需验证/异常来检查是否存在具有相同键列的行。	使用相同的键列更新行。

• 行顺序：文件中的所有日志都应按事务中应用的自然顺序。 对于多次更新的同一行来说，这一点很重要。 打开镜像使用文件中的顺序应用更改。

• 文件顺序：应以单调递增数字添加文件。

• 文件名：文件名为 20 位数字，如 00000000000000000001.parquet 第一个文件， 00000000000000000002.parquet 第二个数字。 文件名应以连续数字表示。 镜像服务会自动删除文件，但最后一个文件将保留，以便发布者系统可以引用该文件以按顺序添加下一个文件。

非顺序文件

还支持非顺序文件，文件将根据其时间戳进行读取。 若要指定此项并默认为更新或插入（upsert）操作而不是仅插入，请更新 _metadata.json 文件，如下所示：

{
   "keyColumns" : ["id"],
   "fileDetectionStrategy": LastUpdateTimeFileDetection,
   "isUpsertDefaultRowMarker": true
}

“default to upsert”不依赖于非顺序文件。 支持以下所有组合：

• 将 fileDetectionStrategy 作为 LastUpdateTimeFileDetection 和 isUpsertDefaultRowMarker 设置为 true。
• 仅当 isUpsertDefaultRowMarker 为 true 时。
• 仅将 fileDetectionStrategy 设置为 LastUpdateTimeFileDetection。
• 违约

初始加载

对于将数据初始加载到打开的镜像数据库中， __rowMarker__ 初始数据文件是可选的，不建议这样做。 镜像将整个文件视为 INSERT（如果不存在）。__rowMarker__

为了获得更好的性能和准确的指标， __rowMarker__ 只有增量更改才能应用更新/删除/upsert作。

增量更改

打开镜像会按顺序读取增量更改，并将其应用于目标 Delta 表。 顺序在更改日志和文件的顺序中隐式。

从任何行/文件中找到列后， __rowMarker__ 数据更改被视为增量更改。

更新的行必须包含包含所有列的完整行数据。

下面是一些行历史记录的 parquet 数据示例，用于将 E0001 从 Redmond 更改为 Bellevue。 在此方案中，该 EmployeeID 列已标记为 登陆区域中元数据文件中的键列。

EmployeeID,EmployeeLocation,__rowMarker__
E0001,Redmond,0
E0002,Redmond,0
E0003,Redmond,0
E0001,Bellevue,1

如果更新键列，则它应由上一个键列上的 DELETE 和具有新键和数据的 INSERT 行显示。 例如，将 E0001 的唯一标识符__rowMarker__更改为 E0002 的EmployeeID行历史记录。 无需为 DELETE 行提供所有列数据，只需提供键列。

EmployeeID,EmployeeLocation,__rowMarker__
E0001,Bellevue,0
E0001,NULL,2
E0002,Bellevue,0

表作

打开镜像支持表作，例如添加、删除和重命名表。

添加表

打开镜像会选取应用程序添加到登陆区域的任何表。 每次迭代中打开新表的镜像扫描。

删除表

打开镜像可跟踪文件夹名称。 如果删除了表文件夹，则打开镜像会删除镜像数据库中的表。

如果重新创建文件夹，则打开镜像会删除该表，并使用文件夹中的新数据重新创建该表，方法是跟踪该文件夹的 ETag。

尝试删除表时，可以尝试删除该文件夹，但有可能打开镜像仍使用文件夹中的数据，从而导致发布者删除失败。

重命名表

若要重命名表，请删除并重新创建包含初始数据和增量数据的文件夹。 需要将数据重新填充到重命名的表。

Schema

可以在架构文件夹中指定表路径。 架构登陆区域应具有 <schemaname>.schema 文件夹名称。 可以有多个架构，并且架构中可以有多个表。

例如，如果架构（Schema1、）和表（Schema2、Table A、Table B）Table C在登陆区域中创建，请在 OneLake 中创建类似于以下路径的文件夹：

• https://onelake.dfs.fabric.microsoft.com/<workspace id>/<mirrored database id>/Files/LandingZone/Schema1.schema/TableA
• https://onelake.dfs.fabric.microsoft.com/<workspace id>/<mirrored database id>/Files/LandingZone/Schema1.schema/TableB
• https://onelake.dfs.fabric.microsoft.com/<workspace id>/<mirrored database id>/Files/LandingZone/Schema2.schema/TableC

表列和列作

列类型

• 登陆区域中支持简单 parquet 类型。
• 复杂类型应编写为 JSON 字符串。
• 二进制复杂类型（如地理、图像等）可以存储为登陆区域中的二进制类型。

添加列

如果将新列添加到 parquet 或 CSV 文件，则打开镜像会将这些列添加到增量表。

删除列

如果从新日志文件中删除列，则打开新行中这些列的镜像存储 NULL ，旧行包含数据中存在的列。 若要删除列， 请删除该表 并在登陆区域中再次创建表文件夹，这将导致使用新的架构和数据重新创建 Delta 表。

打开镜像始终将以前版本添加数据中的所有列联合在一起。 若要删除列，请重新创建表/文件夹。

更改列类型

若要更改列类型，请删除并重新创建包含新列类型的初始和增量数据的文件夹。 提供新的列类型而不重新创建表会导致错误，该表的复制将停止。 重新创建表文件夹后，复制会随着新的数据和架构而恢复。

重命名列

若要重命名列，请删除表文件夹，并使用所有数据和新的列名重新创建该文件夹。

清理过程

打开镜像的清理过程会将所有已处理的文件移动到名为 _ProcessedFiles 或 _FilesReadyToDelete的单独文件夹中。 七天后，将从此文件夹中删除文件。

后续步骤

相关内容

• 监视 Fabric 镜像数据库复制