Acessar tabelas do Databricks a partir de clientes Delta

Esta página descreve como usar a API REST do Unity para criar, ler e escrever em tabelas gerenciadas e externas do Catálogo Unity a partir de clientes Delta externos. Para obter uma lista completa de integrações com suporte, consulte as integrações do Catálogo do Unity.

Criar, ler e gravar usando a API REST do Unity

A API REST do Unity fornece aos clientes externos acesso de criação, leitura e gravação a tabelas registradas no Catálogo do Unity. Configure o acesso usando a URL do workspace como o endpoint. Os seguintes tipos de tabela são acessíveis:

* Com suporte para tabelas Delta gerenciadas com confirmações de catálogo.

Requisitos

Azure Databricks dá suporte ao acesso à API REST do Unity para tabelas como parte do Catálogo do Unity. Você deve ter o Catálogo do Unity habilitado em seu espaço de trabalho para usar esses endpoints.

Você também deve concluir as seguintes etapas de configuração para configurar o acesso a tabelas de clientes Delta usando a API REST do Unity:

• Habilite o Acesso a dados externos no seu metastore. Confira Habilitar o acesso a dados externos no metastore.
• Conceda ao principal que acessa dados externamente o privilégio EXTERNAL USE SCHEMA no esquema que contém os objetos. Consulte Conceder privilégios de catálogo principal do Unity.
• Para tabelas externas acessadas pelo caminho: conceda ao principal o EXTERNAL USE LOCATION privilégio no local externo que contém o caminho da tabela. Consulte Conceder privilégios de catálogo principal do Unity.
• Verifique se o principal tem privilégios relevantes:
  • SELECT na tabela para leituras
  • MODIFY na tabela para gravações
  • CREATE no esquema para criação de tabela
  • Para gravações externas em tabelas Delta gerenciadas, verifique se a tabela que está sendo gravada tem confirmações de catálogo habilitadas.
• Autenticar usando um dos seguintes métodos:
  • PAT (token de acesso pessoal): consulte Authorize o acesso aos recursos Azure Databricks.
  • Autenticação M2M (máquina a máquina) do OAuth: oferece suporte à atualização automática de credenciais e tokens para trabalhos Spark de longa execução (>1 hora). Consulte Autorizar o acesso da entidade de serviço ao Azure Databricks com OAuth.

Limitações

• No momento, não há suporte para o acesso externo às tabelas UniForm com IcebergCompatV3. Depois de gravar externamente em uma tabela UniForm, você deve executar MSCK REPAIR TABLE no Databricks para gerar metadados do Iceberg.
• Atualmente, não há suporte para alterações de esquema (por exemplo), ALTER TABLEatualizações de propriedade de tabela e alterações de recursos de tabela em tabelas gerenciadas de clientes externos.
• Clientes externos não podem executar operações de manutenção de tabela, como OPTIMIZE, VACUUMe ANALYZE, em tabelas Delta gerenciadas.
• Clientes externos não podem criar clones rasos.
• Clientes externos não podem criar tabelas com colunas geradas, colunas padrão ou colunas de restrição.
• Ao criar tabelas externas, Azure Databricks recomenda usar o Apache Spark para garantir que as definições de coluna estejam em um formato compatível com o Apache Spark. A API não valida a correção da especificação da coluna. Se a especificação não for compatível com o Apache Spark, o Databricks Runtime poderá não conseguir ler as tabelas.

Acessar tabelas Delta com Apache Spark usando autenticação PAT

A configuração a seguir é necessária para ler ou gravar tabelas Delta gerenciadas e externas do Catálogo do Unity com Apache Spark, usando a autenticação PAT.

"spark.sql.extensions": "io.delta.sql.DeltaSparkSessionExtension",
"spark.sql.catalog.spark_catalog": "io.unitycatalog.spark.UCSingleCatalog",
"spark.sql.catalog.<uc-catalog-name>": "io.unitycatalog.spark.UCSingleCatalog",
"spark.sql.catalog.<uc-catalog-name>.uri": "<workspace-url>",
"spark.sql.catalog.<uc-catalog-name>.token": "<token>",
"spark.sql.defaultCatalog": "<uc-catalog-name>",
"spark.jars.packages": "io.delta:delta-spark_4.1_2.13:4.2.0,io.unitycatalog:unitycatalog-spark_2.13:0.4.1,org.apache.hadoop:hadoop-azure:3.4.2"

Substitua as seguintes variáveis:

• <uc-catalog-name>: o nome do catálogo no Unity Catalog que contém suas tabelas.
• <token>: Token de acesso pessoal (PAT) para o principal que está configurando a integração.

• <workspace-url>: A URL do workspace Azure Databricks , incluindo a ID do workspace. Por exemplo, adb-1234567890123456.12.azuredatabricks.net.

Para obter detalhes adicionais sobre como configurar o Apache Spark para armazenamento de objetos na nuvem, consulte a documentação do Catálogo do Unity OSS.

Para criar tabelas Delta gerenciadas com confirmações de catálogo, use o seguinte SQL:

CREATE TABLE <uc-catalog-name>.<schema-name>.<table-name> (id INT, desc STRING)
TBLPROPERTIES ('delta.feature.catalogManaged' = 'supported') USING delta;

Para criar tabelas Delta externas, use o seguinte SQL:

