Aller au contenu principal
Dernière mise à jour le

Mettre à jour le schéma d’une table de streaming avec ALTER TABLE

info

Bêta

La mise à jour d’un schéma de table de streaming avec ALTER TABLE est en version bêta. Pour demander l’accès, inscrivez-vous à la version bêta.

ALTER TABLE prend en charge les modifications de schéma au niveau des colonnes : ajout, suppression et renommage de colonnes, ainsi que l'élargissement du type d'une colonne. Il s'agit d'opérations portant uniquement sur les métadonnées. Elles ne nécessitent pas de refresh complet, ne reset pas le point de contrôle de streaming et ne réingèrent pas les données.

remarque

Auto Loader suit son propre schéma source ; par conséquent, DROP COLUMN et RENAME COLUMN pourraient ne pas s’appliquer pleinement aux tables prises en charge par Auto Loader. Voir Les schémas sources Auto Loader ne sont pas mis à jour.

Opérations prises en charge​

Toutes les opérations nécessitent un pipeline qui publie dans Unity Catalog. Elles nécessitent également des métadonnées externes, sauf sur les tables gérées créées avec CREATE TABLE ... FLOW. Certaines opérations ont des exigences supplémentaires :

Opérations

Exigences supplémentaires

AJOUTER UNE COLONNE

Aucune exigence supplémentaire.

SUPPRIMER UNE COLONNE

Mode de mappage des colonnes name

RENOMMER LA COLONNE

Mode de mappage des colonnes name

ALTER COLUMN ... TYPE

Élargissement de type

Opérations

Exigences supplémentaires

AJOUTER UNE COLONNE

Aucune exigence supplémentaire.

SUPPRIMER UNE COLONNE

Mode de mappage des colonnes name

RENOMMER LA COLONNE

Mode de mappage des colonnes name

ALTER COLUMN ... TYPE

Élargissement de type

Activer les métadonnées externes​

Les Opérations sur les colonnes nécessitent des métadonnées externes sur le pipeline qui possède la table de streaming. S’il n’est pas activé, la commande échoue avec une erreur. Voir Activer l'accès aux données externes pour les tables de streaming et les vues matérialisées.

remarque

Les métadonnées externes ne sont pas requises pour les tables gérées dans les pipelines créés avec la syntaxe CREATE TABLE ... FLOW.

Définissez pipelines.externalMetadata.enabled sur true dans la configuration du pipeline :

JSON
{
  "configuration": {
    "pipelines.externalMetadata.enabled": "true"
  }
}

Pour définir ceci dans l'Lakeflow Pipelines Editor, sélectionnez les paramètres du pipeline et ajoutez pipelines.externalMetadata.enabled avec la valeur true.

Exécutez une mise à jour du pipeline après l'avoir activé. Les opérations sur la colonne ALTER TABLE sont disponibles à partir de ce moment.

Activer le mappage des colonnes​

DROP COLUMN et RENAME COLUMN nécessitent le mode de mappage de colonnes name. Définissez-le dans la définition du pipeline, ce qui l'appliquera lors de la prochaine mise à jour :

SQL
CREATE OR REFRESH STREAMING TABLE orders
  TBLPROPERTIES ('delta.columnMapping.mode' = 'name')
  AS SELECT * FROM STREAM read_files('/Volumes/main/sales/raw');
attention

L'activation du mappage des colonnes est irréversible et augmente les versions du protocole de lecture et d'écriture de la table. Les anciennes versions de Databricks Runtime et les lecteurs externes pourraient ne plus être en mesure de lire la table. Voir Évolution des schémas dans Databricks.

Activer l’élargissement de type​

ALTER COLUMN ... TYPE nécessite un élargissement de type. Sans cela, l’instruction échoue au lieu d’élargir la colonne. Activez-la pour chaque table du pipeline avec la configuration pipelines.enableTypeWidening :

JSON
{
  "configuration": {
    "pipelines.enableTypeWidening": "true"
  }
}

Ou activez-la pour une seule table avec la propriété de table delta.enableTypeWidening :

SQL
CREATE OR REFRESH STREAMING TABLE orders
  TBLPROPERTIES ('delta.enableTypeWidening' = 'true')
  AS SELECT * FROM STREAM read_files('/Volumes/main/sales/raw');

Les tables avec élargissement de type activé nécessitent Databricks Runtime 15.4 LTS ou une version ultérieure pour être lues. Voir l'élargissement de type dans LakeFlow Pipelines.

Mettre à jour le code source de votre pipeline après le ALTER​

ALTER TABLE modifie la table. Cela ne modifie pas le code source de votre pipeline. Si votre table de streaming déclare un schéma explicite, vous devez effectuer la même modification dans le code source du pipeline, sinon la prochaine mise à jour du pipeline réalignera la table sur le schéma déclaré. Il s’agit du comportement général décrit dans Limitation : mises à jour du pipeline et modifications effectuées avec ALTER.

Pour une table de streaming avec un schéma implicite, tel que CREATE OR REFRESH STREAMING TABLE st AS SELECT * FROM ..., aucune modification du code source n'est nécessaire.

Si le pipeline s'exécute selon un planning, une mise à jour déclenchée pourrait s'exécuter entre votre ALTER TABLE et votre modification de code source, et réconcilier la table avec le schéma déclaré. Pour éviter cela, suspendez le pipeline pendant que vous effectuez la modification correspondante :

  1. Suspendre le calendrier du pipeline.
  2. Exécuter l’instruction ALTER TABLE.
  3. Mettez à jour le code source du pipeline pour qu'il corresponde au nouveau schéma.
  4. Reprenez le planning du pipeline.

