Partilhar via

Aceder a tabelas Databricks a partir de clientes Delta

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

Dica

Para informações sobre como ler dados Azure Databricks usando Microsoft Fabric, consulte Use Microsoft Fabric para ler dados registados no Unity Catalog.

Criar, ler e escrever usando a API REST da Unity

Importante

Criar e escrever tabelas geridas pelo Unity Catalog com clientes Delta está atualmente em fase Beta. O suporte externo ao cliente é limitado.

A API REST da Unity fornece a clientes externos acesso à criação, leitura e escrita de tabelas registadas no Unity Catalog. Configure o acesso usando a URL do espaço de trabalho como endpoint. Os seguintes tipos de tabelas estão acessíveis:

Tipo de tabela Leitura Escreve Criar
Delta de gestão Sim Sim* Sim*
Delta Externo Sim Sim Sim

* Suportado para tabelas Delta geridas com confirmações de catálogo.

Requerimentos

O Azure Databricks suporta o acesso da API REST da Unity a tabelas como parte do Unity Catalog. Você deve ter o Unity Catalog habilitado em seu espaço de trabalho para usar esses endpoints.

Deve também completar os seguintes passos de configuração para configurar o acesso às tabelas a partir dos clientes Delta usando a API REST da Unity:

Limitações

  • O acesso externo a tabelas UniForm com o IcebergCompatV3 não é atualmente suportado. Depois de escrever externamente numa tabela UniForm, deve executar MSCK REPAIR TABLE em Databricks para gerar metadados Iceberg.
  • Alterações de esquema (por exemplo, ALTER TABLE), atualizações de propriedades de tabelas e alterações de funcionalidades de tabela não são atualmente suportadas em tabelas geridas de clientes externos.
  • Clientes externos não podem realizar operações de manutenção de tabelas, como OPTIMIZE, VACUUM, e ANALYZE, em tabelas Delta geridas.
  • Clientes externos não conseguem criar clones superficiais.
  • Clientes externos não podem criar tabelas com colunas geradas, colunas por defeito ou colunas de restrição.
  • Ao criar tabelas externas, o Azure Databricks recomenda usar o Apache Spark para garantir que as definições das colunas estão num formato compatível com o Apache Spark. A API não valida a exatidão da especificação da coluna. Se a especificação não for compatível com o Apache Spark, o Databricks Runtime pode não conseguir ler as tabelas.

Aceder a tabelas Delta com Apache Spark usando autenticação PAT

A seguinte configuração é necessária para ler ou escrever em tabelas Delta geridas pelo Unity Catalog e externas com Apache Spark usando 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 responsável que configura a integração.
  • : A URL do espaço de trabalho Azure Databricks , incluindo o ID do espaço de trabalho. Por exemplo, adb-1234567890123456.12.azuredatabricks.net.

Observação

As versões dos pacotes apresentadas acima estão atualizadas até à última atualização desta página. Podem estar disponíveis versões mais recentes. Verifica se as versões dos pacotes são compatíveis com a versão do teu Spark.

Para mais detalhes sobre a configuração do Apache Spark para armazenamento de objetos na cloud, consulte a documentação do Unity Catalog OSS.

Importante

Databricks Runtime 16.4 e superiores são necessários para ler, escrever ou criar tabelas quando os commits de catálogo estão ativados. O Databricks Runtime 18.0 e versões superiores é necessário para poder ativar ou desativar commits de catálogo em tabelas existentes.

Para criar tabelas Delta geridas com commits de catálogo, utilize o seguinte comando 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>;

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

O Azure Databricks também suporta autenticação OAuth máquina-a-máquina (M2M). O OAuth gere automaticamente a renovação de tokens e credenciais para a autenticação do Catálogo Unity.

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

A seguinte configuração é necessária para criar, ler ou escrever em tabelas geridas pelo Unity Catalog e tabelas Delta externas com Apache Spark usando 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:

  • : A URL do espaço de trabalho Azure Databricks , incluindo o ID do espaço de trabalho. Por exemplo, adb-1234567890123456.12.azuredatabricks.net.

Observação

As versões dos pacotes apresentadas acima estão atualizadas até à última atualização desta página. Podem estar disponíveis versões mais recentes. Verifica se as versões dos pacotes são compatíveis com a versão do teu Spark.

Criar tabelas Delta usando a API

Para criar uma tabela Delta externa usando a API REST do Unity Catalog, 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 Unity Catalog:

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 espaço de trabalho Azure Databricks
  • <token>: Token para o principal que faz a chamada de API
  • <uc-catalog-name>: Nome do catálogo no Unity Catalog que conterá a tabela externa
  • <schema-name>: Nome do esquema dentro do catálogo onde a tabela será criada
  • <table-name>: O nome da tabela externa
  • <path>: Caminho totalmente qualificado para os dados da tabela

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

A chamada de 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>")

Observação

A API Create Table para clientes externos tem as seguintes limitações:

  • Somente tabelas Delta externas são suportadas ("table_type": "EXTERNAL" e "data_source_format": "DELTA").
  • Apenas são permitidos os seguintes campos:
    • name
    • catalog_name
    • schema_name
    • table_type
    • data_source_format
    • columns
    • storage_location
    • properties
  • Não há suporte para máscaras de coluna.
  • Last updated on