타입 범위 확장

Databricks Runtime 15.4 LTS 이상의 Delta Lake 테이블에서 사용할 수 있는 형식 확대를 사용하면 데이터 파일을 다시 작성하지 않고 열 데이터 형식을 더 넓은 형식으로 변경할 수 있습니다.

모든 Unity 카탈로그 관리 테이블은 기본적으로 Delta Lake를 사용합니다. Delta Lake 및 Apache Iceberg에 대한 Unity 카탈로그 관리 테이블을 참조하세요.

참고 사항

형식 확대를 사용하도록 설정하면 판독기 및 기록기 프로토콜이 업그레이드됩니다. 이는 외부 Delta Lake 클라이언트와의 호환성에 영향을 줄 수 있습니다. Delta Lake 기능 호환성 및 프로토콜을 참조하세요.

형식 확장이 활성화된 테이블은 Databricks Runtime 15.4 LTS 이상에서만 읽을 수 있습니다.

지원되는 형식 변경

다음 규칙에 따라 형식을 확장할 수 있습니다.

원본 유형	지원되는 광범위한 형식
`BYTE`	`SHORT`, `INT`, `BIGINT`, `DECIMALDOUBLE`
`SHORT`	`INT`, `BIGINT`, , `DECIMAL`, `DOUBLE`
`INT`	`BIGINT`, , `DECIMALDOUBLE`
`BIGINT`	`DECIMAL`
`FLOAT`	`DOUBLE`
`DECIMAL`	더 높은 정밀도와 규모로 `DECIMAL`
`DATE`	`TIMESTAMP_NTZ`
`VOID`	모든 형식

형식 변경은 구조체, 맵 및 배열 내에 중첩된 최상위 열 및 필드에 대해 지원됩니다.

참고 사항

VOID 모든 형식에 대해 테이블에서 형식 확대를 사용하도록 설정할 필요가 없습니다. 열 형식 VOID 을 업데이트하는 모든 작업은 추가 구성 없이 성공합니다. VOID 형식 확대는 Databricks Runtime 18.2 이상에서 사용할 수 있습니다.

10진수 동작

Spark는 기본적으로 작업이 정수 형식을 decimal 또는 double으로 승격한 후, 다운스트림 데이터 수집 과정에서 해당 값을 다시 정수 열에 기록할 때 값의 소수 부분을 제거합니다. 할당 정책 동작에 대한 자세한 내용은 스토어 할당을 참조하세요.

숫자 형식을 decimal으로 변경할 때, 전체 정밀도는 시작 정밀도보다 크거나 같아야 합니다. 또한 배율을 늘리면 전체 정확도가 해당 크기만큼 증가해야 합니다.

byte, short및 int 유형의 최소 요구 사항은 decimal(10,0)입니다. long의 최소 목표는 decimal(20,0)입니다.

decimal(10,1)있는 필드에 소수 자릿수를 두 개 추가하려는 경우 최소 대상은 decimal(12,3).

형식 확장 기능 활성화

참고 사항

delta.enableTypeWidening 테이블 속성을 true로 설정하여 기존 테이블에서 형식 확장을 사용하도록 설정할 수 있습니다.

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

테이블을 만드는 동안 형식 확대를 사용하도록 설정할 수도 있습니다.

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

수동으로 형식 변경 적용

명령을 ALTER COLUMN 사용하여 수동으로 형식을 변경합니다.

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

이 작업은 기본 데이터 파일을 다시 작성하지 않고 테이블 스키마를 업데이트합니다. 자세한 내용은 ALTER TABLE를 참조하세요.

자동 스키마 진화를 사용하여 형식 확장

형식 확장과 함께 스키마 진화를 사용하여 들어오는 데이터의 형식과 일치하도록 대상 테이블의 데이터 형식을 업데이트합니다.

참고 사항

형식 확대를 사용하도록 설정하지 않으면 스키마 진화는 항상 대상 테이블의 열 형식과 일치하도록 데이터를 다운캐스트하려고 시도합니다. 대상 테이블의 데이터 형식을 자동으로 확장하지 않으려면 스키마 진화를 사용하도록 설정된 워크로드를 실행하기 전에 형식 확대를 해제해야 합니다.

