Configuration requise et format de la zone d’atterrissage de mise en miroir

Cet article détaille les exigences relatives aux opérations de zone d’atterrissage et de table/colonne pour la mise en miroir ouverte dans Microsoft Fabric.

Une fois que vous avez créé votre base de données mise en miroir ouverte via le portail Fabric ou l’API publique dans votre espace de travail Fabric, vous obtenez une URL de zone d’atterrissage dans OneLake dans la page d’accueil de votre élément de base de données mis en miroir. Cette zone d’atterrissage est l’emplacement où votre application crée un fichier de métadonnées et des données terrestres au format Parquet ou texte délimité, y compris CSV. Les fichiers peuvent être décompressés ou compressés avec Snappy, GZIP ou ZSTD. Pour plus d’informations, consultez les fichiers de données et le format pris en charge.

Zone d’atterrissage

Pour chaque base de données mise en miroir, il existe un emplacement de stockage unique dans OneLake pour les métadonnées et les tables delta. La mise en miroir ouverte fournit un dossier de zone d’atterrissage pour que l’application crée un fichier de métadonnées et envoie des données dans OneLake. La mise en miroir surveille ces fichiers dans la zone d’atterrissage et lit le dossier pour les nouvelles tables et données ajoutées.

Par exemple, si vous avez des tables (Table A, Table B, Table C) à créer dans la zone d’atterrissage, créez des dossiers comme les URL suivantes :

• 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

Fichier de métadonnées dans la zone d’atterrissage

Chaque dossier de table doit contenir un _metadata.json fichier.

Ce fichier de métadonnées de table contient un enregistrement JSON pour spécifier uniquement les colonnes clés uniques en tant que keyColumns.

Par exemple, pour déclarer des colonnes C1 et C2 comme clé unique composée pour la table :

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

Si keyColumns ou _metadata.json n’est pas spécifié, alors les mises à jour et les suppressions ne sont pas possibles. Ce fichier peut être ajouté à tout moment, mais une fois ajouté keyColumns ne peut pas être modifié.

Fichier d’événements dans la zone d’atterrissage

Si vous êtes un partenaire qui implémente une solution de mise en miroir ouverte ou un client qui souhaite nous fournir plus de détails sur le type de source que vous mettent en miroir dans OneLake, nous avons ajouté un nouveau _partnerEvents.json fichier. Cela n’est pas obligatoire, mais il est fortement recommandé.

Exemple :

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

Conditions requises du _partnerEvents.json fichier :

• Le _partnerEvents.json fichier doit être placé au niveau de la base de données mise en miroir dans la zone d’atterrissage, et non par table.
• Il sourceType peut s’agir de n’importe quelle chaîne descriptive représentant la source. Il n’existe aucune contrainte sur cette valeur, par exemple : « SQL », « Oracle », « Salesforce », etc.
• Il partnerName peut être défini sur n’importe quel nom de votre choix et peut être représentatif du nom de votre organisation. Gardez le nom cohérent entre toutes les bases de données miroirs.

Fichier de données et format dans la zone d’atterrissage

La mise en miroir ouverte prend en charge l’entrée de données dans des formats parquet ou de texte délimité. Les fichiers peuvent être décompressés ou compressés avec Snappy, GZIP ou ZSTD.

Conditions requises pour Parquet

Exigences de texte délimitées

• Pour le format de texte délimité, le fichier doit avoir une ligne d’en-tête dans la première ligne.

• Pour le texte délimité, fournissez des informations supplémentaires dans votre _metadata.json fichier. La FileExtension propriété est requise. Les fichiers texte délimités ont les propriétés et les valeurs par défaut suivantes :

  Propriété	Descriptif	Remarques
  FirstRowAsHeader	True/false pour l’en-tête de première ligne.	Obligatoire pour les true fichiers texte délimités.
  RowSeparator	Caractère utilisé pour séparer les lignes.	La valeur par défaut est \r\n. Prend également en charge \n et \r.
  ColumnSeparator	Caractère utilisé pour séparer les colonnes.	La valeur par défaut est ,. Prend également en charge ;, |et \t.
  QuoteCharacter	Caractère utilisé pour citer des valeurs contenant des délimiteurs.	La valeur par défaut est ". Peut également être ' ou une chaîne vide.
  EscapeCharacter	Permet d’échapper des guillemets à l’intérieur des valeurs entre guillemets.	La valeur par défaut est \. Peut également être /, "ou vide.
  NullValue	Représentation sous forme de chaîne de valeurs Null.	Peut être "", "N/A", "null", etc.
  Encoding	Encodage de caractères du fichier.	La valeur par défaut est UTF-8. Prend en charge un large éventail d’encodages, notamment ascii, utf-16, windows-1252etc.
  SchemaDefinition	Définit les noms de colonnes, les types et la possibilité de nullabilité.	L’évolution du schéma n’est pas prise en charge.
  FileFormat	Format du fichier de données.	La valeur par défaut est si elle n’est CSV pas spécifiée. Doit être "DelimitedText" destiné aux formats autres que CSV.
  FileExtension	Spécifie l’extension de fichier comme .tsv, .psv.	Obligatoire lors de l’utilisation DelimitedTextde .

  Par exemple, le _metadata.json fichier d’un .tsv fichier de données avec quatre colonnes :

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

