Режим совместимости

Это важно

Эта функция доступна в общедоступной предварительной версии.

С помощью режима совместимости можно читать управляемые таблицы каталога Unity, материализованные представления и потоковые таблицы из внешних систем, сохраняя оптимальную производительность в Azure Databricks. Эта функция автоматически создает доступные только для чтения версии таблиц, к которым можно обращаться любой клиент Delta Lake или Iceberg.

Обзор

При включении управляемой таблицы, потоковой таблицы или материализованного представления режим совместимости создает версию таблицы только для чтения в выбранном расположении. Эта версия совместимости включает метаданные версии 1 для форматов Delta Lake и Iceberg, предоставляя следующие возможности:

Взаимодействие с любым клиентом Delta Lake: чтение управляемых таблиц, включая потоковые таблицы или материализованные представления, от клиентов, таких как Amazon Athena, Microsoft Fabric, Snowflake и Amazon Redshift непосредственно из хранилища или через REST API Unity
Взаимодействие с любым клиентом Iceberg: чтение управляемых таблиц, включая потоковые таблицы или материализованные представления, от клиентов Iceberg, таких как Apache Spark, Apache Trino и Snowflake через каталог REST Iceberg
Автоматизация по принципу "настрой и забудь": автоматизация обновлений данных и метаданных для версий совместимости с возможностью настройки интервалов обновления до почти реального времени.

Предпосылки

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

Кроме того, убедитесь, что у вас есть внешнее расположение, зарегистрированное в Unity Catalog с соответствующими параметрами и разрешениями.

Целевое расположение должно существовать в учетной записи хранения и быть пустым.
Целевое расположение или любой из родительских папок должны быть зарегистрированы в качестве внешнего расположения в каталоге Unity.
Для внешнего расположения необходимо иметь CREATE EXTERNAL TABLE привилегии.
Целевое расположение и все родительские или дочерние папки не должны использоваться в качестве расположения режима совместимости для другой таблицы за последние 7 дней.

Включение режима совместимости в таблицах

Для потоковых таблиц, материализованных представлений и управляемых мелких клонов задайте следующие свойства таблицы во время создания таблицы:

CREATE [STREAMING TABLE | MATERIALIZED VIEW | TABLE] my_catalog.my_schema.my_table
TBLPROPERTIES(
  'delta.universalFormat.enabledFormats' = 'compatibility',
  'delta.universalFormat.compatibility.location' = '<location>'
)

Для управляемых таблиц каталога Unity можно также включить режим совместимости при изменении существующей таблицы:

-- For existing managed tables
ALTER TABLE my_catalog.my_schema.my_table SET TBLPROPERTIES(
  'delta.universalFormat.enabledFormats' = 'compatibility',
  'delta.universalFormat.compatibility.location' = '<location>'
)

Для создания версии совместимости в первый раз требуется до одного часа. Вы можете вручную обновить таблицу, чтобы убедиться, что она работает.

Замечание

Необходимо указать полное трехкомпонентное имя таблицы (catalog.schema.table_name). Например, для users.john.my_tableusers является каталогом, а john — схемой.

Проверьте, включен ли режим совместимости

Чтобы убедиться, что режим совместимости включен в таблице, проверьте, существует ли delta.universalFormat.enabledFormats = 'compatibility' свойство таблицы. Это свойство можно просмотреть в пользовательском интерфейсе обозревателя каталогов на вкладке сведений для таблицы.

Вы также можете выполнить следующие команды SQL в записной книжке:

DESC DETAIL my_catalog.my_schema.my_table
DESC EXTENDED my_catalog.my_schema.my_table

Найдите эти свойства в выходных данных:

delta.universalFormat.enabledFormats: "compatibility" — указывает, что включен режим совместимости
delta.universalFormat.compatibility.location — отображает расположение версии режима совместимости

Настройка интервалов обновления

Для управляемых таблиц каталога Unity можно настроить частоту обновления версии режима совместимости, задав интервал обновления:

-- Evaluate whether a refresh is needed after every commit (fastest)
ALTER TABLE my_catalog.my_schema.my_table SET TBLPROPERTIES(
  'delta.universalFormat.enabledFormats' = 'compatibility',
  'delta.universalFormat.compatibility.location' = '<location>',
  'delta.universalFormat.compatibility.targetRefreshInterval' = '0 MINUTES'
)

-- Refresh hourly (default)
ALTER TABLE my_catalog.my_schema.my_table SET TBLPROPERTIES(
  'delta.universalFormat.enabledFormats' = 'compatibility',
  'delta.universalFormat.compatibility.location' = '<location>',
  'delta.universalFormat.compatibility.targetRefreshInterval' = '1 HOUR'
)

