Acessar tabelas do Azure Databricks a partir de clientes Apache Iceberg

O catálogo Apache Iceberg REST permite que clientes suportados, como Apache Spark, Apache Flink e Trino, leiam e escrevam em tabelas Iceberg registadas no Unity Catalog em Azure Databricks.

Para obter uma lista completa das integrações suportadas, consulte Integrações do Catálogo Unity.

Observação

O Unity Catalog também possui um endpoint da API do Iceberg REST de leitura única. Este é um endpoint legado. Consulte Ler tabelas Databricks pelo cliente Apache Iceberg (legado).

Use o ponto de extremidade do catálogo Unity Catalog Iceberg

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

Configure o acesso usando o ponto de extremidade /api/2.1/unity-catalog/iceberg-rest. Consulte a especificação da API REST do Iceberg para obter detalhes sobre como usar esta API REST.

Observação

O Azure Databricks introduziu a distribuição de credenciais para alguns clientes leitor Iceberg. A Databricks recomenda o uso da venda automática de credenciais para controlar o acesso a locais de armazenamento em nuvem para sistemas suportados. Consulte o Unity Catalog vending de credenciais para acesso a sistemas externos e as tabelas Access Iceberg usando sistemas externos.

Se a venda automática de credenciais não for suportada para o seu cliente, você deverá configurar o acesso do cliente ao local de armazenamento que contém os arquivos e metadados para a tabela Delta ou Iceberg. Consulte a documentação do seu cliente Iceberg para obter detalhes de configuração.

Requerimentos

O Azure Databricks dá suporte ao acesso do catálogo REST do Iceberg a tabelas como parte do Unity Catalog. Você deve ter o Unity Catalog habilitado no seu espaço de trabalho para usar esses endpoints. Os seguintes tipos de tabelas estão acessíveis através do Catálogo Iceberg REST:

Tópico Leitura Escreve
Iceberg gerenciado Sim Sim
Iceberg estrangeiro Sim Não
Delta gerenciado (com leituras do Iceberg habilitadas) Sim Não
Delta externo (com leituras Iceberg ativadas) Sim Não

As tabelas Iceberg estrangeiras não são automaticamente atualizadas ao usar a API do Catálogo REST do Iceberg para ler tabelas. Para atualizares, deves executar REFRESH FOREIGN TABLE para ler o instantâneo mais recente. A venda automática de credenciais em mesas Iceberg estrangeiras não é suportada.

Observação

Deve configurar tabelas Delta para serem acessíveis usando a API do Catálogo REST do Iceberg. Veja Como ler tabelas Delta com clientes Iceberg.

Deve completar os seguintes passos de configuração para configurar o acesso para ler ou escrever em tabelas Azure Databricks a partir de clientes Iceberg usando o catálogo Iceberg REST:

Observação

A especificação Iceberg não permite ficheiros de dados duplicados num único snapshot de tabela. Para evitar isto, quando é detetado, o Unity Catalog impede motores externos de gravarem ficheiros de dados duplicados na tabela.

Use tabelas Iceberg com o Apache Spark

Segue-se um exemplo de como configurar o Apache Spark para aceder às tabelas Azure Databricks através da API Iceberg REST Catalog usando autenticação OAuth:

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

# Configuration for accessing 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>.rest.auth.type": "oauth2",
"spark.sql.catalog.<spark-catalog-name>.uri": "<workspace-url>/api/2.1/unity-catalog/iceberg-rest",
"spark.sql.catalog.<spark-catalog-name>.oauth2-server-uri": "<workspace-url>/oidc/v1/token",
"spark.sql.catalog.<spark-catalog-name>.credential":"<oauth_client_id>:<oauth_client_secret>",
"spark.sql.catalog.<spark-catalog-name>.warehouse":"<uc-catalog-name>"
"spark.sql.catalog.<spark-catalog-name>.scope":"all-apis"

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 na sessão do Spark.
  • <oauth_client_id>: ID de cliente OAuth para o principal de autenticação.
  • <oauth_client_secret>: Segredo do cliente OAuth para o principal autenticador.

Com essas configurações, você pode consultar tabelas no Unity Catalog usando o Apache Spark. Para acessar tabelas em vários catálogos, você deve configurar cada catálogo separadamente.

Ao consultar tabelas no Unity Catalog usando configurações do Spark, lembre-se do seguinte:

  • Você precisará "spark.sql.extensions": "org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions" somente se estiver executando procedimentos armazenados específicos do Iceberg.

  • O Azure Databricks usa o armazenamento de objetos na nuvem para todas as tabelas. Você deve adicionar o JAR iceberg-spark-runtime como pacotes Spark:

    • AWS: org.apache.iceberg:iceberg-aws-bundle:<iceberg-version>
    • Azure: org.apache.iceberg:iceberg-azure-bundle:<iceberg-version>
    • GCP (Google Cloud Platform): org.apache.iceberg:iceberg-gcp-bundle:<iceberg-version>

    Para mais informações, consulte a documentação da integração AWS do Iceberg para o Spark .

    Observação

    Essas configurações não são necessárias ao acessar tabelas Iceberg do Azure Databricks. Não há suporte para o carregamento de JARs externos do Iceberg em clusters do Azure Databricks.

Acessar tabelas do Azure Databricks com o Snowflake

O Snowflake oferece duas opções para aceder a tabelas através do catálogo Iceberg REST: usar as bases de dados ligadas ao catálogo do Snowflake, ou usar tabelas externas.

