Поделиться через

SYNC

  • Статья

применимо:отмечено Databricks SQL отмечено Databricks Runtime отмечено только каталог Unity

Используйте команду SYNC для обновления внешних таблиц в хранилище метаданных Hive до внешних таблиц в каталоге Unity. Вы также можете использовать SYNC для обновления управляемых таблиц Hive, хранящихся за пределами хранилища рабочих областей Databricks (иногда называемого корневым каталогом DBFS) до внешних таблиц в каталоге Unity. Его нельзя использовать для обновления управляемых таблиц Hive, хранящихся в хранилище рабочей области. Чтобы обновить эти таблицы, используйте CREATE TABLE CLONE.

Вы можете использовать SYNC для создания таблиц в каталоге Unity из существующих таблиц хранилища метаданных Hive, а также обновления таблиц каталога Unity при изменении исходных таблиц в хранилище метаданных Hive.

Команда SYNC может выполняться на уровне схемы с помощью синтаксиса SYNC SCHEMA или отдельной таблицы с помощью синтаксиса SYNC TABLE.

Команда выполняет операцию записи (ALTER TABLE) в каждую исходную таблицу, которую она обновляет, чтобы добавить дополнительные свойства таблицы для ее учета. В случае таблиц Delta для выполнения операции записи кластер или хранилище SQL, который выполняет команду, должен иметь доступ на запись к расположению таблицы.

В Databricks Runtime версии 12.2 LTS или выше это поведение можно отключить, сначала задав конфигурацию spark.databricks.sync.command.disableSourceTableWrites Spark для true, а затем выполнив команду SYNC. Если задано значение true, SYNC не добавляет новые свойства таблицы и поэтому может не обнаружить, была ли таблица уже переведена на каталог Unity. В этом случае для определения того, была ли таблица ранее обновлена до Unity Catalog, используется исключительно имя таблицы. Если исходная таблица была переименована с момента последней команды SYNC, пользователь должен вручную переименовать целевую таблицу, прежде чем повторно запустить команду SYNC при trueконфигурации.

Внимание

При выполнении команды SYNC операция SET TBLPROPERTIES добавляет свойство таблицы, указывающее ссылку на внешнюю таблицу целевого каталога Unity. Эта операция вычисляет новый моментальный снимок Delta и добавляет новую запись в журнал Delta таблицы, записывая в целевой путь таблицы в облачном хранилище.

Синтаксис

SYNC { SCHEMA target_schema [AS EXTERNAL] FROM source_schema |
       TABLE target_table [AS EXTERNAL] FROM source_table }
  [SET OWNER principal]
  [DRY RUN]

Параметры

  • SCHEMA

    SYNC все таблицы в схеме.

    • целевая_схема

      Существующая схема в каталоге Unity, в которой пользователь может создавать таблицы.

    • source_schema

      Существующая схема в каталоге hive_metastore, принадлежащем пользователю.

  • TABLE

    SYNC отдельную таблицу.

    • target_table

      Новая или существующая таблица в каталоге Unity в схеме, в которой пользователь может создавать таблицы. Если таблица уже существует, она заменена, чтобы соответствовать source_table, и пользователь также должен владеть таблицей. Если таблица не существует, она будет создана.

    • source_table

      Существующая таблица в hive_metastore которой владеет пользователь.

  • основной

    При необходимости задайте владельцу обновленных таблиц в каталоге Unity значение principal. Владелец по умолчанию — текущий пользователь.

  • AS EXTERNAL

    SYNC управляемая таблица или схема Hive, которая хранится за пределами хранилища рабочей области Databricks (иногда называемого корневым каталогом DBFS), преобразуется в внешние таблицы в каталоге Unity. Невозможно использовать AS EXTERNAL для обновления управляемых таблиц Hive, хранящихся в хранилище рабочей области.

  • DRY RUN

    Проверяет, можно ли обновить source_table или таблицы внутри source_schema без реального создания или обновления целевых таблиц, если это указано. Команда возвращает DRY_RUN_SUCCESS, если таблицу можно обновить.

  • AS EXTERNAL Начиная с Databricks Runtime версии 13.2 и выше, можно добавить эту необязательную часть предложения, чтобы указать, что управляемые таблицы в метахранилище Hive обновляются как внешние таблицы в Unity Catalog. При использовании с SYNC SCHEMAона применяется ко всем таблицам, включая управляемые таблицы в source_schema.

Возвраты

Отчет со следующими столбцами:

  • source_schema STRING

    Имя исходной схемы. Если источник является неподдерживаемым временным представлением, то схема является NULL.

  • source_name STRING NOT NULL

    Имя исходной таблицы.

  • source_type STRING NOT NULL

    Тип таблицы: MANAGED или EXTERNAL

  • target_catalog STRING NOT NULL

    Целевой каталог в Unity Catalog, где синхронизируется таблица.

  • target_schema STRING NOT NULL

    Целевая схема в каталоге Unity, где синхронизируется таблица.

  • target_name STRING NOT NULL

    Имя таблицы в каталоге Unity, с которой синхронизируется исходная таблица. Это имя соответствует имени исходной таблицы.

  • status_code STRING NOT NULL

    Код состояния для результата команды SYNC для исходной таблицы.

  • description STRING

    Описательное сообщение о состоянии команды синхронизации для исходной таблицы.

Стандартные коды состояния, возвращаемые SYNC

Команда SYNC предоставляет уникальное поле status_code в выходных данных для каждой таблицы, обновляемой до каталога Unity, представляющего состояние обновления. Ниже приведены некоторые распространенные коды состояния, а также рекомендации по их устранению:

  • DRY_RUN_SUCCESS: Пробный запуск успешно выполнен.

    Таблицу можно обновить до каталога Unity с помощью команды SYNC.

  • DBFS_ROOT_LOCATION: таблица, расположенная в корне файловой системы Databricks.

    Таблица находится в корневом расположении файловой системы Databricks. Это не поддерживается в каталоге Unity. Скопируйте данные таблицы в каталог Unity с помощью команды CREATE TABLE с параметром DEEP CLONE.

  • EXTERNAL_TABLE_IN_MANAGED_LOCATION: путь к внешней таблице не может находиться в управляемом хранилище.

    Путь, заданный для внешней таблицы, находится в управляемом хранилищем Unity Catalog. Если таблица должна находиться в управляемом хранилище, обновите таблицу как управляемую таблицу с помощью команды CREATE TABLE с параметром DEEP CLONE или переместите расположение таблицы из управляемого хранилища каталога Unity.

  • HIVE_SERDE. Таблица не подлежит обновлению с Hive Metastore до Unity Catalog. Причина: таблица Hive SerDe.

    Таблицы Hive SerDe не поддерживаются каталогом Unity. Измените таблицы в формате Delta и выполните команду 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. Для управляемых таблиц создайте управляемую таблицу в каталоге Unity с помощью команды CREATE TABLE с параметром DEEP CLONE. Кроме того, используйте предложение AS EXTERNAL с командой SYNC для создания внешней таблицы в каталоге Unity.

  • READ_ONLY_CATALOG: Данные в каталоге Delta Sharing доступны только для чтения и не могут быть изменены или удалены.

    Выбранный каталог — это разностный каталог общего доступа, который доступен только для чтения. Таблицы в каталоге только для чтения нельзя обновлять с помощью команды 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: представления не поддерживаются.

    Повторно создайте представления вручную с помощью команды SHOW CREATE TABLE в каталоге Unity.

Примеры

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