파이프라인에서 기본 게시 모드 사용

2025-06-28

중요합니다

이 문서에서는 가상 스키마(레거시 게시 모드)를 사용하는 LIVE 파이프라인을 기본 게시 모드로 마이그레이션하는 방법을 설명합니다.

기본 게시 모드를 사용하면 단일 파이프라인이 여러 카탈로그 및 스키마에 쓸 수 있으며 파이프라인 내에서 테이블 및 뷰를 사용하기 위한 간소화된 구문을 포함합니다. 레거시 게시 모드는 더 이상 사용되지 않는 것으로 간주되며 Databricks는 모든 파이프라인을 기본 게시 모드로 마이그레이션하는 것이 좋습니다.

마이그레이션은 파이프라인의 메타데이터에 영향을 주지만 데이터 세트를 읽거나 이동하거나 쓰지 않습니다.

파이프라인이 레거시 게시 모드를 사용하는지 알 수 있는 방법

레거시 게시 모드 파이프라인은 Lakeflow 선언적 파이프라인 설정 UI의 요약 필드에 표시됩니다. 파이프라인의 JSON 사양에서 target 필드가 설정되어 있는 경우, 파이프라인이 레거시 게시 모드를 사용하는 것을 확인할 수도 있습니다.

기본 게시 모드로 마이그레이션하기 위한 고려 사항

다음 참고 사항은 마이그레이션 중에 유의하는 데 유용합니다.

파이프라인을 기본 게시 모드로 마이그레이션한 후에는 가상 스키마를 사용하여 LIVE 다시 마이그레이션할 수 없습니다.
레거시 및 기본 게시 모드 간의 구문 변경 내용을 처리하여 마이그레이션을 위해 파이프라인을 준비해야 할 수 있습니다. 대부분의 파이프라인에는 변경이 필요하지 않습니다. 자세한 내용은 마이그레이션을 위한 파이프라인 준비를 참조하세요.
마이그레이션은 메타데이터에만 영향을 줍니다. 데이터 세트를 읽거나 쓰거나 이동하지 않습니다.
기본 게시 모드에서는 구체화된 뷰 및 스트리밍 테이블을 만든 후 스키마 간에 이동할 수 없습니다.
기본 게시 모드에는 Databricks CLI 버전 v0.230.0 이상이 필요합니다. Databricks CLI 설치 또는 업데이트를 참조하세요.

기본 게시 모드로 마이그레이션

다음 단계를 사용하여 기본 게시 모드로 마이그레이션합니다.

Databricks UI에서 마이그레이션하려는 파이프라인을 엽니다.
업데이트를 일시 중지하고 현재 실행 중인 파이프라인을 중지합니다.

마이그레이션을 완료하기 전에 하나 이상의 업데이트를 실행해야 합니다. 파이프라인이 트리거되었거나 이미 일시 중지된 경우 수동으로 단일 업데이트를 실행합니다. 파이프라인이 연속적이면, 상태에 도달했는지 (또는 이미 그 상태에 있는지) RUNNING 확인한 다음, 파이프라인을 일시 중지합니다.
필요에 따라 마이그레이션해야 할 수 있는 코드를 준비합니다.

기본 게시 모드는 일반적으로 레거시 게시 모드와 호환되지만 업그레이드할 때 파이프라인 코드가 올바르게 실행되도록 마이그레이션을 위해 파이프라인 을 올바르게 준비해야 합니다. 대부분의 파이프라인은 변경이 필요하지 않습니다.
파이프라인 설정에 구성을 추가하고 pipelines.enableDPMForExistingPipeline를 true로 설정합니다.
수동 업데이트를 시작하고 업데이트를 완료하도록 합니다.
파이프라인 설정 JSON 페이지로 이동합니다. target 필드를 찾아서 schema로 대체하세요 (동일한 값 유지). 구성에는 다음과 같은 JSON이 포함되어야 합니다.
```
...
"catalog": "main",
"configuration": {
  "pipelines.setMigrationHints": "true",
  "pipelines.enableDPMForExistingPipeline": "true"
},
"schema": "default",
"data_sampling": "false",
...
```
JSON을 저장합니다.
파이프라인 설정에서 pipelines.setMigrationHints 및 pipelines.enableDPMForExistingPipeline에 대한 파이프라인 구성을 제거합니다.
마이그레이션 전과 마찬가지로 파이프라인 업데이트를 사용하도록 설정합니다.

이제 파이프라인에서 기본 게시 모드를 사용할 수 있습니다. 문제가 표시되면 다음 섹션을 사용하여 문제를 해결합니다. 문제가 지속되면 Databricks 계정 관리자에게 문의하세요.

