Acessar tabelas do Azure Databricks a partir de clientes Apache Iceberg

O catálogo REST do Apache Iceberg permite que os clientes suportados, como Apache Spark, Apache Flink e Trino, leiam e gravem em tabelas Iceberg registradas no Unity Catalog no Azure Databricks.

Para obter uma lista completa das integrações suportadas, consulte Integrações do Catálogo Unity.

Use o ponto de extremidade do catálogo Unity Catalog Iceberg

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

Configure o acesso usando o ponto de extremidade /api/2.1/unity-catalog/iceberg-rest. Consulte a especificação da API REST do Iceberg para obter detalhes sobre como usar esta API REST.

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 podem ser acessados através do Catálogo REST do Iceberg:

As tabelas estrangeiras do Iceberg não são atualizadas automaticamente ao ler por meio da API do catálogo REST do Iceberg. Para atualizares, deves executar REFRESH FOREIGN TABLE para ler o instantâneo mais recente. A venda automática de credenciais em mesas Iceberg estrangeiras não é suportada.

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:

• Habilite acesso a dados externos para o 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. Consulte Conceder privilégios principais ao Catálogo Unity.
• Autentique-se usando um token de acesso pessoal do Azure Databricks ou OAuth. Consulte Autorizar o acesso aos recursos do Azure Databricks.

Use tabelas 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 na sessão do Spark.
• <workspace-url>: A URL do espaço de trabalho do Azure Databricks.
• <oauth_client_id>: ID de cliente OAuth para o principal de autenticação.
• <oauth_client_secret>: Segredo do cliente OAuth para o principal autenticador.

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

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 JAR iceberg-spark-runtime como pacotes Spark:

  • AWS: org.apache.iceberg:iceberg-aws-bundle:<iceberg-version>
  • Azure: org.apache.iceberg:iceberg-azure-bundle:<iceberg-version>
  • GCP (Google Cloud Platform): 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 .

  Observação

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

Acessar tabelas do Azure Databricks com o Snowflake

A seguir está um exemplo das definições de configuração para o Snowflake acessar tabelas do Azure Databricks conectando-se ao Catálogo REST do Iceberg no Catálogo 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 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>: A URL do espaço de trabalho do Azure Databricks.
• <token>: token PAT para o responsável principal pela configuração da integração.

Usar tabelas do Azure Databricks com o PyIceberg

A seguir está um exemplo das definições de configuração para permitir que o PyIceberg acesse as tabelas do Azure Databricks conectando-se ao Catálogo REST do Iceberg no Catálogo 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 no Unity Catalog que você precisa acessar.
• <token>: token PAT para o responsável principal pela configuração da 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 de API REST como a deste exemplo curl 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>

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