Tablo şemasını güncelleştirme

Tablolar, veri gereksinimleri değiştikçe tablo yapısında değişiklik yapılmasına olanak tanıyarak şema evrimi destekler. Aşağıdaki değişiklik türleri desteklenir:

Bu değişiklikleri açıkça DDL kullanarak veya örtük olarak DML kullanarak yapın.

Önemli

Şema güncelleştirmeleri tüm eşzamanlı yazma işlemleriyle çakışıyor. Databricks, yazma çakışmalarını önlemek için şema değişikliklerini koordine etmenizi önerir.

Tablo şemasının güncelleştirilmesi, bu tablodan okunan tüm akışları sonlandırır. İşlemeye devam etmek için, Yapılandırılmış Akış için Üretimde dikkat edilmesi gerekenler bölümünde açıklanan yöntemleri kullanarak akışı yeniden başlatın.

Sütun eklemek için şemayı açıkça güncelleştirin

ALTER TABLE table_name ADD COLUMNS (col_name data_type [COMMENT col_comment] [FIRST|AFTER colA_name], ...)

Varsayılan olarak null değer kabul edebilirlik true.

İç içe bir alana sütun eklemek için şunu kullanın:

ALTER TABLE table_name ADD COLUMNS (col_name.nested_col_name data_type [COMMENT col_comment] [FIRST|AFTER colA_name], ...)

Örneğin, çalıştırmadan ALTER TABLE boxes ADD COLUMNS (colB.nested STRING AFTER field1) önceki şema aşağıdaki gibiyse:

- root
| - colA
| - colB
| +-field1
| +-field2

sonrasındaki şema:

- root
| - colA
| - colB
| +-field1
| +-nested
| +-field2

Not

İç içe sütunlar eklemek yalnızca yapılar için desteklenir. Diziler ve eşlemeler desteklenmez.

Sütun açıklamasını veya sıralamasını değiştirmek için şemayı açıkça güncelleştirin

ALTER TABLE table_name ALTER [COLUMN] col_name (COMMENT col_comment | FIRST | AFTER colA_name)

İç içe bir alandaki sütunu değiştirmek için şunu kullanın:

ALTER TABLE table_name ALTER [COLUMN] col_name.nested_col_name (COMMENT col_comment | FIRST | AFTER colA_name)

Örneğin, çalıştırmadan ALTER TABLE boxes ALTER COLUMN colB.field2 FIRST önceki şema aşağıdaki gibiyse:

- root
| - colA
| - colB
| +-field1
| +-field2

sonrasındaki şema:

- root
| - colA
| - colB
| +-field2
| +-field1

Sütunları değiştirmek için şemayı net bir şekilde güncelleyin

ALTER TABLE table_name REPLACE COLUMNS (col_name1 col_type1 [COMMENT col_comment1], ...)

Örneğin, aşağıdaki DDL'yi çalıştırırken:

ALTER TABLE boxes REPLACE COLUMNS (colC STRING, colB STRUCT<field2:STRING, nested:STRING, field1:STRING>, colA STRING)

önceki şema şuysa:

- root
| - colA
| - colB
| +-field1
| +-field2

sonrasındaki şema:

- root
| - colC
| - colB
| +-field2
| +-nested
| +-field1
| - colA

Şemayı sütunları yeniden adlandırmak için açıkça güncelleştirin

Not

Bu özellik Databricks Runtime 10.4 LTS ve üzerinde kullanılabilir.

Sütunların var olan verilerini yeniden yazmadan sütunları yeniden adlandırmak için tablo için sütun eşlemeyi etkinleştirmeniz gerekir. Bkz Delta Lake sütun eşlemesi ile sütunları yeniden adlandırma ve bırakma.

Sütun adını değiştirmek için:

ALTER TABLE table_name RENAME COLUMN old_col_name TO new_col_name

İç içe bir alanı yeniden adlandırmak için:

ALTER TABLE table_name RENAME COLUMN col_name.old_nested_field TO new_nested_field

Örneğin, aşağıdaki komutu çalıştırdığınızda:

ALTER TABLE boxes RENAME COLUMN colB.field1 TO field001

Önceki şema şuysa:

- root
| - colA
| - colB
| +-field1
| +-field2

Ardından aşağıdaki şema şu şekildedir:

- root
| - colA
| - colB
| +-field001
| +-field2

