Acesse tabelas do Azure Databricks a partir de clientes do Apache Iceberg

O catálogo REST do Apache Iceberg permite que clientes compatíveis, como Apache Spark, Apache Flink e Trino, leiam e escrevam em tabelas iceberg registradas no Catálogo do Unity no Azure Databricks.

Para obter uma lista completa de integrações com suporte, consulte as integrações do Catálogo do Unity.

Observação

O Catálogo do Unity também possui um ponto de extremidade de API REST do Iceberg em modo somente leitura. Este é um endpoint legado. Consulte Ler tabelas do Databricks a partir de clientes Apache Iceberg (herdado).

Usar o ponto de extremidade do catálogo do Iceberg no Catálogo do Unity

O Catálogo do Unity fornece uma implementação da especificação da API do catálogo REST do Iceberg.

Configurar o acesso usando o endpoint /api/2.1/unity-catalog/iceberg-rest. 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 a distribuição de credenciais do Catálogo Unity para acesso a sistemas externos e Acessar tabelas Iceberg usando 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 que contém os arquivos e metadados da tabela Delta ou Iceberg. Consulte a documentação do cliente 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 acessíveis usando o Catálogo REST do Iceberg:

Tópico	Leitura	Escrever
Iceberg Gerenciado	Sim	Sim
Iceberg Estrangeiro	Sim	Não
Delta Gerenciado (com leituras do Iceberg habilitadas)	Sim	Não
Delta Externo (com a leituras do Iceberg habilitadas)	Sim	Não

Tabelas de Iceberg estrangeiras não são atualizadas automaticamente ao usar a API do Catálogo REST do Iceberg para ler tabelas. Para atualizar, você deverá executar REFRESH FOREIGN TABLE para ler o instantâneo mais recente. Não há suporte para distribuição de credenciais em tabelas do Iceberg Estrangeiro.

Observação

Você deve configurar tabelas Delta para serem acessíveis usando a API do Catálogo REST do Iceberg. Consulte Ler tabelas do Delta Lake com clientes Iceberg usando o UniForm.

Você deve concluir as seguintes etapas de configuração para configurar o acesso para ler ou gravar em tabelas do Azure Databricks de clientes Iceberg usando o catálogo REST do Iceberg:

Habilite o Acesso a dados externos no seu metastore. Consulte 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. Consulte Conceder privilégios de administrador principal do Catálogo do Unity.
Autenticar usando um token de acesso pessoal ou OAuth do Azure Databricks. Consulte Autorizar o acesso aos recursos do Azure Databricks.

Observação

A especificação Iceberg não permite arquivos de dados duplicados em um instantâneo único de tabela. Para evitar isso, quando detectado, o Catálogo do Unity impede que mecanismos externos confirmem arquivos de dados duplicados na tabela.

Usar tabelas do Iceberg com o Apache Spark

Os exemplos a seguir mostram como configurar o Apache Spark para acessar Azure Databricks tabelas por meio da API do Catálogo REST do Iceberg. O Azure Databricks oferece suporte à autenticação OAuth e por token de acesso pessoal (PAT).

Para acessar tabelas em vários catálogos, você deve configurar cada catálogo separadamente.

Observação

Você deve incluir o JAR de runtime do Iceberg Spark e o JAR do pacote específico da nuvem nos seus pacotes do Spark. A versão do JAR de runtime deve corresponder às versões do Spark e do Scala. Por exemplo, para Spark 3.5 com Scala 2.12:

org.apache.iceberg:iceberg-spark-runtime-3.5_2.12:<iceberg-version>

Além do pacote específico da nuvem:

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. Esses JARs não são necessários para acessar tabelas Iceberg de clusters do Azure Databricks.

Autenticação OAuth

CLI

pyspark \
  --packages org.apache.iceberg:iceberg-spark-runtime-3.5_2.12:<iceberg-version>,org.apache.iceberg:iceberg-aws-bundle:<iceberg-version> \
  --conf "spark.sql.catalog.<spark-catalog-name>=org.apache.iceberg.spark.SparkCatalog" \
  --conf "spark.sql.catalog.<spark-catalog-name>.type=rest" \
  --conf "spark.sql.catalog.<spark-catalog-name>.rest.auth.type=oauth2" \
  --conf "spark.sql.catalog.<spark-catalog-name>.uri=https://<workspace-url>/api/2.1/unity-catalog/iceberg-rest" \
  --conf "spark.sql.catalog.<spark-catalog-name>.oauth2-server-uri=https://<workspace-url>/oidc/v1/token" \
  --conf "spark.sql.catalog.<spark-catalog-name>.credential=<oauth_client_id>:<oauth_client_secret>" \
  --conf "spark.sql.catalog.<spark-catalog-name>.warehouse=<uc-catalog-name>" \
  --conf "spark.sql.catalog.<spark-catalog-name>.scope=all-apis"

