Élargissement du type

Disponible sur les tables Delta Lake dans Databricks Runtime 15.4 LTS et versions ultérieures, l’élargissement du type vous permet de modifier les types de données de colonne en un type plus large sans réécrire des fichiers de données.

Toutes les tables managées Unity Catalog utilisent Delta Lake par défaut. Consultez les tables managées du catalogue Unity pour Delta Lake et Apache Iceberg.

Note

L’activation de l’élargissement des types met à niveau les protocoles de lecture et d’écriture. Cela peut affecter la compatibilité avec les clients Delta Lake externes. Consultez les protocoles et la compatibilité des fonctionnalités Delta Lake.

Les tables avec extension de type activée ne peuvent être lues que par Databricks Runtime 15.4 LTS et versions ultérieures.

Modifications de type prises en charge

Vous pouvez élargir les types en fonction des règles suivantes :

Type de source	Prise en charge de types plus étendus
`BYTE`	`SHORT`, , `INTBIGINT`, , `DECIMALDOUBLE`
`SHORT`	`INT`, `BIGINT`, `DECIMAL`, `DOUBLE`
`INT`	`BIGINT`, `DECIMAL`, `DOUBLE`
`BIGINT`	`DECIMAL`
`FLOAT`	`DOUBLE`
`DECIMAL`	`DECIMAL` avec une plus grande précision et une échelle
`DATE`	`TIMESTAMP_NTZ`
`VOID`	Tout type

Les modifications de type sont prises en charge pour les colonnes de niveau supérieur et les champs imbriqués dans des structs, des cartes et des tableaux.

Note

VOID vers n’importe quel type ne nécessite pas que l’élargissement du type soit activé sur la table. Toute opération qui met à jour le type d’une VOID colonne réussit sans configuration supplémentaire. VOID l’élargissement des types est disponible dans Databricks Runtime 18.2 et versions ultérieures.

Comportement décimal

Spark tronque par défaut la partie fractionnaire d’une valeur quand une opération promeut un type entier en une decimal ou double, et qu’une ingestion en aval écrit ensuite la valeur dans une colonne entière. Pour plus d’informations sur le comportement de la stratégie d’affectation, consultez Affectation du Windows Store.

Lors de la modification d’un type numérique en decimal, la précision totale doit être égale ou supérieure à la précision de départ. Si vous augmentez également l’échelle, la précision totale doit augmenter d’un montant correspondant.

La cible minimale pour les types byte, short et int est decimal(10,0). La cible minimale pour long est decimal(20,0).

Si vous souhaitez ajouter deux décimales à un champ avec decimal(10,1), la cible minimale est decimal(12,3).

Activer l’élargissement du type

Note

Vous pouvez activer l’élargissement du type sur une table existante en définissant la propriété de table delta.enableTypeWidening sur true :

  ALTER TABLE <table_name> SET TBLPROPERTIES ('delta.enableTypeWidening' = 'true')

Vous pouvez également activer l'élargissement des types lors de la création d'une table :

  CREATE TABLE T(c1 INT) TBLPROPERTIES('delta.enableTypeWidening' = 'true')

Appliquer manuellement une modification de type

Utilisez la commande ALTER COLUMN pour modifier manuellement les types :

ALTER TABLE <table_name> ALTER COLUMN <col_name> TYPE <new_type>

Cette opération met à jour le schéma de table sans réécrire les fichiers de données sous-jacents. Consultez ALTER TABLE pour plus d’informations.

Élargir les types avec évolution automatique du schéma

Utilisez l’évolution du schéma avec l’élargissement du type pour mettre à jour les types de données dans les tables cibles pour correspondre au type de données entrantes.

Note

Sans extension de type activée, l’évolution du schéma tente toujours de décomposer les données pour correspondre aux types de colonnes dans la table cible. Si vous ne souhaitez pas étendre automatiquement les types de données dans vos tables cibles, vous devez désactiver l’élargissement du type avant d’exécuter des charges de travail avec l’évolution du schéma activée.

Pour utiliser l’évolution du schéma pour élargir le type de données d’une colonne pendant l’ingestion, vous devez remplir les conditions suivantes :

