Acessar tabelas do Databricks a partir de clientes do Apache Iceberg

info

Visualização

Unity Catalog Apache Iceberg REST O catálogo API está em Public Preview em Databricks Runtime 16.4 LTS e acima.

O Unity Catalog tem uma implementação somente de leitura da API do Iceberg REST Catalog, que está disponível de forma geral. Esse endpoint é recomendado para a leitura de tabelas Delta com leituras Iceberg ativadas. Consulte Ler tabelas Databricks de clientes Iceberg (legado) para obter mais informações.

Use o catálogo REST do Apache Iceberg para ler e gravar em tabelas registradas no Unity Catalog - tabelas registradas no Databricks a partir de clientes Iceberg compatíveis, incluindo Apache Spark, Apache Flink, Trino e Snowflake.

Para obter uma lista completa das integrações compatíveis, consulte Integrações do Unity Catalog.

Use o catálogo Unity Catalog Iceberg endpoint

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

Configure 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 o uso dessa API REST.

nota

A Databricks introduziu a venda de credenciais para alguns clientes do Iceberg Reader. A Databricks recomenda usar a venda de credenciais para controlar o acesso aos locais de armazenamento em nuvem para sistemas compatíveis. Consulte a venda de credenciais do Unity Catalog para acesso externo ao sistema.

Se a venda de credenciais não for compatível com o seu cliente, o senhor 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 seu cliente Iceberg para obter detalhes sobre a configuração.

Requisitos

A Databricks oferece suporte ao acesso do catálogo Iceberg REST às tabelas como parte do Unity Catalog. O senhor deve ter o Unity Catalog ativado em seu workspace para usar esses endpoints. Os tipos de tabela a seguir podem ser acessados por meio do Iceberg REST Catalog:

tópico	Ler	Gravar
gerenciar Iceberg	Sim	Sim
Iceberg estrangeiro	Sim	Não
gerenciar Delta (com Iceberg reads habilitado)	Sim	Não
Delta externo (com a leitura do Iceberg ativada)	Sim	Não

As tabelas estrangeiras do Iceberg não são atualizadas automaticamente durante a leitura por meio da API do catálogo REST do Iceberg. Para refresh, o senhor deve executar REFRESH FOREIGN TABLE para ler o Snapshot mais recente. Não há suporte para a venda de credenciais em tabelas do Foreign Iceberg.

nota

O senhor deve configurar as tabelas Delta para que sejam acessíveis por meio da API do catálogo REST do Iceberg. Veja as tabelas Ler Delta com clientes Iceberg.

O senhor deve concluir as etapas de configuração a seguir para configurar o acesso para ler ou gravar em tabelas do Databricks a partir de clientes do Iceberg usando o catálogo REST do Iceberg:

Ative o acesso externo a dados para sua metastore. Consulte Habilitar o acesso externo a dados no metastore.
Conceda ao principal que configura a integração o privilégio EXTERNAL USE SCHEMA no esquema que contém as tabelas. Consulte Conceder um diretor EXTERNAL USE SCHEMA.
Faça a autenticação usando um Databricks tokens de acesso pessoal ou OAuth. Consulte Autorização de acesso a Databricks recurso.

Usar tabelas Iceberg com o Apache Spark

Veja a seguir um exemplo de como configurar o Apache Spark para acessar as tabelas do Databricks por meio da API Iceberg REST Catalog usando a autenticação OAuth:

"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>.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_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 o senhor deseja atribuir ao catálogo na sua sessão do Spark.
<workspace-url>: URL do site Databricks workspace.
<oauth_client_id>: ID do cliente OAuth para o principal de autenticação.
<oauth_client_secret>: Segredo do cliente OAuth para o principal de autenticação.

Com essas configurações, o senhor 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.

Quando o senhor consultar tabelas no Unity Catalog usando configurações do Spark, tenha em mente o seguinte:

Você precisará do "spark.sql.extensions": "org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions" somente se estiver executando procedimentos armazenados específicos do Iceberg.
A Databricks usa o armazenamento de objetos na nuvem para todas as tabelas. O senhor deve adicionar o iceberg-spark-runtime JAR como Spark pacote:
- 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 AWS para o Spark.

nota

Essas configurações não são necessárias ao acessar tabelas do Iceberg a partir do Databricks. Não há suporte para o carregamento de JARs externos do Iceberg no clustering do Databricks.

Ler tabelas do Databricks com o Snowflake

A seguir, um exemplo das definições de configuração recomendadas para permitir que o Snowflake leia as tabelas do Databricks conectando-se ao Iceberg REST Catalog no Unity Catalog:

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>'
    ACCESS_DELEGATION_MODE = VENDED_CREDENTIALS
  )
  REST_AUTHENTICATION = (
    TYPE = BEARER
    BEARER_TOKEN = '<token>'
  )
  ENABLED = TRUE;

Substitua as seguintes variáveis:

<catalog-integration-name>: O nome que o senhor deseja atribuir ao catálogo registrado no Snowflake.
<uc-schema-name>: O nome do esquema no Unity Catalog que o senhor precisa acessar.
<uc-catalog-name>: O nome do catálogo no Unity Catalog que o senhor precisa acessar.
<workspace-url>: URL do site Databricks workspace.
<token>: Tokens PAT para o principal que está configurando a integração.

Usar tabelas do Databricks com o PyIceberg

A seguir, um exemplo das definições de configuração para permitir que o PyIceberg acesse as tabelas do Databricks conectando-se ao Iceberg REST Catalog no Unity Catalog:

Python
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>: URL do site Databricks workspace.
<uc-catalog-name>: O nome do catálogo no Unity Catalog que o senhor precisa acessar.
<token>: Tokens PAT para o principal que está configurando a integração.

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

Exemplo de curl da API REST

O senhor também pode usar uma chamada de API REST como a deste exemplo em curl para carregar uma tabela:

Bash
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": "s3://bucket/path/to/iceberg/table/metadata/file",
  "metadata": <iceberg-table-metadata-json>,
  "config": {
    "expires-at-ms": "<epoch-ts-in-millis>",
    "s3.access-key-id": "<temporary-s3-access-key-id>",
    "s3.session-token":"<temporary-s3-session-token>",
    "s3.secret-access-key":"<temporary-secret-access-key>",
    "client.region":"<aws-bucket-region-for-metadata-location>"
  }
}

nota

O campo expires-at-ms na resposta indica o tempo de expiração das credenciais e tem um tempo de expiração default de uma hora. Para melhorar o desempenho, faça com que o cliente armazene em cache as credenciais até o tempo de expiração antes de solicitar uma nova.

Use o catálogo Unity Catalog Iceberg endpoint​

Requisitos​

Usar tabelas Iceberg com o Apache Spark​

Ler tabelas do Databricks com o Snowflake​

Usar tabelas do Databricks com o PyIceberg​

Exemplo de curl da API REST​

Use o catálogo Unity Catalog Iceberg endpoint

Requisitos

Usar tabelas Iceberg com o Apache Spark

Ler tabelas do Databricks com o Snowflake

Usar tabelas do Databricks com o PyIceberg

Exemplo de curl da API REST