本文详细介绍了 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/TableAhttps://onelake.dfs.fabric.microsoft.com/<workspace id>/<mirrored database id>/Files/LandingZone/TableBhttps://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。
所有列都应在文件 _metadata.json 中有一个数据类型。 当前支持的数据类型如下：
| 支持的数据类型 | DESCRIPTION |
|---|---|
| 加倍 | 需要高精度时使用的具有十进制数的数字（例如 3.14159）。 |
| 单身 | 具有十进制数但精度低于 Double 的数字（例如 3.14）。 |
| Int16 | 一个小整数，通常介于 -32,768 和 32,767 之间。 |
| Int64 | 用于大量计数或 ID 的一个非常大的整数。 |
| Int32 | 标准整数，通常用于计数或索引。 |
| 日期时间 | 完整日期和时间值（例如，2025-06-17 14：30：00）。 |
| IDate | 没有时间的日历日期（例如 2025-06-17）。 |
| ITime | 没有日期的一天时间（例如 14：30：00）。 |
| 字符串 | 名称、标签或说明等文本数据。 |
| 布尔型 | 真假值，通常用于切换选项或是/否选择。 |
| ByteArray | 原始二进制数据，如文件、图像或编码内容。 |
登陆区域中的事件文件
如果您是正在实施开放镜像解决方案的合作伙伴，或者希望向我们提供有关镜像到 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必须为带分隔符的文本文件。RowSeparator用于分隔行的字符。 默认值为 \r\n。 也支持\n和\r。ColumnSeparator用于分隔列的字符。 默认值为 ,。 此外还支持;、|和\t。QuoteCharacter用于引用带有分隔符的值的字符。 默认值为 "。 可以是'或空字符串。EscapeCharacter用于转义带引号内的引号。 默认值为 \。 也可以是/、"，或者为空。NullValuenull 值的字符串表示形式。 可以是 ""、"N/A"，"null"等等。Encoding文件的字符编码。 默认值为 UTF-8。 支持各种编码，包括ascii、utf-16等等windows-1252。SchemaDefinition定义列名、类型和是否允许为空。 不支持架构演变。 FileFormat数据文件的格式。 如果未指定，默认为 CSV。 必须为非 CSV 格式使用"DelimitedText"。FileExtension指定文件扩展名，例如 .tsv，.psv。使用 DelimitedText时必需 。例如，
_metadata.json包含四列的数据文件的文件.tsv：{ "KeyColumns": [ "id" ], "ConditionalUpdateColumn": "seqNum", "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" } }
格式要求
写入登陆区域的所有文件具有以下格式：
<rowMarker><DataColumns>
rowMarker：列名是__rowMarker__（包括rowMarker前后的两个下划线）。__rowMarker__价值观和行为：__rowMarker__（场景）如果目标中不存在具有相同键列的行 如果目标中存在具有相同键列的行 0（插入）将行插入目标 将行插入目标，不针对重复键列检查进行验证。 1（更新）将行插入目标，不执行验证或抛出异常来检查是否存在具有相同键列的行。 更新具有相同键列的行。 2（删除）没有数据变化，不会执行验证或异常检查以确认是否存在具有相同键列的行。 删除具有相同键列的行。 4（Upsert）将行插入目标，不执行验证或抛出异常来检查是否存在具有相同键列的行。 更新具有相同键列的行。 行顺序：文件中的所有日志都应按事务中应用的自然顺序排列。 对于多次更新的同一行来说，这一点很重要。 开放镜像使用文件中的顺序应用更改。
文件顺序：文件应该以单调递增的编号添加。
文件名：文件名为 20 位数字，例如第一个文件为
00000000000000000001.parquet，第二个文件为00000000000000000002.parquet。 文件名应以连续编号表示。 镜像服务会自动删除文件，但最后一个文件将保留，以便发布者系统可以参考该文件来按顺序添加下一个文件。
重要
该 __rowMarker__ 列必须是列表中的最后一列
初始加载
对于向开放镜像数据库初次加载数据，初始数据文件中的 __rowMarker__ 是可选的，但不建议使用。 当 __rowMarker__ 不存在时，镜像会将整个文件视为 INSERT。
为了获得更好的性能和准确的指标，__rowMarker__ 仅在应用更新/删除/更新插入操作的增量更改时是必填字段。
增量更改
开放镜像会按顺序读取增量更改，并将其应用于目标 Delta 表。 顺序在更改日志和文件顺序中为隐式。
一旦在任何行/文件中找到 __rowMarker__ 列，数据更改即被视为增量更改。
更新的行必须包含所有列的完整行数据。
以下是将 EmployeeLocation E0001 的 EmployeeID 从 Redmond 更改为 Bellevue 的行历史记录的一些示例 Parquet 数据。 在此应用场景中，EmployeeID 列已标记为登陆区域中的元数据文件中的键列。
EmployeeID,EmployeeLocation,__rowMarker__
E0001,Redmond,0
E0002,Redmond,0
E0003,Redmond,0
E0001,Bellevue,1
如果更新了键列，则应通过对之前的键列执行 DELETE 操作并使用新键和数据对行执行 INSERT 来呈现。 例如，将 __rowMarker__ E0001 的唯一标识符 EmployeeID 更改为 E0002 的行历史记录。 无需为 DELETE 行提供所有列数据，只需提供键列。
EmployeeID,EmployeeLocation,__rowMarker__
E0001,Bellevue,0
E0001,NULL,2
E0002,Bellevue,0
表操作
开放镜像支持表操作，例如添加、删除和重命名表。
添加表
开放镜像会选取应用程序添加到登陆区域的任何表。 开放镜像在每次迭代中扫描新表。
删除表
开放镜像可跟踪文件夹名称。 如果删除了表文件夹，则开放镜像会删除镜像数据库中的表。
如果重新创建文件夹，则开放镜像会删除该表，并使用文件夹中的新数据重新创建该表，这是通过跟踪文件夹的 ETag 来实现的。
尝试删除表时，可以尝试删除该文件夹，但开放镜像功能可能仍在使用该文件夹中的数据，导致发布者无法删除。
重命名表
若要重命名表，请删除并重新创建包含初始数据和增量数据的文件夹。 需要将数据重新填充到重命名的表中。
架构
可以在架构文件夹中指定表路径。 架构登陆区域应具有文件夹名称 <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/TableAhttps://onelake.dfs.fabric.microsoft.com/<workspace id>/<mirrored database id>/Files/LandingZone/Schema1.schema/TableBhttps://onelake.dfs.fabric.microsoft.com/<workspace id>/<mirrored database id>/Files/LandingZone/Schema2.schema/TableC
表列和列操作
列类型
- 登陆区域中支持简单 Parquet 类型。
- 复杂类型应写为 JSON 字符串。
- 二进制复杂类型（如地理、图像等）可以作为二进制类型存储在登陆区域中。
添加列
如果向 Parquet 或 CSV 文件添加新列，则打开的镜像会将这些列添加到 Delta 表。
删除列
如果从新日志文件中删除了列，则开放镜像会将这些列的 NULL 存储在新行中，而旧行会将这些列存储在数据中。 若要删除列，请删除表并在登陆区域中再次创建表文件夹，这将导致使用新架构和数据重新创建 Delta 表。
开放镜像始终会将先前版本的已添加数据中的所有列联合起来。 若要移除列，请重新创建表/文件夹。
更改列类型
若要更改列类型，请删除包含初始和增量数据的文件夹，然后使用新列类型重新创建。 提供新的列类型而不重新创建表会导致错误，该表的复制将停止。 重新创建表文件夹后，将使用新数据和架构恢复复制。
重命名列
若要重命名列，请删除表文件夹，并使用所有数据和新的列名重新创建该文件夹。
清理过程
用于开放镜像的清理过程会将所有已处理的文件移动到一个名为 _ProcessedFiles 或 _FilesReadyToDelete 的单独文件夹中。 七天后，将从此文件夹中删除文件。