La commande d’écriture s’exécute avec l’évolution automatique du schéma activée.
L’élargissement du type est activé sur la table cible.
Le type de colonne source est plus large que le type de colonne cible.
L’élargissement du type prend en charge la modification de type.

Les incompatibilités de type qui ne répondent pas à toutes ces conditions suivent les règles habituelles de validation du schéma. Consultez Application du schéma.

Exemple

Les exemples suivants montrent comment l’élargissement du type fonctionne avec l’évolution du schéma.

Python

Créez une table cible avec une INT colonne et une table source avec une BIGINT colonne :

spark.sql("CREATE TABLE target_table (id INT, data STRING) TBLPROPERTIES ('delta.enableTypeWidening' = 'true')")
spark.sql("CREATE TABLE source_table (id BIGINT, data STRING)")

Utilisez saveAsTable() avec l’évolution du schéma pour convertir automatiquement la colonne INT en BIGINT lors d’un ajout :

spark.table("source_table").write.mode("append").option("mergeSchema", "true").saveAsTable("target_table")

Utiliser MERGE INTO avec l’évolution du schéma :

from delta.tables import DeltaTable

source_df = spark.table("source_table")
target_table = DeltaTable.forName(spark, "target_table")

(target_table.alias("target")
  .merge(source_df.alias("source"), "target.id = source.id")
  .withSchemaEvolution()
  .whenMatchedUpdateAll()
  .whenNotMatchedInsertAll()
  .execute()
)

Scala

Créez une table cible avec une INT colonne et une table source avec une BIGINT colonne :

spark.sql("CREATE TABLE target_table (id INT, data STRING) TBLPROPERTIES ('delta.enableTypeWidening' = 'true')")
spark.sql("CREATE TABLE source_table (id BIGINT, data STRING)")

Utilisez saveAsTable() avec l’évolution du schéma pour convertir automatiquement la colonne INT en BIGINT lors d’un ajout :

spark.table("source_table").write.mode("append").option("mergeSchema", "true").saveAsTable("target_table")

Utiliser MERGE INTO avec l’évolution du schéma :

import io.delta.tables.DeltaTable

val sourceDf = spark.table("source_table")
val targetTable = DeltaTable.forName(spark, "target_table")

targetTable.alias("target")
  .merge(sourceDf.alias("source"), "target.id = source.id")
  .withSchemaEvolution()
  .whenMatched().updateAll()
  .whenNotMatched().insertAll()
  .execute()

SQL

Créez une table cible avec une INT colonne et une table source avec une BIGINT colonne :

CREATE TABLE target_table (id INT, data STRING) TBLPROPERTIES ('delta.enableTypeWidening' = 'true');
CREATE TABLE source_table (id BIGINT, data STRING);

Utilisez INSERT INTO avec l’évolution du schéma pour convertir automatiquement la colonne INT en BIGINT lors d’un ajout :

INSERT WITH SCHEMA EVOLUTION INTO target_table SELECT * FROM source_table;

Utiliser MERGE INTO avec l’évolution du schéma :

MERGE WITH SCHEMA EVOLUTION INTO target_table
USING source_table
ON target_table.id = source_table.id
WHEN MATCHED THEN UPDATE SET *
WHEN NOT MATCHED THEN INSERT *;

Chargeur automatique

Important

La prise en charge de l’élargissement du type dans le chargeur automatique est disponible en préversion publique.

Auto Loader prend en charge l'élargissement des types avec l'évolution automatique du schéma. Lorsque vous utilisez le chargeur automatique pour ingérer des données dans une table Delta Lake avec l’élargissement du type et l’évolution du schéma activée, les types de colonnes sont automatiquement étendus pour correspondre aux données entrantes.

(spark.readStream
  .format("cloudFiles")
  .option("cloudFiles.format", "json")
  .option("cloudFiles.schemaLocation", "<path-to-schema-location>")
  .load("<path-to-source-data>")
  .writeStream
  .option("mergeSchema", "true")
  .option("checkpointLocation", "<path-to-checkpoint>")
  .trigger(availableNow=True)
  .toTable("table_name")
)

Consultez la section Élargissement automatique du type avec Auto Loader. En outre, la table cible doit avoir l’élargissement de type activé. Consultez Activer l'élargissement des types.

Désactiver la fonctionnalité de tableau d’élargissement de types

