Pular para o conteúdo principal
Última atualização em

Acesse tabelas do Databricks a partir de clientes Delta.

Esta página descreve como usar a API REST do Unity para criar, ler e gravar em tabelas gerenciadas Unity Catalog e em tabelas externas a partir de clientes Delta externos. Para obter uma lista completa das integrações compatíveis, consulte IntegraçõesUnity Catalog.

Crie, leia e escreva usando a API REST do Unity.​

info

Beta

A criação e a gravação de tabelas no Unity Catalog a partir de clientes Delta estão em versão Beta. O suporte externo ao cliente é limitado.

A API REST do Unity fornece aos clientes externos acesso para criar, ler e gravar tabelas registradas no Unity Catalog. Configure o acesso usando a URLworkspace como endpoint. Os seguintes tipos de tabela estão acessíveis:

Tipo de tabela

Ler

Gravar

Criar

Delta

Sim

Sim*

Sim*

Delta externo

Sim

Sim

Sim

* Suportado para gerenciamento de tabelas Delta com confirmação de catálogo.

Requisitos​

Databricks oferece suporte ao acesso API REST do Unity para tabelas como parte do Unity Catalog. Você precisa ter Unity Catalog ativado em seu workspace para usar esses endpoints.

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

Limitações​

  • O acesso externo a tabelas UniForm com IcebergCompatV3 não é suportado atualmente. Após escrever externamente em uma tabela UniForm , você deve executar MSCK REPAIR TABLE no Databricks para gerar metadados Iceberg .
  • Alterações de esquema (por exemplo, ALTER TABLE), atualizações de propriedades de tabela e alterações de recursos de tabela não são atualmente suportadas em tabelas gerencia de clientes externos.
  • Clientes externos não podem executar operações de manutenção de tabelas, como OPTIMIZE, VACUUM e ANALYZE, em tabelas Delta gerenciadas.
  • Clientes externos não podem criar clones superficiais.
  • Clientes externos não podem criar tabelas com colunas geradas automaticamente, colunas default ou colunas de restrição.
  • Ao criar tabelas externas, a Databricks recomenda o uso do 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.

Acesse tabelas Delta com Apache Spark usando autenticação PAT.​

A seguinte configuração é necessária para ler ou gravar em tabelas gerenciadas Unity Catalog e tabelas Delta 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",
"spark.jars": "/path/to/gcs-connector-3.0.2-shaded.jar"
nota

Você precisa download o arquivo JAR do conectorGCS separadamente. Atualize o caminho spark.jars para apontar para o arquivo de downloads gcs-connector-3.0.2-shaded.jar .

Substitua as seguintes variáveis:

  • <uc-catalog-name>: O nome do catálogo no Unity Catalog que contém suas tabelas.

  • <token>access token pessoal (PAT) para a entidade principal que configura a integração.

  • <workspace-url>: O URLworkspace Databricks . Por exemplo, cust-success.cloud.databricks.com.

nota

As versões dos pacotes mostradas acima são as atuais até a última atualização desta página. Versões mais recentes podem estar disponíveis. Verifique se as versões dos pacotes são compatíveis com a sua versão Spark .

Para obter mais detalhes sobre como configurar Apache Spark para armazenamento de objetos cloud , consulte a documentação OSSUnity Catalog.

importante

É necessário Databricks Runtime 16.4 ou superior para ler, gravar ou criar tabelas com o recurso de confirmação de catálogo ativado. É necessário Databricks Runtime 18.0 ou superior para habilitar ou desabilitar a confirmação de catálogo em tabelas existentes.

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

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, utilize o seguinte SQL:

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

Acesse tabelas Delta com Apache Spark usando autenticação OAuth.​

O Databricks também oferece suporte à autenticação OAuth de máquina para máquina (M2M). OAuth gerencia automaticamente os tokens e a renovação de credenciais para autenticação Unity Catalog .

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

A seguinte configuração é necessária para criar, ler ou gravar em tabelas gerenciadas 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",
"spark.jars": "/path/to/gcs-connector-3.0.2-shaded.jar"
nota

Você precisa download o arquivo JAR do conectorGCS separadamente. Atualize o caminho spark.jars para apontar para o arquivo de downloads gcs-connector-3.0.2-shaded.jar .

Substitua as seguintes variáveis:

nota

As versões dos pacotes mostradas acima são as atuais até a última atualização desta página. Versões mais recentes podem estar disponíveis. Verifique se as versões dos pacotes são compatíveis com a sua versão Spark .

Crie tabelas Delta usando a API.​

Para criar uma tabela Delta externa usando a API REST Unity Catalog , siga estes passos:

Passo 1: Faça uma solicitação POST para a APICriar Tabela.​

Utilize a seguinte solicitação API para registrar os metadados da tabela no Unity Catalog:

Bash
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 Databricks
  • <token>: tokens para a entidade principal que está fazendo a chamada 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>: Nome da tabela externa
  • <path>Caminho completo para os dados da tabela.

o passo 2: Inicializar 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 a localização da tabela, crie uma tabela Delta vazia usando o Spark:

O esquema utilizado neste passo deve corresponder exatamente às definições de coluna fornecidas na solicitação API .

Python

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>")
nota

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

  • Somente tabelas Delta externas são suportadas ("table_type": "EXTERNAL" e "data_source_format": "DELTA").

  • Somente os seguintes campos são permitidos:

    • name
    • catalog_name
    • schema_name
    • table_type
    • data_source_format
    • columns
    • storage_location
    • properties

  • Máscaras de coluna não são suportadas.

Nesta página