SYNC
적용 대상:
Databricks SQL Databricks 런타임 Unity 카탈로그만
이 SYNC 명령을 사용하여 Hive Metastore의 외부 테이블을 Unity 카탈로그의 외부 테이블로 업그레이드합니다. Databricks 작업 영역 스토리지 외부에 저장된 Hive 관리 테이블(DBFS 루트라고도 함)을 Unity 카탈로그의 외부 테이블로 업그레이드하는 데 사용할 SYNC 수도 있습니다. 작업 영역 스토리지에 저장된 Hive 관리 테이블을 업그레이드하는 데 사용할 수 없습니다. 이러한 테이블을 업그레이드하려면 CREATE TABLE CLONE을 사용합니다.
기존 Hive Metastore 테이블에서 Unity 카탈로그에 새 테이블을 만들고 Hive Metastore의 원본 테이블이 수정될 때 Unity 카탈로그 테이블을 업데이트하는 데 사용할 SYNC 수 있습니다.
SYNC 명령은 SYNC SCHEMA 구문을 사용하여 스키마 수준에서 실행하거나 SYNC TABLE 구문을 사용하여 개별 테이블에 대해 실행할 수 있습니다.
이 명령은 업그레이드하는 각 원본 테이블에 쓰기 작업(ALTER TABLE)을 수행하여 부기용 테이블 속성을 추가합니다.
델타 테이블의 경우 쓰기 작업을 수행하려면 명령을 실행하는 클러스터 또는 SQL Warehouse에 테이블 위치에 대한 쓰기 액세스 권한이 있어야 합니다.
Databricks Runtime 12.2 LTS 이상에서는 명령을 실행 SYNC 하기 전에 Spark 구성 spark.databricks.sync.command.disableSourceTableWrites 을 설정하여 이 동작을 해제할 true 수 있습니다. 로 trueSYNC 설정하면 새 테이블 속성이 추가되지 않으므로 테이블이 이전에 Unity 카탈로그로 업그레이드되었는지 검색하지 못할 수 있습니다.
이 경우 테이블 이름만 사용하여 테이블이 이전에 Unity 카탈로그로 업그레이드되었는지 확인합니다.
마지막 SYNC 명령 이후 원본 테이블의 이름이 변경된 경우 사용자는 구성 true이 있을 때 SYNC 명령을 다시 실행하기 전에 대상 테이블의 이름을 수동으로 바꿔야 합니다.
Important
명령이 SYNC 실행되면 SET TBLPROPERTIES 작업은 대상 Unity 카탈로그 외부 테이블 참조를 나타내는 테이블 속성을 추가합니다. 이 작업은 새 Delta 스냅샷 계산하고 테이블 델타 로그에 새 항목을 추가하여 클라우드 스토리지의 대상 테이블 경로에 기록합니다.
구문
SYNC { SCHEMA target_schema [AS EXTERNAL] FROM source_schema |
TABLE target_table [AS EXTERNAL] FROM source_table }
[SET OWNER principal]
[DRY RUN]
매개 변수
SCHEMASYNC스키마 내의 모든 테이블입니다.-
사용자가 테이블을 만들 권한이 있는 Unity 카탈로그의 기존 스키마입니다.
-
사용자가 소유한
hive_metastore카탈로그의 기존 스키마입니다.
-
TABLESYNC개별 테이블입니다.-
사용자가 테이블을 만들 권한이 있는 스키마의 Unity 카탈로그에 있는 새 테이블 또는 기존 테이블입니다. 테이블이 이미 존재하는 경우
source_table과 일치하도록 바꿔지며 사용자도 테이블을 소유해야 합니다. 테이블이 없으면 만들어집니다. -
사용자가 소유한
hive_metastore의 기존 테이블입니다.
-
-
선택적으로 Unity 카탈로그에서 업그레이드된 테이블의 소유자를
principal로 설정합니다. 기본 소유자는 현재 사용자입니다. AS EXTERNALSYNCDatabricks 작업 영역 스토리지(DBFS 루트라고도 함) 외부에 저장된 Hive 관리 테이블 또는 스키마를 Unity 카탈로그의 외부 테이블에 저장합니다. 작업 영역 스토리지에 저장된 Hive 관리 테이블을 업그레이드하는 데 사용할AS EXTERNAL수 없습니다.DRY RUN지정된 경우 대상 테이블을 실제로 만들거나 업그레이드하지 않고
source_table또는source_schema내의 테이블을 업그레이드할 수 있는지 여부를 확인합니다. 이 명령은 테이블을 업그레이드할 수 있는 경우DRY_RUN_SUCCESS를 반환합니다.AS EXTERNALDatabricks Runtime 13.2 이상을 시작하면 이 선택적 절을 추가하여 Hive 메타스토어의 관리 테이블이 Unity 카탈로그의 외부 테이블로 업그레이드되도록 지정할 수 있습니다. 함께SYNC SCHEMA사용하면 관리되는 테이블을 비롯한 모든 테이블에 적용됩니다.source_schema.
반품
다음 열이 포함된 보고서:
source_schema STRING원본 스키마의 이름입니다. 원본이 지원되지 않는 임시 뷰인 경우 스키마는
NULL입니다.source_name STRING NOT NULL원본 테이블의 이름입니다.
source_type STRING NOT NULL테이블 형식:
MANAGED또는EXTERNALtarget_catalog STRING NOT NULL테이블이 동기화되는 Unity 카탈로그의 대상 카탈로그입니다.
target_schema STRING NOT NULL테이블이 동기화되는 Unity 카탈로그의 대상 스키마입니다.
target_name STRING NOT NULL원본 테이블이 동기화되는 Unity 카탈로그의 테이블 이름입니다. 이 이름은 원본 테이블 이름과 일치합니다.
status_code STRING NOT NULL원본 테이블에 대한
SYNC명령의 결과에 대한 상태 코드입니다.description STRING원본 테이블의 동기화 명령 상태에 대한 설명 메시지입니다.
SYNC에서 반환된 일반 상태 코드
SYNC 명령은 업그레이드 상태를 나타내는 Unity 카탈로그로 업그레이드할 각 테이블의 출력에 고유한 status_code 필드를 제공합니다.
이를 해결하기 위한 권장 사항과 함께 몇 가지 일반적인 상태 코드는 다음과 같습니다.
DRY_RUN_SUCCESS: 시험 실행에 성공했습니다.테이블은
SYNC명령을 사용하여 Unity 카탈로그로 업그레이드할 수 있습니다.DBFS_ROOT_LOCATION: Databricks 파일 시스템 루트에 있는 테이블입니다.테이블은 Databricks 파일 시스템 루트 위치에 있습니다. Unity 카탈로그에서는 지원되지 않습니다.
DEEP CLONE옵션과 함께 CREATE TABLE 명령을 사용하여 테이블 데이터를 Unity 카탈로그 위치에 복사합니다.EXTERNAL_TABLE_IN_MANAGED_LOCATION: 외부 테이블 경로는 관리 스토리지 아래에 있을 수 없습니다.외부 테이블에 지정된 경로는 Unity 카탈로그 관리 스토리지 내에 있습니다. 테이블이 관리되는 스토리지 아래에 있어야 하는 경우
DEEP CLONE옵션과 함께 CREATE TABLE 명령을 사용하여 테이블을 관리형 테이블로 업그레이드하거나 테이블 위치를 Unity 카탈로그 관리되는 스토리지 밖으로 이동합니다.HIVE_SERDE: 이 테이블은 Hive Metastore에서 Unity 카탈로그로 업그레이드할 수 없습니다. 이유: Hive SerDe 테이블입니다.Hive SerDe 테이블은 Unity 카탈로그에서 지원되지 않습니다. 테이블을 델타 형식으로 변경하고
SYNC명령을 실행하여 업그레이드합니다.INVALID_DATASOURCE_FORMAT: 데이터 원본 형식이 지정되지 않았거나 지원되지 않습니다.지원되는 데이터 원본 형식(Delta, Parquet, CSV, JSON, ORC, TEXT) 중 하나를 사용합니다.
LOCATION_OVERLAP: 입력 경로가 다른 외부 테이블과 겹칩니다.테이블 위치가 다른 외부 테이블과 겹칩니다. 테이블에 다른 위치를 사용하거나 겹치는 외부 테이블을 제거합니다.
MULTIPLE_EXT_LOCATIONS: 입력 경로에 다른 외부 위치가 포함되어 있습니다.제공된 테이블 경로의 하위 디렉터리인 외부 위치가 두 개 이상 있습니다. 테이블 위치 내의 외부 위치가 필요한지 확인합니다.
MULTIPLE_TARGET_TABLE: 다른 동기화 테이블이 이미 존재합니다. 원본 테이블당 하나의 대상 테이블만 허용됩니다.원본 테이블은 이전에 허용되지 않는 다른 대상 테이블과 이미 동기화되었습니다.
SYNC를 다른 테이블에 강제 적용하려면 원본 테이블에서 테이블 속성upgraded_to를 제거하거나 더 이상 필요하지 않은 경우 Unity 카탈로그에서 이전에 동기화된 테이블을 제거합니다.NOT_EXTERNAL: 테이블은 Hive 메타스토어에서 Unity 카탈로그로 업그레이드할 수 없습니다. 이유: 외부 테이블이 아닙니다.SYNC명령은 Unity 카탈로그로의 외부 테이블 마이그레이션만 지원합니다. 관리 테이블의 경우DEEP CLONE옵션과 함께 CREATE TABLE 명령을 사용하여 Unity 카탈로그에서 관리 테이블을 만듭니다. 또는 명령과AS EXTERNAL함께 절을SYNC사용하여 Unity 카탈로그에서 외부 테이블을 만듭니다.READ_ONLY_CATALOG: 델타 공유 카탈로그 내의 데이터는 읽기 전용이며 수정하거나 삭제할 수 없습니다.선택한 카탈로그는 읽기 전용인 델타 공유 카탈로그입니다. 읽기 전용 카탈로그 내의 테이블은
SYNC명령을 사용하여 업데이트할 수 없습니다.SUCCESS: 테이블이 성공적으로 동기화되었습니다.TABLE_ALREADY_EXISTS: 대상 테이블이 이미 존재합니다.선택한 테이블과 동일한 이름을 가진 테이블이 Unity 카탈로그에 이미 존재합니다. Unity 카탈로그에서 기존 테이블의 이름을 바꾸거나 제거하고
SYNC명령을 다시 실행합니다.TEMP_TABLE_NOT_SUPPORTED: 임시 테이블 또는 뷰가 지원되지 않습니다.임시 테이블 또는 뷰는 Unity 카탈로그로 업그레이드할 수 없습니다. 임시 테이블이나 뷰를 사용하려면 Unity 카탈로그에서 SHOW CREATE TABLE 명령을 사용하여 Unity 카탈로그에서 다시 만듭니다.
TIMEOUT: 동기화 작업 시간이 초과되었습니다.동기화 명령 작업을 완료하는 데 300초 이상 걸렸습니다.
spark.databricks.sync.command.task.timeout을 초 단위로 더 높은 값으로 늘립니다. 기본값은 300입니다. 오류가 지속되면 지원에 문의하세요.VIEWS_NOT_SUPPORTED: 뷰가 지원되지 않습니다.Unity 카탈로그에서 SHOW CREATE TABLE 명령을 사용하여 뷰를 수동으로 다시 만듭니다.
예제
-- Sync an existing hive metastore table hive_metastore.default.my_tbl to a Unity Catalog
-- table named main.default.my_tbl.
> SYNC TABLE main.default.my_tbl FROM hive_metastore.default.my_tbl;
source_schema source_name source_type target_catalog target_schema target_name status_code description
------------- ----------- ----------- -------------- ------------- ----------- ----------- ---------------------------------
default my_tbl external main default my_tbl SUCCESS Table main.default.my_tbl synced.
-- Sync an existing managed hive metastore table hive_metastore.default.my_tbl to an external table named main.default.my_tbl in Unity Catalog.
> SYNC TABLE main.default.my_tbl AS EXTERNAL FROM hive_metastore.default.my_tbl;
source_schema source_name source_type target_catalog target_schema target_name status_code description
------------- ----------- ----------- -------------- ------------- ----------- ----------- ---------------------------------
default my_tbl managed main default my_tbl SUCCESS Table main.default.my_tbl synced.
-- SYNC a table in DRY RUN mode to evaluate the upgradability of the hive metastore table.
> SYNC TABLE main.default.my_tbl FROM hive_metastore.default.my_tbl DRY RUN;
source_schema source_name source_type target_catalog target_schema target_name status_code description
------------- ----------- ----------- -------------- ------------- ----------- --------------- ---------------------------------
default my_tbl external main default my_tbl DRY_RUN_SUCCESS
-- SYNC all the eligible tables in schema hive_metastore.mydb to a Unity Catalog schema main.my_db_uc.
-- The upgraded tables in main.my_db_uc will be owned by alf@melmak.et
> SYNC SCHEMA main.my_db_uc FROM hive_metastore.my_db SET OWNER `alf@melmak.et`;
source_schema source_name source_type target_catalog target_schema target_name status_code description
------------- ----------- ----------- -------------- ------------- ----------- ----------- ---------------------------------
...
-- DRY RUN mode of SYNC SCHEMA to evaluate all the tables in a schema
-- hive_metastore.mydb for upgrading to Unity Catalog.
> SYNC SCHEMA main.my_db_uc FROM hive_metastore.my_db DRY RUN;
source_schema source_name source_type target_catalog target_schema target_name status_code description
------------- ----------- ----------- -------------- ------------- ----------- ----------- ---------------------------------
...
-- Sync all tables including managed tables in a schema hive_metastore.mydb
-- as external tables in Unity Catalog.
> SYNC SCHEMA main.my_db_uc AS EXTERNAL FROM hive_metastore.my_db;
source_schema source_name source_type target_catalog target_schema target_name status_code description
------------- ----------- ----------- -------------- ------------- ----------- ----------- ---------------------------------
...
관련된 문서
피드백
출시 예정: 2024년 내내 콘텐츠에 대한 피드백 메커니즘으로 GitHub 문제를 단계적으로 폐지하고 이를 새로운 피드백 시스템으로 바꿀 예정입니다. 자세한 내용은 다음을 참조하세요. https://aka.ms/ContentUserFeedback
다음에 대한 사용자 의견 제출 및 보기