데이터 수집 시 열의 데이터 형식을 확장하기 위해 스키마 진화를 사용하려면 다음 조건을 충족해야 합니다.

쓰기 명령은 자동 스키마 진화를 사용하도록 설정하여 실행됩니다.
대상 테이블에는 형식 확장이 활성화되어 있습니다.
원본 열 형식이 대상 열 형식보다 넓습니다.
형식 확장은 형식 변경을 지원합니다.

이러한 모든 조건을 충족하지 않는 형식 불일치는 일반적인 스키마 적용 규칙을 따릅니다. 스키마 적용을 참조하세요 .

Example

다음 예제에서는 스키마 진화와 함께 형식 확장이 작동하는 방법을 보여 줍니다.

Python

INT 열이 있는 대상 테이블과 BIGINT 열이 있는 소스 테이블을 만듭니다:

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

saveAsTable()를 스키마 진화와 함께 사용하여 append 작업 중에 INT 열을 BIGINT로 자동 확장합니다:

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

스키마 진화와 함께 MERGE INTO 사용:

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

INT 열이 있는 대상 테이블과 BIGINT 열이 있는 소스 테이블을 만듭니다:

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

saveAsTable()를 스키마 진화와 함께 사용하여 append 작업 중에 INT 열을 BIGINT로 자동 확장합니다:

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

스키마 진화와 함께 MERGE INTO 사용:

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

INT 열이 있는 대상 테이블과 BIGINT 열이 있는 소스 테이블을 만듭니다:

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

INSERT INTO를 스키마 진화와 함께 사용하여 append 작업 중에 INT 열을 BIGINT로 자동 확장합니다:

INSERT WITH SCHEMA EVOLUTION INTO target_table SELECT * FROM source_table;

스키마 진화와 함께 MERGE INTO 사용:

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 *;

자동 로더

Important

자동 로더의 형식 확장 지원은 공개 미리 보기로 제공됩니다.

자동 로더는 자동 스키마 진화를 통해 형식 확대를 지원합니다. 자동 로더를 사용하여 형식 확장 및 스키마 진화를 사용하도록 설정된 Delta Lake 테이블에 데이터를 수집하는 경우 열 형식은 들어오는 데이터와 일치하도록 자동으로 확장됩니다.

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

자동 로더를 사용하여 자동 형식 확대를 참조하세요. 또한 대상 테이블에는 형식 확대를 사용하도록 설정해야 합니다. 형식 확장을 활성화하는 방법을 참조하세요.

형식 확대 테이블 기능 비활성화하기

속성을 false설정하여 사용 가능한 테이블에서 실수로 형식이 확대되는 것을 방지할 수 있습니다.

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

이 설정은 테이블의 이후 형식 변경을 방지하지만 형식 확장 테이블 기능을 제거하거나 이전 형식 변경 내용을 실행 취소하지는 않습니다.

형식 확장 테이블 기능을 완전히 제거해야 하는 경우 다음 예제와 같이 DROP FEATURE 명령을 사용할 수 있습니다.

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

참고 사항

Databricks Runtime 15.4 LTS를 사용하여 형식 확대를 사용하도록 설정한 테이블은 대신 기능을 typeWidening-preview 삭제해야 합니다.

형식 확장 삭제 시 Databricks는 현재 테이블 스키마를 준수하지 않는 모든 데이터 파일을 다시 작성합니다. Delta Lake 테이블 기능 삭제 및 테이블 프로토콜 다운그레이드를 참조하세요.

Delta Lake 테이블에서 스트리밍하기

구조적 스트리밍의 형식 확장 지원은 Databricks Runtime 16.4 LTS 이상에서 사용할 수 있습니다.

형식 확대를 사용하도록 설정된 Delta Lake 테이블에서 스트리밍하는 경우 대상 테이블의 옵션으로 스키마 mergeSchema 진화를 사용하도록 설정하여 스트리밍 쿼리에 대한 자동 형식 확대를 구성할 수 있습니다. 대상 테이블에는 형식 확대를 사용하도록 설정해야 합니다. 형식 확장을 활성화하는 방법을 참조하세요.

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