Python

from pyspark.sql import SparkSession

spark = SparkSession.builder \
    .config("spark.jars.packages", "org.apache.iceberg:iceberg-spark-runtime-3.5_2.12:<iceberg-version>,org.apache.iceberg:iceberg-aws-bundle:<iceberg-version>") \
    .config("spark.sql.catalog.<spark-catalog-name>", "org.apache.iceberg.spark.SparkCatalog") \
    .config("spark.sql.catalog.<spark-catalog-name>.type", "rest") \
    .config("spark.sql.catalog.<spark-catalog-name>.rest.auth.type", "oauth2") \
    .config("spark.sql.catalog.<spark-catalog-name>.uri", "https://<workspace-url>/api/2.1/unity-catalog/iceberg-rest") \
    .config("spark.sql.catalog.<spark-catalog-name>.oauth2-server-uri", "https://<workspace-url>/oidc/v1/token") \
    .config("spark.sql.catalog.<spark-catalog-name>.credential", "<oauth_client_id>:<oauth_client_secret>") \
    .config("spark.sql.catalog.<spark-catalog-name>.warehouse", "<uc-catalog-name>") \
    .config("spark.sql.catalog.<spark-catalog-name>.scope", "all-apis") \
    .getOrCreate()

Substitua as seguintes variáveis:

<spark-catalog-name>: o nome que você deseja atribuir ao catálogo em sua sessão do Spark.
<uc-catalog-name>: o nome do catálogo no Unity Catalog que contém suas tabelas.
<oauth_client_id>: ID do cliente OAuth para a entidade de autenticação.
<oauth_client_secret>: segredo do cliente OAuth para a entidade de autenticação.
<iceberg-version>: a versão do Iceberg a ser usada, por exemplo 1.9.2.

<workspace-url>: a URL do espaço de trabalho do Azure Databricks. Por exemplo, adb-1234567890123456.12.azuredatabricks.net.

Autenticação PAT

CLI

pyspark \
  --packages org.apache.iceberg:iceberg-spark-runtime-3.5_2.12:<iceberg-version>,org.apache.iceberg:iceberg-aws-bundle:<iceberg-version> \
  --conf "spark.sql.catalog.<spark-catalog-name>=org.apache.iceberg.spark.SparkCatalog" \
  --conf "spark.sql.catalog.<spark-catalog-name>.type=rest" \
  --conf "spark.sql.catalog.<spark-catalog-name>.uri=https://<workspace-url>/api/2.1/unity-catalog/iceberg-rest" \
  --conf "spark.sql.catalog.<spark-catalog-name>.token=<token>" \
  --conf "spark.sql.catalog.<spark-catalog-name>.warehouse=<uc-catalog-name>"

Python

from pyspark.sql import SparkSession

spark = SparkSession.builder \
    .config("spark.jars.packages", "org.apache.iceberg:iceberg-spark-runtime-3.5_2.12:<iceberg-version>,org.apache.iceberg:iceberg-aws-bundle:<iceberg-version>") \
    .config("spark.sql.catalog.<spark-catalog-name>", "org.apache.iceberg.spark.SparkCatalog") \
    .config("spark.sql.catalog.<spark-catalog-name>.type", "rest") \
    .config("spark.sql.catalog.<spark-catalog-name>.uri", "https://<workspace-url>/api/2.1/unity-catalog/iceberg-rest") \
    .config("spark.sql.catalog.<spark-catalog-name>.token", "<token>") \
    .config("spark.sql.catalog.<spark-catalog-name>.warehouse", "<uc-catalog-name>") \
    .getOrCreate()

Substitua as seguintes variáveis:

<spark-catalog-name>: o nome que você deseja atribuir ao catálogo em sua sessão do Spark.
<uc-catalog-name>: o nome do catálogo no Unity Catalog que contém suas tabelas.
<token>: um token de acesso pessoal (PAT) para a entidade de autenticação. Consulte Autenticar com os tokens de acesso pessoal do Azure Databricks (herdados).
<iceberg-version>: a versão do Iceberg a ser usada, por exemplo 1.9.2.