• Seuls les formats de texte délimités sont censés avoir un type de données dans le fichier _metadata.json. Les fichiers Parquet n’ont pas besoin de spécifier des informations de type de colonne. Les types de données actuellement pris en charge :

Configuration requise pour le format

Tous les fichiers écrits dans la zone d’atterrissage ont le format suivant :

<rowMarker><DataColumns>

• rowMarker: nom de colonne est __rowMarker__ (y compris deux traits de soulignement avant et après rowMarker). __rowMarker__ valeurs et comportements :

  __rowMarker__ (Scénario)	Si la ligne n’existe pas avec la ou les mêmes colonnes clés dans la destination	Si la ligne existe avec la ou les mêmes colonnes clés dans la destination
  0 (Insertion)	Insérer la ligne vers la destination	Insérez la ligne vers la destination, sans validation pour la vérification de colonne de clé dup.
  1 (Mise à jour)	Insérez la ligne vers la destination, sans validation/exception pour vérifier l’existence de la ligne avec la même colonne clé.	Mettez à jour la ligne avec la même colonne clé.
  2 (Supprimer)	Aucune modification de données, aucune validation/exception pour vérifier l’existence d’une ligne avec la même colonne clé.	Supprimez la ligne avec la même colonne clé.
  4 (Insertion ou mise à jour)	Insérez la ligne vers la destination, sans validation/exception pour vérifier l’existence de la ligne avec la même colonne clé.	Mettez à jour la ligne avec la même colonne clé.

• Ordre de ligne : tous les journaux d’activité du fichier doivent être dans l’ordre naturel comme appliqué dans la transaction. Cela est important pour la même ligne mise à jour plusieurs fois. La mise en miroir ouverte applique les modifications à l’aide de l’ordre dans les fichiers.

• Ordre de fichier : les fichiers doivent être ajoutés en nombres monotoniquement croissants.

• Nom de fichier : le nom de fichier est de 20 chiffres, comme 00000000000000000001.parquet pour le premier fichier et 00000000000000000002.parquet pour le deuxième. Les noms de fichiers doivent être en nombres continus. Les fichiers seront supprimés automatiquement par le service de mise en miroir, mais le dernier fichier sera laissé afin que le système d’éditeur puisse le référencer pour ajouter le fichier suivant dans la séquence.

Fichiers non séquentiels

Les fichiers non séquentiels sont également pris en charge ; les fichiers seront lus en fonction de leur horodatage. Pour spécifier cette valeur et la valeur par défaut pour les modifications upsert plutôt que les insertions, mettez à jour le fichier _metadata.json comme suit :

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

La fonction « default to upsert » ne dépend pas des fichiers non séquentiels. Toutes les combinaisons suivantes sont prises en charge :

• Sélectionner à la fois fileDetectionStrategy comme LastUpdateTimeFileDetection et isUpsertDefaultRowMarker comme vrai.
• Ayez seulement isUpsertDefaultRowMarker réglé sur true.
• Utilisez uniquement fileDetectionStrategy en tant que LastUpdateTimeFileDetection.
• Par défaut

Chargement initial

Pour la charge initiale des données dans une base de données mise en miroir ouverte, __rowMarker__ dans le fichier de données initial est facultatif et non recommandé. La mise en miroir traite l’intégralité du fichier en tant qu’insert lorsqu’il __rowMarker__ n’existe pas.

Pour améliorer les performances et les métriques précises, __rowMarker__ il s’agit d’un champ obligatoire uniquement pour les modifications incrémentielles pour appliquer l’opération de mise à jour/suppression/upsert.

Modifications incrémentielles

Ouvrez la mise en miroir lit les modifications incrémentielles dans l’ordre et les applique à la table Delta cible. L’ordre est implicite dans le journal des modifications et dans l’ordre des fichiers.