Vous pouvez empêcher l’élargissement accidentel du type sur les tables activées en définissant la propriété sur false :

  ALTER TABLE <table_name> SET TBLPROPERTIES ('delta.enableTypeWidening' = 'false')

Ce paramètre empêche les modifications de type futures apportées à la table, mais ne supprime pas la fonctionnalité de table étendue de type ou annule les modifications de type précédentes.

Si vous devez supprimer complètement les fonctionnalités de table d’élargissement du type, vous pouvez utiliser la commande DROP FEATURE comme indiqué dans l’exemple suivant :

 ALTER TABLE <table-name> DROP FEATURE 'typeWidening' [TRUNCATE HISTORY]

Note

Les tables pour lesquelles l’élargissement de type a été activé à l’aide de Databricks Runtime 15.4 LTS vous imposent de supprimer la fonctionnalité typeWidening-preview à la place.

Lorsque vous supprimez l’élargissement du type, Databricks réécrit tous les fichiers de données qui ne sont pas conformes au schéma de table actuel. Consultez Supprimer une fonctionnalité de table Delta Lake et passer à une version antérieure du protocole de table.

Diffusion en continu à partir d’une table Delta Lake

La prise en charge de l’élargissement de type dans Structured Streaming est disponible dans Databricks Runtime 16.4 LTS et versions ultérieures.

Lors de la lecture en continu à partir d’une table Delta Lake avec l’extension des types activée, vous pouvez configurer l’extension automatique des types pour les requêtes en continu en activant l’évolution du schéma avec l’option mergeSchema dans la table cible. La table cible doit avoir l’élargissement de type activé. Consultez Activer l'élargissement des types.

Python

(spark.readStream
  .table("delta_source_table")
  .writeStream
  .option("checkpointLocation", "/path/to/checkpointLocation")
  .option("mergeSchema", "true")
  .toTable("output_table")
)

Scala

spark.readStream
  .table("delta_source_table")
  .writeStream
  .option("checkpointLocation", "/path/to/checkpointLocation")
  .option("mergeSchema", "true")
  .toTable("output_table")

Quand mergeSchema est activé et que l'extension de type est activée pour la table cible :

Les modifications de type sont appliquées automatiquement à la table en aval sans intervention manuelle.
Les nouvelles colonnes sont ajoutées automatiquement au schéma de table en aval.

Sans mergeSchema activé, les valeurs sont gérées en fonction de la spark.sql.storeAssignmentPolicy configuration, qui, par défaut, réduit les valeurs pour correspondre au type de colonne cible. Pour plus d’informations sur la stratégie d’affectation, consultez Store assignment.

Gérer les modifications de type dans un flux

Lors de la diffusion en continu à partir d’une table Delta Lake, vous pouvez fournir un emplacement de suivi de schéma pour suivre les modifications de schéma non additifs, y compris les modifications de type. Fournir un emplacement de suivi de schéma est requis dans Databricks Runtime 18.0 et versions ultérieures, et il est facultatif dans Databricks Runtime 18.1 et versions ultérieures.

Vous ne pouvez pas définir un(e) schemaTrackingLocation à l’aide de SQL. Voir Fonctionnalités non prises en charge.

schemaTrackingLocation doit être défini dans un emplacement situé sur le même chemin d’accès que votre point de contrôle de streaming. Par exemple:

Python

checkpoint_path = "/path/to/checkpointLocation"

(spark.readStream
  .option("schemaTrackingLocation", checkpoint_path)
  .table("delta_source_table")
  .writeStream
  .option("checkpointLocation", checkpoint_path)
  .toTable("output_table")
)

Scala

val checkpointPath = "/path/to/checkpointLocation"

spark.readStream
  .option("schemaTrackingLocation", checkpointPath)
  .table("delta_source_table")
  .writeStream
  .option("checkpointLocation", checkpointPath)
  .toTable("output_table")

Après avoir défini un emplacement de suivi de schéma, le flux évolue son schéma suivi lorsqu’il détecte une modification de type, puis s’arrête. À ce moment-là, vous devez gérer le changement de type, par exemple en activant l’élargissement de type pour la table en aval ou en mettant à jour la requête de traitement en continu.

