Freigeben über

Typerweiterung

Wichtig

Dieses Feature befindet sich in der öffentlichen Vorschau in Databricks Runtime 15.4 LTS und höher.

Tabellen mit aktivierter Typerweiterung ermöglichen es Ihnen, Spaltendatentypen in einen breiteren Typ zu ändern, ohne zugrunde liegende Datendateien neu zu schreiben. Sie können Spaltentypen manuell ändern oder die Schemaentwicklung verwenden, um Spaltentypen zu entwickeln.

Wichtig

Die Typweiterung ist in Databricks Runtime 15.4 LTS und höher verfügbar. Tabellen mit aktivierter Typweiterung können nur in Databricks Runtime 15.4 LTS und höher gelesen werden.

Für die Typerweiterung ist Delta Lake erforderlich. Alle verwalteten Tabellen im Unity-Katalog verwenden standardmäßig Delta Lake-Tabellen.

Unterstützte Typänderungen

Sie können Typen entsprechend den folgenden Regeln erweitern:

Quellentyp Unterstützte breitere Typen
byte short, , intlong, , decimaldouble
short int long decimal double
int long, decimaldouble
long decimal
float double
decimal decimal mit größerer Präzision und Skalierung
date timestampNTZ

Um zu vermeiden, dass ganzzahlige Werte versehentlich zu Dezimalzahlen konvertiert werden, müssen Sie die Typänderungen von byte, short, int oder long zu decimal oder double manuell vornehmen. Wenn ein ganzzahliger Typ auf decimal oder double befördert wird und eine nachgeschaltete Verarbeitung diesen Wert wieder in eine ganzzahlige Spalte schreibt, schneidet Spark den Bruchteil der Werte standardmäßig ab.

Hinweis

Beim Ändern eines numerischen Typs in decimalmuss die Gesamtgenauigkeit gleich oder größer als die Anfangsgenauigkeit sein. Wenn Sie auch die Skalierung erhöhen, muss die Gesamtgenauigkeit um einen entsprechenden Betrag erhöht werden.

Das Mindestziel für die Typen byte, short und int ist decimal(10,0). Das Mindestziel für long ist decimal(20,0).

Wenn Sie einem Feld mit decimal(10,1)zwei Dezimalstellen hinzufügen möchten, ist das Mindestziel decimal(12,3).

Typänderungen werden für Spalten und Felder auf oberster Ebene unterstützt, die in Strukturen, Zuordnungen und Arrays geschachtelt sind.

Aktivieren der Typerweiterung

Sie können die Typerweiterung für eine vorhandene Tabelle aktivieren, indem Sie die Tabelleneigenschaft delta.enableTypeWidening auf true festlegen:

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

Sie können die Typerweiterung auch während der Tabellenerstellung aktivieren:

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

Wichtig

Wenn Sie die Typerweiterung aktivieren, wird die Tabellenfunktion typeWidening festgelegt, wodurch die Lese- und Schreibprotokolle aktualisiert werden. Sie müssen Databricks Runtime 15.4 oder höher verwenden, um mit Tabellen mit aktivierter Typweiterung zu interagieren. Wenn externe Clients auch mit der Tabelle interagieren, überprüfen Sie, ob sie diese Tabellenfunktion unterstützen. Siehe Delta Lake Featurekompatibilität und Protokolle.

Manuelles Anwenden einer Typänderung

Verwenden Sie den Befehl ALTER COLUMN, um Typen manuell zu ändern:

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

Dieser Vorgang aktualisiert das Tabellenschema, ohne die zugrunde liegenden Datendateien neu zu schreiben.

Erweitern von Typen mit der automatischen Schemaentwicklung

Die Schemaentwicklung funktioniert mit der Typerweiterung, um Datentypen in Zieltabellen zu aktualisieren, sodass sie dem Typ der eingehenden Daten entsprechen.

Hinweis

Ohne Typweitergabe aktiviert, versucht die Schemaentwicklung immer, Daten zu downcasten, um Spaltentypen in der Zieltabelle abzugleichen. Wenn Sie Datentypen in Ihren Zieltabellen nicht automatisch erweitern möchten, deaktivieren Sie die Typweitergabe, bevor Sie Workloads mit aktivierter Schemaentwicklung ausführen.

Um die Schemaentwicklung zu verwenden, um den Datentyp einer Spalte während der Aufnahme zu erweitern, müssen Sie die folgenden Bedingungen erfüllen:

  • Der Schreibbefehl wird mit aktivierter automatischer Schemaentwicklung ausgeführt.
  • Für die Zieltabelle ist die Typerweiterung aktiviert.
  • Der Quellspaltentyp ist breiter als der Zielspaltentyp.
  • Die Typerweiterung unterstützt die Typänderung.
  • Die Typänderung ist nicht einer von byte, short, int, long oder zu decimal oder double. Diese Typänderungen können nur manuell mit ALTER TABLE angewendet werden, um versehentliche Umwandlungen von Ganzzahlen zu Dezimalzahlen zu vermeiden.

Typenkollisionen, die nicht alle diese Bedingungen erfüllen, unterliegen den normalen Regeln der Schemaüberprüfung. Weitere Informationen finden Sie unter Schemaerzwingung.

Deaktivieren Sie die Funktion zum Erweitern von Tabellen für Typen

Sie können die versehentliche Typenerweiterung für aktivierte Tabellen verhindern, indem Sie die Eigenschaft auf false festlegen:

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