<workspace-url>: a URL do espaço de trabalho do Azure Databricks. Por exemplo, adb-1234567890123456.12.azuredatabricks.net.

Acessar tabelas do Azure Databricks com Snowflake

O Snowflake fornece duas opções para acessar tabelas por meio do catálogo REST do Iceberg: usar bancos de dados vinculados ao catálogo do Snowflake ou usar tabelas externas.

Para ambas as opções, primeiro configure uma integração de catálogo do Snowflake. O Azure Databricks dá suporte aos seguintes métodos de autenticação para integrações de catálogo do Snowflake:

Token de portador: usa um token de acesso pessoal (PAT) ou OAuth do Azure Databricks. Compatível com todas as nuvens.
OAuth da entidade de serviço do Entra (somente Azure): usa uma entidade de serviço do Microsoft Entra ID para autenticar diretamente no ponto de extremidade de token do Entra.

Para obter mais detalhes sobre as opções de autenticação snowflake para integrações de catálogo REST, consulte a documentação do Snowflake.

Snowflake com autenticação de token de portador

O exemplo a seguir configura uma integração de catálogo do Snowflake usando um token de portador. Você pode usar um token de acesso pessoal (PAT) do Azure Databricks ou um token OAuth gerado de um principal de serviço do Azure Databricks. Para obter detalhes sobre como gerar tokens OAuth, consulte Autorizar o acesso da entidade de serviço ao Azure Databricks com o OAuth.

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-rest',
    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 no Unity Catalog que você precisa acessar.
<workspace-url>: a URL do espaço de trabalho do Azure Databricks. Por exemplo, https://cust-success.cloud.databricks.com ou https://adb-1234567890123456.12.azuredatabricks.net.
<token>: um PAT (token de acesso pessoal) para a entidade configurando a integração.

Snowflake com OAuth da entidade de serviço do Entra

No Azure, as integrações de catálogo do Snowflake que usam uma entidade de serviço com suporte do Entra não podem usar o ponto de extremidade de token OIDC do Azure Databricks (<workspace-url>/oidc/v1/token). Em vez disso, você deve autenticar-se diretamente no ponto de extremidade de token do Microsoft Entra. Isso é diferente da abordagem OAuth usada para outros clientes iceberg (como o Apache Spark) no Azure.

Observação

A documentação do Snowflake pode indicar que não há suporte para a ID do Entra. A configuração a seguir usa o Entra OAuth direcionado ao escopo do recurso do Azure Databricks, sendo o caminho suportado para leitura do Catálogo do Unity a partir do Snowflake no Azure.

Antes de começar, verifique se você tem:

Uma entidade de serviço do Entra com o privilégio EXTERNAL USE SCHEMA concedido no esquema de destino no Catálogo do Unity. Consulte Conceder privilégios de administrador principal do Catálogo do Unity.
A ID do cliente e o segredo do cliente da entidade de serviço.
Sua ID de locatário do Azure.

Execute o seguinte SQL no Snowflake:

CREATE OR REPLACE CATALOG INTEGRATION <catalog-integration-name>
  CATALOG_SOURCE = ICEBERG_REST
  TABLE_FORMAT = ICEBERG
  CATALOG_NAMESPACE = '<uc-schema-name>'
  REST_CONFIG = (
    CATALOG_URI = 'https://<workspace-url>/api/2.1/unity-catalog/iceberg-rest'
    WAREHOUSE = '<uc-catalog-name>'
  )
  REST_AUTHENTICATION = (
    TYPE = OAUTH
    OAUTH_TOKEN_URI = 'https://login.microsoftonline.com/<azure-tenant-id>/oauth2/v2.0/token'
    OAUTH_CLIENT_ID = '<entra-client-id>'
    OAUTH_CLIENT_SECRET = '<entra-client-secret>'
    OAUTH_ALLOWED_SCOPES = ('2ff814a6-3304-4ab8-85cb-cd0e6f879c1d/.default')
  )
  ENABLED = TRUE
  REFRESH_INTERVAL_SECONDS = 600;

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>: a URL do espaço de trabalho do Azure Databricks. Por exemplo, adb-1234567890123456.12.azuredatabricks.net.
<azure-tenant-id>: Seu ID de locatário do Microsoft Entra ID.
<entra-client-id>: a ID do aplicativo (client) da entidade de serviço do Entra.
<entra-client-secret>: um segredo do cliente para a entidade de serviço do Entra.

Importante