Pour reprendre le traitement, définissez la configuration Spark spark.databricks.delta.streaming.allowSourceColumnTypeChange ou l’option de lecteur DataFrameallowSourceColumnTypeChange, comme dans l’exemple suivant :

Python

checkpoint_path = "/path/to/checkpointLocation"

(spark.readStream
  .option("schemaTrackingLocation", checkpoint_path)
  .option("allowSourceColumnTypeChange", "<delta_source_table_version>")
  # alternatively to allow all future type changes for this stream:
  # .option("allowSourceColumnTypeChange", "always")
  .table("delta_source_table")
  .writeStream
  .option("checkpointLocation", checkpoint_path)
  .toTable("output_table")
)

Scala

val checkpointPath = "/path/to/checkpointLocation"

spark.readStream
  .option("schemaTrackingLocation", checkpointPath)
  .option("allowSourceColumnTypeChange", "<delta_source_table_version>")
  // alternatively to allow all future type changes for this stream:
  // .option("allowSourceColumnTypeChange", "always")
  .table("delta_source_table")
  .writeStream
  .option("checkpointLocation", checkpointPath)
  .toTable("output_table")

SQL

  -- To unblock for this particular stream just for this series of schema change(s):
  SET spark.databricks.delta.streaming.allowSourceColumnTypeChange.ckpt_<checkpoint_id> = "<delta_source_table_version>"
  -- To unblock for this particular stream:
  SET spark.databricks.delta.streaming.allowSourceColumnTypeChange = "<delta_source_table_version>"
  -- To unblock for all streams:
  SET spark.databricks.delta.streaming.allowSourceColumnTypeChange = "always"

Lorsque le flux s’arrête, un message d’erreur affiche l’ID <checkpoint_id> de point de contrôle et la version <delta_source_table_version>de la table source Delta Lake.

Pour obtenir la liste complète des options delta Lake de streaming, consultez Delta Lake.

Pipelines de Lakeflow

Vous pouvez activer l’élargissement de type pour les pipelines Lakeflow, soit au niveau du pipeline, soit pour des tables spécifiques. L'élargissement des types permet d’élargir automatiquement les types de colonnes pendant l’exécution du pipeline sans nécessiter une actualisation complète des tables de flux. Les modifications de type dans les vues matérialisées déclenchent toujours une recompilation complète et lorsqu’une modification de type est appliquée à une table source, les vues matérialisées qui dépendent de cette table nécessitent une recomcompute complète pour refléter les nouveaux types.

Activer l’élargissement du type pour un pipeline entier

Pour activer l'élargissement des types pour toutes les tables d’un pipeline, définissez la configuration du pipeline pipelines.enableTypeWidening :

JSON

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

YAML

configuration:
  pipelines.enableTypeWidening: 'true'

Activer l’élargissement du type pour des tables spécifiques

Vous pouvez également activer l’élargissement du type pour des tables individuelles en définissant la propriété delta.enableTypeWideningde table :

Python

import dlt

@dlt.table(
  table_properties={"delta.enableTypeWidening": "true"}
)
def my_table():
  return spark.readStream.table("source_table")

SQL

CREATE OR REFRESH STREAMING TABLE my_table
TBLPROPERTIES ('delta.enableTypeWidening' = 'true')
AS SELECT * FROM source_table

Compatibilité avec les lecteurs en aval

Les tables avec extension de type activée ne peuvent être lues que dans Databricks Runtime 15.4 LTS et versions ultérieures. Si vous souhaitez qu’une table avec l’élargissement du type activé dans votre pipeline soit lisible par les lecteurs sur Databricks Runtime 14.3 et ci-dessous, vous devez :

Désactivez l’élargissement du type en supprimant la propriété delta.enableTypeWidening/pipelines.enableTypeWidening ou en la définissant sur false, puis déclenchez une actualisation complète de la table.
Activez le mode de compatibilité sur votre table.

OpenSharing

Note

La prise en charge de l’élargissement de type dans OpenSharing est disponible dans Databricks Runtime 16.1 et versions ultérieures.

Le partage d’une table Delta Lake avec extension de type activée est pris en charge dans Databricks-to-Databricks OpenSharing. Le fournisseur et le destinataire doivent se trouver sur Databricks Runtime 16.1 ou version ultérieure.

