Ler tabelas do Databricks de clientes Iceberg

Artigo
02/11/2025

Use o catálogo REST do Iceberg para ler tabelas registradas no Catálogo do Unity no Azure Databricks de clientes Iceberg com suporte, incluindo Apache Spark, Apache Flink, Trino e Snowflake.

Leia usando o ponto de extremidade do catálogo Iceberg do Catálogo do Unity

O Catálogo do Unity fornece uma implementação somente leitura da API do catálogo REST do Iceberg para tabelas com leituras do Iceberg habilitadas.

Configurar o acesso usando o endpoint /api/2.1/unity-catalog/iceberg. Consulte a especificação da API REST do Iceberg para obter detalhes sobre como usar essa API REST.

Observação

O Azure Databricks introduziu a venda automática de credenciais para alguns clientes leitores de Iceberg. O Databricks recomenda usar a venda automática de credenciais para controlar o acesso a locais de armazenamento em nuvem para sistemas com suporte. Consulte Provisionamento de credenciais do Catálogo do Unity para acesso a sistemas externos.

Se a venda automática de credenciais não for suportada para o cliente, você deverá configurar o acesso do cliente ao local de armazenamento em nuvem que contém os arquivos e metadados da tabela Delta com leituras de Iceberg (UniForm) habilitadas. Consulte a documentação do cliente leitor do Iceberg para obter detalhes de configuração.

Requisitos

O Azure Databricks dá suporte ao acesso do catálogo REST do Iceberg às tabelas como parte do Catálogo do Unity. Você deve ter o Catálogo do Unity habilitado em seu espaço de trabalho para usar esses endpoints. Os seguintes tipos de tabela são elegíveis para as leituras do catálogo REST do Iceberg:

Tabelas gerenciadas do Catálogo do Unity com leituras do Iceberg (UniForm) habilitadas.
Tabelas externas do Catálogo do Unity, armazenadas no Delta Lake, com leituras do Iceberg (UniForm) habilitadas.

Confira Ler tabelas Delta com clientes Iceberg.

Você deve concluir as seguintes etapas de configuração para habilitar o acesso para que clientes Iceberg leiam tabelas do Databricks, usando o catálogo REST do Iceberg.

Habilite o Acesso a dados externos no seu metastore. Confira Habilitar o acesso a dados externos no metastore.
Conceda à entidade de segurança que configura a integração o privilégio EXTERNAL USE SCHEMA no esquema que contém as tabelas. Confira Conceder a uma entidade de segurança EXTERNAL USE SCHEMA.
Autentique usando um token de acesso pessoal do Databricks. Confira Autorizar o acesso aos recursos do Azure Databricks.

Ler tabelas do Iceberg com o Apache Spark

Veja a seguir um exemplo das configurações para configurar o Apache Spark para ler tabelas do Azure Databricks como Iceberg:

"spark.sql.extensions": "org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions",

# Configuration for accessing Uniform tables in Unity Catalog
"spark.sql.catalog.<spark-catalog-name>": "org.apache.iceberg.spark.SparkCatalog",
"spark.sql.catalog.<spark-catalog-name>.type": "rest",
"spark.sql.catalog.<spark-catalog-name>.uri": "<workspace-url>/api/2.1/unity-catalog/iceberg",
"spark.sql.catalog.<spark-catalog-name>.token":"<token>",
"spark.sql.catalog.<spark-catalog-name>.warehouse":"<uc-catalog-name>"

Substitua as seguintes variáveis:

<uc-catalog-name>: o nome do catálogo no Unity Catalog que contém suas tabelas.
<spark-catalog-name>: o nome que você deseja atribuir ao catálogo em sua sessão do Spark.
<workspace-url>: URL do workspace do Azure Databricks.
<token>: token PAT para a entidade de segurança que está configurando a integração.

Com essas configurações, você pode consultar tabelas do Azure Databricks como Iceberg no Apache Spark usando o identificador <catalog-name>.<schema-name>.<table-name>. Para acessar tabelas em vários catálogos, você deve configurar cada catálogo separadamente.

Ao consultar tabelas no Catálogo do Unity usando configurações do Spark, tenha o seguinte em mente:

Você precisará de "spark.sql.extensions": "org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions" apenas se estiver executando procedimentos armazenados específicos do Iceberg.
O Azure Databricks usa o armazenamento de objetos de nuvem para todas as tabelas. Você deve adicionar o JAR do pacote do Iceberg específico de nuvem como um pacote Spark:
- AWS: org.apache.iceberg:iceberg-aws-bundle:<iceberg-version>
- Azure: org.apache.iceberg:iceberg-azure-bundle:<iceberg-version>
- GCP: org.apache.iceberg:iceberg-gcp-bundle:<iceberg-version>
Para obter detalhes, consulte a documentação da integração do Iceberg com AWS para Spark.

Ler tabelas do Databricks com Snowflake

Veja a seguir um exemplo das configurações recomendadas para permitir que o Snowflake leia tabelas do Azure Databricks como Iceberg:

CREATE OR REPLACE CATALOG INTEGRATION <catalog-integration-name>
  CATALOG_SOURCE = ICEBERG_REST
  TABLE_FORMAT = ICEBERG
  CATALOG_NAMESPACE = '<uc-schema-name>'
  REST_CONFIG = (
    CATALOG_URI = '<workspace-url>/api/2.1/unity-catalog/iceberg',
    WAREHOUSE = '<uc-catalog-name>'
  )
  REST_AUTHENTICATION = (
    TYPE = BEARER
    BEARER_TOKEN = '<token>'
  )
  ENABLED = TRUE;

Substitua as seguintes variáveis:

<catalog-integration-name>: o nome que você deseja atribuir ao catálogo registrado no Snowflake.
<uc-schema-name>: o nome do esquema no Catálogo do Unity que você precisa acessar.
<uc-catalog-name>: o nome do catálogo do Unity que você precisa acessar.
<workspace-url>: URL do workspace do Azure Databricks.
<token>: token PAT para a entidade de segurança que está configurando a integração.

Exemplo de curl da API REST

Você também pode usar uma chamada à API REST como a desta curl exemplo para carregar uma tabela:

curl -X GET -H "Authentication: Bearer $OAUTH_TOKEN" -H "Accept: application/json" \
https://<workspace-instance>/api/2.1/unity-catalog/iceberg/v1/catalogs/<uc_catalog_name>/namespaces/<uc_schema_name>/tables/<uc_table_name>

Em seguida, você deve receber uma resposta como esta:

{
  "metadata-location": "abfss://my-container@my-storage-account.dfs.core.windows.net/path/to/iceberg/table/metadata/file",
  "metadata": <iceberg-table-metadata-json>,
  "config": {
    "expires-at-ms": "<epoch-ts-in-millis>",
    "adls.sas-token.<storage-account-name>.dfs.core.windows.net": "<temporary-sas-token>"
  }
}

Observação

O campo expires-at-ms na resposta indica o tempo de expiração das credenciais e tem um tempo de expiração padrão de uma hora. Para obter um melhor desempenho, tenha o cliente armazenando as credenciais em cache até o tempo de expiração antes de solicitar uma nova.

Compartilhar via