Abrir requisitos y formato de zona de aterrizaje de creación de reflejo

En este artículo se detallan los requisitos de operación de tabla y columna y zona de aterrizaje para la creación de reflejo abierta en Microsoft Fabric.

Una vez que haya creado la base de datos reflejada abierta a través del portal de Fabric o la API pública en el área de trabajo de Fabric, obtendrá una dirección URL de zona de aterrizaje en OneLake en la página principal del elemento de base de datos reflejada. Esta zona de aterrizaje es donde la aplicación crea un archivo de metadatos y los datos de tierra en formato de texto parquet o delimitado, incluido CSV. Los archivos se pueden comprimir o comprimir con Snappy, GZIP o ZSTD. Para obtener más información, consulte archivos de datos y formato admitidos.

Zona de aterrizaje

Para cada base de datos reflejada, hay una ubicación de almacenamiento única en OneLake para metadatos y tablas delta. La creación de reflejo abierta proporciona una carpeta de zona de aterrizaje para que la aplicación cree un archivo de metadatos e inserte datos en OneLake. La creación de reflejo supervisa estos archivos en la zona de aterrizaje y lee la carpeta de nuevas tablas y datos agregados.

Por ejemplo, si tiene tablas (Table A, Table B, Table C) que se van a crear en la zona de aterrizaje, cree carpetas como las siguientes direcciones 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

Archivo de metadatos en la zona de aterrizaje

Cada carpeta de tabla debe contener un _metadata.json archivo.

Este archivo de metadatos de tabla contiene un registro JSON para especificar actualmente solo las columnas de clave únicas como keyColumns.

Por ejemplo, para declarar columnas C1 y C2 como una clave única compuesta para la tabla:

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

Si no se especifica keyColumns o _metadata.json, no es posible actualizar o eliminar. Este archivo se puede agregar en cualquier momento, pero una vez agregado keyColumns no se puede cambiar.

Archivo de eventos en la zona de aterrizaje

Si es un socio que implementa una solución de replicación abierta o un cliente que desee proporcionar más detalles sobre el tipo de origen que está replicando en OneLake, hemos agregado un nuevo archivo _partnerEvents.json. Esto no es necesario, pero se recomienda encarecidamente.

Ejemplo:

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

Requisitos del _partnerEvents.json archivo:

• El _partnerEvents.json archivo debe colocarse en el nivel de base de datos reflejado en la zona de aterrizaje, no por tabla.
• sourceType puede ser cualquier cadena descriptiva que represente el origen. No hay restricciones en este valor, por ejemplo: "SQL", "Oracle", "Salesforce", etc.
• partnerName se puede establecer en cualquier nombre de su elección y puede ser representativo del nombre de su organización. Mantenga el nombre coherente en todas las bases de datos reflejadas.

Archivo de datos y formato en la zona de aterrizaje

La creación de reflejo abierta admite la ingesta de datos en formatos de texto parquet o delimitados. Los archivos se pueden comprimir o comprimir con Snappy, GZIP o ZSTD.

Requisitos de Parquet

Requisitos de texto delimitados

• Para el formato de texto delimitado, el archivo debe tener una fila de encabezado en la primera fila.

• Para el texto delimitado, proporcione información adicional en el _metadata.json archivo. La FileExtension propiedad es necesaria. Los archivos de texto delimitados tienen las siguientes propiedades y valores predeterminados:

  Propiedad	Description	Notas
  FirstRowAsHeader	True/false para el encabezado de primera fila.	Se requiere que sea true para los archivos de texto delimitados.
  RowSeparator	Carácter usado para separar filas.	El valor predeterminado es \r\n. También admite \n y \r.
  ColumnSeparator	Carácter usado para separar columnas.	El valor predeterminado es ,. También admite ;, |y \t.
  QuoteCharacter	Carácter usado para comillas de valores que contienen delimitadores.	El valor predeterminado es ". También puede ser o una ' cadena vacía.
  EscapeCharacter	Se usa para escape entre comillas dentro de valores entre comillas.	El valor predeterminado es \. También puede ser /, "o vacío.
  NullValue	Representación de cadena de valores NULL.	Puede ser "", "N/A", "null", etc.
  Encoding	Codificación de caracteres del archivo.	El valor predeterminado es UTF-8. Admite una amplia gama de codificaciones, como ascii, utf-16, windows-1252etc.
  SchemaDefinition	Define los nombres de columna, los tipos y la nulabilidad.	No se admite la evolución del esquema.
  FileFormat	Formato del archivo de datos.	El valor predeterminado es CSV si no se especifica. Debe ser "DelimitedText" para formatos distintos de CSV.
  FileExtension	Especifica la extensión de archivo como .tsv, .psv.	Obligatorio cuando se usa DelimitedText.

  Por ejemplo, el _metadata.json archivo de un .tsv archivo de datos con cuatro columnas:

  {
  "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"
                           }
  }
  