Интервал обновления по умолчанию — 1 HOUR. Установка интервала обновления ниже 1 часа не рекомендуется и не будет выполнять обновления чаще. Исключение возникает, если интервал обновления установлен на 0 MINUTES. В этом случае Azure Databricks проверяет наличие изменений после каждой фиксации и активирует обновление при необходимости.

Для потоковых таблиц и материализованных представлений интервал обновления не требуется. По умолчанию устанавливается значение 0 MINUTES.

Замечание

Изменения, которые значительно влияют на время обновления (например, переименование столбцов или включение расширения типов), выполняются почасово независимо от целевого интервала обновления.

Обновление вручную

Чтобы запустить обновление версии совместимости вручную, выполните следующие действия.

REFRESH [TABLE | STREAMING TABLE | MATERIALIZED VIEW] my_catalog.my_schema.my_table SYNC UNIFORM

Обновление вручную полезно для проверки правильной работы режима совместимости или для гарантии, что версия совместимости обновлена перед последующим чтением. Однако ожидание автоматического обновления может быть более экономичным.

Мониторинг состояния создания данных и метаданных

Режим совместимости создает данные и метаданные автоматически и асинхронно. Для управляемых таблиц каталога Unity по умолчанию создается почасовая версия или на основе настроенного интервала обновления. Для потоковых таблиц и материализованных представлений генерация происходит после обновлений таблиц при новых коммитах.

Чтобы проверить успешность создания данных и метаданных, выполните приведенные ниже действия.

Используется DESCRIBE HISTORY для поиска последней версии исходной таблицы:
```
DESC HISTORY my_catalog.my_schema.my_table
```
Эта команда возвращает журнал обновлений в режиме совместимости, включая версию Delta Lake и метку времени. Верхняя строка содержит последнюю версию и метку времени.
Используется DESCRIBE EXTENDED для поиска соответствующей версии режима совместимости:
```
DESC EXTENDED my_catalog.my_schema.my_table
```
Найдите поля в разделе "Единенная информация о совместимости":
- Последняя обновленная версия: версия Delta Lake, которая была обновлена в режиме совместимости
- Последнее обновление: временная метка последнего обновления
Режим совместимости актуален, если версия таблицы соответствует версии, найденной на шаге 1.
Используйте DESC HISTORY в самой версии совместимости:
```
DESC HISTORY delta.\`<compatibility_location>\`
```
В обозревателе каталогов просмотрите поля метаданных для версии совместимости. Режим совместимости является актуален, если версия Delta Lake соответствует версии, найденной на шаге 3.

Мониторинг затрат

Прогнозная оптимизация обрабатывает вычислительный кластер, который выполняет автоматическое обновление для режима совместимости. Чтобы просмотреть связанные затраты, выполните запрос к таблицам системного выставления счетов:

SELECT
  DATE_TRUNC('DAY', start_time) AS day,
  SUM(usage_quantity) AS dbus
FROM
  system.storage.predictive_optimization_operations_history
WHERE
  operation_type = "COMPATIBILITY_MODE_REFRESH"
GROUP BY 1
ORDER BY 1 DESC;

Этот запрос сообщает об использовании только автоматических обновлений. Затраты на обновления вручную связаны с вычислительными ресурсами, и нет прямого способа отдельно отслеживать эти затраты. Как правило, стоимость ручного триггера пропорциональна стоимости начальной операции записи в исходную таблицу.

Удаление неиспользуемых файлов данных

Чтобы удалить неиспользуемые файлы данных в версии совместимости таблицы, используйте VACUUMследующую команду:

VACUUM delta.'<compatibility_mode_location_path>';

Чтобы найти путь к расположению режима совместимости, используйте DESCRIBE EXTENDED команду в разделе "Проверить, включен ли режим совместимости". В выходных данных значением delta.universalFormat.compatibility.location является расположение.

Получение версий совместимости от внешних клиентов

Вы можете использовать любой клиент Delta Lake или Iceberg для чтения данных из версий совместимости. См. ниже примеры для Amazon Athena, Snowflake (delta reader) и Fabric.

Amazon Athena

В редакторе запросов Athena создайте внешнюю таблицу с указанным расположением:
```
CREATE EXTERNAL TABLE <table_name>
LOCATION '<compatibility_location>'
TBLPROPERTIES ('table_type' = 'DELTA')
```
Прочитайте таблицу:
```
SELECT * FROM <table_name>
```

Средство чтения Snowflake Delta Lake

Создайте интеграцию хранилища для доступа к расположению хранилища (см. документацию по Snowflake).

Создайте внешнюю таблицу с форматом Delta Lake:

CREATE OR REPLACE EXTERNAL TABLE <table_name>
WITH LOCATION = @<my_location>
FILE_FORMAT = (TYPE = PARQUET)
TABLE_FORMAT = DELTA
AUTO_REFRESH = false
REFRESH_ON_CREATE = false;