Diese Einstellung verhindert zukünftige Typänderungen an der Tabelle, entfernt jedoch nicht die Funktion zum Erweitern von Typen in Tabellen und macht auch keine geänderten Typen rückgängig, die bereits geändert wurden.

Wenn Sie die Tabellenfunktionen für die Typerweiterung vollständig entfernen müssen, können Sie den Befehl DROP FEATURE verwenden, wie im folgenden Beispiel gezeigt:

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

Hinweis

Tabellen, die die Typweiterung mithilfe von Databricks Runtime 15.4 LTS aktiviert haben, erfordern stattdessen das Ablegen der Funktion typeWidening-preview .

Beim Ablegen der Typverbreiterung werden alle Datendateien, die nicht dem aktuellen Tabellenschema entsprechen, umgeschrieben. Weitere Informationen finden Sie unter Löschen eines Delta Lake-Tabellenfeatures und Herabstufen des Tabellenprotokolls.

Streamen aus einer Delta-Tabelle

Hinweis

Unterstützung für Type Widening in Structured Streaming ist in Databricks Runtime 16.3 und höher verfügbar.

Beim Streamen aus einer Delta-Tabelle werden Typänderungen als nicht-additive Schemaänderungen behandelt, ähnlich wie das Umbenennen oder Ablegen einer Spalte mit der Spaltenzuordnung.

Sie können einen Schemaverfolgungsort bereitstellen, um das Streaming von Delta Lake-Tabellen mit angewendeter Typänderung zu ermöglichen.

Jeder Streaminglesevorgang aus einer Datenquelle muss über einen eigenen schemaTrackingLocation-Wert verfügen. Das angegebene Verzeichnis schemaTrackingLocation muss im Verzeichnis enthalten sein, das für die checkpointLocation Zieltabelle für streaming-Schreibvorgänge angegeben ist.

Hinweis

Für Streamingworkloads, die Daten aus mehreren Quell-Delta-Tabellen kombinieren, müssen Sie eindeutige Verzeichnisse in der checkpointLocation jeweiligen Quelltabelle angeben.

Die Option schemaTrackingLocation wird verwendet, um den Pfad für die Schemanachverfolgung anzugeben, wie im folgenden Codebeispiel gezeigt:

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")

Nach der Bereitstellung eines Speicherorts für die Schemanachverfolgung wird der Datenstrom sein nachverfolgtes Schema weiterentwickeln, solange eine Typänderung erkannt wird, und dann die Weiterentwicklung stoppen. Zu diesem Zeitpunkt können Sie alle erforderlichen Maßnahmen ergreifen, um die Typänderung zu bewältigen, wie zum Beispiel die Typverbreiterung in der nachgelagerten Tabelle zu aktivieren oder die Streamingabfrage zu aktualisieren.

Um die Verarbeitung fortzusetzen, legen Sie die Spark-Konfiguration spark.databricks.delta.streaming.allowSourceColumnTypeChange oder die DataFrame-Leseoption allowSourceColumnTypeChangefest:

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"

Die Prüfpunkt-ID <checkpoint_id> und die Version der Delta Lake-Quelltabelle <delta_source_table_version> werden in der Fehlermeldung angezeigt, wenn der Datenstrom beendet wird.

Delta-Sharing

Hinweis

Unterstützung von Type Widening in Delta Sharing ist in Databricks Runtime 16.1 und höher verfügbar.

Das Teilen einer Delta Lake-Tabelle mit aktivierter Typweiterung wird in Databricks-to-Databricks Delta Sharing unterstützt. Der Anbieter und Empfänger müssen sich auf Databricks Runtime 16.1 oder höher befinden.

Zum Lesen des Änderungsdaten-Feeds aus einer Delta-Lake-Tabelle mit aktivierter Typ-Erweiterung mithilfe von Delta Sharing müssen Sie das Antwortformat auf delta festlegen.

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

Das Lesen des Datenfeeds über Typänderungen hinweg wird nicht unterstützt. Sie müssen den Vorgang stattdessen in zwei separate Lesevorgänge aufteilen, eine endend auf der Tabellenversion, die die Typänderung enthält, und die andere beginnend mit der Version, die die Typänderung enthält.

Einschränkungen

Apache Iceberg Kompatibilität

Apache Iceberg unterstützt nicht alle Typänderungen, die durch die Typweiterung abgedeckt werden, siehe Iceberg Schema Evolution. Insbesondere werden die folgenden Typänderungen von Azure Databricks nicht unterstützt:

  • byte, short, int, long, bis decimal oder double
  • Erhöhung der Dezimalskala
  • date bis timestampNTZ

Wenn uniForm mit Iceberg-Kompatibilität auf einer Delta Lake-Tabelle aktiviert ist, führt das Anwenden einer dieser Typänderungen zu einem Fehler.

Wenn Sie eine dieser nicht unterstützten Typänderungen auf eine Delta Lake-Tabelle anwenden, führt die Aktivierung von Uniform mit Iceberg-Kompatibilität in der Tabelle zu einem Fehler. Um den Fehler zu beheben, müssen Sie die Funktion zur Typenerweiterungstabelle entfernen.

Weitere Einschränkungen

  • Das Bereitstellen eines Schemanachverfolgungsorts mithilfe von SQL beim Streamen aus einer Delta Lake-Tabelle mit einer Typänderung wird nicht unterstützt.
  • Das Freigeben einer Tabelle mithilfe der Delta-Freigabe mit aktivierter Typweiterung mit Nicht-Databricks-Consumern wird nicht unterstützt.