Pular para o conteúdo principal

Criar tabelas Delta externas a partir de clientes externos

info

Visualização

Esse recurso está em Public Preview.

Esta página fornece informações sobre como criar tabelas externas d Unity Catalog, suportadas por Delta Lake, a partir de clientes e sistemas externos.

nota

A Databricks recomenda o uso do Apache Spark para criar tabelas externas, a fim de garantir que as definições das colunas 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.

Requisitos​

É possível criar tabelas externas utilizando o Apache Spark, a API do Unity Catalog ou outros clientes externos.

Criar tabelas Delta utilizando o Apache Spark​

A seguir, apresentamos um exemplo das configurações necessárias para configurar o Apache Spark para criar tabelas Delta externas do Unity Catalog:

"spark.sql.extensions": "io.delta.sql.DeltaSparkSessionExtension",
"spark.sql.catalog.spark_catalog": "io.unitycatalog.spark.UCSingleCatalog",
"spark.hadoop.fs.s3.impl": "org.apache.hadoop.fs.s3a.S3AFileSystem",
"spark.sql.catalog.<uc-catalog-name>": "io.unitycatalog.spark.UCSingleCatalog",
"spark.sql.catalog.<uc-catalog-name>.uri": "<workspace-url>/api/2.1/unity-catalog",
"spark.sql.catalog.<uc-catalog-name>.token": "<token>",
"spark.sql.defaultCatalog": "<uc-catalog-name>",

Substitua as seguintes variáveis:

  • <uc-catalog-name>: O nome do catálogo no Unity Catalog que contém suas tabelas.
  • <workspace-url>URL do Databricks workspace.
  • <token>: tokens OAuth para o principal que configura a integração.

Para que o Apache Spark e o Delta Lake funcionem em conjunto com o Unity Catalog, é necessário ter pelo menos o Apache Spark 3.5.3. e Delta Lake 3.2.1.

Inclua as seguintes dependências ao iniciar o Apache Spark:

--packages "org.apache.hadoop:hadoop-aws:3.3.4,\
io.delta:delta-spark_2.12:3.2.1,\
io.unitycatalog:unitycatalog-spark_2.12:0.2.0"

Agora é possível criar tabelas externas utilizando SQL:

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

Criar tabelas Delta utilizando a API​

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

Passo 1: Efetue uma solicitação POST para a API Criar tabela​

Utilize a seguinte solicitação API para registrar os metadados da tabela em 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 Databricks workspace
  • <token>: tokens para o principal que realiza a chamada " API "
  • <uc-catalog-name>: Nome do catálogo no Unity Catalog que conterá a tabela externa
  • <schema-name>: Nome do esquema no catálogo em que a tabela será criada
  • <table-name>: Nome da tabela externa
  • <path>: caminho totalmente qualificado para os dados da tabela

Passo 2: Inicialize a localização da tabela Delta​

A chamada “ API ” 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 utilizando o Spark:

O esquema utilizado nesta etapa deve corresponder exatamente às definições de coluna fornecidas na solicitação da 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 Criar Tabela para clientes externos apresenta as seguintes limitações:

  • Apenas 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

  • As máscaras de coluna não são suportadas.

Última atualização em