마이그레이션을 위한 파이프라인 준비

기본 게시 모드는 일반적으로 레거시 게시 모드와 역호환되지만, 일부 파이프라인은 실행을 위해 수정이 필요할 수 있습니다. 다음 참고는 마이그레이션을 위해 파이프라인을 준비하는 데 도움이 될 수 있습니다.

`LIVE` 키워드

레거시 게시 모드의 키워드는 LIVE 파이프라인 기본값을 사용하여 개체의 카탈로그 및 스키마를 한정합니다. 기본 게시 모드는 더 이상 키워드를 LIVE 사용하여 테이블 또는 뷰를 한정하지 않습니다. 키워드는 LIVE 무시되고 파이프라인의 기본 카탈로그 및 스키마로 대체됩니다. 일반적으로 이는 레거시 게시 모드에서 LIVE 키워드와 동일한 기본 카탈로그 및 스키마를 사용하며, 나중에 파이프라인에 USE CATALOG 또는 USE SCHEMA 명령을 추가하지 않는 한 그렇습니다.

레거시 게시 모드에서 키워드(예: LIVE)가 없는 table1 부분적으로 정규화된 테이블 및 뷰 참조는 Spark 기본값을 사용합니다. 기본 게시 모드에서 부분적으로 정규화된 참조는 파이프라인 기본값을 사용합니다. Spark 기본값과 파이프라인이 다른 경우 마이그레이션하기 전에 부분적으로 정규화된 테이블 또는 뷰의 이름을 정규화해야 합니다.

비고

마이그레이션 후 코드에서 키워드를 LIVE 제거할 수 있습니다. 필요에 따라 키워드를 LIVE 정규화된 테이블 또는 뷰 이름으로 바꿀 수 있습니다.

`LIVE` 키워드를 사용한 열 참조

키워드를 LIVE 사용하여 기본 게시 모드에서 열을 정의할 수 없습니다. 예를 들어 다음 코드는 다음과 같습니다.

CREATE OR REPLACE MATERIALIZED VIEW target AS SELECT LIVE.source.id FROM LIVE.source;

마이그레이션하기 전에 다음으로 바꿔야 합니다.

CREATE OR REPLACE MATERIALIZED VIEW target AS SELECT source.id FROM LIVE.source;

이 버전은 두 가지 게시 모드 모두에서 작동합니다.

경고 및 오류

레거시 게시 모드의 일부 경고는 기본 게시 모드의 오류로 대체되었습니다.

자체 참조 기본 게시 모드에서는 자체 참조(또는 순환 참조)가 허용되지 않으며 레거시 게시 모드에서 정의되지 않은 결과가 발생했습니다. 다음은 그 예입니다.

CREATE OR REPLACE MATERIALIZED VIEW table1 AS SELECT * FROM target_catalog.target_schema.table1;

는 레거시 게시 모드에서 경고를 생성하고 정의되지 않은 결과를 갖습니다. 기본 게시 모드에서는 오류가 생성됩니다.

다중 파트 이름 기본 게시 모드(다중 파트 이름)의 이름에는 마침표가 사용할 수 없습니다. 예를 들어 다음 Python 코드는 레거시 모드에서 유효하지만 기본 모드에서는 유효하지 않습니다.

@dlt.view(name=”a.b.c”)
def transform():
  return …

마이그레이션하기 전에 보기 이름을 마침표 문자가 포함되지 않은 이름으로 바꿉니다.

문제 해결

다음 표에서는 레거시 게시 모드에서 마이그레이션할 때 발생할 수 있는 오류를 설명합니다.

오류	설명
`CANNOT_MIGRATE_HMS_PIPELINE`	Hive 메타스토어 파이프라인에는 마이그레이션이 지원되지 않습니다. 또는 마이그레이션 전에 Hive 메타스토어에서 Unity 카탈로그로 파이프라인을 복제할 수 있습니다. Hive 메타스토어 파이프라인복제하여 Unity 카탈로그 파이프라인 만들기 참조하세요.
`MISSING_EXPECTED_PROPERTY`	이 오류는 구성을 추가 `pipelines.enableDPMForExistingPipeline` 하기 전에 최근 업데이트를 실행하지 않았음을 나타냅니다. 해당 구성을 제거하고, 누락된 경우에는 `pipelines.setMigrationHints` 구성을 추가하고 `true`로 설정합니다. 업데이트를 실행한 다음 3단계에서 계속 진행합니다.
`PIPELINE_INCOMPATIBLE_WITH_DPM`	이 오류는 파이프라인 코드가 기본 게시 모드와 완전히 호환되지 않음을 나타냅니다. 마이그레이션을 위한 파이프라인 준비를 참조하세요.