Ler tabelas do Databricks de clientes do Iceberg

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

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

O Unity Catalog fornece uma implementação somente de leitura da API do catálogo REST do Iceberg para tabelas com leituras do Iceberg ativadas.

Configure o acesso usando o endpoint /api/2.1/unity-catalog/iceberg. Consulte a especificação da API REST do Iceberg para obter detalhes sobre o uso dessa API REST.

Observação

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 em nuvem que contém os arquivos e metadados da tabela Delta com leituras Iceberg (UniForm) ativadas. Consulte a documentação do cliente leitor 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 seguintes tipos de tabela são elegíveis para leituras do catálogo Iceberg REST:

  • Unity Catalog gerenciar tabelas com Iceberg reads (UniForm) ativado.

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

Consulte Habilitar leituras em Iceberg nas tabelas Delta (UniForm).

O senhor deve concluir as seguintes etapas de configuração para configurar o acesso à leitura de tabelas do Databricks a partir de clientes do Iceberg usando o catálogo REST do Iceberg:

Ler tabelas Iceberg com o Apache Spark

A seguir, um exemplo das configurações para que o Apache Spark leia as tabelas do 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 o senhor deseja atribuir ao catálogo na sua sessão do Spark.

  • <workspace-url>: URL do site Databricks workspace.

  • <token>: Tokens PAT para o principal que está configurando a integração.

Com essas configurações, o senhor pode consultar as tabelas do 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.

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 JAR do pacote Iceberg específico da nuvem 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 obter detalhes, consulte a documentação da integração do Iceberg AWS para o Spark.

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

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:

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>

Em seguida, você deve receber uma resposta como esta:

{
  "metadata-location": "gs://bucket/path/to/iceberg/table/metadata/file",
  "metadata": <iceberg-table-metadata-json>,
  "config": {
    "expires-at-ms": "<epoch-ts-in-millis>",
    "gcs.oauth2.token": "<temporary-oauth-token>",
    "gcs.oauth2.token-expires-at": "<epoch-ts-in-millis>"
  }
}

Observação

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.