O escopo 2ff814a6-3304-4ab8-85cb-cd0e6f879c1d/.default é a ID do aplicativo do Azure Databricks registrada no Entra. Isso difere do escopo all-apis usado com o endpoint OIDC do Azure Databricks. Usar o escopo errado é uma causa comum de falhas de autenticação ao configurar essa integração.

Depois de criar a integração do catálogo, siga a documentação do Snowflake para criar um banco de dados vinculado ao catálogo para acessar suas tabelas.

Para obter mais informações sobre como criar e gerenciar principais de serviço do Entra para o Azure Databricks, consulte Autenticar com as entidades de serviço do Microsoft Entra.

Observação

O Snowflake não dá suporte à autenticação Entra para integrações de catálogo que utilizam rede de comunicação privada (Link Privado do Azure) para conexão ao Azure Databricks. A conexão com o ponto de extremidade do catálogo REST do Iceberg no Azure Databricks deve usar redes públicas ao autenticar com uma entidade de serviço do Entra.

Bancos de dados vinculados ao catálogo

Os bancos de dados vinculados ao catálogo do Snowflake sincronizam automaticamente com o Unity Catalog para detectar esquemas e tabelas Iceberg. Isso elimina a necessidade de atualização manual de metadados.

Depois de configurar uma integração de catálogo do Snowflake, consulte a documentação do Snowflake para criar um banco de dados vinculado ao catálogo para acessar suas tabelas.

Importante

A tentativa de gravar do Snowflake em tabelas de leitura apenas do Azure Databricks pode resultar em erros. Consulte a documentação do Snowflake para operações com suporte.

Tabelas externas

Como alternativa, você pode criar tabelas externas depois de criar uma integração de catálogo do Snowflake. Essa abordagem requer atualizar manualmente metadados para ver atualizações.

CREATE OR REPLACE ICEBERG TABLE my_table
  CATALOG = '<catalog-integration-name>'
  CATALOG_TABLE_NAME = '<uc-table-name>';

Usar tabelas do Azure Databricks com PyIceberg

Para usar pyIceberg para acessar tabelas do Azure Databricks, você deve instalar o PyIceberg com as dependências necessárias. PyIceberg requer pyarrow operações de tabela, como ler dados e inspecionar metadados de tabela. Instale o PyIceberg com o recurso pyarrow extra:

pip install "pyiceberg[pyarrow]"

Observação

Se você não instalar pyarrow, as operações como descrever ou ler tabelas falharão. Para obter a lista completa de dependências opcionais, consulte a documentação de PyIceberg.

Veja a seguir um exemplo das configurações para permitir que PyIceberg acesse tabelas do Azure Databricks conectando-se ao Catálogo REST do Iceberg no Catálogo do Unity:

catalog:
  unity_catalog:
    uri: https://<workspace-url>/api/2.1/unity-catalog/iceberg-rest
    warehouse: <uc-catalog-name>
    token: <token>

Substitua as seguintes variáveis:

<workspace-url>: a URL do espaço de trabalho do Azure Databricks. Por exemplo, adb-1234567890123456.12.azuredatabricks.net.

<uc-catalog-name>: o nome do catálogo no Unity Catalog que você precisa acessar.
<token>: um PAT (token de acesso pessoal) para a entidade configurando a integração.

Consulte a documentação para a configuração do catálogo REST do PyIceberg.

Exemplo de curl da API REST

O exemplo a seguir curl carrega uma tabela usando a API REST:

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

A resposta tem esta aparência:

{
  "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 expires-at-ms campo indica quando as credenciais expiram. O tempo de expiração padrão é de uma hora. Para obter um melhor desempenho, o cliente armazenará as credenciais em cache até que elas expirem antes de solicitar novas.

Comentários

Esta página foi útil?

Last updated on 2026-07-01

Acesse tabelas do Azure Databricks a partir de clientes do Apache Iceberg

Usar o ponto de extremidade do catálogo do Iceberg no Catálogo do Unity

Requisitos

Usar tabelas do Iceberg com o Apache Spark

Autenticação OAuth

CLI

Python

Autenticação PAT

CLI

Python

Acessar tabelas do Azure Databricks com Snowflake

Snowflake com autenticação de token de portador

Snowflake com OAuth da entidade de serviço do Entra

Bancos de dados vinculados ao catálogo

Tabelas externas

Usar tabelas do Azure Databricks com PyIceberg

Exemplo de curl da API REST

Comentários

Recursos adicionais