적용 대상:
Databricks SQL Databricks Runtime Unity Catalog만 적용됨
이 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 이상에서는 spark.databricks.sync.command.disableSourceTableWrites을 true로 설정하여 명령 SYNC을 실행하기 전에 이 동작을 해제할 수 있습니다. 로 trueSYNC 설정하면 새 테이블 속성이 추가되지 않으므로 테이블이 이전에 Unity 카탈로그로 업그레이드되었는지 검색하지 못할 수 있습니다.
이 경우 테이블 이름만 사용하여 테이블이 이전에 Unity 카탈로그로 업그레이드되었는지 확인합니다.
마지막 SYNC 명령 이후 원본 테이블의 이름이 변경된 경우 구성이 SYNC때 true 명령을 다시 실행하기 전에 대상 테이블의 이름을 수동으로 바꿔야 합니다.
중요한
명령이 SYNC 실행되면 SET TBLPROPERTIES 작업은 대상 Unity 카탈로그 외부 테이블 참조를 나타내는 테이블 속성을 추가합니다. 이 작업은 새 델타 스냅샷을 계산하고 테이블 델타 로그에 새 항목을 추가하여 클라우드 스토리지의 대상 테이블 경로에 기록합니다.
구문
SYNC { SCHEMA target_schema [AS EXTERNAL] FROM source_schema |
TABLE target_table [AS EXTERNAL] FROM source_table }
[SET OWNER principal]
[DRY RUN]
매개 변수
SCHEMASYNC스키마 내의 모든 테이블입니다.TABLESYNC개별 테이블입니다.-
선택적으로 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 카탈로그에서는 지원되지 않습니다. CREATE TABLE 명령을
DEEP CLONE옵션과 함께 사용하여 테이블 데이터를 Unity 카탈로그 위치로 복사합니다.EXTERNAL_TABLE_IN_MANAGED_LOCATION: 외부 테이블 경로는 관리 스토리지 아래에 있을 수 없습니다.외부 테이블에 지정된 경로는 Unity 카탈로그 관리 스토리지 내에 있습니다. 테이블이 관리되는 스토리지 아래에 있어야 하는 경우 CREATE TABLE 옵션과 함께
DEEP CLONE명령을 사용하여 테이블을 관리되는 테이블로 업그레이드하거나 Unity 카탈로그 관리 스토리지에서 테이블 위치를 이동합니다.HIVE_SERDE: 이 테이블은 Hive Metastore에서 Unity 카탈로그로 업그레이드할 수 없습니다. 이유: Hive SerDe 테이블입니다.Hive SerDe 테이블은 Unity 카탈로그에서 지원되지 않습니다. 테이블을 델타 형식으로 변경하고
SYNC명령을 실행하여 업그레이드합니다.INVALID_DATASOURCE_FORMAT: 데이터 원본 형식이 지정되지 않았거나 지원되지 않습니다.지원되는 데이터 원본 형식 중 하나 사용: Delta, Parquet, CSV, JSON, ORC, TEXT, AVRO
LOCATION_OVERLAP: 입력 경로가 다른 외부 테이블과 겹칩니다.테이블 위치가 다른 외부 테이블과 겹칩니다. 테이블에 다른 위치를 사용하거나 겹치는 외부 테이블을 제거합니다.
MULTIPLE_EXT_LOCATIONS: 입력 경로에 다른 외부 위치가 포함되어 있습니다.제공된 테이블 경로의 하위 디렉터리인 외부 위치가 두 개 이상 있습니다. 테이블 위치 내의 외부 위치가 필요한지 확인합니다.
MULTIPLE_TARGET_TABLE: 다른 동기화 테이블이 이미 존재합니다. 원본 테이블당 하나의 대상 테이블만 허용됩니다.원본 테이블은 이전에 허용되지 않는 다른 대상 테이블과 이미 동기화되었습니다.
SYNC를 다른 테이블에 강제 적용하려면 원본 테이블에서 테이블 속성upgraded_to를 제거하거나 더 이상 필요하지 않은 경우 Unity 카탈로그에서 이전에 동기화된 테이블을 제거합니다.NOT_EXTERNAL: 테이블은 Hive 메타스토어에서 Unity 카탈로그로 업그레이드할 수 없습니다. 이유: 외부 테이블이 아닙니다.SYNC명령은 Unity 카탈로그로의 외부 테이블 마이그레이션만 지원합니다. 관리되는 테이블의 경우 CREATE TABLE 옵션과 함께DEEP CLONE명령을 사용하여 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: 동기화 작업 시간이 초과되었습니다.동기화 테이블 명령 작업을 완료하는 데 600초 이상이 걸렸습니다.
spark.databricks.sync.command.task.timeout을 초 단위로 더 높은 값으로 늘립니다.또는 동기화 스키마 작업이 시간 초과될 수 있으며, 이 경우에는
TimeoutException을 볼 수 있습니다.spark.databricks.sync.command.task.create.timeout을 초 단위로 더 높은 값으로 늘립니다.두 플래그의 기본값은 600입니다. 문제가 지속되면 지원에 문의하세요.
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
------------- ----------- ----------- -------------- ------------- ----------- ----------- ---------------------------------
...
문제 해결
테이블 주석의 ASCII가 아닌 문자가 제대로 동기화되지 않음
명령을 사용하여
SYNCHive 메타스토어에서 Unity 카탈로그로 테이블을 업그레이드하는 경우 ASCII가 아닌 문자(예: 일본어 또는 중국어 텍스트)가 포함된 테이블 주석이 손상된 것처럼 보일 수 있습니다. 예를 들어 영향을 받는 주석은 일련의 물음표(???)로 표시되거나 카탈로그 탐색기에서 렌더링되지 않을 수 있습니다. 그러나 주석을 사용하여DESCRIBE TABLE EXTENDED쿼리하면 올바른 값이 반환됩니다.이 문제는 Hive metastore가 기본적으로 ASCII가 아닌 문자를 지원하지 않는 문자 집합을 사용하여
latin1주석을 저장할 수 있기 때문에 발생합니다. Unity 카탈로그가 주석을 사용하여SYNC검색하는 경우 지원되지 않는 문자가 손실되거나 손상될 수 있습니다.업그레이드
SYNC한 후 주석에서 ASCII가 아닌 문자를 복구하거나 복원하려면 Unity 카탈로그의 영향을 받는 테이블에서 다음 명령을 실행합니다.MSCK REPAIR TABLE <catalog>.<schema>.<table_name> SYNC METADATA;