mergeSchema가 사용하도록 설정되고 대상 테이블에 형식 확장이 활성화된 경우:

수동 개입 없이도 유형 변경 내용이 다운스트림 테이블에 자동으로 적용됩니다.
새 열은 다운스트림 테이블 스키마에 자동으로 추가됩니다.

사용하도록 설정하지 않으면 mergeSchema 기본적으로 대상 열 형식과 일치하도록 spark.sql.storeAssignmentPolicy 값을 다운캐스트하는 구성에 따라 값이 처리됩니다. 할당 정책 동작에 대한 자세한 내용은 스토어 할당을 참조하세요.

스트림에서 유형 변경 처리

Delta Lake 테이블에서 스트리밍할 때 형식 변경을 포함하여 비가산적 스키마 변경 내용을 추적하는 스키마 추적 위치를 제공할 수 있습니다. Databricks Runtime 18.0 이하에서는 스키마 추적 위치를 제공해야 하며 Databricks Runtime 18.1 이상에서는 선택 사항입니다.

SQL로는 schemaTrackingLocation을 설정할 수 없습니다. 지원되지 않는 기능을 참조하세요.

schemaTrackingLocation 는 스트리밍 검사점과 동일한 경로 내의 위치로 설정해야 합니다. 다음은 그 예입니다.

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

스키마 추적 위치를 설정한 후 스트림은 형식 변경을 감지한 다음 중지될 때 추적된 스키마를 진화합니다. 이때 다운스트림 테이블에서 형식 확대를 사용하도록 설정하거나 스트리밍 쿼리를 업데이트하는 등 형식 변경을 처리해야 합니다.

처리를 다시 시작하려면 다음 예제와 같이 Spark 구성 spark.databricks.delta.streaming.allowSourceColumnTypeChange 또는 DataFrame 판독기 옵션을 allowSourceColumnTypeChange설정합니다.

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"

스트림이 중지되면 검사점 ID <checkpoint_id> 및 Delta Lake 원본 테이블 버전 <delta_source_table_version>이 오류 메시지로 표시됩니다.

스트리밍 Delta Lake 옵션의 전체 목록은 Delta Lake를 참조하세요.

Lakeflow 파이프라인

파이프라인 수준에서 또는 개별 테이블에 대해 Lakeflow 파이프라인에 대해 형식 확대를 사용하도록 설정할 수 있습니다. 형식 확대를 사용하면 스트리밍 테이블을 완전히 새로 고치지 않고도 파이프라인 실행 중에 열 형식을 자동으로 확장할 수 있습니다. 구체화된 뷰의 형식 변경은 항상 전체 다시 계산을 트리거하며, 원본 테이블에 형식 변경이 적용되면 해당 테이블에 의존하는 구체화된 뷰는 새 형식을 반영하기 위해 전체 다시 계산이 필요합니다.

전체 파이프라인에 대해 형식 확장 사용

파이프라인의 모든 테이블에 대해 형식 확대를 사용하도록 설정하려면 파이프라인 구성 pipelines.enableTypeWidening을 설정합니다.

JSON

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

YAML

configuration:
  pipelines.enableTypeWidening: 'true'

특정 테이블에 대해 형식 확장 사용

테이블 속성을 delta.enableTypeWidening설정하여 개별 테이블에 대해 형식 확대를 사용하도록 설정할 수도 있습니다.

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

다운스트림 판독기와의 호환성

형식 확장이 활성화된 테이블은 Databricks Runtime 15.4 LTS 이상에서만 읽을 수 있습니다. 파이프라인에서 형식 확장이 설정된 테이블을 Databricks Runtime 14.3 이하의 판독기에서 읽을 수 있게 하려면 다음 중 하나를 수행해야 합니다.

속성을 delta.enableTypeWidening/pipelines.enableTypeWidening 제거하거나 false로 설정하여 형식 확대를 해제하고 테이블의 전체 새로 고침을 트리거합니다.
테이블에서 호환성 모드 를 사용하도록 설정합니다.

OpenSharing

참고 사항