• Solo se espera que los formatos de texto delimitados tengan un tipo de datos en el archivo _metadata.json. Los archivos Parquet no requieren especificar la información del tipo de columna. Los tipos de datos admitidos actualmente:

Requisitos de formato

Todos los archivos escritos en la zona de aterrizaje tienen el siguiente formato:

<rowMarker><DataColumns>

• rowMarker: el nombre de columna es __rowMarker__ (incluidos dos caracteres de subrayado antes y después rowMarkerde ). __rowMarker__ valores y comportamientos:

  __rowMarker__ (Escenario)	Si la fila no existe con las mismas columnas de clave en el destino	Si la fila existe con las mismas columnas de clave en el destino
  0 (Insertar)	Insertar la fila en el destino	Inserte la fila en el destino, sin validación de la comprobación de columnas de clave dup.
  1 (Actualización)	Inserte la fila en el destino, sin validación o excepción para comprobar la existencia de fila con la misma columna de clave.	Actualice la fila con la misma columna de clave.
  2 (Eliminar)	Sin cambio de datos, sin validación o excepción para comprobar la existencia de fila con la misma columna de clave.	Elimine la fila con la misma columna de clave.
  4 (Inserción/Actualización)	Inserte la fila en el destino, sin validación o excepción para comprobar la existencia de fila con la misma columna de clave.	Actualice la fila con la misma columna de clave.

• Orden de fila: todos los registros del archivo deben estar en orden natural, tal como se aplica en la transacción. Esto es importante para que la misma fila se actualice varias veces. La creación de reflejo abierta aplica los cambios mediante el orden de los archivos.

• Orden de archivo: los archivos se deben agregar en números que aumentan de forma monotónica.

• Nombre de archivo: el nombre de archivo es de 20 dígitos, como 00000000000000000001.parquet para el primer archivo y 00000000000000000002.parquet para el segundo. Los nombres de archivo deben estar en números continuos. El servicio de creación de reflejo eliminará los archivos automáticamente, pero el último archivo se dejará para que el sistema del publicador pueda hacer referencia a él para agregar el siguiente archivo en secuencia.

Archivos no sequentiales

También se admiten archivos no secuenciales; los archivos se leerán basándose en su marca de tiempo. Para especificar esto y predefinir cambios como "upsert" en lugar de como inserciones, actualice el archivo _metadata.json de la siguiente manera:

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

El 'valor predeterminado de upsert' no depende de los archivos no secuenciales. Se admiten todas las combinaciones siguientes:

• Configure fileDetectionStrategy como LastUpdateTimeFileDetection y establezca isUpsertDefaultRowMarker como verdadero.
• Solo tiene isUpsertDefaultRowMarker como true.
• Solo tiene fileDetectionStrategy como LastUpdateTimeFileDetection.
• Predeterminado

Carga inicial

Para la carga inicial de datos en una base de datos reflejada abierta, __rowMarker__ en el archivo de datos inicial es opcional y no se recomienda. La creación de reflejo trata todo el archivo como INSERT cuando __rowMarker__ no existe.

Para mejorar el rendimiento y las métricas precisas, __rowMarker__ es un campo obligatorio solo para que los cambios incrementales apliquen la operación update/delete/upsert.

Cambios incrementales

La creación de reflejo abierta lee los cambios incrementales en orden y los aplica a la tabla Delta de destino. El orden es implícito en el registro de cambios y en el orden de los archivos.

Los cambios de datos se consideran cambios incrementales una vez que la __rowMarker__ columna se encuentra desde cualquier fila o archivo.

Las filas actualizadas deben contener los datos de fila completos, con todas las columnas.

