Leia tabelas Databricks a partir de clientes Iceberg

Artigo
01/21/2025

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

Ler usando o ponto de extremidade do catálogo Unity Catalog Iceberg

Unity Catalog fornece uma implementação apenas de leitura da API do catálogo REST do Iceberg para tabelas nas quais as leituras Iceberg estão ativadas.

Configure o acesso usando o ponto de extremidade /api/2.1/unity-catalog/iceberg. 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 distribuição de credenciais do Unity Catalog para acesso de 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 em nuvem que contém os arquivos e metadados para a tabela Delta com leituras Iceberg (UniForm) habilitadas. Consulte a documentação do seu cliente leitor 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 tabela são elegíveis para leituras do catálogo REST do Iceberg:

Tabelas geridas pelo Unity Catalog com leituras Iceberg (UniForm) ativadas.
Tabelas externas do Unity Catalog armazenadas com Delta Lake com leituras Iceberg (UniForm) habilitadas.

Veja Ler tabelas Delta com clientes Iceberg.

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

Habilite de acesso a dados externos para seu metastore. Consulte Habilitar acesso a dados externos no metastore.
Conceda ao usuário principal que configura a integração o privilégio EXTERNAL USE SCHEMA no esquema que contém as tabelas. Ver Conceder um EXTERNO principal USE SCHEMA.
Autentique-se usando um token de acesso pessoal Databricks. Consulte Autorização do acesso aos recursos do Azure Databricks.

Leia as tabelas do Iceberg com o Apache Spark

A seguir está 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 na sessão do Spark.
<workspace-url>: URL do espaço de trabalho do Azure Databricks.
<token>: token PAT para o responsável principal pela configuração da 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 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 pacote Iceberg específico da nuvem JAR 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 mais informações, consulte a documentação da integração AWS do Iceberg para o Spark .

Leia tabelas Databricks utilizando Snowflake

A seguir está um exemplo das definições de configuração recomendadas para permitir que o Snowflake leia as 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 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>: URL do espaço de trabalho do Azure Databricks.
<token>: token PAT para o responsável principal pela configuração da integração.

Exemplo de curl da API REST

Você também pode usar uma chamada de API REST como a deste exemplo curl 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>

Você deve então 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 um melhor desempenho, faça com que o cliente armazene as credenciais em cache até o tempo de expiração antes de solicitar uma nova.

Compartilhar via