Bkz Delta Lake sütun eşlemesi ile sütunları yeniden adlandırma ve bırakma.

Şemayı sütunları bırakacak şekilde açıkça güncelleştirin

Not

Bu özellik Databricks Runtime 11.3 LTS ve üzerinde kullanılabilir.

Herhangi bir veri dosyasını yeniden yazmadan sütunları yalnızca meta veri işlemi olarak bırakmak için, tablo için sütun eşlemeyi etkinleştirmeniz gerekir. Bkz Delta Lake sütun eşlemesi ile sütunları yeniden adlandırma ve bırakma.

Önemli

Bir sütunu meta verilerden kaldırmak, dosyalardaki sütunun temel verilerini silmez. Bırakılan sütun verilerini temizlemek için REORG TABLE kullanarak dosyaları yeniden yazabilirsiniz. Daha sonra bırakılan sütun verilerini içeren dosyaları fiziksel olarak silmek için VACUUM kullanabilirsiniz.

Bir sütunu düşürmek için:

ALTER TABLE table_name DROP COLUMN col_name

Birden çok sütunu kaldırmak için:

ALTER TABLE table_name DROP COLUMNS (col_name_1, col_name_2)

Sütun türünü veya adını değiştirmek için şemayı açıkça güncelleştirin

Bir sütunun türünü veya adını değiştirebilir veya tabloyu yeniden yazarak bir sütunu bırakabilirsiniz. Bunu yapmak için seçeneğini kullanın overwriteSchema .

Aşağıdaki örnekte sütun türünü değiştirme gösterilmektedir:

(spark.read.table(...)
  .withColumn("birthDate", col("birthDate").cast("date"))
  .write
  .mode("overwrite")
  .option("overwriteSchema", "true")
  .saveAsTable(...)
)

Aşağıdaki örnekte sütun adını değiştirme gösterilmektedir:

(spark.read.table(...)
  .withColumnRenamed("dateOfBirth", "birthDate")
  .write
  .mode("overwrite")
  .option("overwriteSchema", "true")
  .saveAsTable(...)
)

Şema evrimi etkinleştir

Aşağıdaki yöntemlerden birini kullanarak şema evrimini etkinleştirin:

  • Sözdizimini kullanINSERT WITH SCHEMA EVOLUTION: İfadelerle INSERT çalışır. SQL söz dizimine ekleyin WITH SCHEMA EVOLUTION .
  • Sözdizimini kullanMERGE WITH SCHEMA EVOLUTION: İfadelerle MERGE çalışır. SQL söz dizimine WITH SCHEMA EVOLUTION ekleyin veya Azure Databricks API'sinde .withSchemaEvolution() kullanın.
  • mergeSchema Seçeneğini ayarlayın: Toplu yazma veya akış yazma işlemleriyle çalışır. .option("mergeSchema", "true") tek tek yazma işlemlerinde ayarlayın.
  • Spark yapılandırmasını ayarlama (eski):spark.databricks.delta.schema.autoMerge.enabled SparkSession'ın tamamı için olarak ayarlartrue. Üretim kullanımı için önerilmez.

Databricks, Spark yapılandırması ayarlamak yerine WITH SCHEMA EVOLUTION söz dizimini veya mergeSchema seçeneğini kullanarak her yazma işlemi için şema evrimini etkinleştirmeyi önerir.

Bir yazma işleminde şema evrimini etkinleştirmek için seçenekleri veya söz dizimini kullandığınızda bu, Spark yapılandırmasından önceliklidir.

Yeni sütunlar eklemek için yazma işlemleri için şema evrimi etkinleştirme

Şema evrimi etkinleştirildiğinde, kaynak sorguda mevcut olan ancak hedef tabloda eksik olan sütunlar otomatik olarak yazma işleminin bir parçası olarak eklenir. Bkz Şema evrimini etkinleştirme.

Yeni bir sütun eklerken harflerin büyük/küçük durumu korunur. Tablo şemasının sonuna yeni sütunlar eklenir. Ek sütunlar bir yapıdaysa, bunlar hedef tablodaki yapının sonuna eklenir.

"Şema evrimi için söz dizimi INSERT"

Şema evrimini etkinleştirmek için WITH SCHEMA EVOLUTION deyimlerindeki INSERT yan tümcesini kullanabilirsiniz.