Estos son algunos datos parquet de ejemplo del historial de filas para cambiar el EmployeeLocation valor de E0001 EmployeeID de Redmond a Bellevue. En este escenario, la EmployeeID columna se ha marcado como una columna de clave en el archivo de metadatos de la zona de aterrizaje.

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

Si se actualizan las columnas de clave, debe presentarse mediante DELETE en columnas de clave anteriores y filas INSERT con nuevas claves y datos. Por ejemplo, el historial de filas para cambiar el __rowMarker__ identificador único de EmployeeID E0001 a E0002. No es necesario proporcionar todos los datos de columna para una fila DELETE, solo las columnas de clave.

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

Operaciones de tabla

La creación de reflejo abierta admite operaciones de tabla como agregar, quitar y cambiar el nombre de las tablas.

Agregar tabla

Abrir la creación de reflejo recoge cualquier tabla agregada a la zona de aterrizaje por la aplicación. Abra los exámenes de creación de reflejo de las nuevas tablas en cada iteración.

Colocar tabla

La creación de reflejo abierta realiza un seguimiento del nombre de la carpeta. Si se elimina una carpeta de tabla, la creación de reflejo abierta quita la tabla en la base de datos reflejada.

Si se vuelve a crear una carpeta, la creación de reflejo abierta quita la tabla y la vuelve a crear con los nuevos datos de la carpeta, realizado mediante el seguimiento de la ETag de la carpeta.

Al intentar quitar una tabla, puede intentar eliminar la carpeta, pero existe la posibilidad de que la creación de reflejo abierta siga usando los datos de la carpeta, lo que provoca un error de eliminación para el publicador.

Cambiar nombre de tabla

Para cambiar el nombre de una tabla, quite y vuelva a crear la carpeta con datos iniciales e incrementales. Los datos deberán volver a rellenarse en la tabla cuyo nombre ha cambiado.

Schema

Se puede especificar una ruta de acceso de tabla dentro de una carpeta de esquema. Una zona de aterrizaje de esquema debe tener un <schemaname>.schema nombre de carpeta. Puede haber varios esquemas y puede haber varias tablas en un esquema.

Por ejemplo, si tiene esquemas (Schema1, Schema2) y tablas (Table A, Table B, Table C) que se van a crear en la zona de aterrizaje, cree carpetas como las siguientes rutas de acceso en 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

Columnas de tabla y operaciones de columna

Tipos de columna

• Los tipos de parquet simples se admiten en la zona de aterrizaje.
• Los tipos complejos se deben escribir como una cadena JSON.
• Los tipos complejos binarios, como geography, images, etc. se pueden almacenar como tipo binario en la zona de aterrizaje.

Agregar columna

Si se agregan nuevas columnas a los archivos parquet o CSV, la creación de reflejo abierta agrega las columnas a las tablas delta.

Eliminar columna

Si se quita una columna de los nuevos archivos de registro, abra almacenes NULL de creación de reflejo para esas columnas en filas nuevas y las filas antiguas tengan las columnas presentes en los datos. Para eliminar la columna, quite la tabla y vuelva a crear la carpeta de tabla en la zona de aterrizaje, lo que dará lugar a la recreación de la tabla Delta con nuevos esquemas y datos.

La creación de reflejo abierta siempre combina todas las columnas de la versión anterior de los datos agregados. Para quitar una columna, vuelva a crear la tabla o carpeta.

Cambiar el tipo de columna

Para cambiar un tipo de columna, quite y vuelva a crear la carpeta con datos iniciales e incrementales con el nuevo tipo de columna. Proporcionar un nuevo tipo de columna sin volver a crear la tabla genera un error y la replicación de esa tabla se detendrá. Una vez que se vuelva a crear la carpeta de tabla, la replicación se reanuda con nuevos datos y esquema.

Cambiar nombre de columna

Para cambiar el nombre de una columna, elimine la carpeta table y vuelva a crearla con todos los datos y con el nuevo nombre de columna.

Proceso de limpieza

Un proceso de limpieza para abrir la creación de reflejo mueve todos los archivos procesados a una carpeta independiente denominada _ProcessedFiles o _FilesReadyToDelete. Después de siete días, los archivos se quitan de esta carpeta.

Paso siguiente

Contenido relacionado

• Supervisión de la replicación de base de datos reflejada en Fabric