Pour lire le flux des données de modification d’une table Delta Lake avec l’extension de type activée à l’aide d’OpenSharing, vous devez définir le format de réponse sur delta :

spark.read
  .format("deltaSharing")
  .option("responseFormat", "delta")
  .option("readChangeFeed", "true")
  .option("startingVersion", "<start version>")
  .option("endingVersion", "<end version>")
  .load("<table>")

La lecture du flux des données de modification lors de changements de type n’est pas prise en charge. Vous devez à la place fractionner l’opération en deux lectures distinctes, une se terminant à la version de table contenant la modification de type et l'autre commençant à la version contenant la modification de type.

Limites

Compatibilité d’Apache Iceberg

Apache Iceberg ne prend pas en charge toutes les modifications de type couvertes par l’élargissement du type. Voir l’évolution du schéma iceberg.

Les modifications de type non prises en charge sont les suivantes :

byte, short, intlong à decimal oudouble
Augmentation de l’échelle décimale
De date à timestampNTZ.

Lorsque vous activez UniForm avec la compatibilité Iceberg sur une table Delta Lake, l’application de l’un des changements de type précédents entraîne une erreur. Consultez lire les tables Delta Lake avec les clients Iceberg à l’aide de UniForm.

Si vous appliquez l’une de ces modifications de type non prises en charge à une table Delta Lake, vous avez deux options :

Régénérer les métadonnées Iceberg : utilisez la commande suivante pour régénérer les métadonnées Iceberg sans la fonctionnalité de table étendue de type :
```
ALTER TABLE <table-name> SET TBLPROPERTIES ('delta.universalFormat.config.icebergCompatVersion' = '<version>')
```
Cela vous permet de maintenir la compatibilité uniforme après l’application des modifications de type incompatibles.
Supprimez la fonctionnalité de table d'élargissement des types : consultez Désactiver la table d'élargissement des types.

Fonctions dépendantes du type

Certaines fonctions SQL retournent des résultats qui dépendent du type de données d’entrée. Par exemple, hash la fonction retourne des valeurs de hachage différentes pour la même valeur logique si le type d’argument est différent : hash(1::INT) retourne un résultat différent de hash(1::BIGINT).

Les autres fonctions dépendantes de type sont les suivantes : xxhash64, bit_get, bit_reverse, typeof.

Pour obtenir des résultats stables dans les requêtes qui utilisent ces fonctions, vous devez convertir explicitement des valeurs en type souhaité :

Python

spark.read.table("table_name") \
  .selectExpr("hash(CAST(column_name AS BIGINT))")

Scala

spark.read.table("main.johan_lasperas.dlt_type_widening_bronze2")
  .selectExpr("hash(CAST(a AS BIGINT))")

SQL

-- Use explicit casting for stable hash values
SELECT hash(CAST(column_name AS BIGINT)) FROM table_name

Fonctionnalités non prises en charge

Vous ne pouvez pas définir un emplacement de suivi de schéma à l’aide de SQL lors de la diffusion en continu à partir d’une table Delta Lake avec une modification de type.
Vous ne pouvez pas partager via OpenSharing une table dont l’extension de type est activée avec des consommateurs non Databricks.

Commentaires

Est-ce que cette page vous a été utile?

Last updated on 2026-07-10

Élargissement du type

Modifications de type prises en charge

Comportement décimal

Activer l’élargissement du type

Appliquer manuellement une modification de type

Élargir les types avec évolution automatique du schéma

Exemple

Python

Scala

SQL

Chargeur automatique

Désactiver la fonctionnalité de tableau d’élargissement de types

Diffusion en continu à partir d’une table Delta Lake

Python

Scala

Gérer les modifications de type dans un flux

Python

Scala

Python

Scala

SQL

Pipelines de Lakeflow

Activer l’élargissement du type pour un pipeline entier

JSON

YAML

Activer l’élargissement du type pour des tables spécifiques

Python

SQL

Compatibilité avec les lecteurs en aval

OpenSharing

Limites

Compatibilité d’Apache Iceberg

Fonctions dépendantes du type

Python

Scala

SQL

Fonctionnalités non prises en charge

Commentaires

Ressources supplémentaires