Gérer un changement de type de source incompatible​

Si une source modifie un type de colonne de manière incompatible, par exemple user_id de STRING vers INT, la mise à jour du pipeline échoue car Delta ne peut pas convertir la colonne existante. Migrez la colonne sur place au lieu d’exécuter un refresh complet :

SQL
-- 1. Add a column with the new type.
ALTER TABLE main.bronze.users ADD COLUMN user_id_new INT;

-- 2. Backfill it from the old column.
UPDATE main.bronze.users SET user_id_new = CAST(user_id AS INT);

-- 3. Drop the old column.
ALTER TABLE main.bronze.users DROP COLUMN user_id;

-- 4. Rename the new column into place.
ALTER TABLE main.bronze.users RENAME COLUMN user_id_new TO user_id;

Mettez ensuite à jour le code source du pipeline pour déclarer user_id comme INT et exécutez une mise à jour. La mise à jour réussit sans Reset de point de contrôle ni refresh complète.

L'étape 2 est une instruction DML sur une table de streaming, qui a ses propres exigences. Voir Ajouter, modifier ou supprimer des données dans une table de streaming cible. Si une query en aval effectue un stream à partir de cette table, vous devrez peut-être définir skipChangeCommits lors de sa lecture afin que le remplissage ne fasse pas échouer ce flux.

Gérer les changements de schéma source non additifs​

Lorsqu'une source lue par votre table de streaming supprime ou renomme une colonne, le Stream s'arrête et signale le changement au lieu de deviner votre intention. Confirmez le changement pour continuer :

JSON
{
  "configuration": {
    "spark.databricks.delta.streaming.allowSourceColumnDrop": "always",
    "spark.databricks.delta.streaming.allowSourceColumnRename": "always"
  }
}

Définissez chaque configuration sur always ou sur une version spécifique de table Delta :

  • always reconnaît toutes les modifications actuelles et futures de ce type pour le pipeline.
  • Un numéro de version reconnaît toutes les modifications de schéma jusqu’à cette version de la table source incluse. Recherchez la version dans l’historique de la table source avec DESCRIBE HISTORY, ou à partir de l’erreur signalée lorsque le stream s’arrête.
remarque

La reconnaissance d'un changement de source ne le propage pas à la table de streaming. Utilisez ALTER TABLE pour effectuer la modification correspondante sur la cible.

Limitations​

Les limitations suivantes s’appliquent lorsque vous mettez à jour un schéma de table de streaming avec ALTER TABLE.

  • Une full refresh régénère la table de streaming à partir du code source du pipeline ; les modifications de colonnes effectuées avec ALTER TABLE ne sont donc pas conservées. Effectuez la modification équivalente dans le code source du pipeline si vous avez besoin qu'elle survive à une refresh complète.
  • Auto Loader suit son schéma source indépendamment de la table de streaming. Pour qu'une DROP COLUMN ou RENAME COLUMN prenne effet sur une table prise en charge par Auto Loader, consultez Les schémas source d'Auto Loader ne sont pas mis à jour.
  • Les vues de streaming ne sont pas prises en charge. L’évolution des schémas ne fonctionne pas lorsqu’une vue de streaming se trouve sur le chemin de la table de streaming, couvrant à la fois les flux qui lisent à partir d’une vue de streaming et les flux définis à partir de celle-ci. Utilisez les opérations de colonne ALTER TABLE uniquement sur les tables de streaming dont les flux lisent directement depuis leurs sources.
  • DROP COLUMN et RENAME COLUMN sont bloqués sur les tables de streaming avec un flux AUTO CDC, qui suit l’état des données modifiées indexé sur les identifiants de colonne. La commande échoue avec une erreur. ADD COLUMN et ALTER COLUMN ... TYPE sont pris en charge.
  • Seules les colonnes de niveau supérieur sont prises en charge. Les modifications apportées aux champs imbriqués dans des structs, des tableaux ou des maps ne le sont pas.

Les schémas source Auto Loader ne sont pas mis à jour​

Si un flux est lu avec Auto Loader, Auto Loader suit le schéma de ses fichiers sources séparément du schéma de la table de streaming, et ALTER TABLE ne le modifie pas. Pour une source qui continue de produire la colonne :

  • DROP COLUMN: Auto Loader continue d'inférer la colonne à partir des fichiers sources, et la mise à jour suivante l'écrit dans la table.
  • RENAME COLUMN: Auto Loader continue de produire l’ancien nom de colonne. Pour une table à schéma implicite, l’ancienne colonne est rajoutée aux côtés de la nouvelle.

Pour qu'une suppression ou un renommage prenne effet sur une table de streaming prise en charge par Auto Loader, limitez également ce qu'Auto Loader lit. Déclarez un schéma de lecture explicite qui omet la colonne et définissez l'option rescuedDataColumn afin que le champ omis soit placé dans la colonne de données sauvée plutôt que d'être supprimé. Lorsque vous fournissez un schéma, Auto Loader n'ajoute pas de colonne de données sauvée pour vous ; sans cette option, le champ est donc ignoré. Voir Qu'est-ce que la colonne de données sauvée ?.

Ressources supplémentaires​

Sur cette page