Acessar tabelas do Databricks a partir de clientes do Apache Iceberg

info

Visualização

API do catálogo REST Apache Iceberg Unity Catalog está em versão de visualização pública no Databricks Runtime 16.4 LTS e acima. Este endpoint é recomendado para leitura e gravação em tabelas de clientes Iceberg .

O Unity Catalog também tem um endpoint de API do Iceberg REST Catalog somente leitura. Este é um endpoint legado. Veja Ler tabelas do Databricks de clientes do Apache Iceberg (legado).

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

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 privilégios de administrador principal do Unity Catalog.
Autentique usando um access token pessoal Databricks ou OAuth. Veja Autorizar acesso ao recurso Databricks.

nota

A especificação Iceberg não permite arquivos de dados duplicados em um único Snapshot de tabela. Para evitar que isso ocorra, quando detectado, Unity Catalog impede que mecanismos externos enviem arquivos de dados duplicados para a tabela.

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 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 o senhor deseja atribuir ao catálogo na sua sessão do Spark.
<workspace-url>: O Databricks workspaceURL.
<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.
Databricks utiliza armazenamento de objetos cloud para todas as tabelas. Você precisa adicionar o arquivo JAR iceberg-spark-runtime como um pacote do 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 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.

Acessar tabelas do Databricks com o Snowflake

A seguir, um exemplo das definições de configuração do Snowflake para acessar 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>: O Databricks workspaceURL.
<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>: O Databricks workspaceURL.
<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​

Acessar 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

Acessar tabelas do Databricks com o Snowflake

Usar tabelas do Databricks com o PyIceberg

Exemplo de curl da API REST