Требования к зоне приземления для зеркального отображения и её формат

2025-07-17

В этой статье описываются требования к зоне посадки и операции с таблицами или столбцами для открытого зеркального отображения в Microsoft Fabric.

После создания открытой зеркальной базы данных с помощью портала Fabric или общедоступного API в рабочей области Fabric вы получите URL-адрес целевой зоны в OneLake на домашней странице зеркального элемента базы данных. В этой посадочной зоне ваше приложение создает файл метаданных и размещает данные в формате 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 является обязательным. Текстовые файлы с разделителями имеют следующие свойства и значения по умолчанию:

Недвижимость	Описание	Примечания.
`FirstRowAsHeader`	Истина/ложь для заголовка первой строки.	Должно быть `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" ],
"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"
                         }
}

Ожидается, что только текстовые форматы с разделителями имеют тип данных в файле _metadata.json. Файлы Parquet не требуют указания информации о типе столбца. Типы данных, поддерживаемые в настоящее время:

Поддерживаемый тип данных	Описание
`Double`	Число с десятичными знаками, используемое при необходимости высокой точности (например, 3.14159).
`Single`	Число с десятичными знаками, но менее точным, чем Double (например, 3.14).
`Int16`	Небольшое целое число, обычно от -32 768 до 32 767.
`Int64`	Очень большое число, используемое для больших подсчетов или идентификаторов.
`Int32`	Стандартное целое число, обычно используемое для подсчета или индексирования.
`DateTime`	Полное значение даты и времени (например, 2025-06-17 14:30:00).
`IDate`	Дата календаря без времени (например, 2025-06-17).
`ITime`	Время дня без даты (например, 14:30:00).
`String`	Текстовые данные, такие как имена, метки или описания.
`Boolean`	Истинное или ложное значение, часто используемое для переключателей или да/нет вариантов.
`ByteArray`	Необработанные двоичные данные, такие как файлы, изображения или закодированное содержимое.

Требования к формату

Все файлы, записанные в зону загрузки, имеют следующий формат:

<rowMarker><DataColumns>

rowMarker: имя столбца это __rowMarker__ (включая два символа подчеркивания до и после rowMarker). __rowMarker__ значения и поведение:

`__rowMarker__` (Сценарий)	Если строка не существует с такими же ключевыми столбцами в целевом месте	Если в целевой базе данных существует строка с такими же ключевыми столбцами
`0` (Вставка)	Вставьте строку в место назначения	Вставьте строку в пункт назначения без проверки дублирующего ключевого столбца.
`1` (Обновление)	Вставьте строку в место назначения, не проверяя наличие строки с таким же ключевым столбцом, без валидации или исключения.	Обновите строку с одним и тем же ключевым столбцом.
`2` (Удаление)	Отсутствие изменения данных, отсутствует проверка или обработка исключений для проверки наличия строки с таким же ключевым столбцом.	Удалите строку с таким же ключевым столбцом.
`4` (Обновление или вставка)	Вставьте строку в место назначения, не проверяя наличие строки с таким же ключевым столбцом, без валидации или исключения.	Обновите строку с одним и тем же ключевым столбцом.

Порядок строк: все логи в файле должны быть в естественном порядке в соответствии с их применением в транзакции. Это важно для одной строки, обновляемой несколько раз. Открытое зеркалирование применяет изменения в соответствии с порядком в файлах.
Порядок файлов: файлы следует добавлять в монотонно увеличивающееся число.
Имя файла: 20 цифр, например 00000000000000000001.parquet для первого файла, а 00000000000000000002.parquet для второго — 20 цифр. Имена файлов должны находиться в непрерывных числах. Файлы будут удалены службой зеркального отображения автоматически, но последний файл будет оставлен, чтобы система издателя могли ссылаться на него, чтобы добавить следующий файл в последовательность.

Это важно

Столбец __rowMarker__ должен быть последним столбцом в списке

Начальная загрузка

Для начальной загрузки данных в открытую зеркальную базу данных __rowMarker__ в исходном файле данных является необязательным и не рекомендуется. Зеркалирование обрабатывает весь файл как вставку, если __rowMarker__ отсутствует.

Для повышения производительности и точности метрик поле __rowMarker__ является обязательным только для применения операций изменения, удаления или вставки при поэтапных изменениях.

Постепенные изменения

Открытое зеркальное отображение считывает инкрементальные изменения в заданном порядке и применяет их к целевой таблице Delta. Порядок подразумевается в журнале изменений и в порядке расположения файлов.

Изменения данных считаются добавочными изменениями после того, как столбец __rowMarker__ найден из любой строки или файла.

Обновленные строки должны содержать полные данные строки со всеми столбцами.

Ниже приведены примеры данных Parquet из журнала истории строк для изменения EmployeeLocation на EmployeeID E0001 с Redmond на Bellevue. В этом сценарии 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/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 добавляются новые столбцы, открытое зеркалирование добавляет эти столбцы в delta-таблицы.

Удалить столбец

Если столбец удаляется из новых файлов журнала, открытое зеркальное хранение использует NULL для этих удалённых столбцов в новых строках, тогда как старые строки содержат столбцы, присутствующие в данных. Чтобы удалить столбец, удалите таблицу и создайте папку таблицы в целевой зоне еще раз, что приведет к воссозданию таблицы Delta с новой схемой и данными.

Открытое зеркалирование всегда объединяет все столбцы из предыдущей версии для добавленных данных. Чтобы удалить столбец, создайте заново таблицу или папку.

Изменение типа столбца

Чтобы изменить тип столбца, удалите и повторно создайте папку с начальными и добавочными данными с новым типом столбца. Предоставление нового типа столбца без повторного создания таблицы приводит к ошибке, и репликация для этой таблицы остановится. После повторного создания папки таблицы репликация возобновляется с новыми данными и схемой.

Переименование столбца

Чтобы переименовать столбец, удалите папку таблицы и создайте папку со всеми данными и новым именем столбца.

Процесс очистки

Процесс очистки для открытия зеркального отображения перемещает все обработанные файлы в отдельную папку с именем _ProcessedFiles или _FilesReadyToDelete. Через семь дней файлы удаляются из этой папки.

Следующий шаг

Руководство по настройке открытых зеркальных баз данных Microsoft Fabric

Мониторинг зеркальной репликации базы данных Fabric