Les modifications de données sont considérées comme des modifications incrémentielles une fois que la __rowMarker__ colonne est trouvée à partir de n’importe quelle ligne/fichier.

Les lignes mises à jour doivent contenir les données de ligne complètes, avec toutes les colonnes.

Voici quelques exemples de données parquet de l’historique des lignes pour changer la EmployeeLocationEmployeeID version E0001 de Redmond à Bellevue. Dans ce scénario, la EmployeeID colonne a été marquée comme colonne clé dans le fichier de métadonnées dans la zone d’atterrissage.

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

Si des colonnes clés sont mises à jour, il doit être présenté par une fonction DELETE sur les colonnes clés précédentes et une ligne INSERT avec de nouvelles clés et des données. Par exemple, l’historique des lignes pour modifier l’identificateur __rowMarker__ unique de EmployeeID E0001 en E0002. Vous n’avez pas besoin de fournir toutes les données de colonne pour une ligne DELETE, uniquement les colonnes clés.

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

Opérations de table

La mise en miroir ouverte prend en charge les opérations de table telles que l’ajout, la suppression et le renommage des tables.

Ajouter une table

Ouvrez la mise en miroir récupère n’importe quelle table ajoutée à la zone d’atterrissage par l’application. Ouvrez les analyses de mise en miroir pour les nouvelles tables dans chaque itération.

Supprimer une table

La mise en miroir ouverte effectue le suivi du nom du dossier. Si un dossier de table est supprimé, l’ouverture de la mise en miroir supprime la table dans la base de données mise en miroir.

Si un dossier est recréé, l’ouverture de la mise en miroir supprime la table et la recrée avec les nouvelles données du dossier, effectuée en suivant l’ETag pour le dossier.

Lorsque vous tentez de supprimer une table, vous pouvez essayer de supprimer le dossier, mais il est possible que l’ouverture de la mise en miroir utilise toujours les données du dossier, ce qui provoque un échec de suppression pour l’éditeur.

Renommer la table

Pour renommer une table, supprimez et recréez le dossier avec des données initiales et incrémentielles. Les données doivent être renseignées à nouveau dans la table renommée.

Schema

Un chemin d’accès de table peut être spécifié dans un dossier de schéma. Une zone d’atterrissage de schéma doit avoir un <schemaname>.schema nom de dossier. Il peut y avoir plusieurs schémas et il peut y avoir plusieurs tables dans un schéma.

Par exemple, si vous avez des schémas (Schema1, Schema2) et des tables (Table A, , Table BTable C) à créer dans la zone d’atterrissage, créez des dossiers comme les chemins suivants dans 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

Colonnes de table et opérations de colonne

Types de colonnes

• Les types parquet simples sont pris en charge dans la zone d’atterrissage.
• Les types complexes doivent être écrits sous forme de chaîne JSON.
• Les types complexes binaires tels que la géographie, les images, etc. peuvent être stockés en tant que type binaire dans la zone d’atterrissage.

Ajouter une colonne

Si de nouvelles colonnes sont ajoutées aux fichiers Parquet ou CSV, la mise en miroir ouverte ajoute les colonnes aux tables delta.

Supprimer une colonne

Si une colonne est supprimée des nouveaux fichiers journaux, ouvrez les magasins NULL de mise en miroir pour ces colonnes dans les nouvelles lignes et les anciennes lignes ont les colonnes présentes dans les données. Pour supprimer la colonne, supprimez la table et créez à nouveau le dossier de la table dans la zone d’atterrissage, ce qui entraînera la récréation de la table Delta avec de nouveaux schémas et données.

L’ouverture de la mise en miroir unione toujours toutes les colonnes de la version précédente des données ajoutées. Pour supprimer une colonne, recréez la table/dossier.

Modifier le type de colonne

Pour modifier un type de colonne, supprimez et recréez le dossier avec des données initiales et incrémentielles avec le nouveau type de colonne. La fourniture d’un nouveau type de colonne sans recréer la table génère une erreur et la réplication de cette table s’arrête. Une fois le dossier de table recréé, la réplication reprend avec de nouvelles données et schémas.

Renommer la colonne

Pour renommer une colonne, supprimez le dossier de table et recréez le dossier avec toutes les données et avec le nouveau nom de colonne.

Processus de nettoyage

Un processus de nettoyage pour l’ouverture de la mise en miroir déplace tous les fichiers traités vers un dossier distinct appelé _ProcessedFiles ou _FilesReadyToDelete. Après sept jours, les fichiers sont supprimés de ce dossier.

Étape suivante

Contenu connexe

• Surveiller la réplication mise en miroir de la base de données Fabric