INSERT WITH SCHEMA EVOLUTION INTO target_table
SELECT * FROM source_table

üzerindeki source_table sorgu hedef tabloda mevcut olmayan sütunları döndürürse, bu sütunlar otomatik olarak şemaya target_table eklenir. Mevcut satırlar, yeni sütunlar için NULL değerlerini alır.

INSERT DataFrame API kullanarak şema evrimi ile

Aşağıdaki örnekte, seçeneğinin mergeSchema toplu yazma işlemiyle kullanılması gösterilmektedir:

Python

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

Scala programlama dili

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

INSERT akışta şema evrimiyle

Aşağıdaki örnekte, Seçeneğin mergeSchema Otomatik Yükleyici ile birlikte kullanılması gösterilmektedir. Bkz. Otomatik Yükleyici nedir?.

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

Birleştirme için otomatik şema evrimi

Şema evrimi, birleştirmedeki hedef ve kaynak tablo arasındaki şema uyuşmazlıklarını çözmenize olanak tanır. Aşağıdaki iki durumu işler:

  1. Kaynak tabloda bir sütun var ancak hedef tabloda yok ve ekleme veya güncelleme işlemleri içinde ismiyle belirtilmiştir. Alternatif olarak, bir UPDATE SET * veya INSERT * eylemi vardır.

    Bu sütun hedef şemaya eklenir ve değerleri kaynaktaki ilgili sütundan doldurulur.

    • Bu yalnızca birleştirme kaynağındaki sütun adı ve yapısı hedef atamayla tam olarak eşleştiğinde geçerlidir.

    • Yeni sütunun kaynak şemada mevcut olması gerekir. Eylem yan tümcesinde yeni sütunun atanması bu sütunu tanımlamaz.

    Bu örnekler şemanın evrimini sağlar:

    -- The column newcol is present in the source but not in the target. It will be added to the target.
UPDATE SET target.newcol = source.newcol

-- The field newfield doesn't exist in struct column somestruct of the target. It will be added to that struct column.
UPDATE SET target.somestruct.newfield = source.somestruct.newfield

-- The column newcol is present in the source but not in the target.
-- It will be added to the target.
UPDATE SET target.newcol = source.newcol + 1

-- Any columns and nested fields in the source that don't exist in target will be added to the target.
UPDATE SET *
INSERT *

    Bu örnekler, sütun newcol şema source içinde yoksa şema evrimini tetiklemez:

    UPDATE SET target.newcol = source.someothercol
UPDATE SET target.newcol = source.x + source.y
UPDATE SET target.newcol = source.output.newcol

  2. Hedef tabloda bir sütun var ancak kaynak tabloda yok.

    Hedef şema değiştirilmez. Bu sütunlar:

    • UPDATE SET *, için değiştirilmeden bırakılır.

    • NULL, INSERT * olarak ayarlanır.

    • Eylem yan tümcesinde atanmışsa yine de açıkça değiştirilebilir.

    Örneğin:

    UPDATE SET *  -- The target columns that are not in the source are left unchanged.
INSERT *  -- The target columns that are not in the source are set to NULL.
UPDATE SET target.onlyintarget = 5  -- The target column is explicitly updated.
UPDATE SET target.onlyintarget = source.someothercol  -- The target column is explicitly updated from some other source column.

Otomatik şema geliştirmeyi el ile etkinleştirmeniz gerekir. Bkz Şema evrimini etkinleştirme.

Not

Databricks Runtime 12.2 LTS ve üzerindeki kaynak tabloda bulunan sütunlar ve yapı alanları, ekleme veya güncelleme işlemlerinde isimlerine göre belirtilebilir. Databricks Runtime 11.3 LTS ve altında, birleştirme ile şema evrimi için yalnızca INSERT * veya UPDATE SET * eylemler kullanılabilir.

Databricks Runtime 13.3 LTS ve üzerinde, şema evrimini, map<int, struct<a: int, b: int>> gibi haritaların içine yerleştirilmiş yapılarla kullanabilirsiniz.

Birleştirme için şema evrimi söz dizimi

Databricks Runtime 15.4 LTS ve üzerinde SQL veya tablo API'lerini kullanarak birleştirme deyiminde şema evrimi belirtebilirsiniz:

SQL