CREATE TABLE <uc-catalog-name>.<schema-name>.<table-name> (id INT, desc STRING)
USING delta
LOCATION <path>;

Acessar tabelas Delta com o Apache Spark usando a autenticação OAuth

Azure Databricks também dá suporte à autenticação M2M (máquina a máquina) do OAuth. O OAuth manipula automaticamente o token e a renovação de credenciais para a autenticação do Catálogo do Unity.

A autenticação OAuth para clientes externos do Spark requer:

• Cliente Spark do Catálogo do Unity versão 0.4.1 ou posterior (io.unitycatalog:unitycatalog-spark)
• Apache Spark 4.0 ou posterior
• Delta Spark 4.2.0 ou posterior
• Uma entidade de serviço OAuth M2M com permissões apropriadas. Consulte Autorizar o acesso ao principal de serviço ao Azure Databricks com OAuth.

A configuração a seguir é necessária para criar, ler ou gravar em tabelas gerenciadas do Catálogo do Unity e tabelas Delta externas com Apache Spark usando a autenticação OAuth:

"spark.sql.extensions": "io.delta.sql.DeltaSparkSessionExtension",
"spark.sql.catalog.spark_catalog": "io.unitycatalog.spark.UCSingleCatalog",
"spark.sql.catalog.<uc-catalog-name>": "io.unitycatalog.spark.UCSingleCatalog",
"spark.sql.catalog.<uc-catalog-name>.uri": "<workspace-url>",
"spark.sql.catalog.<uc-catalog-name>.auth.type": "oauth",
"spark.sql.catalog.<uc-catalog-name>.auth.oauth.uri": "<oauth-token-endpoint>",
"spark.sql.catalog.<uc-catalog-name>.auth.oauth.clientId": "<oauth-client-id>",
"spark.sql.catalog.<uc-catalog-name>.auth.oauth.clientSecret": "<oauth-client-secret>",
"spark.sql.defaultCatalog": "<uc-catalog-name>",
"spark.jars.packages": "io.delta:delta-spark_4.1_2.13:4.2.0,io.unitycatalog:unitycatalog-spark_2.13:0.4.1,org.apache.hadoop:hadoop-azure:3.4.2"

Substitua as seguintes variáveis:

• <uc-catalog-name>: o nome do catálogo no Unity Catalog que contém suas tabelas.
• <oauth-token-endpoint>: URL do ponto de extremidade do token OAuth. Para construir essa URL:
  1. Localize a ID da conta Azure Databricks. Veja como localizar seu ID de conta.
  2. Use o formato: https://accounts.cloud.databricks.com/oidc/accounts/<account-id>/v1/token
• <oauth-client-id>: ID do cliente OAuth para seu principal de serviço. Consulte Autorizar o acesso do principal de serviço para o Azure Databricks com OAuth.
• <oauth-client-secret>: segredo do cliente OAuth para sua entidade de serviço. Consulte Autorizar o acesso do principal ao Azure Databricks com OAuth.

• <workspace-url>: A URL do Azure Databricks workspace, incluindo a ID do workspace. Por exemplo, adb-1234567890123456.12.azuredatabricks.net.

Criar tabelas Delta usando a API

Para criar uma tabela Delta externa usando a API REST do Catálogo do Unity, siga estas etapas:

Etapa 1: fazer uma solicitação POST para a API Criar Tabela

Use a seguinte solicitação de API para registrar os metadados da tabela no Catálogo do Unity:

curl --location --request POST 'https://<workspace-url>/api/2.0/unity-catalog/tables/' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
  "name": "<table-name>",
  "catalog_name": "<uc-catalog-name>",
  "schema_name": "<schema-name>",
  "table_type": "EXTERNAL",
  "data_source_format": "DELTA",
  "storage_location": "<path>",
  "columns": [
    {
      "name": "id",
      "type_name": "LONG",
      "type_text": "bigint",
      "type_json": "\"long\"",
      "type_precision": 0,
      "type_scale": 0,
      "position": 0,
      "nullable": true
    },
    {
      "name": "name",
      "type_name": "STRING",
      "type_text": "string",
      "type_json": "\"string\"",
      "type_precision": 0,
      "type_scale": 0,
      "position": 1,
      "nullable": true
    }
  ]
}'

Substitua as seguintes variáveis:

• <workspace-url>: URL do workspace Azure Databricks
• <token>: token para o principal que está fazendo a chamada à API
• <uc-catalog-name>: nome do catálogo no Catálogo do Unity que conterá a tabela externa
• <schema-name>: nome do esquema dentro do catálogo em que a tabela será criada
• <table-name>: nome da tabela externa
• <path>: caminho totalmente qualificado para os dados da tabela

Etapa 2: Configurar a localização da tabela Delta

A chamada à API acima registra a tabela em :[UC], mas não cria os arquivos Delta no local de armazenamento. Para inicializar o local da tabela, escreva uma tabela Delta vazia usando o Spark:

O esquema usado nesta etapa deve corresponder exatamente às definições de coluna fornecidas na solicitação de API.

from pyspark.sql.types import StructType, StructField, StringType, LongType

# Define schema matching your API call
schema = StructType([
    StructField("id", LongType(), True),
    StructField("name", StringType(), True)
])

# Create an empty DataFrame and initialize the Delta table
empty_df = spark.createDataFrame([], schema)
empty_df.write \
    .format("delta") \
    .mode("overwrite") \
    .save("<path>")