Compartilhar via

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

Importante

A API de Catálogo REST do Unity Catalog para Apache Iceberg está em versão prévia pública no Databricks Runtime 16.4 LTS e superior. Esse ponto de extremidade é recomendado para ler e gravar em tabelas de clientes Iceberg.

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

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.

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. Veja 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 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 por meio do 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 leitura do Iceberg habilitada) Sim Não

As tabelas de Iceberg estrangeiras não são atualizadas automaticamente ao ler por meio da API do Catálogo REST do Iceberg. 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 por meio da API do Catálogo REST do Iceberg. Confira Ler tabelas Delta com clientes Iceberg.

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:

Usar tabelas do Iceberg com o Apache Spark

Veja a seguir um exemplo de como configurar o Apache Spark para acessar tabelas do Azure Databricks por meio da API do Catálogo REST do Iceberg usando a 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 em sua sessão do Spark.
  • <workspace-url>: a URL do espaço de trabalho do Azure Databricks.
  • <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.

Com essas configurações, você pode consultar tabelas no Catálogo do Unity usando o Apache Spark. 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 iceberg-spark-runtime aos pacotes do Spark.

    • AWS: org.apache.iceberg:iceberg-aws-bundle:<iceberg-version>
    • Azul: 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.

    Observação

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

Acessar tabelas do Azure Databricks com Snowflake

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

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 do Unity que você precisa acessar.
  • <workspace-url>: a URL do espaço de trabalho do Azure Databricks.
  • <token>: token PAT para a entidade de segurança que está configurando a integração.

Usar tabelas do Azure Databricks com 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.
  • <uc-catalog-name>: o nome do catálogo do Unity que você precisa acessar.
  • <token>: token PAT para a entidade de segurança que está configurando a integração.

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

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 "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>

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.

  • Last updated on