Обновите таблицу (автоматическое обновление не поддерживается для формата Delta Lake в Snowflake):
```
ALTER EXTERNAL TABLE <table_name> REFRESH;
```
Прочитайте таблицу:
```
SELECT * FROM <table_name>;
```

Microsoft Fabric

Создайте емкость Synapse Fabric, рабочую область и записную книжку.
Создайте lakehouse с данными в совместимом расположении.
Прочитайте файлы как таблицу Delta Lake.
```
spark.read.format("delta").load("Files/<path_to_data>")
```

Чтение версий, совместимых с REST API Unity

Таблицы с включенным режимом совместимости можно считывать по имени через REST API Unity со специальными параметрами. Для таблиц потоковой передачи задайте следующий параметр API:

GET /api/2.1/unity-catalog/tables/{full_name}?read_streaming_table_as_managed=true

Для материализованных представлений задайте следующий параметр API:

GET /api/2.1/unity-catalog/tables/{full_name}?read_materialized_view_as_managed=true

Чтение версий совместимости из каталога Iceberg REST

Таблицы с включенным режимом совместимости можно считывать из любого клиента Iceberg с помощью каталога REST Iceberg. Режим совместимости работает автоматически для форматов таблиц Delta Lake и Iceberg.

Требования к установке

Включите доступ к внешним данным в хранилище метаданных.
Предоставьте EXTERNAL USE SCHEMA привилегию на схему.
Создайте личный маркер доступа Azure Databricks (PAT).

Конфигурация Apache Spark

bin/spark-sql --packages org.apache.iceberg:iceberg-spark-runtime-3.5_2.12:1.8.0,org.apache.iceberg:iceberg-azure-bundle:1.8.0 \
  --conf "spark.sql.extensions=org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions" \
  --conf spark.sql.catalog.catalog_name=org.apache.iceberg.spark.SparkCatalog \
  --conf spark.sql.catalog.catalog_name.type=rest \
  --conf spark.sql.catalog.catalog_name.uri=<workspace-url>/api/2.1/unity-catalog/iceberg-rest \
  --conf spark.sql.catalog.catalog_name.token=<PAT> \
  --conf spark.sql.catalog.catalog_name.warehouse=<uc-catalog-name>

Дополнительные сведения см. в разделе "Использование таблиц Айсберга" с Apache Spark.

Конфигурация Snowflake

CREATE OR REPLACE CATALOG INTEGRATION my_uc_int
  CATALOG_SOURCE = ICEBERG_REST
  TABLE_FORMAT = ICEBERG
  CATALOG_NAMESPACE = '<uc-schema-name>'
  REST_CONFIG = (
    CATALOG_URI = '<workspace-url>/api/2.1/unity-catalog/iceberg-rest'
    CATALOG_NAME = '<uc-catalog-name>'
    ACCESS_DELEGATION_MODE = VENDED_CREDENTIALS
  )
  REST_AUTHENTICATION = (
    TYPE = BEARER
    BEARER_TOKEN = '<PAT>'
  )
  ENABLED = TRUE;

CREATE OR REPLACE ICEBERG TABLE my_table
  CATALOG = 'my_uc_int'
  CATALOG_TABLE_NAME = '<uc-st/mv-name>';

Отключение режима совместимости

Чтобы отключить режим совместимости, снимите соответствующее свойство таблицы.

-- For UC managed tables
ALTER TABLE my_table UNSET TBLPROPERTIES('delta.universalFormat.enabledFormats')

-- For streaming tables and materialized views
CREATE OR REPLACE [STREAMING TABLE | MATERIALIZED VIEW] my_table
TBLPROPERTIES('delta.universalFormat.enabledFormats' = '')

Предупреждение

Отмена задания режима совместимости немедленно останавливает создание данных и метаданных. Через 7 дней связанные данные и метаданные будут удалены. В течение этого 7-дневного периода можно восстановить данные и метаданные, повторно включив режим совместимости в той же таблице.

Ограничения

Доступ только для чтения: версия совместимости доступна только для чтения. Вы не можете записать в совместимую версию.
Нет поддержки RLS/CLS: нельзя включить режим совместимости в таблицах с безопасностью на уровне строк (RLS) или безопасностью на уровне столбцов (CLS).
Переименование столбца партиции не поддерживается. Переименование столбцов партиции не поддерживается в таблицах с включенным режимом совместимости. Поддерживается переименование столбцов данных.
Ограниченные функции таблицы: следующие возможности недоступны в версии совместимости:
- Столбцы сортировки
- Первичные ключи
- Переход по времени
- Изменение потока данных
- Имена столбцов со специальными символами (будут переименованы)

Обратная связь

Были ли сведения на этой странице полезными?

Last updated on 2025-12-03