Включить доступ к внешним данным для потоковых таблиц и материализованных представлений

Если вы включили внешний доступ к данным в Unity Catalog, вы можете добавить внешний доступ к управляемым конвейером и автономным материализованным представлениям и таблицам потоков. Это позволяет внешним клиентам Delta и Iceberg получать доступ к наборам данных через интерфейсы REST API каталога Unity и каталога Iceberg, не требуя полного копирования данных.

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

Capabilities

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

  • Копирование данных не требуется: Внешний доступ включен без дедупликации полного набора данных.
  • Внешний доступ через API: Чтение материализованных представлений и потоковых таблиц с помощью API Delta Lake или Iceberg.
  • Согласованность чтения после записи: После обновления набора данных внешние читатели могут получить доступ к актуальным данным, что гарантирует отсутствие устаревших данных. Обновления доступны сразу после обновления.
  • Объект одной таблицы: Наборы данных отображаются внешне как управляемые таблицы с тем же именем, что и исходный набор данных в API каталога Unity.
  • Низкая стоимость: Так как полный набор данных не копируется, затраты на предоставление внешнего доступа низки.

Requirements

Требования к наборам данных:

  • Каталог Unity: Таблицы потоковой передачи и материализованные представления должны использоваться в каталоге Unity.
  • Версия среды выполнения Databricks: Необходимо использовать Databricks Runtime 17.3 и более поздней версии.
  • Режим публикации по умолчанию: Внешняя читаемость поддерживается только в режиме публикации по умолчанию. Чтобы использовать внешнюю читаемость, переходите к режиму публикации по умолчанию. Функции, зависящие от внешних метаданных, такие как CDF материализованного представления, будут работать в устаревшем режиме публикации.

Требования для клиентов:

  • Версия Delta API: Клиент должен поддерживать API Delta Lake версии 4.0.0 или выше, включая векторы удаления, и должен использовать API каталога Unity Catalog для доступа.
  • Версия API Айсберга: Кроме того, клиент может получить доступ с помощью API каталога Iceberg, поддерживающих спецификацию Iceberg версии 3.
  • Привилегии Unity Catalog: Субъект, читающий наборы данных извне, должен иметь привилегию EXTERNAL USE SCHEMA на схему и привилегию SELECT на таблицу.

Note

Если клиент не поддерживает эти требования, можно также использовать режим совместимости, который поддерживает все клиенты Delta и Iceberg, но требует создания полной копии набора данных.

Включение доступа к набору данных

Существует два шага для обеспечения внешнего доступа к набору данных.

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

    • Конфигурация конвейера: Установите pipelines.externalMetadata.enabled в значение true, чтобы включить внешние метаданные для всех наборов данных в конвейере. Автономные материализованные представления и таблицы потоков, созданные с помощью Databricks SQL, не имеют конфигурации конвейера; Вместо этого используйте свойство таблицы.

      Пользовательский интерфейс параметров конвейера

      В настройках конвейера выполните следующие шаги:

      1. Откройте конвейер и нажмите кнопку "Параметры".
      2. В разделе "Конфигурация" добавьте пару "ключ-значение": "Ключpipelines.externalMetadata.enabled", "Значениеtrue".
      3. Нажмите кнопку Сохранить.

      JSON конфигурации конвейера

      В разделе configuration вашего JSON конвейера добавьте:

      {
  "configuration": {
    "pipelines.externalMetadata.enabled": "true"
  }
}

    • Свойство таблицы: Добавьте следующее свойство в определение потоковой таблицы или материализованного представления. Для конвейеров Lakeflow Connect см. свойства таблицы Set Delta.

      CREATE OR REFRESH [MATERIALIZED VIEW | STREAMING TABLE] tbl_name
TBLPROPERTIES('pipelines.externalMetadata.enabled' = 'true')

    После сохранения конфигурации запустите или перезапустите конвейер, чтобы применить изменения:

    • Активированные конвейеры: один раз запустите конвейер.
    • Непрерывные конвейеры: остановка и перезапуск конвейера.

    Для автономных SQL-объектов Databricks используйте CREATE OR REPLACE MATERIALIZED VIEW или CREATE OR REFRESH STREAMING TABLE с элементом таблицы. Инструкция create или refresh применяет это свойство.

  2. Если вы планируете читать набор данных с помощью современного клиента Iceberg, добавьте следующие свойства UniForm Iceberg V3 в дополнение к свойству внешних метаданных. Для конвейеров Lakeflow Connect см. свойства таблицы Set Delta.

    Недвижимость Использование
    'pipelines.externalMetadata.enabled' = 'true' Включите внешний доступ к столу. Такая настройка на уровне таблицы имеет приоритет над конфигурацией конвейера, когда установлены обе параметры.
    'delta.columnMapping.mode' = 'name' Для Iceberg необходимо сопоставление столбцов.
    'delta.enableRowTracking' = 'true' Включите отслеживание строк при чтении Iceberg.
    'delta.universalFormat.enabledFormats' = 'iceberg' Включите чтение из Iceberg.
    'delta.enableIcebergCompatV3' = 'true' Используйте Iceberg V3 для чтения таблиц Iceberg. 
    CREATE OR REFRESH [MATERIALIZED VIEW | STREAMING TABLE] tbl_name