OpenSharing의 형식 확장 지원은 Databricks Runtime 16.1 이상에서 사용할 수 있습니다.

형식 확대를 사용하도록 설정된 Delta Lake 테이블을 공유하는 것은 Databricks-to-Databricks OpenSharing에서 지원됩니다. 공급자와 받는 사람은 Databricks Runtime 16.1 이상에 있어야 합니다.

OpenSharing을 사용하여 형식 확장이 활성화된 Delta Lake 테이블에서 변경 데이터 피드를 읽으려면 응답 형식을 다음으로 delta설정해야 합니다.

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

형식 변경 내용 간에 변경 데이터 피드를 읽는 것은 지원되지 않습니다. 대신 두 개의 별도 읽기로 작업을 분할해야 합니다. 하나는 형식 변경이 포함된 테이블 버전에서 끝나고 다른 하나는 형식 변경이 포함된 버전에서 시작됩니다.

Limitations

Apache Iceberg 호환성

Apache Iceberg는 형식 확대에서 적용되는 모든 형식 변경을 지원하지 않습니다. 빙산 스키마 진화를 참조하세요.

지원되지 않는 형식 변경에는 다음이 포함됩니다.

byte, short, int, long 또는 decimaldouble
소수 자릿수 증가
date - timestampNTZ

Delta Lake 테이블에서 Iceberg 리드를 활성화하면, 앞선 타입 변경 중 하나를 적용하면 오류가 발생합니다. Iceberg 클라이언트를 사용하여 Delta Lake 테이블 읽기를 참조하세요.

이러한 지원되지 않는 형식 변경 내용 중 하나를 Delta Lake 테이블에 적용하는 경우 다음 두 가지 옵션이 있습니다.

Iceberg 메타데이터 다시 생성: 다음 명령을 사용하여 테이블 확장 형식 기능 없이 Iceberg 메타데이터를 다시 생성합니다.
```
ALTER TABLE <table-name> SET TBLPROPERTIES ('delta.universalFormat.config.icebergCompatVersion' = '<version>')
```
이를 통해 호환되지 않는 타입 변경을 적용한 후에도 Iceberg 리드와의 호환성을 유지할 수 있습니다.
형식 확장 테이블 기능 제거: 형식 확장 테이블 기능 사용 중지를 참조하세요.

형식 종속 함수

일부 SQL 함수는 입력 데이터 형식에 따라 달라지는 결과를 반환합니다. 예를 들어, hash 함수는 인수 형식이 다르면 동일한 논리 값에 대해 다른 해시 값을 반환합니다. hash(1::INT)는 hash(1::BIGINT)와 다른 결과를 반환합니다.

다른 형식 종속 함수는 다음과 xxhash64bit_getbit_reversetypeof같습니다.

이러한 함수를 사용하는 쿼리에서 안정적인 결과를 위해서는 값을 원하는 형식으로 명시적으로 캐스팅해야 합니다.

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

지원되지 않는 기능

형식이 변경된 Delta Lake 테이블에서 스트리밍할 때 SQL을 사용하여 스키마 추적 위치를 설정할 수 없습니다.
OpenSharing을 사용하여 Databricks가 아닌 소비자에게 형식 확장이 설정된 테이블을 공유할 수 없습니다.

피드백

이 페이지가 도움이 되었나요?

Last updated on 2026-08-03

타입 범위 확장

지원되는 형식 변경

10진수 동작

형식 확장 기능 활성화

수동으로 형식 변경 적용

자동 스키마 진화를 사용하여 형식 확장

Example

Python

Scala

SQL

자동 로더

형식 확대 테이블 기능 비활성화하기

Delta Lake 테이블에서 스트리밍하기

Python

Scala

스트림에서 유형 변경 처리

Python

Scala

Python

Scala

SQL

Lakeflow 파이프라인

전체 파이프라인에 대해 형식 확장 사용

JSON

YAML

특정 테이블에 대해 형식 확장 사용

Python

SQL

다운스트림 판독기와의 호환성

OpenSharing

Limitations

Apache Iceberg 호환성

형식 종속 함수

Python

Scala

SQL

지원되지 않는 기능

피드백

추가 리소스