Tablo şemalarını şema evrimi ile 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:

• Rastgele konumlara yeni sütunlar ekleme
• Mevcut sütunları yeniden sıralama
• Varolan sütunları yeniden adlandırma
• Mevcut sütunların türlerini genişletme, bkz Otomatik şema evrimi ile türleri genişletme

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

Important

Ş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.

El ile şema değişiklikleri

Yeni veri yazmadan bir tablonun şemasını açıkça değiştirmek için deyimleri kullanın ALTER TABLE .

Sütun ekle

İsteğe bağlı olarak konum ve açıklama belirterek mevcut tabloya bir veya daha fazla sütun eklemek için kullanın ALTER TABLE ... ADD COLUMNS :

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.

Örnek: İç içe alanlar ekleme

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

İç 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

Sütun açıklamalarını ve sıralamayı değiştirme

Bir sütunun açıklamasını güncelleştirmek veya onu diğer sütunlara göre yeniden sıralamak için ALTER TABLE ... ALTER COLUMN kullanın:

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

Örnek: İç içe alanları değiştirme

İç 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ştir

Tek bir işlemde sütunları ekleme, kaldırma, yeniden sıralama veya yeniden adlandırma dahil olmak üzere tablonun tam sütun listesini yeniden tanımlamak için kullanın ALTER TABLE ... REPLACE COLUMNS :

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

Örnek: İç içe alanları değiştirme

Ö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

Sütunları yeniden adlandırma

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. Delta Lake sütun eşlemesi ile sütunları yeniden adlandırma ve bırakma konusuna bakın.

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

ALTER TABLE table_name RENAME COLUMN old_col_name TO new_col_name

Örnek: İç içe alanları yeniden adlandırma

İç 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

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

Sütunları sil

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. Delta Lake sütun eşlemesi ile sütunları yeniden adlandırma ve bırakma konusuna bakın.

Note

Bir sütunu meta verilerden kaldırmak, dosyalardaki sütunun temel verilerini silmez. Silinen sütun verilerini tamamen silmek için:

• Dosyaları yeniden yazmak için kullanın REORG TABLE .
• Ardından, bırakılan sütun verilerini içeren dosyaları fiziksel olarak silmek için kullanın VACUUM .

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ştirme

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

Mevcut bir tabloya WITH SCHEMA EVOLUTION veya mergeSchema etmek istediğiniz verilerin şemasına göre şema değişiklikleri yapmak için true kullanın ya da INSERT değerini MERGE olarak ayarlayın.

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

• INSERT WITH SCHEMA EVOLUTION.
• MERGE WITH SCHEMA EVOLUTION WITH SCHEMA EVOLUTION SQL söz diziminde veya .withSchemaEvolution() Azure Databricks API'sinde kullanın.
• Toplu yazma veya akış yazma işlemleri için mergeSchema seçeneğini ayarlayın. .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.

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 bulunan ancak hedef tabloda eksik olan sütunlar otomatik olarak bir yazma işleminin parçası olarak eklenir. Bkz Şema evrimini etkinleştirme.

Aşağıdakileri göz önünde bulundurun:

• 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.

INSERT SQL kullanarak şema evrimi ile

Databricks Runtime 18.1 ve sonraki sürümlerde, şema evrimini etkinleştirmek için INSERT deyimlerinde WITH SCHEMA EVOLUTION yan tümcesini kullanın:

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.

WITH SCHEMA EVOLUTION yan tümcesi, INSERT INTO, INSERT OVERWRITE ve INSERT INTO ... REPLACE biçimlerini destekler. Hedef bir Delta Lake veya Apache Iceberg tablosu olmalıdır. Bu yan tümce kullanıldığında, Hive veya Delta dışı başka bir tabloya ekleme işlemi hata verir.

Databricks Runtime 18.0 veya üzerini kullanıyorsanız, bunun yerine seçeneğiyle şema evrimini mergeSchema etkinleştirin. BkzINSERT. DataFrame API'siyle şema evrimi.

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

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

INSERT Yapılandırılmış Akış ile şema evrimi

Aşağıdaki örnek, Yapılandırılmış Akış için Otomatik Yükleyici'de mergeSchema seçeneğinin kullanımını gösterir. 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

için MERGEşema evrimi, 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 tümcesi içinde 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.

Note

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 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 13.3 LTS ve üzerinde, şema evrimini, map<int, struct<a: int, b: int>> gibi haritaların içine yerleştirilmiş yapılarla kullanabilirsiniz.

MERGESQL, Python ve Scala kullanarak şema evrimi ile

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

import io.delta.tables._

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

Şema evrimi MERGE ile örnek işlemleri

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

Kolonlar	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 sonraki sürümlerde kullanılabilir; Databricks Runtime 11.3 LTS ve önceki sürümlerde bu durumda 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 kapatıldığında, EXCEPT anahtar sözcüğü hedef tablodaki sütun listesi için geçerlidir ve sütunların UPDATE veya INSERT işlemlerinin dışında bırakılmasını sağlar. 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 yer alan ancak hedef tabloda bulunmayan yeni bir sütun, EXCEPT yan tümcesinde listelenmişse hedef şemaya eklenmez. Hedefte zaten mevcut olan dışlanan sütunlar null olarak ayarlanır.

EXCLUDE ile MERGE örnekleri

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

Kolonlar	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

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

SQL

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

Note

Databricks, üretim için bu yaklaşımı önermez. Oturum genelinde bir yapılandırmanın ayarlanması, 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.

Bunun yerine, her yazma işlemi için şema evrimi etkinleştirin:

• INSERT ve toplu/akış yazma işlemleri için .option("mergeSchema", "true") veya INSERT WITH SCHEMA EVOLUTION kullanın
• MERGE ifadeleri için MERGE WITH SCHEMA EVOLUTION kullanın

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, tablodaki verilerin üzerine yazmak şemanın üzerine yazmaz. mode("overwrite") olmadan replaceWhere kullanarak bir tablonun üzerine yazdığınızda, yine de yazılan verilerin şemasını üzerine yazmak isteyebilirsiniz.

Tablonun şemasını ve bölümlemini değiştirmek için seçeneğini olarak overwriteSchemaayarlayıntrue:

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

Note

Dinamik bölüm üzerine yazma kullanırken overwriteSchema, true olarak belirtemezsiniz. Bkz . Dinamik bölüm (eski) ile partitionOverwriteMode üzerine yazılır.