TBLPROPERTIES(
  'delta.columnMapping.mode' = 'name',
  'delta.enableRowTracking' = 'true',
  'delta.enableIcebergCompatV3' = 'true',
  'delta.universalFormat.enabledFormats' = 'iceberg',
  'pipelines.externalMetadata.enabled' = 'true')

    Для материализованных представлений можно использовать вместо этого эквивалентный синтаксис USING ICEBERG.

    CREATE OR REFRESH MATERIALIZED VIEW tbl_name USING ICEBERG

    Для наборов данных, управляемых конвейером, используйте инструкции обновления конвейера выше для применения свойств Iceberg. Для автономных SQL-объектов Databricks запустите определение объекта с обновлёнными свойствами. Используйте CREATE OR REPLACE MATERIALIZED VIEW для материализованного представления или CREATE OR REFRESH STREAMING TABLE для потоковой таблицы. Чтобы просмотреть свойства набора данных, используйте операторы SQL DESCRIBE DETAIL или DESCRIBE EXTENDED.

Устранение неполадок с доступом к внешним данным

Если вы считаете, что внешние метаданные устарели, принципал с MODIFY привилегией в таблице может вручную запустить обновление метаданных на вычислениях общего кластера с помощью Databricks Runtime 17.3 или выше:

REPAIR TABLE <catalog>.<schema>.<table-name> SYNC METADATA;

Вы можете проверить наличие метаданных Iceberg в интерфейсе Catalog Explorer на странице с деталями таблицы. В качестве альтернативы выполните следующие команды в SQL-редакторе или в ноутбуке Azure Databricks:

DESCRIBE DETAIL <catalog>.<schema>.<table-name>;
DESCRIBE EXTENDED <catalog>.<schema>.<table-name>;

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

Чтение данных из внешних клиентов

В следующих разделах приведены примеры того, как читать ваш набор данных из разных клиентов и сред.

Для подробностей настройки см. доступ к клиенту Delta и доступ к клиенту Iceberg.

Использование REST API Unity с модулем чтения Spark Delta

Используйте Apache Spark™ версии 4.0 или более поздней. Вы можете скачать с https://spark.apache.org/downloads.html.

  1. В зависимости от используемого облачного провайдера выполните следующую команду, чтобы запустить оболочку Spark SQL с Delta 4.0 и Unity Catalog.

    AWS

    bin/spark-sql \
    --packages org.apache.spark:spark-hadoop-cloud_2.13:4.0.0,io.unitycatalog:unitycatalog-spark_2.13:0.3.1 \
    --conf spark.sql.extensions=io.delta.sql.DeltaSparkSessionExtension \
    --conf spark.sql.catalog.spark_catalog=io.unitycatalog.spark.UCSingleCatalog \
    --conf spark.hadoop.fs.s3.impl=org.apache.hadoop.fs.s3a.S3AFileSystem \
    --conf spark.sql.catalog.<uc-catalog-name>=io.unitycatalog.spark.UCSingleCatalog \
    --conf spark.sql.catalog.<uc-catalog-name>.uri=<workspace_url> \
    --conf spark.sql.catalog.<uc-catalog-name>.token=<PAT> \
    --conf spark.sql.defaultCatalog=<uc-catalog-name>

    Azure

    bin/spark-sql \
    --packages org.apache.hadoop:hadoop-azure:3.3.6,io.unitycatalog:unitycatalog-spark_2.13:0.3.1 \
    --conf spark.sql.extensions=io.delta.sql.DeltaSparkSessionExtension \
    --conf spark.sql.catalog.spark_catalog=io.unitycatalog.spark.UCSingleCatalog \
    --conf spark.sql.catalog.<uc-catalog-name>=io.unitycatalog.spark.UCSingleCatalog \
    --conf spark.sql.catalog.<uc-catalog-name>.uri=<workspace_url> \
    --conf spark.sql.catalog.<uc-catalog-name>.token=<PAT> \
    --conf spark.sql.defaultCatalog=<uc-catalog-name>

    GCP

    bin/spark-sql \
    --packages io.unitycatalog:unitycatalog-spark_2.13:0.3.1  \
    --conf spark.sql.extensions=io.delta.sql.DeltaSparkSessionExtension \
    --conf spark.sql.catalog.spark_catalog=io.unitycatalog.spark.UCSingleCatalog \
    --conf spark.hadoop.fs.gs.impl=com.google.cloud.hadoop.fs.gcs.GoogleHadoopFileSystem \
    --conf spark.hadoop.fs.AbstractFileSystem.gs.impl=com.google.cloud.hadoop.fs.gcs.GoogleHadoopFS \
    --conf spark.sql.catalog.<uc-catalog-name>=io.unitycatalog.spark.UCSingleCatalog \
    --conf spark.sql.catalog.<uc-catalog-name>.uri=<workspace_url> \
    --conf spark.sql.catalog.<uc-catalog-name>.token=<PAT> \
    --conf spark.sql.defaultCatalog=<uc-catalog-name>

  2. В оболочке SQL теперь можно получить доступ к набору данных с помощью Spark SQL. Рассмотрим пример.

    spark-sql ()> SELECT * FROM <uc-catalog>.<uc-schema>.<uc-table-name>;

