Aller au contenu principal
Dernière mise à jour le

Gestion de schémas

Cette analyse approfondie explique comment Zerobus Ingest dans Lakeflow Connect valide les enregistrements entrants par rapport au schéma de votre table Delta, et comment concevoir votre schéma pour des données partielles ou évolutives.

De nombreux producteurs écrivent dans la même table Delta, et Zerobus Ingest valide chaque enregistrement par rapport au schéma de table fixe unique : un enregistrement est accepté ou rejeté dans son ensemble, et les champs non conformes sont capturés dans une colonne VARIANT de secours lorsqu'une telle colonne est configurée

La table est le contrat​

Le schéma de votre table Delta constitue le contrat faisant autorité pour ce que Zerobus Ingest accepte. Zerobus Ingest contrôle chaque enregistrement par rapport à ce contrat, mais vous choisissez le degré de rigueur ou de flexibilité de celui-ci. Le même service peut appliquer un schéma rigide, accepter un sous-ensemble flexible de colonnes ou capturer tout ce qui ne correspond pas, selon la façon dont vous définissez votre table.

  • Zerobus Ingest contrôle l’accès aux données. Il valide chaque enregistrement par rapport à la table cible et rejette tout ce qui ne correspond pas. Il ne devine jamais et ne supprime jamais de colonnes silencieusement.
  • Vous définissez le contrat. Marquer des colonnes comme requises ou nullables, et ajouter une colonne de secours, est la façon dont vous décidez ce qui « correspond ».
  • Zerobus Ingest n’augmente jamais votre table. Il n’ajoute pas de colonnes, ne modifie pas les types et n’évolue pas le schéma pour s’adapter à un enregistrement. Vous faites évoluer ce que Zerobus Ingest accepte en faisant évoluer la table, et non l’inverse.

La section suivante présente trois façons de définir ce contrat, de la plus permissive à la plus stricte, jusqu'à la méthode fourre-tout.

Comment les enregistrements sont mis en correspondance avec la table​

Un enregistrement doit correspondre à la table de destination : il doit contenir, au minimum, toutes les colonnes non nullables de la table. Les colonnes pouvant être nulles dans la table peuvent être omises de l’enregistrement et sont écrites sous la forme NULL. L’omission d’une colonne nullable est traitée comme un changement sans rupture ; vous pouvez donc ajouter des colonnes nullables à une table et continuer à ingérer des enregistrements plus anciens qui ne les incluent pas.

Zerobus Ingest renvoie une erreur lorsqu'un enregistrement ne correspond pas à la table. Sont concernés :

  • Une colonne non nulle manquante.
  • Un nom de colonne qui n’existe pas dans la table Delta (sauf si vous configurez une colonne de secours).
  • Une colonne dont le type n’est pas compatible avec la table Delta. Pour les types de données Delta et Protobuf pris en charge, consultez Types de données pris en charge.

Trois façons de définir le contrat​

La façon dont vous définissez la table détermine le degré de rigueur ou de tolérance de l'ingestion. Les trois scénarios ci-dessous vont du plus tolérant au plus strict, jusqu'au scénario fourre-tout.

Scénario 1 : toutes les colonnes sont facultatives (accepter un sous-ensemble)​

Rendre chaque colonne nullable. Les producteurs peuvent ensuite envoyer n'importe quel sous-ensemble de colonnes, et les colonnes omises sont écrites sous la forme NULL. Les enregistrements qui incluent une colonne absente de la table sont toujours rejetés.

SQL
CREATE TABLE main.default.air_quality (
  device_name STRING,
  temp INT,
  humidity INT);
  • {"device_name": "sensor-1", "temp": 22, "humidity": 55}: accepté. Toutes les colonnes sont présentes.
  • {"device_name": "sensor-1"}: accepté. temp et humidity sont nullables, ils sont donc écrits sous la forme NULL.
  • {"device_name": "sensor-1", "temp": 22, "region": "us-west"}: rejeté. region n'existe pas dans la table.

Scénario 2 : colonnes obligatoires (imposer des champs spécifiques)​

Marquez les colonnes NOT NULL pour les rendre obligatoires. Chaque enregistrement doit fournir ces colonnes, faute de quoi il est rejeté. Il s’agit de l’extrémité stricte du spectre : utilisez-la lorsqu’un champ doit toujours être présent.

SQL
CREATE TABLE main.default.air_quality (
  device_name STRING NOT NULL,
  temp INT NOT NULL,
  humidity INT);
  • {"device_name": "sensor-1", "temp": 22, "humidity": 55}: accepté. Toutes les colonnes requises sont présentes.
  • {"device_name": "sensor-1", "temp": 22}: accepté. humidity peut être nul, il est donc écrit sous la forme NULL.
  • {"device_name": "sensor-1"}: rejeté. temp n’est pas nullable et est manquant.

Scénario 3 : colonne de récupération (tout capturer)​

Ajoutez une colonne de secours VARIANT pour capturer les champs qui ne correspondent pas au schéma, au lieu de rejeter l'enregistrement. Les champs qui correspondent à la table sont écrits dans leurs colonnes comme d'habitude. Tous les champs supplémentaires ou non conformes sont regroupés dans la colonne de secours sous forme d'objet JSON. Il s'agit de l'extrémité la plus permissive du spectre : les champs supplémentaires et les incohérences de type dans les colonnes nullables sont capturés au lieu d'être rejetés. Un enregistrement est toujours rejeté s'il omet une colonne requise (non nullable), car la colonne de secours ne peut pas fournir une valeur exigée par le schéma. La colonne de secours est en version bêta et prend actuellement en charge l'ingestion au format JSON.

  • {"device_name": "sensor-1", "temp": 22, "region": "us-west"}: accepté. region n’existe pas dans la table ; il est donc capturé dans la colonne de secours au lieu d’être rejeté.

Pour savoir comment configurer une colonne de récupération et connaître les règles exactes, consultez Zerobus rescue column.

évolution des schémas​

Zerobus Ingest n’effectue pas d’évolution automatique de votre table cible. Lorsque la forme de vos données change, faites d’abord évoluer la table (par exemple, avec ALTER TABLE), puis envoyez les enregistrements vers le nouveau schéma.

L’ajout d’une colonne nullable est un changement sans rupture : les producteurs existants qui n’envoient pas la nouvelle colonne continuent de fonctionner, et leurs enregistrements reçoivent NULL pour celle-ci. Cela vous permet de déployer les changements de schéma et les changements de producteur indépendamment.

Schéma Protobuf​

Lorsque vous ingérez avec Protocol Buffers (protobuf), la même règle d’ajustement s’applique à votre définition de message protobuf : elle doit contenir au minimum toutes les colonnes non nullables de la table Delta, et peut omettre celles qui sont nullables.

Les éléments suivants s’appliquent également au schéma protobuf :

  • Zerobus Ingest ne prend pas en charge les schémas proto comportant plus de 2 000 colonnes.
  • Zerobus Ingest prend uniquement en charge les noms de table et de colonne composés de lettres ASCII, de chiffres et de traits de soulignement.
  • Zerobus Ingest ne prend pas en charge l’utilisation d’un schéma proto différent pour les Opérations de « création de Stream » et d’« enregistrement d’ingestion ».
Sur cette page