MERGE WITH SCHEMA EVOLUTION INTO target
USING source
ON source.key = target.key
WHEN MATCHED THEN
  UPDATE SET *
WHEN NOT MATCHED THEN
  INSERT *
WHEN NOT MATCHED BY SOURCE THEN
  DELETE

Python

from delta.tables import *

(targetTable
  .merge(sourceDF, "source.key = target.key")
  .withSchemaEvolution()
  .whenMatchedUpdateAll()
  .whenNotMatchedInsertAll()
  .whenNotMatchedBySourceDelete()
  .execute()
)

Scala programlama dili

import io.delta.tables._

targetTable
  .merge(sourceDF, "source.key = target.key")
  .withSchemaEvolution()
  .whenMatched()
  .updateAll()
  .whenNotMatched()
  .insertAll()
  .whenNotMatchedBySource()
  .delete()
  .execute()

Şema evrimi ile birleştirme işlemi örneği

Şema evrimi ile ve şema evrimi olmadan merge işleminin etkilerinin birkaç örneği aşağıda verilmiştir.

Sütunlar Sorgu (SQL'de) Şema evrimi olmadan davranış (varsayılan) Şema evrimi ile davranış
Hedef sütunlar: key, value
Kaynak sütunlar: key, value, new_value		 MERGE INTO target_table t
USING source_table s
ON t.key = s.key
WHEN MATCHED
THEN UPDATE SET *
WHEN NOT MATCHED
THEN INSERT *		 Tablo şeması değişmeden kalır; yalnızca sütunları keyvalue güncelleştirilir/eklenir. Tablo şeması olarak (key, value, new_value)değiştirilir. Eşleşmeleri olan mevcut kayıtlar, kaynak metindeki value ile new_value ile güncelleştirilir. Yeni satırlar (key, value, new_value) şemasıyla eklenir.
Hedef sütunlar: key, old_value
Kaynak sütunlar: key, new_value		 MERGE INTO target_table t
USING source_table s
ON t.key = s.key
WHEN MATCHED
THEN UPDATE SET *
WHEN NOT MATCHED
THEN INSERT *		 UPDATE ve INSERT eylemleri, hedef sütun old_value kaynakta olmadığından bir hata oluşturur. Tablo şeması olarak (key, old_value, new_value)değiştirilir. Eşleşmeleri olan mevcut kayıtlar, kaynaktaki new_value ile güncellenir ve old_value olduğu gibi bırakılır. Yeni kayıtlar, key, new_value ve NULL olarak belirtilen old_value ile eklenir.
Hedef sütunlar: key, old_value
Kaynak sütunlar: key, new_value		 MERGE INTO target_table t
USING source_table s
ON t.key = s.key
WHEN MATCHED
THEN UPDATE SET new_value = s.new_value		 UPDATE hedef tabloda sütun new_value olmadığından hata oluşturur. Tablo şeması olarak (key, old_value, new_value)değiştirilir. Eşleşen mevcut kayıtlar, new_value şeklinde kaynakta güncellenirken, old_value değiştirilmeden bırakılır; eşleşmeyen kayıtlar için ise NULL olarak new_value girilir. Nota bakın (1).
Hedef sütunlar: key, old_value
Kaynak sütunlar: key, new_value		 MERGE INTO target_table t
USING source_table s
ON t.key = s.key
WHEN NOT MATCHED
THEN INSERT (key, new_value) VALUES (s.key, s.new_value)		 INSERT hedef tabloda sütun new_value olmadığından hata oluşturur. Tablo şeması olarak (key, old_value, new_value)değiştirilir. Yeni kayıtlar, key, new_value ve NULL olarak belirtilen old_value ile eklenir. Mevcut kayıtlara, NULL değişmeden kalacak şekilde new_value için old_value girildi. Nota bakın (1).

(1) Bu davranış, Databricks Runtime 12.2 LTS ve üzeri sürümlerde kullanılabilir; Databricks Runtime 11.3 LTS ve altı sürümlerinde bu koşulda hata verir.

Birleştirme ile sütunları dışlama

Databricks Runtime 12.2 LTS ve üzerinde, sütunları özellikle dışlamak için birleştirme koşullarında EXCEPT klozlarını kullanabilirsiniz. Anahtar sözcüğün davranışı, şema evriminin EXCEPT etkinleştirilip etkinleştirilmediğine bağlı olarak değişir.

Şema evrimi devre dışı bırakılarak, anahtar kelime EXCEPT hedef tablodaki sütunların listesine uygulanır ve sütunların UPDATE veya INSERT eylemlerinden hariç tutulmasına olanak tanır. Hariç tutulan sütunlar null olarak ayarlanır.

Şema evrimi EXCEPT etkinleştirildiğinde, anahtar sözcüğü kaynak tablodaki sütun listesine uygulanır ve sütunların şema evriminden dışlanmasını sağlar. Kaynakta hedefte bulunmayan yeni bir sütun, eğer EXCEPT ifadesinde listelenmişse hedef şemaya eklenmez. Hedefte zaten mevcut olan dışlanan sütunlar null olarak ayarlanır.

Aşağıdaki örneklerde bu söz dizimi gösterilmektedir:

Sütunlar Sorgu (SQL'de) Şema evrimi olmadan davranış (varsayılan) Şema evrimi ile davranış
Hedef sütunlar: id, title, last_updated
Kaynak sütunlar: id, title, review, last_updated		 MERGE INTO target t
USING source s
ON t.id = s.id
WHEN MATCHED
THEN UPDATE SET last_updated = current_date()
WHEN NOT MATCHED
THEN INSERT * EXCEPT (last_updated)		 Eşleşen satırlar, last_updated alanı geçerli tarihe ayarlanarak güncelleştirilir. Yeni satırlar, id ve title değerleri kullanılarak eklenir. Dışlanan alan last_updated olarak nullayarlanır. Alan review hedefte olmadığı için yok sayılır. Eşleşen satırlar, last_updated alanı geçerli tarihe ayarlanarak güncelleştirilir. Şema, alanını revieweklemek için geliştirilir. Yeni satırlar, last_updated hariç, null olarak ayarlanmış tüm kaynak alanlar kullanılarak eklenir.
Hedef sütunlar: id, title, last_updated
Kaynak sütunlar: id, title, review, internal_count		 MERGE INTO target t
USING source s
ON t.id = s.id
WHEN MATCHED
THEN UPDATE SET last_updated = current_date()
WHEN NOT MATCHED
THEN INSERT * EXCEPT (last_updated, internal_count)		 INSERT hedef tabloda sütun internal_count olmadığından hata oluşturur. Eşleşen satırlar, last_updated alanı geçerli tarihe ayarlanarak güncelleştirilir. review alanı hedef tabloya eklenir, ancak internal_count alanı yoksayılır. Eklenen yeni satırlar last_updatednull olarak ayarlandı.

Spark yapılandırmasıyla şema evrimini etkinleştirme (eski)

Spark yapılandırmasını spark.databricks.delta.schema.autoMerge.enabledtrue , geçerli SparkSession'daki tüm yazma işlemleri için şema evrimini etkinleştirmek üzere ayarlayabilirsiniz:

Python

spark.conf.set("spark.databricks.delta.schema.autoMerge.enabled", True)

Scala programlama dili

spark.conf.set("spark.databricks.delta.schema.autoMerge.enabled", true)

SQL

SET spark.databricks.delta.schema.autoMerge.enabled=true

Önemli

Bu yaklaşım üretim kullanımı için önerilmez. Bunun yerine, her yazma işlemi için şema evrimi etkinleştirin:

Oturum genelinde bir yapılandırma ayarlamak, birden çok işlemde istenmeyen şema değişikliklerine yol açabilir ve şemayı hangi işlemlerin geliştirdiği konusunda mantık yürütmeyi zorlaştırır.

Bir yazma işleminde şema evrimini etkinleştirmek için seçenekleri veya söz dizimini kullandığınızda bu, Spark yapılandırmasından önceliklidir.

Tablo şemasını değiştir

Varsayılan olarak, bir tablodaki verilerin üzerine yazmak, şemayı etkilemez. mode("overwrite") kullanılırken replaceWhere olmadan bir tablonun üzerine yazıyorsanız, yine de yazılan verilerin şemasının üzerine yazmak isteyebilirsiniz. seçeneğini overwriteSchemaolarak ayarlayarak tablonun şemasını ve bölümlemini true değiştirirsiniz:

df.write.option("overwriteSchema", "true")

Önemli

Dinamik bölüm üzerine yazma kullanırken overwriteSchema, true olarak belirtemezsiniz.

  • Last updated on