Используйте средство чтения Snowflake Iceberg

В Snowflake можно использовать средство чтения Iceberg. Для этого требуется поддержка Iceberg версии 3 в Snowflake.

  1. Настройте каталог REST Iceberg в 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-table-name>';

  2. Получите доступ к вашему набору данных через Snowflake SQL.

    ALTER ICEBERG TABLE my_table REFRESH;
SELECT * FROM my_table;

Использование каталога REST Iceberg с помощью средства чтения Spark Iceberg

Используйте Apache Spark™ версии 4.0 или более поздней. Вы можете скачать с https://spark.apache.org/downloads.html.

  1. В AWS выполните следующую команду, чтобы запустить оболочку SQL Spark с помощью Iceberg версии 3.

    bin/spark-sql \
  --packages org.apache.iceberg:iceberg-spark-runtime-4.0_2.13:1.10.0,org.apache.iceberg:iceberg-aws-bundle:1.10.0 \
  --conf spark.sql.extensions=org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions \
  --conf spark.sql.catalog.<uc-catalog-name>=org.apache.iceberg.spark.SparkCatalog \
  --conf spark.sql.catalog.<uc-catalog-name>.io-impl=org.apache.iceberg.aws.s3.S3FileIO \
  --conf spark.sql.catalog.<uc-catalog-name>.type=rest \
  --conf spark.sql.catalog.<uc-catalog-name>.uri=<workspace_url>/api/2.1/unity-catalog/iceberg-rest \
  --conf spark.sql.catalog.<uc-catalog-name>.token='<PAT>' \
  --conf spark.sql.catalog.<uc-catalog-name>.warehouse=<uc-catalog-name> \
  --conf spark.sql.iceberg.vectorization.enabled=false

  2. Доступ к набору данных из Spark SQL.

    spark-sql ()> SELECT * FROM <uc-catalog>.<uc-schema>.<uc-table-name>;

Миграция из режима совместимости

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

  1. Включите эту функцию, выполнив действия, описанные в разделе "Как включить доступ к набору данных".
  2. Отключите режим совместимости. См . раздел "Отключить режим совместимости"

Ограничения

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

  • Внешние записи: Внешние записи в наборы данных конвейера не поддерживаются.
  • Доступ по пути: Внешние средства чтения, которым требуется доступ по пути (то есть чтение данных напрямую из расположения хранилища, а не через интерфейс API UC), не поддерживаются. Для поддержки доступа на основе путей можно использовать режим совместимости, который поддерживает доступ на основе пути, но требует полной копии набора данных.
  • Функции безопасности: Поддержка защиты на уровне строк или маскирования на уровне столбцов при внешнем чтении не поддерживается.
  • Путешествия во времени:Путешествия во времени с помощью этой функции не поддерживаются.
  • Фиксации каталога (бета-версия): фиксации каталоганесовместимы с внешним доступом к данным. Чтобы использовать внешний доступ к данным в таблице потоков или материализованном виде, сначала нужно отключить коммиты каталога.
  • Fabric: Чтение из Microsoft Fabric не поддерживается.
  • Last updated on