Para ambas as opções, primeiro configura uma integração com o catálogo Snowflake. O Azure Databricks suporta os seguintes métodos de autenticação para integrações de catálogos Snowflake:

  • Token portador: Utiliza um token de acesso pessoal (PAT) ou token OAuth do Azure Databricks. Suportado em todas as nuvens.
  • Entra service principal OAuth (apenas Azure): Utiliza um principal de serviço Microsoft Entra ID para autenticar diretamente contra o endpoint do token Entra.

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

Snowflake com autenticação por token de portador

O exemplo seguinte configura uma integração de catálogo Snowflake usando um token portador. Pode usar um token de acesso pessoal (PAT) do Azure Databricks ou um token OAuth gerado a partir de um principal de serviço do Azure Databricks. Para detalhes sobre a geração de tokens OAuth, veja Autorizar o acesso do principal de serviço ao Azure Databricks com 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 a atribuir ao catálogo registado no Snowflake.
  • <uc-schema-name>: O nome do esquema que precisa aceder no Catálogo Unity.
  • <uc-catalog-name>: O nome do catálogo no Unity Catalog ao qual é necessário aceder.
  • <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 token de acesso pessoal (PAT) para o principal responsável que configura a integração.

Snowflake com o principal de serviço da Entra OAuth

No Azure, integrações de catálogo Snowflake que utilizam um principal de serviço apoiado pelo Entra não podem usar o endpoint do token OIDC do Azure Databricks (<workspace-url>/oidc/v1/token). Em vez disso, deve autenticar-se diretamente contra o endpoint do token Microsoft Entra. Isto é diferente da abordagem OAuth usada para outros clientes Iceberg (como o Apache Spark) no Azure.

Observação

A documentação da Snowflake pode indicar que o Entra ID não é suportado. A configuração abaixo utiliza o Entra OAuth, direcionado para o âmbito de recursos Azure Databricks, e é o caminho suportado para ler o Unity Catalog a partir do Snowflake no Azure.

Antes de começar, certifique-se de que tem:

  • Um principal de serviço Entra com o privilégio EXTERNAL USE SCHEMA concedido no esquema alvo no Unity Catalog. Consulte Conceder privilégios principais ao Catálogo Unity.
  • O ID de cliente e o segredo do cliente da entidade de serviço.
  • O seu ID de tenant 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 a atribuir ao catálogo registado no Snowflake.
  • <uc-schema-name>: O nome do esquema no Unity Catalog 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, adb-1234567890123456.12.azuredatabricks.net.
  • <azure-tenant-id>: O seu ID de tenant do Microsoft Entra.
  • <entra-client-id>: O ID da aplicação (cliente) do principal de serviço do Entra.
  • <entra-client-secret>: Um segredo de cliente para o principal do serviço Entra.

Importante

O âmbito 2ff814a6-3304-4ab8-85cb-cd0e6f879c1d/.default é o ID da aplicação Azure Databricks registado no Entra. Isto é distinto do all-apis âmbito utilizado com o endpoint OIDC do Azure Databricks. Usar o escopo errado é uma causa comum de falhas de autenticação ao configurar esta integração.

Depois de criar a integração do catálogo, siga a documentação do Snowflake para criar uma base de dados ligada ao catálogo para aceder às suas tabelas.

Para mais informações sobre a criação e gestão de princípios de serviço Entra para Azure Databricks, consulte Autenticar com princípios de serviço Microsoft Entra.

Observação

O Snowflake não suporta autenticação Entra para integrações de catálogos que utilizam redes privadas (Azure Private Link) para se ligar ao Azure Databricks. A ligação ao endpoint do catálogo REST do Azure Databricks Iceberg deve usar rede pública ao autenticar com um principal de serviço Entra.

Bases de dados ligadas a catálogos

As bases de dados ligadas a catálogos da Snowflake sincronizam-se automaticamente com o Unity Catalog para detetar esquemas e tabelas Iceberg. Isto elimina a necessidade de atualização manual dos metadados.

Depois de configurar uma integração de catálogo Snowflake, consulte a documentação Snowflake para criar uma base de dados ligada ao catálogo e aceder às suas tabelas.

Importante

Tentar escrever do Snowflake para tabelas apenas de leitura Azure Databricks pode resultar em erros. Consulte a documentação do Snowflake para operações suportadas.

Tabelas externas

Alternativamente, pode criar tabelas externas depois de criar uma integração do catálogo Snowflake. Esta abordagem requer a atualização manual dos metadados para ver as 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 o PyIceberg

Para usar o PyIceberg para aceder às tabelas Azure Databricks, deve instalar o PyIceberg com as dependências necessárias. O PyIceberg exige pyarrow operações de tabela, como ler dados e inspecionar metadados de tabelas. Instale o PyIceberg com o pyarrow extra:

pip install "pyiceberg[pyarrow]"

Observação

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

A seguir está um exemplo das definições de configuração para permitir que o PyIceberg acesse as tabelas do Azure Databricks conectando-se ao Catálogo REST do Iceberg no Catálogo 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:

  • <uc-catalog-name>: O nome do catálogo no Unity Catalog ao qual é necessário aceder.
  • <token>: Um token de acesso pessoal (PAT) para o principal responsável que configura a integração.

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

Exemplo de curl da API REST

O seguinte curl exemplo 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 a seguinte 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 validade padrão é de uma hora. Para melhor desempenho, peça ao cliente para guardar as credenciais em cache até expirarem antes de pedir novas.

  • Last updated on